@marcomigozzi/trailhead 0.16.1 → 0.18.0

package/plugins/trailhead/hooks/lib/trailhead-git-env.js

@@ -0,0 +1,40 @@
+'use strict';
+// Repo-location environment for git spawns.
+//
+// Git gives these variables precedence over `-C` and the cwd, so an exported
+// GIT_DIR (a hook, `git rebase --exec`, a parent shell) silently redirects every
+// git call to another repository. Each git spawn in the plugin builds its env
+// through gitEnv() so it always acts on the checkout it was pointed at.
+//
+// The names are `git rev-parse --local-env-vars` minus GIT_CONFIG*: those carry
+// the parent's `-c` options and are meant to be inherited. A static list keeps
+// this free of a git spawn; refresh it from that command when git adds a name.
+// Names must be deleted: an empty string is not "unset" (`fatal: '' is not a git repository`).
+//
+// hooks/lib/trailhead-git-env.js is a byte-identical copy for the hooks (they
+// install without the templates); a test keeps the two in sync.
+
+const GIT_LOCATION_VARS = Object.freeze([
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_IMPLICIT_WORK_TREE',
+  'GIT_GRAFT_FILE',
+  'GIT_INDEX_FILE',
+  'GIT_NO_REPLACE_OBJECTS',
+  'GIT_REPLACE_REF_BASE',
+  'GIT_PREFIX',
+  'GIT_SHALLOW_FILE',
+  'GIT_COMMON_DIR',
+]);
+
+// A new env object: `base` without the repo-location names, then `extra` on top.
+// Never mutates `base` (process.env by default).
+function gitEnv(base = process.env, extra = {}) {
+  const out = {};
+  for (const [k, v] of Object.entries(base)) if (!GIT_LOCATION_VARS.includes(k)) out[k] = v;
+  return { ...out, ...extra };
+}
+
+module.exports = { GIT_LOCATION_VARS, gitEnv };

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

@@ -96,11 +96,21 @@ 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 `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
+- **What it shows**: the map as a link with its destination (dim), then `In progress · n` (first, right under
+  the maps list), `Needs you · n`, `Frontier · n`, `UAT · n`, `Paused · n` and `Blocked · n` (an empty group is left out). Each group, the
+  maps list included, has its own glyph and colour (`◈` Maps violet, `▶` In progress accent, `!` Needs you orange, `◆` Frontier green,
+  `◎` UAT cyan, `‖` Paused grey, `■` Blocked red): the heading is the glyph, the bold name in that colour and a dim rule to the pane's edge, and
+  every ticket's block (its row and the dim lines under it) sits after a gutter in the same colour, so the groups tell apart without
+  colour too: in the terminal a `│ ` on each of its lines, on the desktop one bar as tall as the block; the lines under the row are indented past it. A row is `#n title`
+  (a link to the issue) and the type (`build` cyan, `decision` orange, any other dim; dim on a blocked row). The unverified-count line is amber. 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
+  blocked rows are dim. `In progress` is global for you: after the shown scope's own claimed tickets it lists your
+  open in-progress tickets (assigned to the `gh` login) of every other open map and of the whiteboard, each with a dim
+  `on map #<n> <title>` or `on whiteboard` line under it, in the map view and the Dashboard view alike (never a
+  ticket the view already lists; paused, blocked, UAT and needs-you ones stay in their own scope's groups). The login is
+  read once per host (`viewer{login}`), the tickets by one paged `gh api graphql` read of the open `trailhead:ticket`
+  issues with `filterBy:{assignee:<login>}`, in the same refresh as the view's reads; a failed or unreadable read keeps
+  the last list (the `myTickets` atom) and sets no footer error. 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
@@ -108,7 +118,7 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   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
+  clears it) shows once, under `Needs you`, between In progress and 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
@@ -128,13 +138,14 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   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
+  (base64url of the root, a `.`, then base64url of the repo as `host/owner/name`) and the verb `cd`s there first;
+  if the root has moved, the verb finds the checkout again by the repo's `origin` remote. 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;
-  reasons: `gh not installed`, `gh not authenticated (run gh auth login)`,
+  reasons: `gh not installed`, `checkout not found: <path>` (the pinned folder is gone and no other checkout of the repo was found), `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…`
@@ -185,7 +196,7 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   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,
+  `trailhead:ticket` + `trailhead:whiteboard` tickets as In progress / Needs you / Frontier / 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
@@ -245,14 +256,17 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   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
+  pane held for the old one. A pinned checkout deleted since (a finished worktree) moves the pin, silently, to a live checkout of
+  the same repo: the main working tree, else another `git worktree`, else a same-remote clone beside it (probes run as `git -C`
+  from `/`, retried at most once a minute). 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 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` (save the turn-end read below): a request inside the floor
+  (`GH_ISSUE_WRITE`), outside any heredoc body (`isTrackerWrite`: a body is data, so a `gh issue close` line in a
+  `cat <<EOF` writes nothing); reads never refresh. Never two fetches inside `MIN_REFRESH_MS` (save the turn-end read below): 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, and one more when the turn ends after it. The host drops a refused timer without a word (a refused `every` period ends
@@ -264,14 +278,25 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   involved; it leaves an armed trailing refresh alone, so the read after the search index caught up still follows.
   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).
+- **Auto-open**: in fullscreen (`e.viewport.isFullscreen === true` in the `AbovePrompt` render, or in the
+  viewport of a `session.attach`, so a surface that attaches later tries again), when a map is active. Never on
+  the main screen, never again after the person acted on the pane (the command, closing it by hand, the `close`
+  button). The open runs from a zero-delay timer because a render may not write state.
+  The auto-open counts as done only once the pane is actually drawn (seen placed by a later check, or by the pane's
+  own render, which fires only when drawn). Being unasked, the open can stay undrawn (`isPlaced: false`): below
+  144 columns, or on a surface that has not reported its layout yet, typical of a fresh session. That does not burn
+  the auto-open: while the pane is listed undrawn nothing opens it again (the host places it itself when it can),
+  and if it vanishes undrawn the next trigger opens it again. `/trailhead:panel` closes a pane only when it is
+  listed and drawn; a listed but undrawn pane is opened again as the person's request (drawn at any width), and if
+  even that leaves it undrawn the pane stays open and the command says so in a fixed sentence (`Map panel is open but not shown yet: ...`; the host's reason goes to the
+  debug log only), so it is never closed unseen. With no surface attached yet (`no-surface`, the start of a session) the command answers
+  that the panel will open once the screen is ready, again on every repeat; the pane's first render on the surface
+  that attaches asks for its read. A desktop session starts at its first message, not when it is created, so nothing
+  can open the pane on a session where nothing was typed, and a `/trailhead:panel` sent as that first message lands
+  right after the auto-open. Within `UNSEEN_MS` of a drawn auto-open the command keeps the pane and answers
+  `Map panel opened.` instead of closing a pane nobody could have seen.
 - **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`, `TIMER_GRACE_MS = 30_000`,
+  `MIN_REFRESH_MS = 15_000`, `TIMER_MS = 180_000`, `GH_TIMEOUT_MS = 20_000`, `TIMER_GRACE_MS = 30_000`, `UNSEEN_MS = 2_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`),

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

@@ -4,6 +4,7 @@
 import type { EngineInterface } from 'claude-code'
 
 import type { AutoRun, RepoPin, RunCounts, WorkState } from '../../types'
+import { gitArgv } from './git-env'
 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'
@@ -48,7 +49,7 @@ async function gate($: EngineInterface, main: string, own: WorkState | null): Pr
 // 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 })
+  const git = (args: string[]) => $.process.run(gitArgv('-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

package/plugins/trailhead/hooks/mod/git-env.ts

@@ -0,0 +1,31 @@
+// Leaf without imports: git argv for the mod's process spawns.
+//
+// Git gives the repo-location variables precedence over `-C` and the cwd, and
+// `$.process.run` can only add or override env, never delete. So an inherited
+// GIT_DIR would redirect every git spawn: wrap the argv in `env -u NAME ...`.
+// The list is templates/trailhead-git-env.js's GIT_LOCATION_VARS (git rev-parse
+// --local-env-vars minus GIT_CONFIG*); hooks/lib/git-env-mod.test.js keeps them equal.
+export const GIT_LOCATION_VARS: readonly string[] = [
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_IMPLICIT_WORK_TREE',
+  'GIT_GRAFT_FILE',
+  'GIT_INDEX_FILE',
+  'GIT_NO_REPLACE_OBJECTS',
+  'GIT_REPLACE_REF_BASE',
+  'GIT_PREFIX',
+  'GIT_SHALLOW_FILE',
+  'GIT_COMMON_DIR',
+]
+
+// `argv` run with the repo-location variables removed from its env.
+export const scrubGitEnv = (argv: readonly string[]): string[] => [
+  'env',
+  ...GIT_LOCATION_VARS.flatMap(name => ['-u', name]),
+  ...argv,
+]
+
+// `git <args>` that acts on the checkout it is pointed at (-C / cwd), never on an inherited GIT_DIR.
+export const gitArgv = (...args: readonly string[]): string[] => scrubGitEnv(['git', ...args])

package/plugins/trailhead/hooks/mod/heredoc.ts

@@ -0,0 +1,79 @@
+// Leaf without imports: heredoc bodies out of a Bash command (#369).
+//
+// A heredoc body is data (a file being written), not commands, so a `gh issue close` line inside
+// one is no tracker write. Only the opener line stays, with every body and terminator line dropped.
+// The mod imports nothing from hooks/lib, so this is a small twin of shell-scan.js's
+// stripHeredocBodies; hooks/lib/heredoc-mod.test.js keeps their output equal.
+// When it cannot tell, a line is kept: a lost write leaves a stale pane, an extra read costs one `gh` call.
+// Known difference: an opener inside `$(..)` is not seen here (shell-scan sees it), so those lines stay.
+
+// The heredoc openers of one line, in order: [{ tag, isDash }]. A `<<` counts outside quotes and outside
+// `((..))` arithmetic, and not as a here-string (`<<<`); an opener with no word after it is no opener.
+// The scan stops at an unquoted `#` that starts a comment (line start, or after whitespace or `;&|(`).
+// `quoteIn` is the quote still open from an earlier line; the quote open at the end of the line is returned.
+function openersOf(
+  line: string,
+  quoteIn: string,
+): { found: Array<{ tag: string; isDash: boolean }>; quote: string } {
+  const found: Array<{ tag: string; isDash: boolean }> = []
+  let quote = quoteIn
+  let arith = 0
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i]
+    if (quote !== '') {
+      if (c === '\\' && quote === '"') i++
+      else if (c === quote) quote = ''
+    } else if (c === '\\') {
+      i++
+    } else if (line.startsWith('${', i)) {
+      // A parameter expansion holds no opener (`${x:-<<EOF}`); skip to its `}`, or the rest of the line.
+      const end = line.indexOf('}', i)
+      if (end < 0) break
+      i = end
+    } else if (c === '#' && (i === 0 || /[\s;&|(]/.test(line[i - 1]))) {
+      break
+    } else if (c === "'" || c === '"') {
+      quote = c
+    } else if (line.startsWith('((', i)) {
+      arith++
+      i++
+    } else if (arith > 0 && line.startsWith('))', i)) {
+      arith--
+      i++
+    } else if (arith === 0 && line.startsWith('<<', i)) {
+      if (line[i + 2] === '<') {
+        i += 2
+        continue
+      }
+      const isDash = line[i + 2] === '-'
+      const word = /^\s*((?:\\.|'[^']*'|"[^"]*"|[^\s;&|<>()'"\\])+)/.exec(line.slice(i + (isDash ? 3 : 2)))
+      if (word !== null) {
+        found.push({ tag: word[1].replace(/\\(.)|['"]/g, '$1'), isDash })
+        i += (isDash ? 3 : 2) + word[0].length - 1
+      } else {
+        i++
+      }
+    }
+  }
+  return { found, quote }
+}
+
+// Every line from an opener to its terminator (the terminator included) goes; a body that never ends
+// takes the rest of the command, as the shell reads it.
+export function stripHeredocBodies(command: string): string {
+  const lines = command.split('\n')
+  const kept: string[] = []
+  let quote = ''
+  for (let i = 0; i < lines.length; i++) {
+    kept.push(lines[i])
+    const scan = openersOf(lines[i], quote)
+    quote = scan.quote
+    for (const { tag, isDash } of scan.found) {
+      while (i + 1 < lines.length) {
+        i++
+        if ((isDash ? lines[i].replace(/^\t+/, '') : lines[i]) === tag) break
+      }
+    }
+  }
+  return kept.join('\n')
+}

package/plugins/trailhead/hooks/mod/map-pane-view.ts

@@ -15,7 +15,8 @@ export type TicketGroups = {
   paused: readonly PaneTicket[]
   blocked: readonly PaneTicket[]
 }
-export type Failure = { error: unknown } | { exitCode: number; stderr: string }
+// `missingRoot`: the folder `gh` was to run in, when it no longer exists (a spawn there fails like a missing binary).
+export type Failure = { error: unknown; missingRoot?: string } | { exitCode: number; stderr: string }
 export type RefreshDecision = { run: true } | { run: false; waitMs: number }
 
 // The most rows one `gh issue list` is asked for.
@@ -429,6 +430,7 @@ const errorText = (err: unknown): string => {
 // One short line saying why `gh` gave nothing.
 export const failureReason = (failure: Failure): string => {
   if ('error' in failure) {
+    if (failure.missingRoot !== undefined) return `checkout not found: ${failure.missingRoot}`
     const text = errorText(failure.error)
     if (/ENOENT|not found/i.test(text)) return 'gh not installed'
     if (/timed? ?out/i.test(text)) return 'offline: cannot reach GitHub'