@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/plugins/trailhead/hooks/mod/session-registry.ts

@@ -0,0 +1,65 @@
+// Liveness di una sessione Claude Code dal registro del motore (<config>/sessions/<pid>.json,
+// con `sessionId` e `pid`). Nessuna chiamata al motore qui: fs e controllo del pid sono iniettati.
+// Il registro e' interno e non tipizzato, quindi ogni dubbio (cartella illeggibile, file non
+// parsabile, registro vuoto) vale "unknown", mai "gone".
+
+export type Liveness = 'live' | 'gone' | 'unknown'
+
+export type RegistryDeps = {
+  // I nomi dei file della cartella del registro; rifiuta se non si legge.
+  list: (dir: string) => Promise<string[]>
+  read: (path: string) => Promise<string>
+  // true/false se il pid si sa vivo/morto, null se la piattaforma non lo dice (conta la sola presenza).
+  pidAlive: (pid: number) => Promise<boolean | null>
+}
+
+type Entry = { sessionId: string; pid: number }
+
+const parseEntry = (text: string): Entry | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    return null
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const r = raw as Record<string, unknown>
+  if (typeof r.sessionId !== 'string' || r.sessionId === '') return null
+  if (!Number.isInteger(r.pid) || (r.pid as number) <= 0) return null
+  return { sessionId: r.sessionId, pid: r.pid as number }
+}
+
+export async function sessionLiveness(dir: string, sessionId: string, deps: RegistryDeps): Promise<Liveness> {
+  let names: string[]
+  try {
+    names = (await deps.list(dir)).filter(name => name.endsWith('.json'))
+  } catch {
+    return 'unknown'
+  }
+  let parsed = 0
+  let doubtful = false
+  for (const name of names) {
+    let entry: Entry | null = null
+    try {
+      entry = parseEntry(await deps.read(`${dir}/${name}`))
+    } catch {
+      entry = null
+    }
+    if (entry === null) {
+      doubtful = true
+      continue
+    }
+    parsed += 1
+    if (entry.sessionId !== sessionId) continue
+    let alive: boolean | null
+    try {
+      alive = await deps.pidAlive(entry.pid)
+    } catch {
+      alive = null
+    }
+    if (alive !== false) return 'live'
+  }
+  // Nessuna voce leggibile (la sessione corrente dovrebbe esserci) o file che non si leggono: non si sa.
+  if (parsed === 0 || doubtful) return 'unknown'
+  return 'gone'
+}

package/plugins/trailhead/hooks/mod/turn-state.ts

@@ -0,0 +1,14 @@
+// Whether a main-loop turn is running, shared by the band (register.tsx) and the map pane, which each
+// need it and may not hook the same event twice with the same matcher. Module state: a hot reload
+// resets it to idle, which only costs a held press being released early.
+let isRunning = false
+
+export const markTurnStart = (): void => {
+  isRunning = true
+}
+
+export const markTurnComplete = (): void => {
+  isRunning = false
+}
+
+export const isMainTurnRunning = (): boolean => isRunning

package/plugins/trailhead/hooks/mod/whiteboard-follow.ts

@@ -0,0 +1,98 @@
+// Pure rules of the map panel following the whiteboard (#306): when this session takes a whiteboard
+// ticket the panel shows the whiteboard once, and a whiteboard ticket created from a map raises a hint.
+// No atoms and no engine calls here, so the rules are easy to test.
+import type { WorkState } from '../../types'
+
+export const WHITEBOARD_LABEL = 'trailhead:whiteboard'
+
+export type Follow = { follow: boolean; memo: number | null }
+
+// Follow once per ticket: the memo is the last ticket followed, kept by the caller across a /clear.
+// A null state (no file, cleared by Resolve) changes nothing; a map ticket, a foreign or an orphaned state
+// is never followed and leaves the memo as it was.
+export const nextFollow = (memo: number | null, state: WorkState | null, own: number | null, isOrphaned: boolean): Follow => {
+  if (state === null || state.map !== null || isOrphaned || own === null || state.ticket !== own) return { follow: false, memo }
+  return state.ticket === memo ? { follow: false, memo } : { follow: true, memo: state.ticket }
+}
+
+// The command split into shell segments of words: quotes group (and are dropped), a backslash escapes outside
+// single quotes, a backslash-newline joins lines, and an unquoted `;`, `&`, `|` or newline ends a segment.
+// Enough shell for reading flags, not a full parser: no expansion, no heredocs.
+const SEPARATORS = new Set([';', '&', '|', '\n'])
+
+function segmentsOf(command: string): string[][] {
+  const segments: string[][] = []
+  let words: string[] = []
+  let word: string | null = null
+  let quote: '"' | "'" | null = null
+  const endWord = () => {
+    if (word !== null) words = [...words, word]
+    word = null
+  }
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i]
+    if (quote !== null) {
+      if (ch === quote) quote = null
+      else if (ch === '\\' && quote === '"' && i + 1 < command.length) word = (word ?? '') + command[++i]
+      else word = (word ?? '') + ch
+    } else if (ch === '\\' && command[i + 1] === '\n') i++
+    else if (ch === '\\' && i + 1 < command.length) word = (word ?? '') + command[++i]
+    else if (ch === '"' || ch === "'") {
+      quote = ch
+      word = word ?? ''
+    } else if (SEPARATORS.has(ch)) {
+      endWord()
+      if (words.length > 0) segments.push(words)
+      words = []
+    } else if (/\s/.test(ch)) endWord()
+    else word = (word ?? '') + ch
+  }
+  endWord()
+  if (words.length > 0) segments.push(words)
+  return segments
+}
+
+const isCreate = (words: string[]): boolean => {
+  const at = words.indexOf('issue')
+  return words.includes('gh') && at >= 0 && words[at + 1] === 'create'
+}
+
+// The values of every label flag: `--label X`, `--label=X`, `-l X`, `-lX`.
+function labelValues(words: string[]): string[] {
+  const values: string[] = []
+  words.forEach((w, i) => {
+    if ((w === '--label' || w === '-l') && i + 1 < words.length) values.push(words[i + 1])
+    else if (w.startsWith('--label=')) values.push(w.slice('--label='.length))
+    else if (w.startsWith('-l') && !w.startsWith('--') && w.length > 2) values.push(w.slice(2))
+  })
+  return values
+}
+
+// A `gh issue create` whose label flags (repeated, `=` or space, comma lists, quoted) carry the whiteboard
+// label. Only the create's own segment counts, so a label named in another command never does.
+export const isWhiteboardCreate = (command: string): boolean =>
+  segmentsOf(command)
+    .filter(isCreate)
+    .some(words => labelValues(words).some(v => v.split(',').some(label => label.trim() === WHITEBOARD_LABEL)))
+
+const ISSUE_URL = /\/issues\/(\d+)\s*$/
+
+const textOf = (value: unknown): string | null => {
+  if (typeof value === 'string') return value
+  const stdout = (value as { stdout?: unknown } | null)?.stdout
+  return typeof stdout === 'string' ? stdout : null
+}
+
+// The number `gh issue create` printed (the issue URL is its last line), from what `next(e)` resolved to:
+// the Bash `result` is `{ stdout }` or a plain string; the call's `text` is the fallback. An errored call,
+// or output with no issue URL, gives none.
+export const createdIssueNumber = (call: unknown): number | null => {
+  const c = call as { result?: unknown; text?: unknown; isError?: unknown } | null
+  if (c === null || typeof c !== 'object' || c.isError === true) return null
+  const out = textOf(c.result) ?? textOf(c.text)
+  const m = out === null ? null : ISSUE_URL.exec(out.trimEnd())
+  return m === null ? null : Number(m[1])
+}
+
+// The toast box is narrow: a few words.
+export const whiteboardHint = (n: number): string => `new whiteboard ticket #${n}: open Whiteboard`

package/plugins/trailhead/hooks/mod/work-state-locate.ts

@@ -0,0 +1,191 @@
+// Where the session's work state lives when it is not in the pinned checkout (#270): the engine writes
+// it in the per-ticket workspace (a git worktree or a sibling clone `<repo>-t<n>`), while the session
+// may sit in the main checkout. Pure parts first, then the engine part that looks the state up.
+import type { EngineInterface } from 'claude-code'
+
+import { isMissing, parseWorkState } from './work-state-view'
+import { MAX_FAILURES, parseWorktreeBranches } from './worktree-porcelain'
+
+const STATE_PATH = '.trailhead/work-state.json'
+const LOOKUP_TIMEOUT_MS = 5_000
+
+export const dirname = (path: string): string => path.replace(/\/+$/, '').replace(/\/[^/]*$/, '') || '/'
+const basename = (path: string): string => path.replace(/\/+$/, '').replace(/^.*\//, '')
+export const trim = (path: string): string => (path.length > 1 ? path.replace(/\/+$/, '') : path)
+
+// The checkout paths of `git worktree list --porcelain`, in the order git prints them (main first).
+export const parseWorktrees = (porcelain: string): string[] => parseWorktreeBranches(porcelain).map(w => w.path)
+
+// The per-ticket clones beside the main working tree: `<basename>-t<digits>`, sorted.
+export const siblingClones = (mainRoot: string, names: readonly string[]): string[] => {
+  const base = basename(mainRoot).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const parent = dirname(mainRoot)
+  const pattern = new RegExp(`^${base}-t\\d+$`)
+  return names
+    .filter(name => pattern.test(name))
+    .sort()
+    .map(name => `${parent === '/' ? '' : parent}/${name}`)
+}
+
+// Where to look, in order: the worktrees, then the sibling clones.
+// The pinned root is the own read, which already missed; no path twice.
+export const candidates = (pinned: string, worktrees: readonly string[], siblings: readonly string[]): string[] => {
+  const all = [...worktrees, ...siblings].map(trim)
+  return all.filter((path, i) => path !== trim(pinned) && all.indexOf(path) === i)
+}
+
+// A state is this session's only when it names the session: a state with no session, or another's, is not adopted.
+export const isOwnState = (text: string, session: string): boolean => parseWorkState(text)?.session === session
+
+// A state that names another session (a state with no session is nobody's, shown as is).
+export const isForeignState = (text: string, session: string): boolean => {
+  const owner = parseWorkState(text)?.session
+  return owner !== undefined && owner !== null && owner !== session
+}
+
+// The first candidate's text that is this session's state.
+export const pickOwn = (texts: readonly (string | null)[], session: string): number => texts.findIndex(text => text !== null && isOwnState(text, session))
+
+// The checkout where this session's state was last found, with the repo it belongs to; machinery, like
+// `remembered` in repo-pin.ts. A checkout of another repo is never tried.
+let lastFound: { key: string; root: string } | null = null
+
+// A hit ends the run of failed lookups for the repo.
+export const noteFound = (found: { key: string; root: string } | null): void => {
+  lastFound = found
+  if (found !== null) for (const memo of failures.keys()) if (memo.startsWith(`${found.key}|`)) failures.delete(memo)
+}
+// Whether the state was last found in this repo, in a checkout other than the pinned one.
+export const wasFoundElsewhere = (key: string, pinned: string): boolean =>
+  lastFound !== null && lastFound.key === key && trim(lastFound.root) !== trim(pinned)
+
+// A scan that found nothing is not repeated for NO_STATE_MS, per repo and session. Time comes from the
+// engine clock; without one nothing is kept.
+const NO_STATE_MS = 10_000
+const misses = new Map<string, number>()
+// A scan that failed is remembered for a shorter while, with how many failed in a row: past MAX_FAILURES
+// the caller stops keeping the last state and treats the file as missing.
+const FAILED_MS = 3_000
+const failures = new Map<string, { at: number | null; count: number }>()
+
+// Writes a miss time, dropping the misses whose window has ended.
+const remember = (map: Map<string, number>, key: string, now: number, windowMs: number): void => {
+  for (const [k, at] of map) if (now - at >= windowMs) map.delete(k)
+  map.set(key, now)
+}
+
+export const resetLocate = (): void => {
+  lastFound = null
+  misses.clear()
+  failures.clear()
+}
+
+async function nowOf($: EngineInterface): Promise<number | null> {
+  try {
+    return await $.clock.now()
+  } catch {
+    return null
+  }
+}
+
+// null: the listing itself failed (not the same as an empty one). Path and branch of each checkout.
+export async function listWorktreeBranches($: EngineInterface, root: string): Promise<{ path: string; branch: string | null }[] | null> {
+  try {
+    const out = await $.process.run(['git', 'worktree', 'list', '--porcelain'], { cwd: root, timeoutMs: LOOKUP_TIMEOUT_MS })
+    return out.exitCode === 0 ? parseWorktreeBranches(out.stdout) : null
+  } catch {
+    return null
+  }
+}
+
+async function listWorktrees($: EngineInterface, root: string): Promise<string[] | null> {
+  return (await listWorktreeBranches($, root))?.map(w => w.path) ?? null
+}
+
+export async function listSiblings($: EngineInterface, mainRoot: string): Promise<string[] | null> {
+  try {
+    const entries = await $.fs.list(dirname(mainRoot))
+    return siblingClones(mainRoot, entries.filter(entry => entry.kind === 'dir').map(entry => entry.name))
+  } catch {
+    return null
+  }
+}
+
+// The file's text; null when it is not there, undefined when the read failed any other way.
+export async function readAt($: EngineInterface, root: string): Promise<string | null | undefined> {
+  try {
+    return (await $.fs.read(`${root}/${STATE_PATH}`)) as string
+  } catch (err) {
+    return isMissing(err) ? null : undefined
+  }
+}
+
+export type Lookup = { kind: 'found'; text: string; root: string } | { kind: 'none' } | { kind: 'failed' }
+
+const NONE: Lookup = { kind: 'none' }
+
+async function scan($: EngineInterface, pinned: string, session: string): Promise<{ kind: 'found'; text: string; root: string } | { kind: 'miss'; hadFailure: boolean }> {
+  const worktrees = await listWorktrees($, pinned)
+  const siblings = await listSiblings($, worktrees?.[0] ?? pinned)
+  const roots = candidates(pinned, worktrees ?? [], siblings ?? [])
+  const texts = await Promise.all(roots.map(root => readAt($, root)))
+  const i = pickOwn(texts.map(text => text ?? null), session)
+  if (i !== -1) return { kind: 'found', text: texts[i] as string, root: roots[i] }
+  return { kind: 'miss', hadFailure: worktrees === null || siblings === null || texts.includes(undefined) }
+}
+
+// This session's state from another checkout of the repo. 'none' is a clean miss; 'failed' means the
+// lookup itself broke (git, the listing, a read), so the caller keeps what it had. `fresh` skips the
+// no-state memory (a helper call just wrote a state).
+export async function locateOwnState($: EngineInterface, pin: { key: string; root: string }, session: string, fresh = false): Promise<Lookup> {
+  const memo = `${pin.key}|${session}`
+  try {
+    // The remembered checkout of this repo is read first and alone, so a steady state costs no process.
+    const first = lastFound !== null && lastFound.key === pin.key && trim(lastFound.root) !== trim(pin.root) ? lastFound.root : null
+    const fast = first === null ? null : await readAt($, first)
+    if (first !== null && typeof fast === 'string' && isOwnState(fast, session)) {
+      failures.delete(memo)
+      return { kind: 'found', text: fast, root: first }
+    }
+    const now = await nowOf($)
+    const seen = misses.get(memo)
+    const failed = failures.get(memo)
+    if (!fresh && now !== null && seen !== undefined && now - seen < NO_STATE_MS) return NONE
+    if (!fresh && now !== null && failed?.at != null && now - failed.at < FAILED_MS) return failedLookup(failed.count)
+    const result = await scan($, pin.root, session)
+    if (result.kind === 'miss' && result.hadFailure) {
+      const count = (failed?.count ?? 0) + 1
+      setFailure(memo, count, now)
+      return failedLookup(count)
+    }
+    failures.delete(memo)
+    if (result.kind === 'found') {
+      misses.delete(memo)
+      noteFound({ key: pin.key, root: result.root })
+      return result
+    }
+    if (now !== null) remember(misses, memo, now, NO_STATE_MS)
+    if (lastFound?.key === pin.key) noteFound(null)
+    return NONE
+  } catch {
+    return failedLookup(bump(memo, await nowOf($)))
+  }
+}
+
+// Failed lookups in a row count against the keep: the MAX_FAILURES-th reads as a missing file.
+const failedLookup = (count: number): Lookup => (count >= MAX_FAILURES ? NONE : { kind: 'failed' })
+
+// The run of failures for the key; only a success ends it, however far apart the failures are. Writing
+// one drops the runs of other keys that are long gone.
+const FAILURE_KEEP_MS = 600_000
+
+function setFailure(memo: string, count: number, now: number | null): void {
+  for (const [k, v] of failures) if (k !== memo && (v.at === null || (now !== null && now - v.at >= FAILURE_KEEP_MS))) failures.delete(k)
+  failures.set(memo, { at: now, count })
+}
+
+function bump(memo: string, now: number | null): number {
+  const count = (failures.get(memo)?.count ?? 0) + 1
+  setFailure(memo, count, now)
+  return count
+}

package/plugins/trailhead/hooks/mod/work-state-prompt.ts

@@ -8,12 +8,8 @@ const ELLIPSIS = '…'
 const encoder = new TextEncoder()
 const bytes = (text: string): number => encoder.encode(text).length
 
-// owner/name from a GitHub origin URL (https, scp form, ssh); null for anything else.
-export const repoSlug = (remote: string | null): string | null => {
-  if (remote === null) return null
-  const m = /^(?:https?:\/\/|ssh:\/\/git@|git@)github\.com[/:]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(remote.trim())
-  return m === null ? null : `${m[1]}/${m[2]}`
-}
+// The repo the links point at: host and owner/name of the pin.
+export type LinkRepo = { host: string; slug: string }
 
 // Flat single line, cut by code point so a surrogate pair is never split.
 // Zero-width and bidi controls are dropped, so the title cannot hide or reorder text.
@@ -40,7 +36,7 @@ const capBytes = (text: string): string => {
   return out
 }
 
-const link = (slug: string | null, n: number): string => (slug === null ? '' : ` https://github.com/${slug}/issues/${n}`)
+const link = (repo: LinkRepo | null, n: number): string => (repo === null ? '' : ` https://${repo.host}/${repo.slug}/issues/${n}`)
 
 const stepLine = (step: string | null): string => {
   const live = 'may have moved on since this snapshot; .trailhead/work-state.json holds the live one'
@@ -48,13 +44,13 @@ const stepLine = (step: string | null): string => {
   return `Step: ${step ?? 'unknown'} (${live})`
 }
 
-export const promptSection = (state: WorkState | null, orphaned: boolean, slug: string | null): string | null => {
+export const promptSection = (state: WorkState | null, orphaned: boolean, repo: LinkRepo | null): string | null => {
   if (state === null || state.ticket === null || orphaned) return null
   const title = state.title === null ? '' : ` "${cutTitle(state.title)}"`
   const lines = [
     '# trailhead work state',
-    state.map === null ? 'Map: none (whiteboard ticket)' : `Map: #${state.map}${link(slug, state.map)}`,
-    `Ticket: #${state.ticket}${title}${link(slug, state.ticket)}`,
+    state.map === null ? 'Map: none (whiteboard ticket)' : `Map: #${state.map}${link(repo, state.map)}`,
+    `Ticket: #${state.ticket}${title}${link(repo, state.ticket)}`,
     stepLine(state.step),
   ]
   if (state.auto) lines.push('Mode: autonomous run')
@@ -62,8 +58,10 @@ export const promptSection = (state: WorkState | null, orphaned: boolean, slug:
   return capBytes(lines.join('\n'))
 }
 
-// What a rebuild keys on: step and autoDone are left out so the text stays cache-stable.
-export const snapshotKey = (state: WorkState | null, orphaned: boolean): string =>
-  JSON.stringify(
-    state === null ? [null, orphaned] : [state.map, state.ticket, state.title, orphaned, state.auto],
-  )
+// What a rebuild keys on: step and autoDone are left out so the text stays cache-stable. The repo is in it,
+// so a pin that moves rebuilds the links.
+export const snapshotKey = (state: WorkState | null, orphaned: boolean, repo: LinkRepo | null): string =>
+  JSON.stringify([
+    repo === null ? null : `${repo.host}/${repo.slug}`,
+    ...(state === null ? [null, orphaned] : [state.map, state.ticket, state.title, orphaned, state.auto]),
+  ])

package/plugins/trailhead/hooks/mod/work-state-view.ts

@@ -1,6 +1,7 @@
 // Pure view logic of the trailhead mod: parse the work state file, build the
 // status line and the pipeline stages. No engine calls here, so it is easy to test.
-import type { WorkState } from '../../types'
+import type { AutoRun, RunCounts, WorkState } from '../../types'
+import { RESUME_HINT_STATUS, runLabel, runParts } from './auto-run-view'
 
 export const STEPS = ['discuss', 'plan', 'execute', 'verify', 'resolve', 'paused'] as const
 export const STAGES = ['discuss', 'plan', 'execute', 'verify'] as const
@@ -11,6 +12,7 @@ export type Stage = { name: StageName; status: StageStatus }
 export type Pipeline = { stages: readonly Stage[]; isPaused: boolean }
 
 const ELLIPSIS = '…'
+export const ELSEWHERE = 'in another session'
 
 // Cuts by code point, so a surrogate pair (an emoji in an issue title) is never split.
 export const fit = (text: string, room: number): string => {
@@ -85,15 +87,29 @@ export const nextOwnTicket = (
 
 export const sameValue = (a: unknown, b: unknown): boolean => stableJson(a) === stableJson(b)
 
-export const statusLine = (state: WorkState | null, isOrphaned: boolean): string | undefined => {
-  if (state === null || state.ticket === null) return undefined
+// What the autonomous run adds to the status: the run found beside the main checkout, its scope counts, and
+// whether the resume hint shows. `elsewhere`: the foreign state's session is not known gone, so the
+// status words it neutrally instead of offering to resume it.
+export type RunInfo = { run: AutoRun | null; counts: RunCounts | null; hint: boolean; elsewhere?: boolean }
+
+export const statusLine = (state: WorkState | null, isOrphaned: boolean, info?: RunInfo): string | undefined => {
+  const hint = info?.hint === true ? RESUME_HINT_STATUS : null
+  if (state === null || state.ticket === null) {
+    // Nessuno stato proprio: il run (slot senza sessione) o il suggerimento di ripresa, se ce ne sono.
+    if (hint !== null) return hint
+    return info?.run == null ? undefined : runLabel(info.run, info.counts)
+  }
   const where = state.map === null ? 'whiteboard' : `map #${state.map}`
   const ticket = state.title === null ? `#${state.ticket}` : `#${state.ticket} ${state.title}`
   // No own "trailhead" prefix: the engine already prefixes a plugin's status with its name.
   const parts = [where, ticket]
   if (state.step !== null) parts.push(state.step)
-  if (state.auto) parts.push(`auto ${state.autoDone} done`)
-  if (isOrphaned) parts.push('orphaned, resume?')
+  if (state.auto) {
+    const [first, ...rest] = runParts(info?.run ?? { done: state.autoDone }, info?.counts ?? null)
+    parts.push(`auto ${first}`, ...rest)
+  }
+  if (isOrphaned) parts.push(info?.elsewhere === true ? ELSEWHERE : 'orphaned, resume?')
+  if (hint !== null) parts.push(hint)
   return parts.join(' · ')
 }
 

package/plugins/trailhead/hooks/mod/worktree-porcelain.ts

@@ -0,0 +1,17 @@
+// Foglia senza import, condivisa da work-state-locate e dal run autonomo: il parser di
+// `git worktree list --porcelain` e il tetto dei fallimenti di fila.
+
+// Quanti fallimenti di fila tengono l'ultimo risultato noto prima di azzerarlo.
+export const MAX_FAILURES = 3
+
+// Path and full branch ref of each checkout in `git worktree list --porcelain` (null: detached or bare).
+export const parseWorktreeBranches = (porcelain: string): { path: string; branch: string | null }[] =>
+  porcelain
+    .split(/\n\s*\n/)
+    .map(block => block.split('\n'))
+    .filter(lines => lines.some(line => line.startsWith('worktree /')))
+    .map(lines => {
+      const path = (lines.find(line => line.startsWith('worktree ')) as string).slice('worktree '.length).replace(/(.)\/+$/, '$1')
+      const branch = lines.find(line => line.startsWith('branch '))
+      return { path, branch: branch === undefined ? null : branch.slice('branch '.length) }
+    })

package/plugins/trailhead/hooks/trailhead-bash-guards.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // trailhead-bash-guards.js: PreToolUse(Bash) hook.
-// One process for the five Bash guards (commit, secret, install, search, body)
-// instead of five: each Bash call pays a single node start-up. The guards keep
+// One process for the six Bash guards (commit, secret, install, search, body, labels)
+// instead of six: each Bash call pays a single node start-up. The guards keep
 // their own modules and verdicts; this runner only calls each one's pure
-// evaluate(cmd) in a fixed order (commit, secret, install, search, body).
+// evaluate(cmd) in a fixed order (commit, secret, install, search, body, labels).
 //   - First block wins: its payload goes to stdout and the hook exits 2; later
 //     guards do not run. An earlier advisory keeps its stderr line.
 //   - No block: advisories (secret-guard's "could not scan") surface on stderr
@@ -11,9 +11,9 @@
 //   - Failure posture is unchanged per guard: a throwing guard counts as allow
 //     and the others still run; a guard module that fails to load is skipped
 //     with a one-line stderr warning.
-//   - --guards=<name,...> picks the guards (default: all five). The Codex install
-//     ships no search-guard and registers --guards=commit,secret,install,body.
-//     A missing, empty, malformed or unknown-name list falls back to all five, so
+//   - --guards=<name,...> picks the guards (default: all six). The Codex install
+//     ships no search-guard and registers --guards=commit,secret,install,body,labels.
+//     A missing, empty, malformed or unknown-name list falls back to all six, so
 //     a config typo never disables a guard.
 //   - TRAILHEAD_MOD_GUARDS=<name,...>@<epoch-ms>: the mod (which has ported those
 //     guards) stamps the guards it already ran; a stamp no older than
@@ -22,7 +22,7 @@
 // Crash-safe: unparseable input or any internal error -> exit 0.
 // Self-contained, no dependencies. Pure functions are exported for tests.
 
-const GUARD_ORDER = ['commit', 'secret', 'install', 'search', 'body'];
+const GUARD_ORDER = ['commit', 'secret', 'install', 'search', 'body', 'labels'];
 const MOD_GUARDS_FRESH_MS = 5000;
 const MOD_GUARDS_RE = /^([a-z][a-z0-9-]*(?:,[a-z][a-z0-9-]*)*)@(\d+)$/;
 
@@ -37,7 +37,7 @@ function parseModGuards(value, now = Date.now()) {
 }
 
 // Guards selected by --guards=<name,...>, in canonical order. Anything but a
-// well-formed list of known names means all five.
+// well-formed list of known names means all six.
 function parseGuardsArg(argv) {
   const arg = argv.find((a) => a.startsWith('--guards='));
   if (!arg) return GUARD_ORDER;