@marcomigozzi/trailhead 0.15.0 → 0.16.0

package/plugins/trailhead/hooks/lib/unblock.test.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-unblock.js. Run: node unblock.test.js
+// No framework: plain asserts, same style as needs-you.test.js.
+//
+// Layers covered:
+//   1. main() against a fake tracker behind an injected `gh` (multi-page reads included).
+//   2. Usage errors (exit 2).
+//   3. 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-unblock.js');
+const { main } = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// --- fake tracker ------------------------------------------------------------
+// dependents: [{number, state, labels}] of the closed issue (paginated output is the
+// concatenation of one JSON object per line, whatever the page size).
+// blockers: { [dependent]: [{number, state}] }. failOn: blocking | blocked_by | edit.
+function makeTracker(init = {}) {
+  const t = { dependents: init.dependents || [], blockers: init.blockers || {}, failOn: init.failOn || null, badJson: !!init.badJson, calls: [], edits: [] };
+  const res = (stdout, status = 0) => ({ status, stdout, stderr: status ? 'forced failure' : '' });
+  const lines = (list) => list.map((o) => JSON.stringify(o)).join('\n') + (list.length ? '\n' : '');
+  t.gh = (args) => {
+    t.calls.push(args.join(' '));
+    if (args[0] === 'api') {
+      const url = args.find((a) => a.startsWith('repos/'));
+      const m = /issues\/(\d+)\/dependencies\/(blocking|blocked_by)$/.exec(url || '');
+      if (!m) return res('', 1);
+      if (t.failOn === m[2]) return res('', 1);
+      if (t.badJson) return res('not json\n');
+      if (m[2] === 'blocking') return res(lines(t.dependents));
+      return res(lines(t.blockers[m[1]] || []));
+    }
+    if (args[0] === 'issue' && args[1] === 'edit') {
+      if (t.failOn === 'edit') return res('', 1);
+      t.edits.push(args.join(' '));
+      const n = Number(args[2]);
+      const d = t.dependents.find((x) => x.number === n);
+      if (d) d.labels = d.labels.filter((l) => l !== args[args.indexOf('--remove-label') + 1]);
+      return res('');
+    }
+    return res('', 1);
+  };
+  return t;
+}
+
+function run(t, argv, extra = {}) {
+  let out = '';
+  let errOut = '';
+  const code = main(argv, { gh: t.gh, stdout: { write: (s) => { out += s; } }, stderr: { write: (s) => { errOut += s; } }, ...extra });
+  let json = null;
+  try { json = JSON.parse(out.trim()); } catch { /* not json */ }
+  return { code, out, json, errOut };
+}
+
+const args = ['--issue', '5', '--repo', 'o/r'];
+const B = 'trailhead:blocked';
+
+// --- last blocker closed -> label removed ------------------------------------
+{
+  const t = makeTracker({
+    dependents: [{ number: 8, state: 'open', labels: [B, 'x'] }],
+    blockers: { 8: [{ number: 5, state: 'closed' }, { number: 6, state: 'closed' }] },
+  });
+  const r = run(t, args);
+  ok('unblock: exits 0 with status ok', r.code === 0 && r.json.status === 'ok');
+  ok('unblock: the dependent is listed', JSON.stringify(r.json.unblocked) === '[8]' && r.json.stillBlocked.length === 0);
+  ok('unblock: the blocked label is removed', t.edits.length === 1 && t.edits[0].includes('--remove-label trailhead:blocked') && t.edits[0].includes('-R o/r'));
+  ok('unblock: the reads are paginated', t.calls.filter((c) => c.startsWith('api')).every((c) => c.includes('--paginate')));
+  const again = run(t, args);
+  ok('unblock: a retry is idempotent (label already gone)', again.code === 0 && again.json.unblocked.length === 0 && t.edits.length === 1);
+}
+
+// --- another blocker still open ----------------------------------------------
+{
+  const t = makeTracker({
+    dependents: [{ number: 8, state: 'open', labels: [B] }],
+    blockers: { 8: [{ number: 5, state: 'closed' }, { number: 6, state: 'open' }, { number: 7, state: 'open' }] },
+  });
+  const r = run(t, args);
+  ok('unblock: an open blocker keeps the label', r.code === 0 && r.json.unblocked.length === 0 && t.edits.length === 0);
+  ok('unblock: stillBlocked names the open blockers', r.json.stillBlocked.length === 1 && r.json.stillBlocked[0].issue === 8 && JSON.stringify(r.json.stillBlocked[0].openBlockers) === '[6,7]');
+}
+
+// --- skipped dependents -------------------------------------------------------
+{
+  const t = makeTracker({
+    dependents: [
+      { number: 8, state: 'open', labels: [] },
+      { number: 9, state: 'closed', labels: [B] },
+      { number: 10, state: 'open', labels: [B] },
+    ],
+    blockers: { 10: [{ number: 5, state: 'closed' }] },
+  });
+  const r = run(t, args);
+  ok('unblock: a dependent without the label is skipped', !t.calls.some((c) => c.includes('issues/8/')));
+  ok('unblock: a closed dependent is skipped', !t.calls.some((c) => c.includes('issues/9/')));
+  ok('unblock: only the open labelled dependent is unblocked', JSON.stringify(r.json.unblocked) === '[10]');
+}
+
+// --- no dependents ------------------------------------------------------------
+{
+  const r = run(makeTracker(), args);
+  ok('unblock: no dependents is ok and empty', r.code === 0 && r.json.status === 'ok' && r.json.unblocked.length === 0 && r.json.stillBlocked.length === 0);
+}
+
+// --- gh failures --------------------------------------------------------------
+{
+  const t = makeTracker({ failOn: 'blocking' });
+  const r = run(t, args);
+  ok('unblock: a failed dependents read is an error', r.code === 1 && r.json.status === 'error' && /dependents|blocking/.test(r.json.reason));
+  ok('unblock: nothing edited after a failed read', t.edits.length === 0);
+}
+{
+  const t = makeTracker({
+    dependents: [{ number: 8, state: 'open', labels: [B] }, { number: 9, state: 'open', labels: [B] }],
+    blockers: { 8: [{ number: 5, state: 'closed' }], 9: [{ number: 5, state: 'closed' }] },
+    failOn: 'blocked_by',
+  });
+  const r = run(t, args);
+  ok('unblock: a failed blockers read is an error naming the step', r.code === 1 && r.json.status === 'error' && /blocked_by|blockers/.test(r.json.reason));
+  ok('unblock: nothing further edited after the failure', t.edits.length === 0 && t.calls.filter((c) => c.includes('issues/9/')).length === 0);
+}
+{
+  const t = makeTracker({
+    dependents: [{ number: 8, state: 'open', labels: [B] }, { number: 9, state: 'open', labels: [B] }],
+    blockers: { 8: [{ number: 5, state: 'closed' }], 9: [{ number: 5, state: 'closed' }] },
+    failOn: 'edit',
+  });
+  const r = run(t, args);
+  ok('unblock: a failed label removal is an error', r.code === 1 && r.json.status === 'error' && /remove/.test(r.json.reason));
+  ok('unblock: the next dependent is not touched after a failed edit', t.calls.filter((c) => c.startsWith('issue edit')).length === 1);
+}
+{
+  const r = run(makeTracker({ badJson: true }), args);
+  ok('unblock: unparseable gh output is an error', r.code === 1 && r.json.status === 'error' && /unparseable/.test(r.json.reason));
+}
+
+// --- multi-page reads ---------------------------------------------------------
+// gh api --paginate with --jq prints one object per line across every page, so a
+// second page is just more lines; the fake returns them concatenated, and the helper
+// must read all of them (two pages of dependents, an open blocker only on page two).
+{
+  const t = makeTracker({
+    dependents: [
+      ...Array.from({ length: 30 }, (_, i) => ({ number: 100 + i, state: 'closed', labels: [] })),
+      { number: 8, state: 'open', labels: [B] },
+    ],
+    blockers: {
+      8: [...Array.from({ length: 30 }, (_, i) => ({ number: 200 + i, state: 'closed' })), { number: 99, state: 'open' }],
+    },
+  });
+  const r = run(t, args);
+  ok('unblock: a dependent on the second page is found', r.code === 0 && r.json.stillBlocked.length === 1 && r.json.stillBlocked[0].issue === 8);
+  ok('unblock: an open blocker only on the second page keeps the label', JSON.stringify(r.json.stillBlocked[0].openBlockers) === '[99]' && t.edits.length === 0);
+}
+
+// --- usage errors -------------------------------------------------------------
+{
+  const t = makeTracker();
+  for (const [name, argv] of [
+    ['no arguments', []],
+    ['missing --repo', ['--issue', '5']],
+    ['missing --issue', ['--repo', 'o/r']],
+    ['bad --issue', ['--issue', 'x', '--repo', 'o/r']],
+    ['bad --repo', ['--issue', '5', '--repo', 'nope']],
+    ['unknown flag', ['--issue', '5', '--repo', 'o/r', '--force']],
+    ['flag without value', ['--issue']],
+  ]) {
+    const r = run(t, argv);
+    ok(`usage: ${name} exits 2 with stderr`, r.code === 2 && r.errOut.startsWith('usage:') && r.out === '');
+  }
+  ok('usage: no gh call on a usage error', t.calls.length === 0);
+}
+
+// --- end-to-end: the script with a fake gh on PATH -----------------------------
+{
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'unblock-e2e-')));
+  const bin = path.join(dir, 'gh');
+  fs.writeFileSync(bin, [
+    '#!/bin/sh',
+    'case "$*" in',
+    '  *dependencies/blocking*) echo \'{"number":8,"state":"open","labels":["trailhead:blocked"]}\' ;;',
+    '  *dependencies/blocked_by*) echo \'{"number":5,"state":"closed"}\' ;;',
+    '  *"issue edit"*) echo "$*" >> "' + path.join(dir, 'edits.log') + '" ;;',
+    '  *) exit 1 ;;',
+    'esac',
+    '',
+  ].join('\n'));
+  fs.chmodSync(bin, 0o755);
+  const r = spawnSync('node', [scriptPath, '--issue', '5', '--repo', 'o/r'], { encoding: 'utf8', env: { ...process.env, PATH: `${dir}:${process.env.PATH}` } });
+  let j = null;
+  try { j = JSON.parse(r.stdout.trim()); } catch { /* not json */ }
+  ok('e2e: exits 0 with one JSON line', r.status === 0 && j && j.status === 'ok' && JSON.stringify(j.unblocked) === '[8]');
+  ok('e2e: the label edit reached gh', fs.readFileSync(path.join(dir, 'edits.log'), 'utf8').includes('--remove-label trailhead:blocked'));
+  const bad = spawnSync('node', [scriptPath], { encoding: 'utf8' });
+  ok('e2e: a usage error exits 2', bad.status === 2);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+console.log(`unblock.test.js: ${passed} checks passed`);

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

@@ -3,6 +3,10 @@
 `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 engine writes it in the ticket's own workspace, so when the pinned checkout has none the mod looks in the
+repo's other checkouts (also when the pinned one holds another session's state; `git worktree list`, sibling `<repo>-t<n>` clones) and adopts the one naming this session
+(`work-state-locate.ts`). After a `/clear` a state in another checkout is not shown (it names the old session),
+unlike the own checkout's orphaned display.
 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,
@@ -13,18 +17,27 @@ the status text, the pipeline stages) are in `work-state-view.ts`. The map pane
 
 - **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.
+  there is none). During an autonomous run ` · auto 3 done · 2 in flight` is appended (see
+  [Autonomous run](#autonomous-run)).
 - **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.
+  `auto · <n> done · <m> in flight` sits at the right end of row two.
+- **Another session / orphaned**: when the file names another session than the current one (a
+  resume, a new window, a parallel session), the ticket is not this session's, so it is not in
+  play and not in the system prompt. By default it reads neutrally: the entry gets
+  ` · in another session` and the band keeps its normal look with `in another session` after
+  the stages, no resume hint. It reads ` · orphaned, resume?` (band drawn dim with
+  `orphaned, resume?` after the stages) only when the Claude Code session registry confirms the
+  session is gone: the registry is `<config dir>/sessions/<pid>.json` (`sessionId`, `pid`; the
+  config dir is `$CLAUDE_CONFIG_DIR`, else `~/.claude`), and a session is gone when no entry names
+  its id with a live pid. The pid is checked through `/proc` where it exists (Linux); elsewhere the
+  entry's presence counts as alive. A registry that cannot be listed or read, has unparseable
+  files, or is empty falls back to the neutral wording, never orphaned. A `/clear` marks the state
+  on screen as orphaned at once, without the registry and 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
@@ -39,24 +52,39 @@ Atoms and the status entry are only written when their content changed.
 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`.
+agent keeps its bearings after a compaction. Links follow the pinned repo (its host included, see "Which repo"), so a shell `cd` out of it keeps
+them; with no pin the numbers stand alone. The section is absent with no state, with a foreign one (orphaned or in another session), 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
+It is a latched snapshot kept in the `promptSnapshot` atom (session scoped): what the model has
+been told. It is reset at `session.start`, after a main-loop compaction (`session.compact`, once it
+did not skip) and on `/clear`; only the first persisting compose after a reset writes it. A later
+compose never rebuilds it: it returns the latched text, so the system prompt stays what the engine
+already holds (the engine composes every turn but keeps sending the first one). Only `prompt.submit`
+advances the latch after that, when the map, ticket, title, orphaned flag or auto flag changed. 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 engine composes the system prompt once per process (first request) and keeps it; only a session
+start, a main-loop compaction and `/clear` compose again. So a change made mid-session (the first
+`trailhead-work-state.js set`, a new ticket, the state cleared) does not reach the model through
+`prompt.compose`. A `prompt.submit` hook treats the latched snapshot as what the model has been told:
+when the live key differs, it attaches the new section as `context` on that prompt, once per change
+(overlapping prompts attach it once), and latches it; a prompt dropped beneath puts the latch back, so
+the next one carries the change, as does one whose hook failed beneath or whose latch write was denied
+(the latch stays where it was and the next prompt retries). A per-session in-memory mirror of the latch,
+set only after a successful atom write, lets overlapping prompts agree on it. If the state went away it attaches a one-line note that the earlier section is
+stale. With no compose yet it does nothing (the first compose carries the state), and it skips slash
+commands and fails open: the prompt is never dropped.
+
 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
+engine's sections untouched. With no pin the section is built without links and
 latched like any other. A `/context` render (`analysis` trait) shows the section but never writes
 the atom.
 
@@ -68,7 +96,7 @@ command file (`commands/panel.md`), because a command registered by a mod cannot
 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`,
+- **What it shows**: the map as a link with its destination (dim), then `Needs you · n`, `Frontier · n`,
   `In progress · n`, `UAT · n`, `Paused · 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 is marked `▸` in the accent and says `this session` in place of its holder;
@@ -76,18 +104,33 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   over the shared file (a state stamped with another session leaves it; a missing file clears it only
   when the last state read was this session's, i.e. its own Resolve); with no own ticket the work
   state decides, as before. A ticket carrying `trailhead:paused` (set by pause, cleared by resume or a
-  `work`/`quick` claim) shows once, under `Paused`, between In progress and Blocked, with its holder
-  when assigned and never a `work` button; the label wins over `trailhead:blocked` and an assignee. A
+  `work`/`quick` claim) shows once, under `Paused`, between In progress and Blocked, with a `resume`
+  button in place of its holder (it runs like `work`, with `/trailhead:resume <n>`, which checks the
+  claim); the label wins over `trailhead:blocked` and an assignee.
+  A ticket carrying `trailhead:needs-you` (an autonomous run parked it for the human; a `work`/`quick` claim
+  clears it) shows once, under `Needs you`, above Frontier. The label wins over paused, UAT, blocked and an
+  assignee. Any assignee is shown as its holder, never a button, even on a paused or blocked row. A blocked
+  row with no assignee is dim with no button. Any other row gets a `work` button, never `resume`, even when
+  paused: the claim clears the mark and resume would not. A
   ticket carrying `trailhead:uat` (a pending UAT follow-up, a marker never a state) shows once, under `UAT`,
-  between In progress and Paused, whatever its state (`paused` wins), keeping its `work` button or holder, with a
+  between In progress and Paused, whatever its state (`paused` and `needs-you` win), keeping its `work` button or holder, with a
   dim `tests <parent title> #<n>` line under it. The parent comes from the `UAT of:` line of its body, read once
-  per refresh by `gh issue list --label trailhead:uat --label trailhead:map-<n>` (`--label trailhead:whiteboard`
-  on the whiteboard view) `--json number,body`, capped like the ticket list at 200: beyond that, or when the read
-  fails, a UAT row is drawn without its parent line (the rows still group by label). A
+  per refresh by a paged `gh api graphql` read of `repository.issues(states: OPEN, labels: ["trailhead:uat"])` (100 a page,
+  up to 10 pages), filtered here to `trailhead:map-<n>` (`trailhead:whiteboard` on the whiteboard view). When a page fails
+  or is unreadable, or pages are left at the cap, a UAT row is drawn without its parent line (the rows still group by
+  label); never a partial map, no search fallback. 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
+  `/trailhead:work <n>` in the new one (a paused row's `resume` does the same with `/trailhead:resume <n>`), both through `$.command.run`.
+  A press during a running turn is held by the panel, which sends nothing to the host: the row shows `queued` with a
+  `cancel` button, and the press runs (`/clear`, then the verb) when the turn ends, an interrupted one included.
+  `cancel` drops it before anything is sent, so the conversation is untouched and the row goes back to its button.
+  With no turn running the press starts at once and the row reads `starting` (no cancel) until the calls settle,
+  across the reset too. One press at a time: another while one is held or starting is ignored. A session that ends
+  while a press is held drops it. A press while the session is not in the pinned repo (a shell `cd` moved it) still
+  starts: the mod cannot move the session, so it appends the pinned checkout to the verb's args as `--in=<token>`
+  (base64url of the root) and the verb `cd`s there first. With no repo pinned, or a checkout that cannot be read
+  (a removed worktree included), the press is refused with a toast before the `/clear`; both are checked again when
+  a held press is sent. 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;
@@ -120,16 +163,40 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   aliased `totalCount` connections on `trailhead:whiteboard`), never a per-ticket query. If that call
   fails or its whiteboard fields are unreadable the row is drawn name-only, no counts and no error (the
   `whiteboard` field of the `mapPane` atom is `null`; a failed read never keeps stale counts).
+- **Total line**: one dim line, `<N> open across all maps + whiteboard`, directly under the `Whiteboard` row (in the map
+  view, its loading state and the no-active-map view) and under the header row in the Dashboard view. It is the sum of the
+  open issues labelled `trailhead:map-<n>` for every open map plus the open issues labelled `trailhead:whiteboard`: the
+  dashboard's own count scopes. Both labels are only ever applied to `trailhead:ticket` issues and a ticket carries one of
+  them, never both, so the label scopes are the ticket count and nothing is counted twice; closed maps never count,
+  whiteboard tickets always do. The source is one extra `gh api graphql` call after the maps read, with one aliased
+  `totalCount`-only connection per open map (at most `MAPS_LIMIT` = 100) plus one for the whiteboard, so it is exact and
+  has no list limit; the cost is up to one connection per enumerated map per refresh, only while the pane is open (15 s
+  floor). The result is the `openTotal` field of the `mapPane` atom, with the map numbers it was computed over. It is
+  hidden while unknown: before a first good count, when the count read fails or is unreadable and the open maps are not
+  the set the last good total covered (a failed read keeps the last total only over exactly the same maps, beside the
+  pane's own failure note), and whenever the maps read fell back to the name-only `gh issue list` (the count query runs
+  only on the GraphQL maps path), including when that fallback fails too and the last maps list is kept: with no maps
+  read there is no set to check the last total against, so it is hidden until the next good read. When more open maps exist than the maps read returned (`totalCount` above the nodes
+  read, so exactly 100 maps is not a cut) the total is a lower bound and reads `at least <N> open across all maps +
+  whiteboard`. In a narrow pane it shortens to `<N> open in total` (`≥<N> open in total` for a lower bound), and is left
+  out when even that does not fit.
 - **Dashboard view**: the `Whiteboard` row (the header has no button for it) opens the repo index. It draws a `Dashboard` title (a link
   to the pinned `trailhead:dashboard` issue when there is one) with a `map` button that goes back to the map
   shown before (the view is kept), a `Maps · n` group with every open map pressable (a press leaves the
   dashboard and views that map, the active one marked `●`), and a `Whiteboard · <n> open · <m> assigned` section (counted
   over the listed tickets; `200+ open` when the list is capped): the open
-  `trailhead:ticket` + `trailhead:whiteboard` tickets as Frontier / In progress / UAT / Paused / Blocked, with the same rows,
+  `trailhead:ticket` + `trailhead:whiteboard` tickets as Needs you / Frontier / In progress / UAT / Paused / Blocked, with the same rows,
   holders and `work` buttons (the work verb takes a whiteboard ticket as is). Unverified ones are counted only.
-  Its reads replace the map's in a refresh: the whiteboard list, `gh issue list --label trailhead:dashboard
+  Its reads replace the map's in a refresh: the whiteboard list (the GraphQL open read above), `gh issue list --label trailhead:dashboard
   --json number,url` and the maps list; a failed list keeps the last one with the footer reason, a failed index
   read alone keeps the last link. Data in the `dashboardPane` atom; the mode survives `/clear` like the view.
+- **Following the whiteboard**: when this session takes a whiteboard ticket (its own work state names a ticket with no
+  map), the panel switches to the Dashboard view by itself, once per ticket. It looks at session start, at the end of a
+  turn and after a call to the work-state helper, always after the work state was re-read. Going back to the map by hand
+  is not undone (the followed ticket is remembered in a module variable, so a `/clear` does not forget it); a different
+  whiteboard ticket later is followed again. After a Resolve the panel stays on the whiteboard. A whiteboard ticket
+  created while a map is shown (`gh issue create` with the `trailhead:whiteboard` label) raises a toast,
+  `new whiteboard ticket #<n>: open Whiteboard`, instead of switching. The rules are pure, in `whiteboard-follow.ts`.
 - **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
@@ -161,26 +228,100 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   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.
+  the open list of `trailhead:map-<map>` (plus the history read under "Burn-down", the UAT parents 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.
+  The open list (a map's, and the whiteboard's) is a `gh api graphql` read of `repository.issues(states: OPEN, labels: [...])`,
+  paged 100 a page up to 200 rows, because `gh issue list --label` goes through the search API, which lags a write by seconds:
+  a ticket just created or closed would show stale. GraphQL `labels` is any-of, so the whiteboard read filters
+  `trailhead:ticket` itself. A page that fails or is unreadable discards the whole GraphQL read (never a partial list)
+  and `gh issue list --label <label> --state open` runs once instead. The UAT-parent read joins the open list on
+  GraphQL (above), with no search fallback. Only the history (`--state all`) stays on `gh issue list` (search-backed): it can
+  trail a write by seconds, which the follow-up read below covers.
+- **Which repo**: the one the session started in, pinned (`repo-pin.ts`) when `$.session.repo()` has a
+  remote of the form host/owner/name (github.com or an Enterprise host, any ssh/https form). The pinned root
+  is the checkout's own toplevel (`git rev-parse --show-toplevel` in the session's project root), so a
+  worktree session uses its worktree. It is checked again on each refresh and `turn.complete`. Every `gh`
+  call runs with the pinned root as `cwd` (`gh` resolves the host and the `{owner}`/`{repo}` placeholders
+  from it), and `.trailhead/active-map` and `.trailhead/work-state.json` are read by absolute path under
+  it, so a shell `cd` out of the repo changes nothing. A check outside any repo, or in one with no usable
+  remote, keeps the pin; a move into another repo moves it, drops the reads in flight and empties what the
+  pane held for the old one. With nothing ever pinned the pane says
+  `Not in a GitHub repository: open the session in a trailhead repo` and makes no `gh` call.
 - **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.
+  `session.start`, `turn.complete`, a Bash call that writes to the tracker, the `refresh` button, and a slow
+  timer started on open. A write is `gh issue edit|close|create|comment|reopen|delete|transfer`, a `gh api` call on a
+  `repos/.../issues` path with a write method (`-X`/`--method` POST, PATCH, PUT, DELETE) or an implicit POST
+  (`-f`, `-F`, `--field`, `--raw-field`, `--input`) and no `-X GET`, or the `trailhead-issue-body.js` helper
+  (`GH_ISSUE_WRITE`); reads never refresh. Never two fetches inside `MIN_REFRESH_MS`: a request inside the floor
+  keeps one trailing refresh for the rest of it. A write that reads at once also arms that trailing refresh, so one
+  more read follows when the floor ends, after the search index (the history) caught up; a burst of writes still costs one
+  read per floor plus one trailing. The host drops a refused timer without a word (a refused `every` period ends
+  the interval), so the slow timer is kept with its due time: past it by more than `TIMER_GRACE_MS` it is held dead
+  and the next trigger starts it again (`isTimerLate`). A read asked while the pane is undrawn is dropped; a render
+  whose list (with no error) is older than `TIMER_MS + TIMER_GRACE_MS` asks for a read at once, as an empty view does.
 - **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.
+  Being unasked, it waits undrawn below 144 columns (`isPlaced: false`), typical of a fresh session; `/trailhead:panel`
+  then opens it again as the person's request (drawn at any width) instead of closing it, and closes it only when even
+  that leaves it undrawn (no surface places panes).
 - **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), `isDashboard`, `dashboardPane`, `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.
+  `MIN_REFRESH_MS = 15_000`, `TIMER_MS = 180_000`, `GH_TIMEOUT_MS = 20_000`, `TIMER_GRACE_MS = 30_000`,
+  `PANEL_COMMAND = 'trailhead:panel'`, `MAPS_LIMIT = MAPS_READ_LIMIT = 100` (`MAPS_LIMIT` not exported); `worktree-porcelain.ts`: `MAX_FAILURES = 3` (shared by the work-state lookup and the run scan); `auto-run-view.ts`: `RESUME_HINT`; `map-pane-view.ts`: `MAPS_READ_LIMIT = 100`, `LIST_LIMIT = 200`, `HISTORY_LIMIT = 5000`.
+- **Atoms**: `mapPane` (with `maps`, the open maps), `activeMap`, `viewedMap` (`null` follows the active map), `isDashboard`, `dashboardPane`, `pendingWork`, `pendingPhase` (`queued` or `starting`), `paneAutoOpened`. Module variables hold the queue and
+  the timers, what `/clear` carries over (`carried`), the held press (`held`) and the one being sent (`inFlight`),
+  because `/clear` empties the atoms while they are needed. Whether a main turn runs is `turn-state.ts`, kept by
+  `register.tsx`'s bare `turn.start`, `turn.complete` and `session.end` hooks and read by the pane.
 - **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
+  hooks on one event with no matcher. So `map-pane.tsx` registers `session.start`, `turn.complete`,
+  `session.end` and `tool.call` with matchers that always hold (or narrow: the tracker write), next to the
   bare hooks of `register.tsx`.
 
+## Autonomous run
+
+The mod only watches an autonomous run (`/trailhead:auto`): no Stop hook, no `$.prompt.submit`
+that drives, no write to a work state or to the tracker.
+
+- **Run membership.** The run's main checkout is `$.session.repo().root` (the main working tree,
+  whatever linked worktree the session sits in); only when that is unreadable the pinned root
+  stands in. A checkout's work state belongs to the run when it says `auto: true` and the checkout is
+  (a) the main checkout or the pinned one, (b) a `git worktree` of the repo on branch
+  `trailhead/t<n>` whose state is for ticket `<n>`, or (c) a sibling directory `<repo>-t<n>` that is an
+  independent checkout (its git dir inside it) on `trailhead/t<n>`, with a state for ticket `<n>`. The
+  session in the state is ignored: slot states are sessionless on purpose. A symlinked alias of one
+  checkout is not recognised as the same path (the mod has no realpath).
+- **Scan gate.** The scan runs only when a run can exist: `<main>/.trailhead/auto-run.json` is
+  present, or the own work state says `auto: true`. Otherwise the run is cleared at once and no process
+  runs, so a session outside a run costs one file read.
+- **Label.** `auto · 3 done · 2 in flight · 1 needs you · 1 paused`: `done` is the highest
+  `autoDone` among the members, `in flight` counts the members whose step is not `paused`; zero
+  counts are left out. With a work state of its own the label sits at the right end of band row two and
+  after the step in the status; without one (the slots' states are sessionless) it is a one-line band and
+  the whole status.
+- **Counts.** `needs you` and `paused` come from one GraphQL `gh api graphql` read with two searches
+  (open `trailhead:ticket` issues labelled `trailhead:needs-you` or `trailhead:paused`), narrowed by the
+  run record's scope (`map:<n>` to `trailhead:map-<n>`, `whiteboard` to `trailhead:whiteboard`,
+  `everything` or an unreadable record to the whole repo). They are scope counts, not run-only counts:
+  `paused` is not narrowed to the run's own tickets, and an earlier needs-you mark stays until the
+  person clears it. The read runs under the pinned root, only while a run is detected, never
+  faster than `MIN_REFRESH_MS`, and on the pin's own host (`--hostname`, so an Enterprise pin is searched there);
+  a failed read keeps the last counts; no pin, or no engine clock, means no call.
+- **Bounded failures.** A scan that fails (the git listing, a read other than a missing file) keeps
+  the last run for at most `MAX_FAILURES = 3` failures in a row, then clears it; a success resets the count.
+  Failures are counted at most once per `MIN_REFRESH_MS` (a turn refreshes several times), so a brief git
+  hiccup never clears a live run; without a clock every failure counts.
+  A clean scan with no member clears the run at once.
+- **Resume hint.** `auto interrupted · /trailhead:auto to resume` (in the status
+  `auto interrupted, /trailhead:auto to resume`) shows while a flag is set and a run member remains. The
+  flag is set by a main-loop `turn.complete` with `isAborted` (an Esc), and by an accepted main-conversation
+  compaction that lands while no main turn is running. A compaction inside a running turn sets nothing; if
+  that turn then ends aborted, the first rule applies. Subagent turns never touch it. It clears at the
+  next main-loop `turn.start` (a background slot's completion starts a new turn), when `/trailhead:auto`
+  is submitted and not dropped, and it is hidden once no member is left (hand-back).
+- **State.** Atoms `autoRun`, `runCounts`, `autoInterrupted`; the module variables are the last run, the
+  failure count, the counts cache and the running-turn flag. The status is recomputed last in each
+  refresh, from all of them at once.
+
 ## Requirements
 
 - Claude Code 2.1.287 or newer (tested on 2.1.296).
@@ -208,7 +349,7 @@ Run from the repo root.
 - 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 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,prompt.submit,session.compact,turn.start,session.end`.
   A module that fails to parse shows `hooks module did not load`.
 
 ## Optional type check

package/plugins/trailhead/hooks/mod/auto-run-view.ts

@@ -0,0 +1,93 @@
+// Pure view logic of the autonomous run in the mod: which checkouts belong to the run, the counts,
+// the label and the resume hint. No engine calls here, so it is easy to test.
+import type { AutoRun, RunCounts, WorkState } from '../../types'
+import { MAX_FAILURES } from './worktree-porcelain'
+
+export const RESUME_HINT = 'auto interrupted · /trailhead:auto to resume'
+// Nello status il separatore è la virgola, perché il punto mediano separa già le parti.
+export const RESUME_HINT_STATUS = 'auto interrupted, /trailhead:auto to resume'
+
+const SLOT_BRANCH = /^refs\/heads\/trailhead\/t(\d+)$/
+const SCOPE = /^(?:map:([1-9]\d*)|whiteboard|everything)$/
+
+export type Where = { kind: 'main' } | { kind: 'worktree'; ticket: number } | { kind: 'clone'; ticket: number; onBranch: boolean }
+
+// The ticket of a slot branch `refs/heads/trailhead/t<n>`; any other branch is no slot.
+export const slotTicket = (branch: string | null): number | null => {
+  const m = branch === null ? null : SLOT_BRANCH.exec(branch)
+  const n = m === null ? 0 : Number(m[1])
+  return n > 0 ? n : null
+}
+
+// Whether a checkout's work state belongs to the run. The session is ignored on purpose: slot states are sessionless.
+export const isRunMember = (where: Where, state: WorkState): boolean => {
+  if (state.auto !== true) return false
+  if (where.kind === 'main') return true
+  if (where.kind === 'clone' && !where.onBranch) return false
+  return state.ticket === where.ticket
+}
+
+export const aggregateRun = (states: readonly WorkState[]): AutoRun | null =>
+  states.length === 0
+    ? null
+    : { done: Math.max(...states.map(s => s.autoDone)), inFlight: states.filter(s => s.step !== 'paused').length }
+
+// The label of the record's scope; null = the whole repo (everything, absent or unreadable).
+export const parseRunScope = (recordText: string): string | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(recordText)
+  } catch {
+    return null
+  }
+  const scope = (raw as { scope?: unknown } | null)?.scope
+  const m = typeof scope === 'string' ? SCOPE.exec(scope) : null
+  if (m === null) return null
+  return m[1] !== undefined ? `trailhead:map-${m[1]}` : scope === 'whiteboard' ? 'trailhead:whiteboard' : null
+}
+
+const COUNTS_QUERY =
+  'query($needs: String!, $paused: String!) { needsYou: search(query: $needs, type: ISSUE, first: 1) { issueCount } paused: search(query: $paused, type: ISSUE, first: 1) { issueCount } }'
+
+// One GraphQL read, two searches, on the pin's own host (an Enterprise pin is searched there). The slug is owner/name (repo-pin keeps it to safe characters).
+export const runCountsArgs = (host: string, slug: string, scopeLabel: string | null): string[] => {
+  const base = `repo:${slug} is:open label:"trailhead:ticket"`
+  const scope = scopeLabel === null ? '' : ` label:"${scopeLabel}"`
+  return [
+    'api', 'graphql', '--hostname', host,
+    '-f', `query=${COUNTS_QUERY}`,
+    '-f', `needs=${base} label:"trailhead:needs-you"${scope}`,
+    '-f', `paused=${base} label:"trailhead:paused"${scope}`,
+  ]
+}
+
+export const parseRunCounts = (stdout: string): RunCounts | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(stdout)
+  } catch {
+    return null
+  }
+  const data = (raw as { data?: Record<string, { issueCount?: unknown } | undefined> } | null)?.data
+  const needsYou = data?.needsYou?.issueCount
+  const paused = data?.paused?.issueCount
+  const ok = (n: unknown): n is number => Number.isInteger(n) && (n as number) >= 0
+  return ok(needsYou) && ok(paused) ? { needsYou, paused } : null
+}
+
+// The parts after "auto": done, in flight (when known), then the counts that are not zero.
+export const runParts = (run: { done: number; inFlight?: number }, counts: RunCounts | null): string[] => [
+  `${run.done} done`,
+  ...(run.inFlight === undefined ? [] : [`${run.inFlight} in flight`]),
+  ...(counts !== null && counts.needsYou > 0 ? [`${counts.needsYou} needs you`] : []),
+  ...(counts !== null && counts.paused > 0 ? [`${counts.paused} paused`] : []),
+]
+
+export const runLabel = (run: { done: number; inFlight?: number }, counts: RunCounts | null): string =>
+  ['auto', ...runParts(run, counts)].join(' · ')
+
+export const showsResumeHint = (flag: boolean, run: AutoRun | null): boolean => flag && run !== null
+
+// Una scansione fallita tiene l'ultimo run, finché non arriva il MAX_FAILURES-esimo fallimento di fila.
+export const nextRunAfterFailure = (prev: AutoRun | null, failures: number): AutoRun | null =>
+  failures >= MAX_FAILURES ? null : prev