@marcomigozzi/trailhead 0.14.0 → 0.16.0

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,14 +96,41 @@ 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`,
-  `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
+- **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;
+  blocked rows are dim. The `ownTicket` atom keeps that mark when another session's work state takes
+  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 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` 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 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;
@@ -84,9 +139,12 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   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`),
+- **Maps list and viewing**: with more than one open map (one `gh api graphql` call for the open
+  `trailhead:map` issues with their sub-issue counts, bounded at 100 maps, no pagination),
   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
+  Each row ends with a dim `<open> open / <total>` count; if the call fails or is unreadable the pane falls
+  back to `gh issue list --label trailhead:map --state open` and draws the names only.
+  The active map has `●` in the accent and an `active` aside (after the counts, `7 open / 23 · active`); 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
@@ -98,6 +156,47 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   `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.
+- **Whiteboard row**: above the Maps list (in the map view, its loading state and the no-active-map view,
+  even with a single map) a `Whiteboard` button switches the pane to the repo index, the `isDashboard` atom.
+  Beside the name it carries the whiteboard's counts in a map row's shape, dim: `<open> open / <total>`
+  (open whiteboard tickets over all of them). They come from the maps read's single GraphQL call (two
+  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 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 (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
@@ -129,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), `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).
@@ -176,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

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

@@ -0,0 +1,165 @@
+// The autonomous run seen from the main checkout (#296): which slots are in flight and the scope counts.
+// Read-only: the mod only watches, it never writes a work state or the tracker. Pure parts are in
+// auto-run-view.ts; here the engine part that scans the checkouts and reads the counts.
+import type { EngineInterface } from 'claude-code'
+
+import type { AutoRun, RepoPin, RunCounts, WorkState } from '../../types'
+import { GH_TIMEOUT_MS, MIN_REFRESH_MS } from './map-pane'
+import { aggregateRun, isRunMember, nextRunAfterFailure, parseRunCounts, parseRunScope, runCountsArgs, slotTicket } from './auto-run-view'
+import type { Where } from './auto-run-view'
+import { pinKey } from './repo-pin'
+import { listSiblings, listWorktreeBranches, readAt, trim } from './work-state-locate'
+import { isMissing, parseWorkState } from './work-state-view'
+
+const RECORD_PATH = '.trailhead/auto-run.json'
+const GIT_TIMEOUT_MS = 5_000
+
+// L'ultimo run noto e i fallimenti di fila (con l'istante dell'ultimo contato): sono macchinario del modulo, non stato disegnato.
+let lastRun: AutoRun | null = null
+let failures = 0
+let lastFailureAt: number | null = null
+let counts: { key: string; at: number; value: RunCounts | null } | null = null
+
+export const resetAutoRun = (): void => {
+  lastRun = null
+  failures = 0
+  lastFailureAt = null
+  counts = null
+}
+
+// Il run sparisce: anche i conteggi e il loro pavimento.
+export const clearRunCounts = (): void => {
+  counts = null
+}
+
+type Gate = { kind: 'closed' } | { kind: 'open'; scope: string | null } | { kind: 'failed' }
+
+// Il run può esistere solo se c'è il record o lo stato proprio è auto: altrimenti nessun processo parte.
+async function gate($: EngineInterface, main: string, own: WorkState | null): Promise<Gate> {
+  try {
+    const text = (await $.fs.read(`${trim(main)}/${RECORD_PATH}`)) as string
+    return { kind: 'open', scope: parseRunScope(text) }
+  } catch (err) {
+    if (!isMissing(err)) return own?.auto === true ? { kind: 'open', scope: null } : { kind: 'failed' }
+    return own?.auto === true ? { kind: 'open', scope: null } : { kind: 'closed' }
+  }
+}
+
+// La regola di cloneOnBranch (trailhead-auto-slot.js): git dir dentro la cartella e HEAD sul branch dello slot.
+// undefined: git non è riuscito a girare.
+async function cloneOnBranch($: EngineInterface, dir: string, ticket: number): Promise<boolean | undefined> {
+  const git = (args: string[]) => $.process.run(['git', '-C', dir, ...args], { cwd: dir, timeoutMs: GIT_TIMEOUT_MS })
+  try {
+    const g = await git(['rev-parse', '--absolute-git-dir'])
+    if (g.exitCode !== 0) return false
+    const gitDir = trim(g.stdout.trim())
+    if (gitDir !== dir && !gitDir.startsWith(`${dir}/`)) return false
+    const b = await git(['symbolic-ref', '--quiet', 'HEAD'])
+    return b.exitCode === 0 && b.stdout.trim() === `refs/heads/trailhead/t${ticket}`
+  } catch {
+    return undefined
+  }
+}
+
+type Candidate = { path: string; where: Where | { kind: 'sibling'; ticket: number } }
+
+// Un checkout alla volta, senza doppioni: vince la grafia di git, il main e il pin contano come main.
+const candidatesOf = (main: string, pinned: string, listed: readonly { path: string; branch: string | null }[], siblings: readonly string[]): Candidate[] => {
+  const all: Candidate[] = [{ path: trim(main), where: { kind: 'main' } }]
+  if (trim(pinned) !== trim(main)) all.push({ path: trim(pinned), where: { kind: 'main' } })
+  for (const w of listed) {
+    const ticket = slotTicket(w.branch)
+    if (ticket !== null) all.push({ path: trim(w.path), where: { kind: 'worktree', ticket } })
+  }
+  for (const path of siblings) {
+    const ticket = Number(/-t(\d+)$/.exec(path)?.[1])
+    if (ticket > 0) all.push({ path: trim(path), where: { kind: 'sibling', ticket } })
+  }
+  return all.filter((c, i) => all.findIndex(o => o.path === c.path) === i)
+}
+
+type Scan = { ok: true; run: AutoRun | null } | { ok: false }
+
+async function scan($: EngineInterface, main: string, pinned: string): Promise<Scan> {
+  const listed = await listWorktreeBranches($, main)
+  const siblings = await listSiblings($, main)
+  if (listed === null || siblings === null) return { ok: false }
+  const candidates = candidatesOf(main, pinned, listed, siblings)
+  const texts = await Promise.all(candidates.map(c => readAt($, c.path)))
+  if (texts.includes(undefined)) return { ok: false }
+  const members: WorkState[] = []
+  for (const [i, c] of candidates.entries()) {
+    const text = texts[i]
+    const state = typeof text === 'string' ? parseWorkState(text) : null
+    if (state === null || !state.auto) continue
+    let where: Where
+    if (c.where.kind === 'sibling') {
+      // Il controllo git costa due processi: solo per un fratello il cui stato è già auto del suo ticket.
+      if (state.ticket !== c.where.ticket) continue
+      const onBranch = await cloneOnBranch($, c.path, c.where.ticket)
+      if (onBranch === undefined) return { ok: false }
+      where = { kind: 'clone', ticket: c.where.ticket, onBranch }
+    } else where = c.where
+    if (isRunMember(where, state)) members.push(state)
+  }
+  return { ok: true, run: aggregateRun(members) }
+}
+
+// Un turno fa più refresh: un fallimento conta solo se dall'ultimo contato è passato MIN_REFRESH_MS,
+// così un singhiozzo breve di git non azzera un run vivo. Senza orologio ogni fallimento conta.
+async function isNewFailure($: EngineInterface): Promise<boolean> {
+  const now = await nowOf($)
+  if (now === null) return true
+  if (lastFailureAt !== null && now - lastFailureAt < MIN_REFRESH_MS) return false
+  lastFailureAt = now
+  return true
+}
+
+// Il run attuale e lo scope del record. Una scansione fallita tiene l'ultimo risultato per al massimo
+// MAX_FAILURES volte di fila; un miss pulito o il gate chiuso lo azzerano subito.
+export async function scanRun($: EngineInterface, input: { main: string; pinned: string; ownState: WorkState | null }): Promise<{ run: AutoRun | null; scope: string | null }> {
+  const g = await gate($, input.main, input.ownState)
+  if (g.kind === 'closed') {
+    lastRun = null
+    failures = 0
+    lastFailureAt = null
+    return { run: null, scope: null }
+  }
+  const result = g.kind === 'open' ? await scan($, trim(input.main), input.pinned) : ({ ok: false } as const)
+  if (result.ok) {
+    failures = 0
+    lastFailureAt = null
+    lastRun = result.run
+  } else if (await isNewFailure($)) {
+    failures += 1
+    lastRun = nextRunAfterFailure(lastRun, failures)
+  }
+  return { run: lastRun, scope: g.kind === 'open' ? g.scope : null }
+}
+
+async function nowOf($: EngineInterface): Promise<number | null> {
+  try {
+    return await $.clock.now()
+  } catch {
+    return null
+  }
+}
+
+// I conteggi dello scope, mai più spesso di MIN_REFRESH_MS; una lettura fallita tiene gli ultimi.
+export async function readRunCounts($: EngineInterface, pin: RepoPin, scope: string | null): Promise<RunCounts | null> {
+  const key = `${pinKey(pin)}|${scope ?? ''}`
+  const now = await nowOf($)
+  const cached = counts !== null && counts.key === key ? counts : null
+  // Senza orologio non c'è pavimento: niente gh a ruota libera, vale il valore in cache (o nulla).
+  if (now === null) return cached?.value ?? null
+  if (cached !== null && now - cached.at < MIN_REFRESH_MS) return cached.value
+  let value = cached?.value ?? null
+  try {
+    const out = await $.process.run(['gh', ...runCountsArgs(pin.host, pin.slug, scope)], { cwd: pin.root, timeoutMs: GH_TIMEOUT_MS })
+    if (out.exitCode === 0) value = parseRunCounts(out.stdout) ?? value
+  } catch {
+    // Lettura fallita: restano gli ultimi conteggi.
+  }
+  counts = { key, at: now, value }
+  return value
+}