@marcomigozzi/trailhead 0.17.0 → 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

@@ -97,8 +97,12 @@ only where no mod does (it says the panel is not available). Claude Code only: t
 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 `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). A row is `#n title`
-  (a link to the issue) and the type, dim. Every assigned row shows its holder as `@login`; the ticket
+  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. `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
@@ -141,7 +145,7 @@ projection leaves the `panel` verb out (`CODEX_MOD_ONLY_VERBS` in `bin/lib/codex
   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…`
@@ -252,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
@@ -271,16 +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 (the attached surfaces place no panes). With no surface attached yet (`no-surface`, the start of a session)
-  the pane stays open and the command answers that it 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.
+- **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'

package/plugins/trailhead/hooks/mod/map-pane.tsx

@@ -50,6 +50,8 @@ import {
 } from './map-pane-view'
 import { elsewhereInProgress, myTicketsFromRows, parseLogin, scopeLine } from './my-tickets'
 import { checkoutArg, currentRepo, isPinCheckout, isSamePin, pinKey, pinPath, refreshPin, toplevelOf } from './repo-pin'
+import { gitArgv, scrubGitEnv } from './git-env'
+import { stripHeredocBodies } from './heredoc'
 import { isMainTurnRunning } from './turn-state'
 import { createdIssueNumber, isWhiteboardCreate, nextFollow, whiteboardHint } from './whiteboard-follow'
 import { fit, isMissing, sameValue } from './work-state-view'
@@ -92,6 +94,24 @@ const CHART_ROWS = 3
 // Space between ticket rows on the desktop, whose native buttons would touch; the terminal stays compact.
 const DESKTOP_ROW_GAP = 0.5
 const AMBER = '#e0af68'
+// Ogni sezione ha il suo glifo e colore (palette Tokyo Night del band), così si distinguono anche senza colore.
+const SECTION_STYLES = {
+  maps: { glyph: '◈', color: '#bb9af7' },
+  'in-progress': { glyph: '▶', color: ACCENT },
+  'needs-you': { glyph: '!', color: '#ff9e64' },
+  frontier: { glyph: '◆', color: '#9ece6a' },
+  uat: { glyph: '◎', color: '#7dcfff' },
+  paused: { glyph: '‖', color: '#a9b1d6' },
+  blocked: { glyph: '■', color: '#f7768e' },
+} as const
+type SectionKey = keyof typeof SECTION_STYLES
+// Il filetto a sinistra di ogni riga, nel colore della sezione: occupa GUTTER colonne.
+const GUTTER = '│ '
+// Sul desktop il filetto è una barra continua di questa larghezza, alta quanto tutto il blocco del ticket.
+const GUTTER_BAR = 0.25
+const RULE_COLOR = '#3b4261'
+// Il tipo di ticket colorato; gli altri tipi restano attenuati.
+const TYPE_COLORS: Readonly<Record<string, string>> = { build: '#7dcfff', decision: '#ff9e64' }
 
 const EMPTY: MapPaneData = {
   map: null,
@@ -132,7 +152,8 @@ export const myTickets = atom({ plugin: 'trailhead', key: 'myTickets' } as const
 export const pendingWork = atom({ plugin: 'trailhead', key: 'pendingWork' } as const, null as number | null)
 // Whether that press waits for the running turn to end (cancellable) or was sent to the host.
 export const pendingPhase = atom({ plugin: 'trailhead', key: 'pendingPhase' } as const, null as 'queued' | 'starting' | null)
-// Set once the pane was opened by the command, by itself or closed by the person: never auto-opened after.
+// Set once the auto-open is done: the pane was seen drawn, or the person acted on it (the command, a close by
+// hand, the close button). An unasked open that stays undrawn does not set it; never auto-opened after it is set.
 export const paneAutoOpened = atom({ plugin: 'trailhead', key: 'paneAutoOpened' } as const, false)
 const PENDING = { plugin: 'trailhead', key: 'pendingWork' } as const
 const WORK_COMMAND = 'trailhead:work'
@@ -213,12 +234,15 @@ async function setPane($: Dollar, next: MapPaneData) {
 type GhResult = { ok: true; stdout: string } | { ok: false; reason: string }
 
 // Always run in the pinned repo, so the session's cwd moving out of it never changes what is read.
+// gh resolves {owner}/{repo} through git, so it gets the same scrubbed env as a git call.
 async function gh($: Dollar, pin: RepoPin, args: readonly string[]): Promise<GhResult> {
   try {
-    const out = await $.process.run(['gh', ...args], { cwd: pin.root, timeoutMs: GH_TIMEOUT_MS })
+    const out = await $.process.run(scrubGitEnv(['gh', ...args]), { cwd: pin.root, timeoutMs: GH_TIMEOUT_MS })
     return out.exitCode === 0 ? { ok: true, stdout: out.stdout } : { ok: false, reason: failureReason(out) }
   } catch (error) {
-    return { ok: false, reason: failureReason({ error }) }
+    // A deleted cwd fails the spawn as ENOENT, the same as a missing binary: look before blaming gh.
+    const missingRoot = (await $.fs.exists(pin.root).catch(() => true)) ? undefined : pin.root
+    return { ok: false, reason: failureReason({ error, missingRoot }) }
   }
 }
 
@@ -600,6 +624,10 @@ async function restoreAfterClear($: Dollar) {
 export const GH_ISSUE_WRITE =
   /\bgh\b[^\n;&|]*\bissue\s+(?:edit|close|create|comment|reopen|delete|transfer)\b|\bgh\b(?=[^\n;&|]*\sapi\s)(?=[^\n;&|]*\brepos\/[^\s;&|]*\/issues\b)(?=[^\n;&|]*(?:\s(?:-X|--method)[\s=]*["']?(?:POST|PATCH|PUT|DELETE)\b|\s(?:-[fF]|--field\b|--raw-field\b|--input\b)))(?![^\n;&|]*\s(?:-X|--method)[\s=]*["']?GET\b)|\btrailhead-issue-body\.js\b/
 
+// A tracker write once heredoc bodies are out: a body line is data, never a command (#369). The matcher
+// stays the regex because the host's `command:` takes no function; the handler runs this check first.
+export const isTrackerWrite = (command: string): boolean => GH_ISSUE_WRITE.test(stripHeredocBodies(command))
+
 // The host runs the verb in the session's own directory, which a shell `cd` may have moved, and the mod cannot
 // move it back: `out` hands the pinned checkout to the verb, which moves first (#312). A checkout that cannot
 // be read is `unknown`, refused, but not told it is elsewhere.
@@ -626,7 +654,7 @@ async function placeOf($: Dollar): Promise<{ pin: RepoPin; where: 'in' | 'out' }
 // Whether the pinned root still answers as a checkout root, the same test the verb's helper applies.
 async function isCheckoutRoot($: Dollar, root: string): Promise<boolean> {
   try {
-    const out = await $.process.run(['git', 'rev-parse', '--show-toplevel'], { cwd: root, timeoutMs: 5_000 })
+    const out = await $.process.run(gitArgv('rev-parse', '--show-toplevel'), { cwd: root, timeoutMs: 5_000 })
     return out.exitCode === 0 && out.stdout.trim() === root
   } catch {
     return false
@@ -869,12 +897,17 @@ const pressDashboard = ($: Dollar, isOn: boolean): void => {
 // so the auto-open runs from a zero-delay timer, a dispatch of its own; `isOpening` keeps two
 // renders from opening twice before the flag is written.
 let isOpening = false
+// Quando l'auto-open ha disegnato il pannello: serve a `/trailhead:panel` per riconoscerne uno mai visto.
+let autoOpenedAt: number | null = null
 // Same for the fill an empty pane asks for from its render.
 let isFilling = false
 
-async function openPane($: Dollar) {
-  await update($, paneAutoOpened, () => true)
+// L'auto-open conta come fatto (`paneAutoOpened`) solo quando il pannello è davvero disegnato, o quando la
+// persona è intervenuta (comando, chiusura a mano, bottone close). Un'apertura non richiesta che resta non
+// disegnata non brucia il flag: un trigger successivo (render in fullscreen, `session.attach`) può riprovare.
+async function openPane($: Dollar, isRequested = false) {
   const opened = await $.ui.open({ id: PANE_ID, title: PANE_TITLE })
+  if (isRequested || opened.isPlaced) await update($, paneAutoOpened, () => true)
   if (opened.isPlaced) void requestRefresh($)
   return opened
 }
@@ -883,9 +916,14 @@ async function autoOpen($: Dollar) {
   if (isOpening) return
   isOpening = true
   try {
-    if (!(await $.ui.panes()).some(pane => pane.id === PANE_ID)) await openPane($)
-    // Found up already (a reload with the pane showing): nothing to open, and renders stop asking.
-    else await update($, paneAutoOpened, () => true)
+    const pane = (await $.ui.panes()).find(p => p.id === PANE_ID)
+    if (pane === undefined) {
+      const opened = await openPane($)
+      if (opened.isPlaced) autoOpenedAt = await $.clock.now()
+    }
+    // Found up and drawn (a reload with the pane showing): nothing to open, and renders stop asking.
+    else if (pane.isPlaced) await update($, paneAutoOpened, () => true)
+    // Listed but undrawn: the host places it itself when it can; its own render then completes the auto-open.
   } catch (err) {
     debug($, `trailhead mod: map pane auto-open failed: ${String(err)}`)
   } finally {
@@ -893,28 +931,43 @@ async function autoOpen($: Dollar) {
   }
 }
 
-// Un pannello aperto ma non disegnato (l'auto-open sotto la soglia dei pannelli non richiesti, tipico di
-// una sessione appena aperta) non è visibile: il comando lo riapre, e una richiesta della persona lo
-// disegna a qualsiasi larghezza. Se nemmeno così viene disegnato lo chiude, tranne quando non c'è ancora
-// nessuna superficie (`no-surface`): è l'attesa normale dell'inizio sessione, il pannello resta aperto e
-// viene disegnato appena una superficie si collega (il suo render chiede la prima lettura).
+// Una lettura sola, da un timer a ritardo zero: un render non può scrivere stato.
+async function autoOpenIfDue($: Dollar) {
+  if ((await read($, activeMap)) !== null && !(await read($, paneAutoOpened))) $.clock.after(0, () => void autoOpen($))
+}
+
+// Il render del pannello scatta solo da disegnato: l'auto-open è completato.
+async function markDrawn($: Dollar) {
+  if (!(await read($, paneAutoOpened))) $.clock.after(0, () => void update($, paneAutoOpened, () => true).catch(err => debug($, `trailhead mod: auto-open flag not set: ${String(err)}`)))
+}
+
+// Un pannello aperto ma non disegnato (l'auto-open sotto la soglia dei pannelli non richiesti, o su una
+// superficie che non ha ancora comunicato il layout) non è visibile: il comando lo riapre, e una richiesta
+// della persona lo disegna a qualsiasi larghezza. Se nemmeno così viene disegnato NON lo chiude: la persona
+// non l'ha mai visto, chiuderlo risponderebbe "closed" a un pannello mai mostrato. Resta aperto e viene
+// disegnato appena la superficie può collocarlo. Chiude solo un pannello elencato E disegnato. Senza
+// superficie collegata (`no-surface`, l'inizio sessione) la risposta è l'attesa normale.
 const PENDING_MESSAGE = 'Map panel will open as soon as the screen is ready.'
+const NOT_SHOWN_MESSAGE = 'Map panel is open but not shown yet: it appears once the screen can place it.'
 const isNoSurface = (reason: string) => reason.startsWith('no-surface')
 
+// Il desktop avvia la sessione al primo invio, non al +: un `/trailhead:panel` come primo messaggio arriva
+// pochi millisecondi dopo l'auto-open. Nessuno fa in tempo a vedere il pannello e a digitare il comando sotto
+// questa soglia, quindi la richiesta è di vederlo, non di chiuderlo.
+const UNSEEN_MS = 2_000
+
 async function togglePanel($: Dollar): Promise<string> {
   const pane = (await $.ui.panes()).find(p => p.id === PANE_ID)
-  if (pane?.isPlaced === false) {
-    const reopened = await openPane($)
-    if (reopened.isPlaced) return 'Map panel opened.'
-    if (isNoSurface(reopened.reason)) return PENDING_MESSAGE
-  }
-  if (pane !== undefined) {
+  const isUnseen = autoOpenedAt !== null && (await $.clock.now()) - autoOpenedAt < UNSEEN_MS
+  autoOpenedAt = null
+  if (pane?.isPlaced === true && !isUnseen) {
     await $.ui.close({ id: PANE_ID })
     return 'Map panel closed.'
   }
-  const opened = await openPane($)
+  const opened = await openPane($, true)
   if (opened.isPlaced) return 'Map panel opened.'
-  return isNoSurface(opened.reason) ? PENDING_MESSAGE : `Map panel not shown: ${opened.reason}`
+  debug($, `trailhead mod: map pane not placed: ${opened.reason}`)
+  return isNoSurface(opened.reason) ? PENDING_MESSAGE : NOT_SHOWN_MESSAGE
 }
 
 // The close button: the pane goes (its `ui.close` hook stops the timers). The press counts as the
@@ -970,12 +1023,14 @@ export function registerMapPane(on: On) {
     return result
   })
 
-  // After the call ran: a Bash `gh issue` write changed the tracker.
+  // After the call ran: a Bash `gh issue` write changed the tracker (heredoc bodies not counted).
   on('tool.call', { tool: 'Bash', command: GH_ISSUE_WRITE }, async ($, e, next) => {
+    // The matcher saw the raw text: a write named only inside a heredoc body is no write.
+    if (typeof e.command !== 'string' || !isTrackerWrite(e.command)) return next(e)
     const result = await next(e)
     lastWriteAt = await $.clock.now()
     void requestRefresh($, { isWrite: true })
-    await hintWhiteboard($, e.command, result)
+    await hintWhiteboard($, stripHeredocBodies(e.command), result)
     return result
     // This hook never judges the call: if it fails, the call goes on untouched.
   }).catch((_$, e, next) => next(e))
@@ -986,7 +1041,14 @@ export function registerMapPane(on: On) {
   // Only in fullscreen, where a pane docks beside the transcript; this bare matcher is
   // narrower than the band's, and the band's own hook (in register.tsx) draws after it.
   on('ui.render', { component: 'AbovePrompt', viewport: { isFullscreen: true } }, async ($, e, next) => {
-    if ((await read($, activeMap)) !== null && !(await read($, paneAutoOpened))) $.clock.after(0, () => void autoOpen($))
+    await autoOpenIfDue($)
+    return next(e)
+  })
+
+  // A surface that attaches later (a fresh desktop session) may place the pane the first open could not: with
+  // its layout saying fullscreen, the auto-open tries again. Without a viewport the render trigger decides.
+  on('session.attach', { viewport: { isFullscreen: true } }, async ($, e, next) => {
+    await autoOpenIfDue($)
     return next(e)
   })
 
@@ -999,6 +1061,7 @@ export function registerMapPane(on: On) {
   })
 
   on('ui.render', { component: 'Pane', requestId: PANE_ID }, async ($, e) => {
+    await markDrawn($)
     const ui = $.ui.resolve(e)
     const { Box, Text, Button, Link } = ui
     // Raster is the terminal surface's only; elsewhere the constructor is not a real element.
@@ -1028,14 +1091,45 @@ export function registerMapPane(on: On) {
       </Box>
     )
     const link = (url: string, label: string) => (url === '' ? label : <Link href={url} label={label} />)
+    // Il filetto di un blocco (riga e righe sotto): sul desktop una barra che si allunga quanto il blocco, nel
+    // terminale un `│` per riga. Occupa sempre GUTTER colonne.
+    const gutter = (key: string, section: SectionKey, lines: number) => {
+      const { color } = SECTION_STYLES[section]
+      return e.surface === 'desktop' ? (
+        <Box key={key} width={GUTTER.length}>
+          <Box key={`${key}-bar`} width={GUTTER_BAR} backgroundColor={color} />
+        </Box>
+      ) : (
+        <Box key={key} flexDirection="column" width={GUTTER.length}>
+          {Array.from({ length: lines }, (_, i) => (
+            <Text key={`${key}-${i}`} color={color}>
+              {GUTTER}
+            </Text>
+          ))}
+        </Box>
+      )
+    }
+    // Intestazione di sezione: glifo e nome nel colore della sezione, poi un filetto fino al bordo.
+    const sectionHead = (key: SectionKey, label: string) => {
+      const { glyph, color } = SECTION_STYLES[key]
+      const rest = cols - glyph.length - 1 - label.length - 1
+      return (
+        <Box key={`section-head-${key}`}>
+          {text(`glyph-${key}`, { color }, `${glyph} `)}
+          {text(`head-${key}`, { bold: true, color }, label)}
+          {rest > 0 ? text(`rule-${key}`, { color: RULE_COLOR }, ` ${'─'.repeat(rest)}`) : null}
+        </Box>
+      )
+    }
 
     // The open maps, one row each; shown with several maps open (or with no active map, to pick one).
     // On the dashboard every map is listed and each row opens it.
     const mapRow = (m: MapSummary) => {
-      const r = mapRowLayout(m, { active, viewed, columns: cols, isDashboard: isBoard })
+      const r = mapRowLayout(m, { active, viewed, columns: cols - GUTTER.length, isDashboard: isBoard })
       return (
         <Box key={`map-row-${m.number}`}>
-          {text(`map-mark-${m.number}`, r.isActive ? accent : {}, r.mark)}
+          {gutter(`map-gutter-${m.number}`, 'maps', 1)}
+          {text(`map-mark-${m.number}`, r.isActive ? { bold: true, color: SECTION_STYLES.maps.color } : {}, r.mark)}
           {r.isPressable ? (
             <Button
               key={`map-${m.number}`}
@@ -1052,7 +1146,7 @@ export function registerMapPane(on: On) {
     const isMapsShown = isBoard ? data.maps.length > 0 : data.maps.length > 1 || (active === null && data.maps.length > 0)
     const mapsGroup = isMapsShown ? (
       <Box key="group-maps" flexDirection="column" marginTop={gap}>
-        {text('head-maps', bold, `Maps · ${data.maps.length}`)}
+        {sectionHead('maps', `Maps · ${data.maps.length}`)}
         {data.maps.map(mapRow)}
       </Box>
     ) : null
@@ -1091,18 +1185,20 @@ export function registerMapPane(on: On) {
 
     // This session's own ticket survives a work-state file another session took over; without one, the file decides.
     const isInPlay = (t: PaneTicket) => (own !== null ? t.number === own : play !== null && !orphaned && play.ticket === t.number)
-    const row = (t: PaneTicket, hasMarkColumn: boolean, scope: string | null = null) => {
-      const r = rowLayout(t, { isInPlay: isInPlay(t), hasMarkColumn, pendingWork: pending, pendingPhase: phase, columns: cols })
+    const row = (t: PaneTicket, section: SectionKey, hasMarkColumn: boolean, scope: string | null = null) => {
+      const r = rowLayout(t, { isInPlay: isInPlay(t), hasMarkColumn, pendingWork: pending, pendingPhase: phase, columns: cols - GUTTER.length })
       const style = r.isInPlay ? accent : r.isDim ? dim : {}
       const holder = r.isDim ? dim : {}
+      const typeColor = t.type === null ? undefined : TYPE_COLORS[t.type]
+      const typeStyle = r.isDim || typeColor === undefined ? dim : { color: typeColor }
       const line = (
-        <Box key={`row-${t.number}`} width={cols} justifyContent="space-between">
+        <Box key={`row-${t.number}`} width={cols - GUTTER.length} justifyContent="space-between">
           <Box>
             {r.mark === null ? null : text(`mark-${t.number}`, r.isInPlay ? accent : {}, r.mark)}
             <Box key={`ticket-${t.number}`}>
               <Text {...style}>{link(t.url, r.label)}</Text>
             </Box>
-            {r.type === null ? null : text(`type-${t.number}`, dim, r.type)}
+            {r.type === null ? null : text(`type-${t.number}`, typeStyle, r.type)}
           </Box>
           {r.aside?.kind === 'holder' ? text(`holder-${t.number}`, holder, r.aside.text) : null}
           {r.aside?.kind === 'self' ? text(`self-${t.number}`, { color: ACCENT }, r.aside.text) : null}
@@ -1130,19 +1226,22 @@ export function registerMapPane(on: On) {
           ) : null}
         </Box>
       )
-      const parent = uatParentLine(t, cols)
-      return parent === null && scope === null ? (
-        line
-      ) : (
-        <Box key={`entry-${t.number}`} flexDirection="column">
-          {line}
-          {parent === null ? null : text(`uat-of-${t.number}`, dim, parent)}
-          {scope === null ? null : text(`scope-of-${t.number}`, dim, scope)}
+      // Le righe sotto (genitore UAT, dove sta) rientrano dopo il filetto, che copre tutto il blocco.
+      const parent = uatParentLine(t, cols - GUTTER.length)
+      const lines = 1 + (parent === null ? 0 : 1) + (scope === null ? 0 : 1)
+      return (
+        <Box key={`entry-${t.number}`} width={cols}>
+          {gutter(`gutter-${t.number}`, section, lines)}
+          <Box key={`entry-lines-${t.number}`} flexDirection="column">
+            {line}
+            {parent === null ? null : text(`uat-of-${t.number}`, dim, parent)}
+            {scope === null ? null : text(`scope-of-${t.number}`, dim, scope)}
+          </Box>
         </Box>
       )
     }
     // `elsewhere`: my tickets of other scopes, listed after the shown scope's with the line naming where each is.
-    const group = (key: string, name: string, rows: readonly PaneTicket[], elsewhere: readonly MyTicket[] = []) => {
+    const group = (key: Exclude<SectionKey, 'maps'>, name: string, rows: readonly PaneTicket[], elsewhere: readonly MyTicket[] = []) => {
       if (rows.length + elsewhere.length === 0) return null
       const hasMarkColumn = [...rows, ...elsewhere].some(isInPlay)
       return (
@@ -1152,9 +1251,9 @@ export function registerMapPane(on: On) {
           marginTop={gap}
           {...(e.surface === 'desktop' ? { rowGap: DESKTOP_ROW_GAP } : {})}
         >
-          {text(`head-${key}`, bold, `${name} · ${rows.length + elsewhere.length}`)}
-          {rows.map(t => row(t, hasMarkColumn))}
-          {elsewhere.map(t => row(t, hasMarkColumn, scopeLine(t, data.maps, cols)))}
+          {sectionHead(key, `${name} · ${rows.length + elsewhere.length}`)}
+          {rows.map(t => row(t, key, hasMarkColumn))}
+          {elsewhere.map(t => row(t, key, hasMarkColumn, scopeLine(t, data.maps, cols - GUTTER.length)))}
         </Box>
       )
     }
@@ -1173,7 +1272,7 @@ export function registerMapPane(on: On) {
     const notes = (d: { unverifiedCount: number; isCapped: boolean }) => [
       d.unverifiedCount === 0 ? null : (
         <Box key="unverified" marginTop={gap}>
-          <Text {...dim}>{unverifiedLine(d.unverifiedCount)}</Text>
+          <Text color={AMBER}>{unverifiedLine(d.unverifiedCount)}</Text>
         </Box>
       ),
       !d.isCapped ? null : (