@marcomigozzi/trailhead 0.13.0 → 0.15.0

package/plugins/trailhead/templates/trailhead-dashboard.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead dashboard regeneration (self-contained, ships in templates/ so it
+// reaches every install channel). Gathers the tracker data the pinned
+// `trailhead:dashboard` issue indexes, renders the whole body deterministically
+// and writes it through trailhead-issue-body.js's guarded write (fail-safe read,
+// updatedAt check, post-write conflict check, secret scan). #253.
+//
+// CLI:
+//   node trailhead-dashboard.js [--repo <owner/name>] [--set-last-audit <ISO-8601 UTC>] [--dry-run]
+// --set-last-audit replaces the `<!-- trailhead:last-audit ... -->` marker (the
+// audit's only writer path); without it the marker is copied verbatim from the
+// existing body. --dry-run gathers and reads through gh, computes and scans, but
+// writes, creates, pins and labels nothing; it prints the old and new byte sizes.
+//
+// Self-heal: ensures the `trailhead:dashboard` label; creates the issue directly
+// with the final scanned body when it is missing (never an empty or placeholder
+// body) and pins it; re-pins it when unpinned. Never closes or prunes a map: the
+// flags are signals, the offers stay with the agent.
+//
+// Prints exactly one line on stdout:
+//   dashboard #33: 4 maps, whiteboard 1, flags: map-14 exhausted, map-98 near cap 92/100 (body 21034 -> 2210 bytes)
+//   aborted: <reason>
+// Exit 0 on success, 1 on an abort or a conflict, 2 on a usage error (stderr).
+// A pin check or pin failure AFTER the body was written is not an abort: the line
+// says `written, pin check failed: <reason>` (or `written, pin failed ...`) and the
+// exit is 0, since the body is in place; the agent surfaces the pin problem.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const issueBody = require('./trailhead-issue-body.js');
+
+const { guardedWrite, loadGuard, secretProblem, readSection, PLACEHOLDER_RE } = issueBody;
+
+const LABEL = 'trailhead:dashboard';
+const TITLE = '📊 trailhead dashboard';
+const NEAR_CAP = 90;
+const CAP = 100;
+const RESOLVED_SHOWN = 10;
+const AUDIT_LINE_RE = /^<!-- trailhead:last-audit [^ ]* -->[ \t\r]*$/;
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+// List-query limits; a list that comes back full is reported as truncated.
+const LIMITS = { maps: 200, scoped: 1000, whiteboard: 200, resolved: 100, inbox: 1000 };
+const NOT_RESOLVED_LABELS = ['trailhead:superseded', 'trailhead:out-of-scope'];
+
+// --- pure render -------------------------------------------------------------
+
+// A title safe to put inside a markdown link text, on one line. Comment
+// delimiters are neutralised so a title can never forge the last-audit marker.
+function linkText(title) {
+  return String(title).replace(/\s+/g, ' ').trim()
+    .replace(/<!--/g, '&lt;!--').replace(/-->/g, '--&gt;')
+    .replace(/([\[\]])/g, '\\$1');
+}
+
+// The last-audit marker the dashboard itself wrote: a line of its own (the last
+// such line), never text embedded in another line.
+function extractAudit(body) {
+  const hits = String(body).split('\n').filter((l) => AUDIT_LINE_RE.test(l));
+  return hits.length ? hits[hits.length - 1].trim() : null;
+}
+
+const issueUrl = (repo, n) => `https://github.com/${repo}/issues/${n}`;
+const link = (repo, n, text) => `[${text}](${issueUrl(repo, n)})`;
+
+// The flags of one map, from its raw numbers. exhausted needs a zero open-scoped
+// count AND a confirmed-empty fog; prunable needs the bounded closed-edge check.
+function mapFlags(m) {
+  const flags = [];
+  if (m.openScoped === 0 && m.fog === false) flags.push('exhausted · closeable');
+  if (m.total >= NEAR_CAP) {
+    const base = `${m.total >= CAP ? 'at cap' : 'near cap'} · ${m.total}/${CAP}`;
+    flags.push(m.closedEdges === true ? `${base} · prunable` : base);
+  }
+  return flags;
+}
+
+// Classifies the open whiteboard tickets with the panel's precedence: unverified
+// (quarantined first), paused, blocked, in progress (assigned), frontier
+// (everything else). A ticket lands in exactly one bucket. #263.
+function classify(whiteboard) {
+  const out = { frontier: [], inProgress: [], paused: [], blocked: [], unverified: [] };
+  for (const t of whiteboard) {
+    if (t.labels.includes('trailhead:unverified')) out.unverified.push(t);
+    else if (t.labels.includes('trailhead:paused')) out.paused.push(t);
+    else if (t.labels.includes('trailhead:blocked')) out.blocked.push(t);
+    else if (t.assignees && t.assignees.length) out.inProgress.push(t);
+    else out.frontier.push(t);
+  }
+  return out;
+}
+
+// snapshot: { repo, maps[], whiteboard[], resolved[], inbox, anchors, lastAudit }.
+function renderDashboard(s) {
+  const lines = [];
+  lines.push("The pinned index of this repo's trailhead surface. Regenerate any time with `/trailhead:dashboard`; it also self-heals on `/trailhead`, `/trailhead:map`, and `/trailhead:whiteboard`.");
+  lines.push('', '## 🗺 Maps');
+  if (s.maps.length === 0) lines.push('_No open maps._');
+  for (const m of s.maps) {
+    lines.push(`- ${link(s.repo, m.number, linkText(m.title))}: ${m.openScoped} open${mapFlags(m).map((f) => ` · ${f}`).join('')}`);
+  }
+  const wb = classify(s.whiteboard);
+  lines.push('', '## 🧷 Whiteboard (map-less tickets)');
+  if (s.whiteboard.length === 0) lines.push('_Nothing on the whiteboard._');
+  for (const [label, list] of [['Frontier', wb.frontier], ['In progress', wb.inProgress], ['Paused', wb.paused], ['Blocked', wb.blocked], ['Unverified', wb.unverified]]) {
+    if (list.length === 0) continue;
+    lines.push(`${label} (${list.length}):`);
+    for (const t of list) lines.push(`- ${link(s.repo, t.number, `${linkText(t.title)} #${t.number}`)}`);
+  }
+  if (s.resolved.length) {
+    lines.push('', `_Recently resolved: ${s.resolved.map((t) => link(s.repo, t.number, `${linkText(t.title)} #${t.number}`)).join(', ')}_`);
+  }
+  lines.push('', '## 📊 Counts');
+  lines.push(`- Untriaged inbox: ${s.inbox}${(s.truncated || []).includes('inbox') ? '+' : ''}`);
+  lines.push(`- Whiteboard frontier: ${wb.frontier.length}`);
+  lines.push(`- Open maps: ${s.maps.length}`);
+  const anchors = [['Codebase', s.anchors.codebase], ['Conventions', s.anchors.conventions]]
+    .filter(([, n]) => n).map(([name, n]) => link(s.repo, n, `${name} #${n}`));
+  if (anchors.length) lines.push('', `Anchors: ${anchors.join(' · ')}`);
+  if (s.lastAudit) lines.push('', s.lastAudit);
+  return lines.join('\n') + '\n';
+}
+
+// --- gather ------------------------------------------------------------------
+
+class GatherError extends Error {}
+
+function ghJson(gh, args) {
+  const r = gh(args);
+  if (r.status !== 0) throw new GatherError(`gh ${args.slice(0, 3).join(' ')} failed: ${(r.stderr || '').split('\n').find((l) => l.trim()) || 'exit ' + r.status}`);
+  try { return JSON.parse(r.stdout); } catch { throw new GatherError(`gh ${args.slice(0, 3).join(' ')} returned unparseable JSON`); }
+}
+
+function ghText(gh, args) {
+  const r = gh(args);
+  if (r.status !== 0) throw new GatherError(`gh ${args.slice(0, 2).join(' ')} failed: ${(r.stderr || '').split('\n').find((l) => l.trim()) || 'exit ' + r.status}`);
+  return r.stdout.trim();
+}
+
+const names = (labels) => (labels || []).map((l) => (typeof l === 'string' ? l : l.name));
+
+function issueList(gh, repo, extra) {
+  return ghJson(gh, ['issue', 'list', ...extra, '-R', repo]);
+}
+
+function gatherMap(gh, repo, m, truncated) {
+  const scoped = issueList(gh, repo, ['--label', `trailhead:map-${m.number}`, '--state', 'open', '--json', 'number', '--limit', String(LIMITS.scoped)]);
+  if (scoped.length >= LIMITS.scoped) truncated.push(`map-${m.number} scoped`);
+  const total = parseInt(ghText(gh, ['api', `repos/${repo}/issues/${m.number}`, '--jq', '.sub_issues_summary.total']), 10);
+  if (!Number.isInteger(total)) throw new GatherError(`map #${m.number}: unreadable sub-issue total`);
+  const out = { number: m.number, title: m.title, openScoped: scoped.length, total, fog: null, closedEdges: null };
+  if (out.openScoped === 0) {
+    // Candidate only: confirm the fog (`## Not yet specified`) is empty.
+    const view = ghJson(gh, ['issue', 'view', String(m.number), '--json', 'body', '-R', repo]);
+    const fog = readSection(String(view.body || ''), 'Not yet specified');
+    // A missing section is unconfirmed (fog stays null: no exhausted flag), only
+    // a present and empty one confirms there is no fog left.
+    out.fog = fog === null ? null : fog.some((l) => !PLACEHOLDER_RE.test(l));
+  }
+  if (total >= NEAR_CAP) {
+    const edges = ghJson(gh, ['api', `repos/${repo}/issues/${m.number}/sub_issues?per_page=100`]);
+    out.closedEdges = Array.isArray(edges) && edges.some((e) => e && e.state === 'closed');
+  }
+  return out;
+}
+
+function firstNumber(gh, repo, label) {
+  const list = issueList(gh, repo, ['--label', label, '--state', 'open', '--json', 'number', '--limit', '1']);
+  return list.length ? list[0].number : null;
+}
+
+function gatherSnapshot(gh, repo) {
+  const truncated = [];
+  const capped = (list, limit, name) => { if (list.length >= limit) truncated.push(name); return list; };
+  const maps = capped(issueList(gh, repo, ['--label', 'trailhead:map', '--state', 'open', '--json', 'number,title', '--limit', String(LIMITS.maps)]), LIMITS.maps, 'maps')
+    .sort((a, b) => a.number - b.number)
+    .map((m) => gatherMap(gh, repo, m, truncated));
+  const whiteboard = capped(issueList(gh, repo, ['--label', 'trailhead:whiteboard', '--state', 'open', '--json', 'number,title,labels,assignees', '--limit', String(LIMITS.whiteboard)]), LIMITS.whiteboard, 'whiteboard')
+    .map((t) => ({ number: t.number, title: t.title, labels: names(t.labels), assignees: (t.assignees || []).map((a) => a.login) }));
+  // Most recently updated first, so the newest closures sit inside the fetched
+  // window even on a repo with a long closed history; then ordered by closedAt.
+  const closed = issueList(gh, repo, ['--label', 'trailhead:whiteboard', '--state', 'closed', '--search', 'sort:updated-desc', '--json', 'number,title,closedAt,labels', '--limit', String(LIMITS.resolved)]);
+  const resolved = closed
+    .filter((t) => !names(t.labels).some((n) => NOT_RESOLVED_LABELS.includes(n)))
+    .sort((a, b) => String(b.closedAt).localeCompare(String(a.closedAt)))
+    .slice(0, RESOLVED_SHOWN)
+    .map((t) => ({ number: t.number, title: t.title }));
+  // A full window only matters when it could not fill the shown list.
+  if (closed.length >= LIMITS.resolved && resolved.length < RESOLVED_SHOWN) truncated.push('resolved');
+  const openIssues = capped(issueList(gh, repo, ['--state', 'open', '--json', 'number,labels', '--limit', String(LIMITS.inbox)]), LIMITS.inbox, 'inbox');
+  const inbox = openIssues.filter((i) => !names(i.labels).some((n) => n.startsWith('trailhead:'))).length;
+  const anchors = { codebase: firstNumber(gh, repo, 'trailhead:codebase'), conventions: firstNumber(gh, repo, 'trailhead:conventions') };
+  return { repo, maps, whiteboard, resolved, inbox, anchors, lastAudit: null, truncated };
+}
+
+// --- summary and self-heal ---------------------------------------------------
+
+function flagSummary(maps) {
+  const parts = [];
+  for (const m of maps) {
+    for (const f of mapFlags(m)) parts.push(`map-${m.number} ${f.replace(' · closeable', '').replace(/ · /g, ' ')}`);
+  }
+  return parts.length ? parts.join(', ') : 'none';
+}
+
+function summaryLine(number, snap) {
+  const cut = snap.truncated && snap.truncated.length ? `, truncated: ${snap.truncated.join(', ')}` : '';
+  return `dashboard${number === null ? '' : ' #' + number}: ${snap.maps.length} maps, whiteboard ${snap.whiteboard.length}, flags: ${flagSummary(snap.maps)}${cut}`;
+}
+
+function findDashboard(gh, repo) {
+  const list = issueList(gh, repo, ['--label', LABEL, '--state', 'open', '--json', 'number', '--limit', '1']);
+  return list.length ? list[0].number : null;
+}
+
+function isPinned(gh, repo, number) {
+  const [owner, name] = repo.split('/');
+  const q = 'query($o:String!,$n:String!){repository(owner:$o,name:$n){pinnedIssues(first:3){nodes{issue{number}}}}}';
+  const data = ghJson(gh, ['api', 'graphql', '-f', `query=${q}`, '-f', `o=${owner}`, '-f', `n=${name}`]);
+  const nodes = (((data.data || {}).repository || {}).pinnedIssues || {}).nodes || [];
+  return nodes.some((n) => n && n.issue && n.issue.number === number);
+}
+
+// Pins the issue; returns null on success or a short failure note.
+function pin(gh, repo, number) {
+  const node = gh(['api', `repos/${repo}/issues/${number}`, '--jq', '.node_id']);
+  if (node.status !== 0 || !node.stdout.trim()) return 'pin failed (node id)';
+  const r = gh(['api', 'graphql', '-f', 'query=mutation($id:ID!){ pinIssue(input:{issueId:$id}){ issue{ number } } }', '-F', `id=${node.stdout.trim()}`]);
+  return r.status === 0 ? null : 'pin failed (pinned slots full?)';
+}
+
+function createDashboard(gh, repo, body, tmpdir) {
+  const dir = fs.mkdtempSync(path.join(tmpdir || os.tmpdir(), 'trailhead-dashboard-'));
+  const file = path.join(dir, 'body.md');
+  try {
+    fs.writeFileSync(file, body);
+    const r = gh(['issue', 'create', '--title', TITLE, '--label', LABEL, '--body-file', file, '-R', repo]);
+    if (r.status !== 0) return { error: `gh issue create failed: ${(r.stderr || '').split('\n').find((l) => l.trim()) || 'exit ' + r.status}` };
+    const m = /\/issues\/(\d+)\s*$/.exec(r.stdout.trim());
+    return m ? { number: Number(m[1]) } : { error: 'gh issue create returned no issue url' };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// --- CLI ---------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const o = { repo: null, setLastAudit: null, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--dry-run') { o.dryRun = true; continue; }
+    if (flag !== '--repo' && flag !== '--set-last-audit') return { error: `usage: unknown argument: ${flag}` };
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const v = argv[i];
+    if (flag === '--repo') {
+      if (!/^[^/\s]+\/[^/\s]+$/.test(v)) return { error: `usage: --repo must be owner/name, got: ${v}` };
+      o.repo = v;
+    } else {
+      if (!ISO_RE.test(v)) return { error: `usage: --set-last-audit must be an ISO-8601 UTC time like 2026-10-14T09:30:00Z, got: ${v}` };
+      o.setLastAudit = v;
+    }
+  }
+  return o;
+}
+
+function defaultRepo(gh) {
+  const r = gh(['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner']);
+  const slug = r.status === 0 ? r.stdout.trim() : '';
+  return /^[^/\s]+\/[^/\s]+$/.test(slug) ? slug : null;
+}
+
+function main(argv, { gh, stdout, stderr, guard, tmpdir, firstEditDelta2 } = {}) {
+  const out = stdout || process.stdout;
+  const err = stderr || process.stderr;
+  const o = parseArgs(argv || []);
+  if (o.error) { err.write(o.error + '\n'); return 2; }
+  const run = gh || issueBody.defaultGh;
+  const g = guard === undefined ? loadGuard() : guard;
+  const abort = (reason) => { out.write(`aborted: ${reason}\n`); return 1; };
+
+  try {
+    const repo = o.repo || defaultRepo(run);
+    if (!repo) return abort('cannot resolve the repository (pass --repo owner/name)');
+    if (!o.dryRun) run(['label', 'create', LABEL, '--color', '5319E7', '--description', 'Pinned index of the trailhead surface', '-R', repo]); // idempotent, failure = already there
+    const snap = gatherSnapshot(run, repo);
+    const marker = o.setLastAudit ? `<!-- trailhead:last-audit ${o.setLastAudit} -->` : null;
+    const number = findDashboard(run, repo);
+
+    if (number === null) {
+      const body = renderDashboard({ ...snap, lastAudit: marker });
+      const problem = secretProblem(body, g);
+      if (problem) return abort(problem);
+      if (o.dryRun) {
+        out.write(`${summaryLine(null, snap)} (dry-run: would create and pin, body ${Buffer.byteLength(body)} bytes), nothing written\n`);
+        return 0;
+      }
+      const created = createDashboard(run, repo, body, tmpdir);
+      if (created.error) return abort(created.error);
+      const note = pin(run, repo, created.number);
+      out.write(`${summaryLine(created.number, snap)} (created${note ? ', ' + note : ' and pinned'}, body ${Buffer.byteLength(body)} bytes)\n`);
+      return 0;
+    }
+
+    const w = guardedWrite(number, (current) => {
+      const carried = marker || extractAudit(current);
+      return renderDashboard({ ...snap, lastAudit: carried });
+    }, { gh: run, repo, guard: g, dryRun: o.dryRun, tmpdir, firstEditDelta2 });
+    if (!w.ok) return abort(w.reason);
+    const sizes = `body ${w.oldSize} -> ${w.newSize} bytes`;
+    if (w.dryRun) {
+      out.write(`${summaryLine(number, snap)} (dry-run, ${sizes}), nothing written\n`);
+      return 0;
+    }
+    // The body is already written: a pin check or pin failure is reported next to
+    // that fact (exit 0), never as an abort that looks like nothing was written.
+    let note = w.historyFull ? issueBody.HISTORY_FULL_NOTE.replace(/^ \((.*)\)$/, ', $1') : '';
+    try {
+      if (!isPinned(run, repo, number)) {
+        const failed = pin(run, repo, number);
+        note += failed ? `, written, ${failed}` : ', re-pinned';
+      }
+    } catch (e) {
+      note += `, written, pin check failed: ${e && e.message ? e.message : String(e)}`;
+    }
+    out.write(`${summaryLine(number, snap)} (${sizes}${note})\n`);
+    return 0;
+  } catch (e) {
+    if (e instanceof GatherError) return abort(e.message);
+    return abort(`unexpected error: ${e && e.message ? e.message : String(e)}`);
+  }
+}
+
+module.exports = { renderDashboard, mapFlags, classify, gatherSnapshot, parseArgs, main };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}

package/plugins/trailhead/templates/trailhead-isolation-answer.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead isolation answer (self-contained, ships in templates/ so it reaches
+// every install channel: bin/trailhead.js copies templates/ wholesale for
+// Claude/npm and Codex). Remembers the answer to the work-start concurrency ask
+// under `isolation: auto` in <project root>/.trailhead/isolation-answer.json, so
+// later work-starts of the same working stretch reuse it. #245.
+//
+// CLI:
+//   node trailhead-isolation-answer.js check  [--repo <dir>] --others <csv|none|unavailable>
+//   node trailhead-isolation-answer.js record [--repo <dir>] --answer yes|no --others <csv|none>
+//   node trailhead-isolation-answer.js clear  [--repo <dir>]
+// --repo defaults to cwd. It is canonicalised to the project root: inside a
+// linked worktree it resolves to the main worktree (git common dir), so a call
+// from a trailhead/t<n> worktree reads the same record; on a git failure (or not
+// a git repo) the given dir is used as is.
+// File shape: { answer: "yes"|"no", others: [ticket numbers], recordedAt, usedAt }
+// `others` is the live-claims fingerprint (open issues assigned to @me minus the
+// current ticket), sorted and deduplicated; `none` is the empty set.
+// A session is a working stretch: it ends after 8 hours without a work-start
+// (sliding idle window; each reuse refreshes usedAt).
+// check prints:
+//   {"status":"reuse","answer","recordedAt","path"}   (only after usedAt was refreshed)
+//   {"status":"ask","reason":"absent|expired|claims-changed|invalid|unavailable","path"}
+// record prints {"status":"written","path","record"}; clear prints
+// {"status":"cleared|absent","path"}.
+// Exit 0 on every normal outcome and on any unexpected I/O error (status
+// skipped with a message, which the caller treats as ask); exit 2 only on a
+// usage error (nothing is written).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+const STATE_DIR = '.trailhead';
+const STATE_FILE = 'isolation-answer.json';
+const IDLE_WINDOW_MS = 8 * 60 * 60 * 1000;
+const ANSWERS = ['yes', 'no'];
+
+const isPosInt = (v) => Number.isInteger(v) && v > 0;
+
+// Sorted, deduplicated copy of a list of ticket numbers.
+const normalise = (list) => [...new Set(list)].sort((a, b) => a - b);
+
+// Strict parse of the --others value. Returns a sorted deduplicated array,
+// the string "unavailable" (when allowed), or null if invalid.
+function parseOthers(text, { allowUnavailable }) {
+  if (text === 'none') return [];
+  if (text === 'unavailable') return allowUnavailable ? 'unavailable' : null;
+  if (typeof text !== 'string' || !/^[1-9]\d*(,[1-9]\d*)*$/.test(text)) return null;
+  return normalise(text.split(',').map(Number));
+}
+
+// Strict ISO-8601 timestamp (as written by toISOString) -> epoch ms, or null.
+function parseTime(text) {
+  if (typeof text !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(text)) return null;
+  const ms = Date.parse(text);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+// Valid record or null (malformed or future timestamp, answer not yes/no,
+// others not an array of positive integers).
+function validateRecord(raw, nowMs) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (!ANSWERS.includes(raw.answer)) return null;
+  if (!Array.isArray(raw.others) || !raw.others.every(isPosInt)) return null;
+  const recordedAt = parseTime(raw.recordedAt);
+  const usedAt = parseTime(raw.usedAt);
+  if (recordedAt === null || usedAt === null) return null;
+  if (recordedAt > nowMs || usedAt > nowMs) return null;
+  return { answer: raw.answer, others: normalise(raw.others), recordedAt: raw.recordedAt, usedAt, usedAtText: raw.usedAt };
+}
+
+// Pure decision: reuse the record or ask again, and why.
+// record: parsed file content (null/undefined = absent); others: array or "unavailable".
+function decide(record, others, now) {
+  if (others === 'unavailable') return { status: 'ask', reason: 'unavailable' };
+  if (record === null || record === undefined) return { status: 'ask', reason: 'absent' };
+  const valid = validateRecord(record, now.getTime());
+  if (valid === null) return { status: 'ask', reason: 'invalid' };
+  if (now.getTime() - valid.usedAt > IDLE_WINDOW_MS) return { status: 'ask', reason: 'expired' };
+  const want = normalise(others);
+  const same = want.length === valid.others.length && want.every((n, i) => n === valid.others[i]);
+  if (!same) return { status: 'ask', reason: 'claims-changed' };
+  return { status: 'reuse', answer: valid.answer, recordedAt: valid.recordedAt };
+}
+
+function parseArgs(argv) {
+  const command = argv[0];
+  if (command !== 'check' && command !== 'record' && command !== 'clear') {
+    return { error: `usage: expected "check", "record" or "clear", got: ${command === undefined ? '(nothing)' : command}` };
+  }
+  const allowed = command === 'check' ? ['--repo', '--others']
+    : command === 'record' ? ['--repo', '--answer', '--others'] : ['--repo'];
+  let repo = null;
+  let answer;
+  let others;
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!allowed.includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const value = argv[i];
+    if (flag === '--repo') repo = value;
+    else if (flag === '--answer') {
+      if (!ANSWERS.includes(value)) return { error: `usage: --answer must be yes or no, got: ${value}` };
+      answer = value;
+    } else if (flag === '--others') {
+      others = parseOthers(value, { allowUnavailable: command === 'check' });
+      if (others === null) {
+        return { error: `usage: --others must be comma-separated positive integers, "none"${command === 'check' ? ' or "unavailable"' : ''}, got: ${value}` };
+      }
+    }
+  }
+  if (command === 'check' && others === undefined) return { error: 'usage: check needs --others' };
+  if (command === 'record' && answer === undefined) return { error: 'usage: record needs --answer' };
+  if (command === 'record' && others === undefined) return { error: 'usage: record needs --others' };
+  return { command, repo, answer, others };
+}
+
+// Project root: the main worktree when dir is inside a linked worktree, else
+// dir as given (also on any git failure or when not a git repo).
+function resolveProjectRoot(dir) {
+  try {
+    const common = execFileSync('git', ['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (common && path.basename(common) === '.git') return path.dirname(common);
+    return dir;
+  } catch {
+    return dir;
+  }
+}
+
+// Reads and parses the file; missing = null, corrupt = {} (invalid, never a crash).
+function readRecord(file, fsMod) {
+  let text;
+  try {
+    text = fsMod.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+
+// Atomic write: a unique temp in the same dir, then rename over the file
+// (never an in-place truncate); the temp is removed if anything fails.
+function writeAtomic(dir, file, text, fsMod) {
+  fsMod.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${STATE_FILE}.${process.pid}-${crypto.randomBytes(4).toString('hex')}.tmp`);
+  try {
+    fsMod.writeFileSync(tmp, text);
+    fsMod.renameSync(tmp, file);
+  } catch (err) {
+    try { fsMod.unlinkSync(tmp); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
+}
+
+function writeResult(stdout, result) {
+  stdout.write(JSON.stringify(result) + '\n');
+}
+
+function main(argv, { cwd, stdout, fs: fsMod, now } = {}) {
+  const cwd_ = cwd || process.cwd();
+  const out = stdout || process.stdout;
+  const fs_ = fsMod || fs;
+  const now_ = now || new Date();
+
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    process.stderr.write(parsed.error + '\n');
+    return 2;
+  }
+
+  const repoDir = parsed.repo ? path.resolve(cwd_, parsed.repo) : cwd_;
+  const root = resolveProjectRoot(repoDir);
+  const dir = path.join(root, STATE_DIR);
+  const file = path.join(dir, STATE_FILE);
+  try {
+    if (parsed.command === 'clear') {
+      if (!fs_.existsSync(file)) {
+        writeResult(out, { status: 'absent', path: file });
+        return 0;
+      }
+      fs_.unlinkSync(file);
+      writeResult(out, { status: 'cleared', path: file });
+      return 0;
+    }
+
+    if (parsed.command === 'record') {
+      const record = { answer: parsed.answer, others: parsed.others, recordedAt: now_.toISOString(), usedAt: now_.toISOString() };
+      writeAtomic(dir, file, JSON.stringify(record, null, 2) + '\n', fs_);
+      writeResult(out, { status: 'written', path: file, record });
+      return 0;
+    }
+
+    const raw = readRecord(file, fs_);
+    const decision = decide(raw, parsed.others, now_);
+    if (decision.status !== 'reuse') {
+      writeResult(out, { ...decision, path: file });
+      return 0;
+    }
+    // Slide the idle window first: reuse is only reported once it is persisted.
+    // No lock: a concurrent record landing between read and write is overwritten,
+    // which at worst leaves a stale fingerprint that re-asks, never a blind reuse.
+    const refreshed = { ...raw, usedAt: now_.toISOString() };
+    writeAtomic(dir, file, JSON.stringify(refreshed, null, 2) + '\n', fs_);
+    writeResult(out, { ...decision, path: file });
+    return 0;
+  } catch (err) {
+    writeResult(out, { status: 'skipped', path: file, message: 'error: ' + (err && err.message ? err.message : String(err)) });
+    return 0;
+  }
+}
+
+module.exports = { IDLE_WINDOW_MS, decide, parseOthers, parseArgs, resolveProjectRoot, main };
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout });
+  process.exit(code);
+}