@marcomigozzi/trailhead 0.12.1 → 0.14.0

package/plugins/trailhead/hooks/lib/work-state.test.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-work-state.js. Run: node work-state.test.js
+// No framework: plain asserts, same style as commit-msg-sync.test.js.
+//
+// Layers covered:
+//   1. Pure mergeState() / sanitizeState().
+//   2. main() with injected cwd/env/stdout against mkdtemp folders.
+//   3. Fault injection: an fs whose write or rename throws.
+//   4. End-to-end: execFileSync of the script itself.
+const assert = require('assert');
+const { execFileSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-work-state.js');
+const { mergeState, sanitizeState, parseArgs, main } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+function mktmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-work-state-test-'));
+}
+
+// Runs main() capturing stdout and stderr; returns { code, lines, err }.
+function run(argv, { cwd, env = {}, fsMod } = {}) {
+  const chunks = [];
+  const errChunks = [];
+  const realErr = process.stderr.write.bind(process.stderr);
+  process.stderr.write = (s) => { errChunks.push(String(s)); return true; };
+  let code;
+  try {
+    code = main(argv, { cwd, env, stdout: { write: (s) => chunks.push(s) }, ...(fsMod ? { fs: fsMod } : {}) });
+  } finally {
+    process.stderr.write = realErr;
+  }
+  const lines = chunks.join('').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  return { code, lines, err: errChunks.join('') };
+}
+
+const statePath = (dir) => path.join(dir, '.trailhead', 'work-state.json');
+const readState = (dir) => JSON.parse(fs.readFileSync(statePath(dir), 'utf8'));
+const trailheadFiles = (dir) => fs.existsSync(path.join(dir, '.trailhead')) ? fs.readdirSync(path.join(dir, '.trailhead')) : [];
+
+// --- fresh set ---------------------------------------------------------------
+{
+  const dir = mktmp();
+  const r = run(['set', '--repo', dir, '--map', '12', '--ticket', '205', '--title', 'Write it', '--step', 'discuss'],
+    { cwd: '/', env: { CLAUDE_CODE_SESSION_ID: 'sess-1' } });
+  const s = readState(dir);
+  ok('fresh set: exit 0', r.code === 0);
+  ok('fresh set: one JSON line, status written', r.lines.length === 1 && r.lines[0].status === 'written');
+  ok('fresh set: output carries path and state', r.lines[0].path === statePath(dir) && r.lines[0].state.ticket === 205);
+  ok('fresh set: exact key set',
+    JSON.stringify(Object.keys(s)) === JSON.stringify(['map', 'ticket', 'title', 'step', 'auto', 'autoDone', 'session', 'updatedAt']));
+  ok('fresh set: values', s.map === 12 && s.ticket === 205 && s.title === 'Write it' && s.step === 'discuss' && s.auto === false);
+  ok('fresh set: session from env', s.session === 'sess-1');
+  ok('fresh set: updatedAt is ISO-8601', new Date(s.updatedAt).toISOString() === s.updatedAt);
+  ok('fresh set: no temp file left', JSON.stringify(trailheadFiles(dir)) === JSON.stringify(['work-state.json']));
+}
+
+// --- --repo default is cwd ---------------------------------------------------
+{
+  const dir = mktmp();
+  run(['set', '--ticket', '1', '--step', 'plan'], { cwd: dir });
+  ok('repo defaults to cwd', readState(dir).ticket === 1);
+}
+
+// --- session absent / empty --------------------------------------------------
+{
+  const dir = mktmp();
+  run(['set', '--ticket', '1', '--step', 'plan'], { cwd: dir, env: {} });
+  ok('session absent -> null', readState(dir).session === null);
+  const dir2 = mktmp();
+  run(['set', '--ticket', '1', '--step', 'plan'], { cwd: dir2, env: { CLAUDE_CODE_SESSION_ID: '' } });
+  ok('session empty -> null', readState(dir2).session === null);
+}
+
+// --- merge on step change ----------------------------------------------------
+{
+  const dir = mktmp();
+  run(['set', '--map', '12', '--ticket', '205', '--title', 'T', '--step', 'discuss'], { cwd: dir });
+  const before = readState(dir);
+  const r = run(['set', '--step', 'plan'], { cwd: dir });
+  const s = readState(dir);
+  ok('merge: step-only set exits 0', r.code === 0);
+  ok('merge: step updated, rest kept', s.step === 'plan' && s.map === 12 && s.ticket === 205 && s.title === 'T');
+  ok('merge: updatedAt not older', s.updatedAt >= before.updatedAt);
+  const r2 = run(['set', '--auto', 'true'], { cwd: dir });
+  ok('merge: auto-only set allowed on a complete file', r2.code === 0 && readState(dir).auto === true && readState(dir).step === 'plan');
+  run(['set', '--auto', 'false'], { cwd: dir });
+  ok('merge: auto back to false', readState(dir).auto === false);
+  run(['set', '--ticket', '205', '--step', 'execute'], { cwd: dir });
+  ok('merge: same ticket keeps title and map', readState(dir).title === 'T' && readState(dir).map === 12);
+}
+
+// --- new ticket resets -------------------------------------------------------
+{
+  const dir = mktmp();
+  run(['set', '--map', '12', '--ticket', '205', '--title', 'Old', '--step', 'verify', '--auto', 'true'], { cwd: dir });
+  run(['set', '--ticket', '300', '--step', 'discuss'], { cwd: dir });
+  const s = readState(dir);
+  ok('new ticket: no carry-over of title/map/auto', s.ticket === 300 && s.title === null && s.map === null && s.auto === false);
+}
+
+// --- none map ----------------------------------------------------------------
+{
+  const dir = mktmp();
+  run(['set', '--map', 'none', '--ticket', '7', '--title', 'W', '--step', 'discuss'], { cwd: dir });
+  ok('map none -> null', readState(dir).map === null);
+}
+
+// --- validation failures: exit 2, nothing written ----------------------------
+for (const argv of [
+  ['set', '--ticket', '0', '--step', 'plan'],
+  ['set', '--ticket', 'abc', '--step', 'plan'],
+  ['set', '--ticket', '1', '--step', 'nope'],
+  ['set', '--ticket', '1', '--step', 'plan', '--map', '-3'],
+  ['set', '--ticket', '1', '--step', 'plan', '--map', 'x'],
+  ['set', '--ticket', '1', '--step', 'plan', '--auto', 'maybe'],
+  ['set', '--ticket', '1', '--step', 'plan', '--auto-done', '-1'],
+  ['set', '--ticket', '1', '--step', 'plan', '--auto-done', '01'],
+  ['set', '--ticket', '1', '--step', 'plan', '--auto-done', '1.5'],
+  ['set', '--ticket', '1', '--step', 'plan', '--auto-done', 'x'],
+  ['set', '--ticket', '1', '--step', 'plan', '--bogus', 'x'],
+  ['set', '--ticket', '1', '--step'],
+  ['set', '--ticket', '1'],
+  ['set', '--step', 'plan'],
+  ['frobnicate'],
+  [],
+]) {
+  const dir = mktmp();
+  const r = run([...argv.slice(0, 1), '--repo', dir, ...argv.slice(1)], { cwd: dir });
+  ok(`usage error exit 2: ${argv.join(' ')}`, r.code === 2);
+  ok(`usage error writes stderr: ${argv.join(' ')}`, r.err.length > 0);
+  ok(`usage error writes nothing: ${argv.join(' ')}`, !fs.existsSync(path.join(dir, '.trailhead')));
+}
+
+// --- title sanitising --------------------------------------------------------
+{
+  const dir = mktmp();
+  run(['set', '--ticket', '1', '--step', 'plan', '--title', '  a\nb\tc\u0000d  '], { cwd: dir });
+  ok('title: control chars collapsed to spaces and trimmed', readState(dir).title === 'a b c d');
+  run(['set', '--ticket', '2', '--step', 'plan', '--title', 'x'.repeat(500)], { cwd: dir });
+  ok('title: capped at 200', readState(dir).title.length === 200);
+}
+
+// --- autoDone ----------------------------------------------------------------
+{
+  const dir = mktmp();
+  run(['set', '--ticket', '1', '--step', 'plan'], { cwd: dir });
+  ok('autoDone: defaults to 0', readState(dir).autoDone === 0);
+  ok('autoDone: parseArgs strict integer', parseArgs(['set', '--auto-done', '0']).patch.autoDone === 0
+    && parseArgs(['set', '--auto-done', '12']).patch.autoDone === 12);
+  run(['set', '--auto', 'true', '--auto-done', '3'], { cwd: dir });
+  ok('autoDone: set with auto true', readState(dir).auto === true && readState(dir).autoDone === 3);
+  run(['set', '--step', 'execute'], { cwd: dir });
+  ok('autoDone: kept by a merge', readState(dir).autoDone === 3 && readState(dir).auto === true);
+  run(['set', '--auto', 'false'], { cwd: dir });
+  ok('autoDone: reset to 0 when auto goes false', readState(dir).autoDone === 0);
+  run(['set', '--auto-done', '5'], { cwd: dir });
+  ok('autoDone: ignored (0) while auto is false', readState(dir).autoDone === 0);
+  run(['set', '--auto', 'true', '--auto-done', '2'], { cwd: dir });
+  run(['set', '--ticket', '9', '--step', 'discuss', '--auto', 'true'], { cwd: dir });
+  ok('autoDone: dropped by a ticket change unless passed again', readState(dir).autoDone === 0);
+  run(['set', '--ticket', '10', '--step', 'discuss', '--auto', 'true', '--auto-done', '4'], { cwd: dir });
+  ok('autoDone: kept on a ticket change when passed again', readState(dir).autoDone === 4);
+  // old file without the field
+  const old = mktmp();
+  fs.mkdirSync(path.join(old, '.trailhead'));
+  fs.writeFileSync(statePath(old), JSON.stringify({ map: null, ticket: 4, title: 'x', step: 'plan', auto: true, session: null, updatedAt: 'z' }));
+  run(['set', '--step', 'execute'], { cwd: old });
+  ok('autoDone: old file without the field gets 0', readState(old).autoDone === 0 && readState(old).auto === true);
+  ok('autoDone: sanitizeState accepts non-negative integers only',
+    sanitizeState({ autoDone: 0 }).autoDone === 0 && sanitizeState({ autoDone: 7 }).autoDone === 7
+    && sanitizeState({ autoDone: -1 }).autoDone === undefined && sanitizeState({ autoDone: 1.5 }).autoDone === undefined
+    && sanitizeState({ autoDone: '3' }).autoDone === undefined);
+}
+
+// --- corrupt and malformed existing file -------------------------------------
+{
+  const dir = mktmp();
+  fs.mkdirSync(path.join(dir, '.trailhead'));
+  fs.writeFileSync(statePath(dir), '{not json');
+  const r = run(['set', '--ticket', '5', '--step', 'plan'], { cwd: dir });
+  ok('corrupt file: overwritten, no crash', r.code === 0 && readState(dir).ticket === 5);
+}
+{
+  const dir = mktmp();
+  fs.mkdirSync(path.join(dir, '.trailhead'));
+  fs.writeFileSync(statePath(dir), JSON.stringify({ map: 'zz', ticket: 9, title: 42, step: 'plan', auto: 'yes', session: 7 }));
+  const r = run(['set', '--step', 'execute'], { cwd: dir });
+  const s = readState(dir);
+  ok('malformed fields dropped, valid kept', r.code === 0 && s.ticket === 9 && s.step === 'execute');
+  ok('malformed fields normalised', s.map === null && s.title === null && s.auto === false);
+}
+{
+  const dir = mktmp();
+  fs.mkdirSync(path.join(dir, '.trailhead'));
+  fs.writeFileSync(statePath(dir), JSON.stringify([1, 2]));
+  const r = run(['set', '--step', 'execute'], { cwd: dir });
+  ok('array file is treated as empty -> usage error without ticket', r.code === 2);
+}
+
+// --- clear -------------------------------------------------------------------
+{
+  const dir = mktmp();
+  run(['set', '--ticket', '1', '--step', 'plan'], { cwd: dir });
+  const r = run(['clear'], { cwd: dir });
+  ok('clear present: cleared, file gone', r.code === 0 && r.lines[0].status === 'cleared' && !fs.existsSync(statePath(dir)));
+  const r2 = run(['clear', '--repo', dir], { cwd: '/' });
+  ok('clear absent: absent, exit 0', r2.code === 0 && r2.lines[0].status === 'absent');
+}
+
+// --- pure functions ----------------------------------------------------------
+{
+  ok('sanitizeState: non-object -> {}', JSON.stringify(sanitizeState(null)) === '{}' && JSON.stringify(sanitizeState('x')) === '{}');
+  const m = mergeState({ ticket: 1, step: 'plan', title: 'a', map: 3, auto: false }, { step: 'verify' });
+  ok('mergeState: merges', m.ticket === 1 && m.step === 'verify' && m.title === 'a' && m.map === 3);
+  const p = parseArgs(['set', '--map', 'none']);
+  ok('parseArgs: map none -> null', p.patch.map === null);
+}
+
+// --- fault injection ---------------------------------------------------------
+for (const failing of ['writeFileSync', 'renameSync']) {
+  const dir = mktmp();
+  run(['set', '--ticket', '1', '--step', 'plan', '--title', 'keep'], { cwd: dir });
+  const bytes = fs.readFileSync(statePath(dir));
+  const broken = { ...fs, [failing]: () => { throw new Error('boom ' + failing); } };
+  // a broken writeFileSync still writes a partial before throwing
+  if (failing === 'writeFileSync') {
+    broken.writeFileSync = (p, d) => { fs.writeFileSync(p, 'partial'); throw new Error('boom'); };
+  }
+  const r = run(['set', '--step', 'execute'], { cwd: dir, fsMod: broken });
+  ok(`failure ${failing}: exit 0, status skipped with message`, r.code === 0 && r.lines[0].status === 'skipped' && /boom/.test(r.lines[0].message));
+  ok(`failure ${failing}: previous file byte-identical`, Buffer.compare(fs.readFileSync(statePath(dir)), bytes) === 0);
+  ok(`failure ${failing}: no temp left`, JSON.stringify(trailheadFiles(dir)) === JSON.stringify(['work-state.json']));
+}
+
+// --- end-to-end --------------------------------------------------------------
+{
+  const dir = mktmp();
+  const env = { ...process.env, CLAUDE_CODE_SESSION_ID: 'e2e' };
+  const out = execFileSync('node', [scriptPath, 'set', '--repo', dir, '--map', '1', '--ticket', '2', '--title', 'E', '--step', 'discuss'], { env, encoding: 'utf8' });
+  ok('e2e: one JSON line', JSON.parse(out.trim()).status === 'written');
+  ok('e2e: session stamped', readState(dir).session === 'e2e');
+  const bad = spawnSync('node', [scriptPath, 'set', '--repo', dir, '--step', 'nope'], { encoding: 'utf8' });
+  ok('e2e: usage error exits 2', bad.status === 2);
+}
+
+console.log(`work-state.test.js: ${passed} checks passed`);

package/plugins/trailhead/hooks/mod/README.md

@@ -0,0 +1,187 @@
+# trailhead mod (contributor note)
+
+`register.tsx` is the trailhead mod: a TypeScript hooks module that Claude Code loads
+next to the command hooks. It shows the ticket in play, read from `.trailhead/work-state.json`
+(written by the skills through `templates/trailhead-work-state.js`; the mod only reads it).
+The typed contract lives in `plugins/trailhead/types/index.d.ts`, wired through the
+`types` key of `plugin.json`. The module is declared in `hooks/hooks.json` under
+`"modules"` (exactly one path, relative to `hooks.json`). The pure parts (parsing the file,
+the status text, the pipeline stages) are in `work-state-view.ts`. The map pane lives in
+`map-pane.tsx` (hooks and drawing) and `map-pane-view.ts` (pure parts); see "Map panel" below.
+
+## What it shows
+
+- **Status entry**: one line under the prompt, `map #198 · #203 Title · plan` (the engine prefixes it with the plugin name, `trailhead:`)
+  (`whiteboard` instead of `map #<n>` for a ticket with no map; the title is left out when
+  there is none). During an autonomous run ` · auto 3 done` is appended.
+- **Band above the prompt**: row one is the ticket number (bold, accent) and the title cut to
+  the band width with `…`; row two is the pipeline `discuss › plan › execute › verify`
+  (`✓` done in green, `▸` current in bold accent, pending dim). Step `resolve` shows all four
+  done, step `paused` shows all four dim followed by `‖ paused`. During an autonomous run
+  `auto · <n> done` sits at the right end of row two.
+- **Orphaned**: when the file names another session than the current one (a `/clear`, a
+  resume, a new window), the entry gets ` · orphaned, resume?` and the band is drawn dim with
+  `orphaned, resume?` after the stages. A `/clear` marks the state on screen as orphaned at
+  once, without waiting for a turn: the engine empties the mod's atoms on `/clear`, so the file is
+  read again when the new session starts (`classic.SessionStart`, source `clear`). A file with no
+  session is never orphaned.
+- **Quiet**: with no file, or a file that cannot be parsed (no valid ticket and step), the
+  band draws nothing and the status entry is cleared. A survey holding the band makes the
+  band yield, and the status entry stays. A read error other than "missing file" keeps what
+  is on screen.
+
+The file is read on `session.start`, `turn.start`, `turn.complete`, and after a Bash call whose
+command contains `trailhead-work-state.js` (so a step change shows without waiting for a turn).
+Atoms and the status entry are only written when their content changed.
+
+## System prompt
+
+Next to the screen pieces, the mod appends one section, `trailhead:work-state`, to the system
+prompt through `prompt.compose` (session side of the cache boundary, after the engine's own
+sections). It names the active map, the ticket in play (number, title, link) and the step, so the
+agent keeps its bearings after a compaction. Links need a GitHub `origin`; without one the numbers
+stand alone. The section is absent with no state, with an orphaned one, and under `--bare`.
+
+It is a latched snapshot kept in the `promptSnapshot` atom (session scoped, never a module
+variable). It is rebuilt only when the map, ticket, title, orphaned flag or auto flag changes, at
+`session.start`, and after a main-loop compaction (`session.compact`, once it did not skip). A
+`precompute` or a subagent's compaction installs nothing in the conversation, so it leaves the
+snapshot alone. A step change deliberately leaves the text alone, so the prompt cache holds; the
+section says the step may have moved on and that `.trailhead/work-state.json` holds the live one.
+For the same reason an autonomous run shows as `Mode: autonomous run`, without the done count.
+
+The issue title is untrusted text from GitHub. It is rendered as quoted data
+(`Ticket: #204 "Title"`), with zero-width and bidi controls removed, inner double quotes turned
+into single ones, and a line saying the title is data, not an instruction. The text is at most
+1024 bytes and carries no skill protocol.
+
+`next(e)` is called once, before any enrichment, and a failure while enriching returns the
+engine's sections untouched. If the repo cannot be read, the section is built without links and
+latched like any other. A `/context` render (`analysis` trait) shows the section but never writes
+the atom.
+
+## Map panel
+
+`/trailhead:panel` opens or closes a pane listing a map's open tickets (the active map's, or the one clicked in the maps list). It is a plugin
+command file (`commands/panel.md`), because a command registered by a mod cannot carry the
+`trailhead:` namespace; the mod answers it before it reaches the model, so the file's body runs
+only where no mod does (it says the panel is not available). Claude Code only: the Codex
+projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex-projection.js`).
+
+- **What it shows**: the map as a link with its destination (dim), then `Frontier · n`,
+  `In progress · n` and `Blocked · n` (an empty group is left out). A row is `#n title` (a link to
+  the issue) and the type, dim. Every assigned row shows its holder as `@login`; the ticket in play
+  in this session (work state, not orphaned) is marked `▸` in the accent; blocked rows are dim. A
+  frontier row has a `work` button that clears the conversation (`/clear`) and then runs
+  `/trailhead:work <n>` in the new one, both through `$.command.run`, which the host queues behind a
+  running turn; the row shows `queued` until the calls settle (across the reset too), and a
+  second press meanwhile is ignored. A refused `/clear`, or one that
+  did not change the session, runs no work command. `trailhead:unverified` tickets are never listed,
+  only counted in one dim line; `trailhead:whiteboard` tickets are dropped. The footer is a `refresh`
+  button and `updated <age>`, or `⚠ <reason> · list from <age>` after a `gh` failure (the last good list is kept;
+  reasons: `gh not installed`, `gh not authenticated (run gh auth login)`,
+  `offline: cannot reach GitHub`, `gh failed (exit <n>)`), and a `close` button at the right edge that
+  closes the panel. A status too long for the room beside the buttons moves to a row of its own under them. Titles come from GitHub and are untrusted:
+  flattened, stripped of control, zero-width and bidi characters, only drawn. Other states: `Loading tickets…`
+  on the first fetch, `No active map. Run /trailhead:map to pick one.`, `No open tickets. Fog may remain: /trailhead:map`.
+- **Maps list and viewing**: with more than one open map (`gh issue list --label trailhead:map --state open`),
+  a `Maps · n` group sits under the header: one row per map, sorted by number, `#n title` cut to the width.
+  The active map has `●` in the accent and an `active` aside; the viewed map is bold; every other row is a
+  `Button`. A press shows that map's tickets, burn-down and `work` buttons (browse); it never writes
+  `.trailhead/active-map`. Pressing the active map's row, or `back to active` (in the dim line
+  `viewing #n · active #m` shown while another map is viewed), goes back. A `work` press on a viewed
+  map's ticket runs `/trailhead:work <n>` as always: the work verb makes the ticket's map the active one
+  (its `trailhead:map-<n>` label), and at the next `turn.complete` the pane sees the active map change
+  and follows (the view resets to the active map). The view also resets when the viewed map leaves a
+  freshly read open list (it closed). A single open map shows no group, as before. With no active
+  map the message stays and the open maps are listed under it, so one can be viewed (`viewing #n` then has a
+  `back` button). The maps read is the 4th of a refresh; a failure of it alone keeps the last list and sets no
+  footer error. Each refresh captures its target (viewed, else active) once and rechecks it before every state
+  write, so a refresh in flight when the view changes never commits the old map's tickets.
+- **Burn-down**: below the groups, a `Burn-down` section shows the shown map's open-ticket count
+  over time, from its first ticket to now. A dim line gives `open <o> · done <d> · removed <r> · peak <p>`
+  (`removed` = closed with `trailhead:superseded` or `trailhead:out-of-scope`; `done` = other closed
+  tickets). The chart has one sample per pane column. On the terminal surface it is a `Raster` (3 rows
+  of eighth blocks, accent colour, key `burndown`); elsewhere a one-row text sparkline (`▁`..`█`).
+  The axis line has the start on the left (`Sep 18`, or `today 09:05` under a day, in UTC) and
+  `now` on the right, but `now` only while the history is fresh: when the history read failed alone, or
+  the whole refresh failed, the last curve is kept, drawn up to the time it was read, and the right label
+  shows its age (`3m ago`). The section is hidden with no active map, while loading, or when the history
+  is empty or has not been read yet.
+  - **Data**: no new storage. One more `gh issue list --label trailhead:map-<map> --state all
+    --limit 5000 --json number,labels,createdAt,closedAt`, run with the other two reads in the same
+    refresh (same timeout, same drop when the pane closed or the map changed). `trailhead:unverified`
+    and `trailhead:whiteboard` rows are skipped.
+  - **Failure**: a failed map or open-list read keeps the whole last good data, chart included. A
+    failed or unreadable history read alone keeps the last good history only when it belongs to the
+    same map (after a map switch no chart is drawn), still accepts the fresh list, and draws the
+    axis end as `<age> ago` instead of `now`. The footer stays about the list.
+  - **Cap**: `gh` returns the newest tickets first, so a history that reaches `HISTORY_LIMIT`
+    misses the oldest; the section then adds `history capped at 5000: starts at the oldest ticket read`.
+- **Through `/clear`**: the engine empties the mod's atoms. At `session.end` with reason `clear` the pane
+  notes the auto-open flag, the viewed map and the active map; at `classic.SessionStart` (source `clear`)
+  it puts the flag back (a pane the person closed is not opened again), reads the active map, puts the
+  view back only when the active map is still the one it was set against, and refreshes at once, past
+  the floor. The pane is filled again with no turn.
+- **Links**: the map and the rows are `Link`s, clickable where the terminal takes OSC 8 links. A
+  terminal Claude Code cannot identify (for example `TERM=xterm-256color` with no `TERM_PROGRAM`)
+  gets the engine's fallback instead: the text, then the URL in dim on the next line, nothing to
+  click. Start Claude Code with `FORCE_HYPERLINK=1` there to get real links.
+- **Where the data comes from**: `.trailhead/active-map` (read locally on `session.start` and
+  `turn.complete`, whether or not the pane is open), then `gh issue view <map>` and
+  `gh issue list --label trailhead:map-<map> --state open` (plus the history read under "Burn-down" and the maps list read) through `$.process.run`,
+  where `<map>` is the viewed map, else the active one. A result is dropped if the pane closed or the shown map changed while `gh` ran.
+- **When it refreshes**: only while the pane is open (a closed pane costs no `gh` call). Opening it,
+  `session.start`, `turn.complete`, a Bash call that runs `gh issue edit|close|create|comment|reopen`,
+  the `refresh` button, and a slow timer started on open. Never two fetches inside `MIN_REFRESH_MS`:
+  a request inside the floor keeps one trailing refresh for the rest of it.
+- **Auto-open**: once, in fullscreen (`e.viewport.isFullscreen === true` in the `AbovePrompt` render),
+  when a map is active. Never on the main screen, never again after the pane was opened or closed
+  by the person (a press on the `close` button counts as closing it). The open runs from a zero-delay timer because a render may not write state.
+- **Constants** (`map-pane.tsx`): `PANE_ID = 'trailhead-map'`, `PANE_TITLE = 'Map'`,
+  `MIN_REFRESH_MS = 15_000`, `TIMER_MS = 180_000`, `GH_TIMEOUT_MS = 20_000`,
+  `PANEL_COMMAND = 'trailhead:panel'`, `MAPS_LIMIT = 100` (not exported); `map-pane-view.ts`: `LIST_LIMIT = 200`, `HISTORY_LIMIT = 5000`.
+- **Atoms**: `mapPane` (with `maps`, the open maps), `activeMap`, `viewedMap` (`null` follows the active map), `pendingWork`, `paneAutoOpened`. Module variables hold the queue and
+  the timers, what `/clear` carries over (`carried`) and the `work` press in flight (`workInFlight`),
+  because `/clear` empties the atoms while they are needed.
+- **Validator note**: `claude plugin validate` follows `$` only inside one file and refuses two
+  hooks on one event with no matcher. So `map-pane.tsx` registers `session.start`, `turn.complete`
+  and `tool.call` with matchers that always hold (or narrow: the `gh issue` write), next to the
+  bare hooks of `register.tsx`.
+
+## Requirements
+
+- Claude Code 2.1.287 or newer (tested on 2.1.296).
+- Command hooks stay the floor. A build without mod support skips only this module;
+  every command hook keeps working.
+- npm delivery is not done yet: `bin/trailhead.js` does not ship the mod, and the
+  Codex projection never sees it. Only the plugin (`--plugin-dir`, marketplace) loads it.
+
+## Dev loop
+
+Run from the repo root.
+
+- Hot reload: `claude --plugin-dir plugins/trailhead` (or set `CLAUDE_CODE_PLUGIN_DIRS`) in an
+  interactive session. Saving `register.tsx` reloads the module.
+- Validate the manifest, types and module: `claude plugin validate plugins/trailhead`.
+  It lists the hooked events and the declared state.
+- Run the mod tests (every `*.test.ts` under the plugin): `claude plugin test plugins/trailhead`.
+  Tests live in `plugins/trailhead/tests/`. The test `on` hooks stand for the engine: they answer
+  `fs.read`, `session.id` and `ui.status`, and the UI tests mount the band and the pane on `terminal` and `desktop`.
+  The map pane tests also answer `process.run` (the `gh` runs), `ui.open`, `ui.close`, `ui.panes`, `command.run`
+  and `tool.call`, and use `mock.clock` for the floor and the timers. The test `$` cannot raise `ui.open`, so a test
+  that has the person open the pane sets the engine's pane list directly.
+  A hook result is `{ value }` or `{ deny }`; a `$.fs.read` that must fail is a `{ deny: 'ENOENT: ...' }`.
+  A `Text` carries no `key`, so the module keys a `Box` around each one and tests read the Text inside it.
+- Everything at once: `npm test`. It runs the `*.test.js` suites, then validate and test.
+  Without `claude` on PATH it fails; set `TRAILHEAD_SKIP_MOD_CHECKS=1` to skip the mod checks.
+- Debugging: `claude --debug`, or `claude -p --plugin-dir plugins/trailhead --debug-file <file> "say ok"`.
+  A healthy load logs `hooks module trailhead@inline loaded (...); events: session.start,classic.SessionStart,turn.complete,tool.call,command.run,ui.render,ui.close,prompt.compose,session.compact,turn.start,session.end`.
+  A module that fails to parse shows `hooks module did not load`.
+
+## Optional type check
+
+An interactive `--plugin-dir` load writes `.claude-plugin/types/` and an engine
+`tsconfig.json` into the plugin (both are git-ignored). After that:
+
+    npx -p typescript@5.9.3 tsc -p plugins/trailhead