@marcomigozzi/trailhead 0.14.0 → 0.16.0

package/plugins/trailhead/templates/trailhead-auto-merge.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead auto-merge helper (self-contained, ships in templates/ so it reaches every
+// install channel). Merges a verified slot branch of an autonomous run into the local
+// trunk (never a push), recovers an interrupted merge, and removes a merged slot. #286.
+//
+// CLI (every command runs against the MAIN checkout, which is on the trunk):
+//   node trailhead-auto-merge.js merge   --repo <main-checkout> --ticket <n> [--trunk <name>]
+//   node trailhead-auto-merge.js recover --repo <main-checkout>
+//   node trailhead-auto-merge.js remove  --repo <main-checkout> --ticket <n> [--trunk <name>]
+//
+// Trunk: --trunk, else the remote default branch (refs/remotes/origin/HEAD), else the
+// first existing of main / master (the base-preflight rule); none -> error.
+// Every git-state path (MERGE_HEAD, MERGE_MSG, rebase-merge, ...) is resolved with
+// `git rev-parse --git-path`, never assumed under .git/.
+//
+// merge: preconditions first, each a distinct status with nothing touched:
+//   not-on-trunk     HEAD of the main checkout is not refs/heads/<trunk>
+//   in-progress      a merge / rebase / cherry-pick is already under way (run recover)
+//   dirty            tracked changes in the main checkout (untracked files are fine)
+//   slot-dirty       the branch's slot worktree has uncommitted tracked work
+//   error            the branch does not exist, or the trunk cannot be resolved
+// Then: already-merged when the tip is an ancestor of the trunk (an idempotent retry);
+// otherwise `git merge --no-edit -m "chore(auto): merge trailhead/t<n>" -m "Refs: #<n>"`
+// (fast-forward when possible, else a merge commit). The main checkout's
+// .trailhead/session-ticket (never written or rewritten here) does not block a merge: a
+// fast-forward creates no commit, so the commit-msg hook never runs; a true merge commit
+// adds --no-verify only when the marker names a ticket other than the merged one (the
+// hook would demand that ticket's Refs trailer, and the helper already builds the whole
+// message). No marker, or the same ticket: the hook stays active.
+//   merged         method ff|merge, from (trunk before), head (trunk after)
+//   conflict       conflicting paths in `conflicts`; the merge is aborted
+//   merge-failed   any other failure (hook refusal, untracked file in the way); aborted
+// An abort that does not leave HEAD at its pre-merge commit with a clean tracked tree
+// falls back to `git reset --merge <pre>` (safe: the preconditions guarantee a clean
+// tracked tree); only when that fails too is the result error "main left mid-merge",
+// the one case the caller must stop on. Never --force, never reset --hard.
+// On merged / already-merged, `behind` lists every OTHER trailhead/t* worktree slot with
+// trunk commits not in its branch ({ticket, path, behind}), informational.
+//
+// recover: no merge under way -> clean; a merge whose MERGE_MSG first line is
+// "chore(auto): merge trailhead/t<n>" -> aborted (same abort / fallback), with `ticket`;
+// anything else (a human's merge, a rebase, a cherry-pick) -> foreign, untouched.
+//
+// remove: only for a branch already merged into the trunk (else not-merged). A worktree
+// slot is removed with `git worktree remove` (no --force: a dirty one is an error and
+// stays) and the branch deleted with `git branch -d`; a clone slot is never deleted
+// (kept). Idempotent: a worktree already gone or a branch already deleted is skipped.
+// removed carries worktreeRemoved / branchDeleted (what THIS call did).
+//
+// One orchestrator runs merges one at a time. Two autonomous runs on the same main
+// checkout are not supported (no lock file); the in-progress precondition keeps this
+// helper from touching a merge it did not start.
+//
+// Prints exactly one JSON line on stdout: {"status":"...", ...}. Exit 0 whenever the
+// status is a result (parked statuses included), 1 on status error, 2 on a usage error.
+
+const { spawnSync } = require('child_process');
+const nodeFs = require('fs');
+const path = require('path');
+
+function defaultGit(args) {
+  const env = { ...process.env, GIT_EDITOR: 'true', GIT_TERMINAL_PROMPT: '0' };
+  const r = spawnSync('git', args, { encoding: 'utf8', env, maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
+}
+
+const firstLine = (s) => String(s || '').split('\n').find((l) => l.trim()) || '';
+const branchOf = (n) => `trailhead/t${n}`;
+const BRANCH_RE = /^refs\/heads\/trailhead\/t(\d+)$/;
+const MERGE_SUBJECT = /^chore\(auto\): merge trailhead\/t(\d+)$/;
+const IN_PROGRESS = ['MERGE_HEAD', 'rebase-merge', 'rebase-apply', 'CHERRY_PICK_HEAD'];
+
+// --- args ---------------------------------------------------------------------
+
+const FLAGS = { merge: ['--repo', '--ticket', '--trunk'], recover: ['--repo'], remove: ['--repo', '--ticket', '--trunk'] };
+
+function parseArgs(argv) {
+  const cmd = argv[0];
+  if (!Object.prototype.hasOwnProperty.call(FLAGS, cmd)) return { error: `usage: expected merge, recover or remove, got: ${cmd === undefined ? '(nothing)' : cmd}` };
+  const o = { cmd, repo: null, ticket: null, trunk: null };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!FLAGS[cmd].includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const v = argv[i];
+    if (flag === '--ticket') {
+      if (!/^[1-9]\d*$/.test(v)) return { error: `usage: --ticket must be a positive integer, got: ${v}` };
+      o.ticket = Number(v);
+    } else if (!v.trim()) {
+      return { error: `usage: ${flag} requires a non-empty value` };
+    } else if (flag === '--repo') {
+      o.repo = v;
+    } else {
+      o.trunk = v;
+    }
+  }
+  if (!o.repo) return { error: `usage: ${cmd} requires --repo` };
+  if (cmd !== 'recover' && !o.ticket) return { error: `usage: ${cmd} requires --ticket` };
+  return o;
+}
+
+// --- git helpers --------------------------------------------------------------
+
+// [{ path, branch|null }] from `git worktree list --porcelain`, main checkout first.
+function parseWorktrees(text) {
+  const out = [];
+  for (const block of String(text).split(/\n\s*\n/)) {
+    let wt = null;
+    let branch = null;
+    for (const line of block.split('\n')) {
+      if (line.startsWith('worktree ')) wt = line.slice('worktree '.length);
+      else if (line.startsWith('branch ')) branch = line.slice('branch '.length);
+    }
+    if (wt) out.push({ path: wt, branch });
+  }
+  return out;
+}
+
+const realOr = (fs, p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+// Absolute path of a git-state file of the main checkout (via --git-path).
+function statePath(ctx, name) {
+  const r = ctx.G(['rev-parse', '--git-path', name]);
+  return r.status === 0 && r.stdout.trim() ? path.resolve(ctx.main, r.stdout.trim()) : null;
+}
+
+const stateExists = (ctx, name) => { const p = statePath(ctx, name); return p !== null && ctx.fs.existsSync(p); };
+const inProgress = (ctx) => IN_PROGRESS.filter((n) => stateExists(ctx, n));
+const head = (ctx) => ctx.G(['rev-parse', 'HEAD']).stdout.trim();
+const trackedDirty = (ctx, dir) => ctx.git(['-C', dir || ctx.main, 'status', '--porcelain', '--untracked-files=no']).stdout.trim() !== '';
+const hasRef = (ctx, ref) => ctx.G(['rev-parse', '--verify', '--quiet', ref]).status === 0;
+const isAncestor = (ctx, a, b) => ctx.G(['merge-base', '--is-ancestor', a, b]).status === 0;
+
+// Trunk name per the base-preflight rule, or null.
+function detectTrunk(ctx, requested) {
+  if (requested) return requested;
+  const h = ctx.G(['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD']);
+  if (h.status === 0 && h.stdout.trim().startsWith('origin/')) return h.stdout.trim().slice('origin/'.length);
+  for (const name of ['main', 'master']) {
+    if (hasRef(ctx, `refs/heads/${name}`) || hasRef(ctx, `refs/remotes/origin/${name}`)) return name;
+  }
+  return null;
+}
+
+// The main checkout's state is exactly the pre-merge one: HEAD at pre, no merge, clean tracked tree.
+const settled = (ctx, pre) => head(ctx) === pre && !stateExists(ctx, 'MERGE_HEAD') && !trackedDirty(ctx);
+
+// Puts the main checkout back at `pre`. Abort first, reset --merge as the fallback.
+function undoMerge(ctx, pre) {
+  if (stateExists(ctx, 'MERGE_HEAD')) ctx.G(['merge', '--abort']);
+  if (settled(ctx, pre)) return true;
+  ctx.G(['reset', '--merge', pre]);
+  return settled(ctx, pre);
+}
+
+const stuck = (ctx, fail) => fail('main left mid-merge: the merge could not be aborted; resolve or abort it by hand in ' + ctx.main);
+
+// Slot worktrees other than `ticket`, with trunk commits their branch lacks.
+function behindList(ctx, trunk, ticket) {
+  const wl = ctx.G(['worktree', 'list', '--porcelain']);
+  if (wl.status !== 0) return [];
+  const out = [];
+  for (const w of parseWorktrees(wl.stdout)) {
+    const m = w.branch && BRANCH_RE.exec(w.branch);
+    if (!m || Number(m[1]) === ticket || realOr(ctx.fs, w.path) === ctx.main || !ctx.fs.existsSync(w.path)) continue;
+    const c = ctx.G(['rev-list', '--count', `${branchOf(m[1])}..refs/heads/${trunk}`]);
+    const n = Number(c.stdout.trim());
+    if (c.status === 0 && Number.isInteger(n) && n > 0) out.push({ ticket: Number(m[1]), path: w.path, behind: n });
+  }
+  return out.sort((a, b) => a.ticket - b.ticket);
+}
+
+// The marker's ticket number, or null (absent, unreadable or unparseable: the hook ignores it too).
+function markerTicket(ctx) {
+  try {
+    const raw = String(ctx.fs.readFileSync(path.join(ctx.main, '.trailhead', 'session-ticket'), 'utf8')).replace(/^\uFEFF/, '');
+    const m = raw.split('\n')[0].replace(/\r$/, '').match(/^#([1-9]\d*)(?:\s|$)/);
+    return m ? Number(m[1]) : null;
+  } catch { return null; }
+}
+
+// --- merge --------------------------------------------------------------------
+
+function mergeBranch(ctx, o) {
+  const { fail, emit } = ctx;
+  const branch = branchOf(o.ticket);
+  const ref = `refs/heads/${branch}`;
+  const trunk = detectTrunk(ctx, o.trunk);
+  if (!trunk) return fail('no trunk found (no remote default branch, main or master); pass --trunk');
+  if (!hasRef(ctx, `refs/heads/${trunk}`)) return fail(`trunk ${trunk} has no local branch`);
+  const result = (status, extra) => { emit({ status, ticket: o.ticket, branch, trunk, ...extra }); return 0; };
+
+  const sym = ctx.G(['symbolic-ref', '-q', 'HEAD']);
+  if (sym.stdout.trim() !== `refs/heads/${trunk}`) return result('not-on-trunk', { reason: `the main checkout is on ${sym.stdout.trim() || 'a detached HEAD'}, not ${trunk}` });
+  const busy = inProgress(ctx);
+  if (busy.length) return result('in-progress', { reason: `${busy.join(', ')} present in the main checkout; run recover first` });
+  if (trackedDirty(ctx)) return result('dirty', { reason: 'tracked changes in the main checkout' });
+  if (!hasRef(ctx, ref)) return fail(`branch ${branch} does not exist`);
+
+  const wl = ctx.G(['worktree', 'list', '--porcelain']);
+  const slot = wl.status === 0 ? parseWorktrees(wl.stdout).find((w) => w.branch === ref && realOr(ctx.fs, w.path) !== ctx.main) : null;
+  if (slot && ctx.fs.existsSync(slot.path) && trackedDirty(ctx, slot.path)) return result('slot-dirty', { path: slot.path, reason: `uncommitted tracked work in ${slot.path} would be left out of the merge` });
+
+  if (isAncestor(ctx, ref, `refs/heads/${trunk}`)) return result('already-merged', { head: head(ctx), behind: behindList(ctx, trunk, o.ticket) });
+
+  const pre = head(ctx);
+  // marker di un altro ticket: l'hook commit-msg rifiuterebbe il merge commit, lo saltiamo
+  const marker = markerTicket(ctx);
+  const skipHook = marker !== null && marker !== o.ticket;
+  const m = ctx.G(['merge', '--no-edit', ...(skipHook ? ['--no-verify'] : []), '-m', `chore(auto): merge ${branch}`, '-m', `Refs: #${o.ticket}`, branch]);
+  if (m.status === 0) {
+    if (!isAncestor(ctx, ref, 'HEAD')) return fail(`git merge reported success but ${branch} is not in the trunk`);
+    const method = ctx.G(['rev-parse', '--verify', '--quiet', 'HEAD^2']).status === 0 ? 'merge' : 'ff';
+    return result('merged', { method, from: pre, head: head(ctx), behind: behindList(ctx, trunk, o.ticket) });
+  }
+
+  const conflicts = ctx.G(['diff', '--name-only', '--diff-filter=U']).stdout.split('\n').filter(Boolean);
+  const reason = firstLine(m.stderr) || firstLine(m.stdout) || `git merge exited ${m.status}`;
+  if (!undoMerge(ctx, pre)) return stuck(ctx, fail);
+  if (conflicts.length > 0) return result('conflict', { conflicts });
+  return result('merge-failed', { reason });
+}
+
+// --- recover ------------------------------------------------------------------
+
+function recoverMerge(ctx) {
+  const { fail, emit } = ctx;
+  const busy = inProgress(ctx);
+  if (!busy.length) { emit({ status: 'clean' }); return 0; }
+  if (!busy.includes('MERGE_HEAD')) { emit({ status: 'foreign', reason: `${busy.join(', ')} in progress, not started by a run` }); return 0; }
+  let msg = '';
+  try { msg = String(ctx.fs.readFileSync(statePath(ctx, 'MERGE_MSG'), 'utf8')); } catch { /* unreadable: foreign */ }
+  const m = MERGE_SUBJECT.exec(firstLine(msg).trim());
+  if (!m) { emit({ status: 'foreign', reason: 'a merge not started by a run is in progress' }); return 0; }
+  if (!undoMerge(ctx, head(ctx))) return stuck(ctx, fail);
+  emit({ status: 'aborted', ticket: Number(m[1]), branch: branchOf(m[1]) });
+  return 0;
+}
+
+// --- remove -------------------------------------------------------------------
+
+// True when dir is an independent checkout (its git dir lives inside it) on `branch`.
+function cloneOnBranch(ctx, dir, branch) {
+  const g = ctx.git(['-C', dir, 'rev-parse', '--absolute-git-dir']);
+  if (g.status !== 0) return false;
+  const gitDir = realOr(ctx.fs, g.stdout.trim());
+  const root = realOr(ctx.fs, dir);
+  if (gitDir !== root && !gitDir.startsWith(root + path.sep)) return false;
+  const b = ctx.git(['-C', dir, 'symbolic-ref', '--quiet', 'HEAD']);
+  return b.status === 0 && b.stdout.trim() === `refs/heads/${branch}`;
+}
+
+function removeSlot(ctx, o) {
+  const { fail, emit } = ctx;
+  const branch = branchOf(o.ticket);
+  const ref = `refs/heads/${branch}`;
+  const trunk = detectTrunk(ctx, o.trunk);
+  if (!trunk) return fail('no trunk found (no remote default branch, main or master); pass --trunk');
+  if (!hasRef(ctx, `refs/heads/${trunk}`)) return fail(`trunk ${trunk} has no local branch`);
+
+  const wl = ctx.G(['worktree', 'list', '--porcelain']);
+  if (wl.status !== 0) return fail(`git worktree list failed: ${firstLine(wl.stderr) || 'exit ' + wl.status}`);
+  const slot = parseWorktrees(wl.stdout).find((w) => w.branch === ref && realOr(ctx.fs, w.path) !== ctx.main);
+
+  if (!slot) {
+    const sibling = path.join(path.dirname(ctx.main), `${path.basename(ctx.main)}-t${o.ticket}`);
+    if (ctx.fs.existsSync(sibling) && cloneOnBranch(ctx, sibling, branch)) { emit({ status: 'kept', ticket: o.ticket, kind: 'clone', path: sibling, reason: 'a clone slot is never deleted' }); return 0; }
+  }
+
+  const branchExists = hasRef(ctx, ref);
+  if (branchExists && !isAncestor(ctx, ref, `refs/heads/${trunk}`)) {
+    emit({ status: 'not-merged', ticket: o.ticket, branch, reason: `${branch} is not merged into ${trunk}; nothing removed` });
+    return 0;
+  }
+
+  let worktreeRemoved = false;
+  if (slot && ctx.fs.existsSync(slot.path)) {
+    const rm = ctx.G(['worktree', 'remove', slot.path]);
+    if (rm.status !== 0) return fail(`git worktree remove failed for ${slot.path}, kept: ${firstLine(rm.stderr) || 'exit ' + rm.status}`);
+    worktreeRemoved = true;
+  } else if (slot) {
+    return fail(`stale worktree of ${branch}: ${slot.path} is gone from disk but git still lists it; run git worktree prune and retry`);
+  }
+
+  let branchDeleted = false;
+  if (branchExists) {
+    const d = ctx.G(['branch', '-d', branch]);
+    if (d.status !== 0) return fail(`git branch -d ${branch} failed: ${firstLine(d.stderr) || 'exit ' + d.status}`);
+    branchDeleted = true;
+  }
+  emit({ status: 'removed', ticket: o.ticket, branch, worktreeRemoved, branchDeleted });
+  return 0;
+}
+
+function main(argv, { git, stdout, stderr, fs } = {}) {
+  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 fsx = fs || nodeFs;
+  const emit = (obj) => out.write(JSON.stringify(obj) + '\n');
+  const fail = (reason, extra) => { emit({ status: 'error', reason, ...extra }); return 1; };
+  const run = git || defaultGit;
+  const mainDir = realOr(fsx, o.repo);
+  const ctx = { git: run, G: (args) => run(['-C', mainDir, ...args]), fs: fsx, main: mainDir, fail, emit };
+  if (ctx.G(['rev-parse', '--git-dir']).status !== 0) return fail(`${o.repo} is not a git repository`);
+  if (o.cmd === 'merge') return mergeBranch(ctx, o);
+  if (o.cmd === 'recover') return recoverMerge(ctx);
+  return removeSlot(ctx, o);
+}
+
+module.exports = { main, parseArgs, parseWorktrees };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}

package/plugins/trailhead/templates/trailhead-auto-queue.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead auto queue (self-contained, ships in templates/ so it reaches every
+// install channel). Builds the ordered work queue of an autonomous run for a chosen
+// run scope: one map, the whiteboard, or everything. #280.
+//
+// CLI:
+//   node trailhead-auto-queue.js scopes [--repo <owner/name>]
+//   node trailhead-auto-queue.js queue --scope map:<n>|whiteboard|everything
+//        [--skip <csv>] [--repo <owner/name>]
+//
+// The frontier is the canonical frontier query (substrate-commands.md): open,
+// `trailhead:ticket`, unassigned, not blocked / unverified / paused. The
+// `trailhead:blocked` label is the source of truth for blockers; this helper adds
+// no dependency logic. The run's own read also skips `trailhead:needs-you` (a ticket
+// a run parked for the human); the human frontier does not. Groups are ordered by
+// map number ascending, the whiteboard last; tickets inside a group ascending by
+// number. `--skip` names the tickets the
+// run already marked needs-you or stopped on; `next` is the lowest ticket of the first
+// group that still has one (null when the scope is drained). A read that hits the
+// 1000 limit fails closed (never a partial queue).
+//
+// Prints exactly one JSON line on stdout:
+//   scopes: {"status":"ok","maps":[{"number","title","frontier"}],"whiteboard":{"frontier"}}
+//   queue:  {"status":"ok","scope","groups":[{"kind","map","title","tickets":[{"number","title","type"}],"resume":[...]}],"drift":[...],"next":{...}|null}
+//   error:  {"status":"error","reason":"..."}
+// Exit 0 on ok, 1 on an error, 2 on a usage error (stderr).
+
+const { spawnSync } = require('child_process');
+
+const LIMIT = 1000;
+const FRONTIER_SEARCH = 'no:assignee -label:trailhead:blocked -label:trailhead:unverified -label:trailhead:paused';
+const NEEDS_YOU = 'trailhead:needs-you';
+// The run's own frontier read: the canonical frontier minus the tickets a run parked
+// for the human. Humans still see those on the frontier (FRONTIER_SEARCH is unchanged).
+const RUN_SEARCH = FRONTIER_SEARCH + ' -label:' + NEEDS_YOU;
+const WHITEBOARD = 'trailhead:whiteboard';
+const MAP_LABEL_RE = /^trailhead:map-(\d+)$/;
+const TYPES = ['decision', 'research', 'prototype', 'build', 'bug', 'task'];
+
+function defaultGh(args) {
+  const r = spawnSync('gh', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
+}
+
+const firstLine = (s) => String(s || '').split('\n').find((l) => l.trim()) || '';
+const names = (labels) => (labels || []).map((l) => (typeof l === 'string' ? l : l.name));
+const byNumber = (a, b) => a.number - b.number;
+
+function parseScope(v) {
+  if (v === 'everything' || v === 'whiteboard') return v;
+  return /^map:[1-9]\d*$/.test(String(v)) ? v : null;
+}
+
+function parseArgs(argv) {
+  const cmd = argv[0];
+  if (cmd !== 'scopes' && cmd !== 'queue') return { error: `usage: expected scopes or queue, got: ${cmd === undefined ? '(nothing)' : cmd}` };
+  const o = { cmd, repo: null, scope: null, skip: [] };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    const allowed = cmd === 'queue' ? ['--repo', '--scope', '--skip'] : ['--repo'];
+    if (!allowed.includes(flag)) 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 (flag === '--scope') {
+      o.scope = parseScope(v);
+      if (!o.scope) return { error: `usage: --scope must be map:<n>, whiteboard or everything, got: ${v}` };
+    } else {
+      const parts = v.split(',').map((s) => s.trim()).filter(Boolean);
+      if (!parts.every((s) => /^[1-9]\d*$/.test(s))) return { error: `usage: --skip must be a csv of ticket numbers, got: ${v}` };
+      o.skip = parts.map(Number);
+    }
+  }
+  if (cmd === 'queue' && !o.scope) return { error: 'usage: queue requires --scope' };
+  return o;
+}
+
+const typeOf = (labelNames) => {
+  const t = TYPES.find((x) => labelNames.includes(`trailhead:${x}`));
+  return t || null;
+};
+
+// Places each ticket: on its open map, else the whiteboard, else nowhere. A ticket
+// on more than one open map is drift (placed on none).
+function place(openMaps, issues) {
+  const open = new Set(openMaps.map((m) => m.number));
+  const byMap = new Map(openMaps.map((m) => [m.number, []]));
+  const whiteboard = [];
+  const drift = [];
+  for (const i of issues) {
+    const ln = names(i.labels);
+    const mapNums = ln.map((l) => (MAP_LABEL_RE.exec(l) || [])[1]).filter(Boolean).map(Number).filter((n) => open.has(n));
+    const row = { number: i.number, title: i.title, type: typeOf(ln) };
+    if (mapNums.length > 1) drift.push({ ...row, maps: [...new Set(mapNums)].sort((a, b) => a - b), whiteboard: ln.includes(WHITEBOARD) });
+    else if (mapNums.length === 1) byMap.get(mapNums[0]).push(row);
+    else if (ln.includes(WHITEBOARD)) whiteboard.push(row);
+  }
+  return { byMap, whiteboard, drift };
+}
+
+// Pure: openMaps [{number,title}], frontier / paused issues [{number,title,labels}],
+// scope, skip [n]. Returns { groups, drift, next } or { error }.
+function buildQueue(openMaps, frontier, paused, scope, skip) {
+  const skipSet = new Set(skip || []);
+  // A needs-you ticket is dropped even when the search index lagged and returned it.
+  const live = (list) => list.filter((i) => !skipSet.has(i.number) && !names(i.labels).includes(NEEDS_YOU));
+  const maps = [...openMaps].sort(byNumber);
+  let wantMaps = maps;
+  let wantWhiteboard = scope === 'whiteboard' || scope === 'everything';
+  if (scope === 'whiteboard') wantMaps = [];
+  else if (scope.startsWith('map:')) {
+    const n = Number(scope.slice(4));
+    wantMaps = maps.filter((m) => m.number === n);
+    if (!wantMaps.length) return { error: `map #${n} is not an open trailhead:map` };
+    wantWhiteboard = false;
+  }
+  const f = place(maps, live(frontier));
+  const p = place(maps, live(paused));
+  const sorted = (rows) => [...rows].sort(byNumber);
+  const groups = wantMaps.map((m) => ({ kind: 'map', map: m.number, title: m.title, tickets: sorted(f.byMap.get(m.number)), resume: sorted(p.byMap.get(m.number)) }));
+  if (wantWhiteboard) groups.push({ kind: 'whiteboard', map: null, title: 'Whiteboard', tickets: sorted(f.whiteboard), resume: sorted(p.whiteboard) });
+  const inScope = (d) => (scope === 'everything'
+    || (scope === 'whiteboard' && d.whiteboard)
+    || (scope.startsWith('map:') && d.maps.includes(Number(scope.slice(4)))));
+  const seen = new Set();
+  const drift = [...f.drift, ...p.drift].filter(inScope).filter((d) => !seen.has(d.number) && seen.add(d.number)).sort(byNumber)
+    .map(({ number, title, type, maps: ms }) => ({ number, title, type, maps: ms }));
+  const first = groups.find((g) => g.tickets.length);
+  const next = first ? { ...first.tickets[0], map: first.map } : null;
+  return { groups, drift, next };
+}
+
+function readList(run, args, what) {
+  const r = run(args);
+  if (r.status !== 0) return { error: `gh issue list (${what}) failed: ${firstLine(r.stderr) || 'exit ' + r.status}` };
+  let rows;
+  try { rows = JSON.parse(r.stdout); } catch { return { error: `gh issue list (${what}) returned unparseable JSON` }; }
+  if (!Array.isArray(rows)) return { error: `gh issue list (${what}) returned unexpected JSON` };
+  if (rows.length >= LIMIT) return { error: `incomplete list: the ${what} read hit the ${LIMIT} limit` };
+  return { rows };
+}
+
+function main(argv, { gh, stdout, stderr } = {}) {
+  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 || defaultGh;
+  const emit = (obj) => out.write(JSON.stringify(obj) + '\n');
+  const fail = (reason) => { emit({ status: 'error', reason }); return 1; };
+  const R = o.repo ? ['-R', o.repo] : [];
+  const lim = ['--limit', String(LIMIT)];
+
+  const maps = readList(run, ['issue', 'list', '--label', 'trailhead:map', '--state', 'open', ...lim, '--json', 'number,title', ...R], 'open maps');
+  if (maps.error) return fail(maps.error);
+  const frontier = readList(run, ['issue', 'list', '--label', 'trailhead:ticket', '--state', 'open', '--search', RUN_SEARCH, ...lim, '--json', 'number,title,labels', ...R], 'frontier');
+  if (frontier.error) return fail(frontier.error);
+
+  if (o.cmd === 'scopes') {
+    const q = buildQueue(maps.rows, frontier.rows, [], 'everything', []);
+    const wb = q.groups.find((g) => g.kind === 'whiteboard');
+    emit({
+      status: 'ok',
+      maps: q.groups.filter((g) => g.kind === 'map').map((g) => ({ number: g.map, title: g.title, frontier: g.tickets.length })),
+      whiteboard: { frontier: wb.tickets.length },
+    });
+    return 0;
+  }
+
+  const paused = readList(run, ['issue', 'list', '--label', 'trailhead:ticket', '--label', 'trailhead:paused', '--assignee', '@me', '--state', 'open', ...lim, '--json', 'number,title,labels', ...R], 'paused claims');
+  if (paused.error) return fail(paused.error);
+  const q = buildQueue(maps.rows, frontier.rows, paused.rows, o.scope, o.skip);
+  if (q.error) return fail(q.error);
+  emit({ status: 'ok', scope: o.scope, groups: q.groups, drift: q.drift, next: q.next });
+  return 0;
+}
+
+module.exports = { main, parseArgs, buildQueue, FRONTIER_SEARCH, RUN_SEARCH, NEEDS_YOU };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}