@marcomigozzi/trailhead 0.17.0 → 0.18.0

package/plugins/trailhead/hooks/mod/repo-pin.ts

@@ -5,6 +5,8 @@ import { atom, read, update } from 'claude-code'
 import type { EngineInterface } from 'claude-code'
 
 import type { RepoPin } from '../../types'
+import { gitArgv } from './git-env'
+import { parseWorktreeBranches } from './worktree-porcelain'
 import { sameValue } from './work-state-view'
 
 type RepoRead = { root: string; remote: string | null }
@@ -71,7 +73,7 @@ let remembered: RepoPin | null = null
 // the caller falls back.
 export async function toplevelOf($: EngineInterface): Promise<string | null> {
   try {
-    const out = await $.process.run(['git', 'rev-parse', '--show-toplevel'], { cwd: await $.session.cwd(), timeoutMs: 5_000 })
+    const out = await $.process.run(gitArgv('rev-parse', '--show-toplevel'), { cwd: await $.session.cwd(), timeoutMs: 5_000 })
     const top = out.stdout.trim()
     return out.exitCode === 0 && top.startsWith('/') ? top : null
   } catch {
@@ -95,9 +97,9 @@ async function gitRepo($: EngineInterface): Promise<{ repo: RepoRead; toplevel:
   try {
     const cwd = await $.session.cwd()
     const run = (argv: string[]) => $.process.run(argv, { cwd, timeoutMs: 5_000 })
-    const top = await run(['git', 'rev-parse', '--show-toplevel'])
+    const top = await run(gitArgv('rev-parse', '--show-toplevel'))
     if (repoFromGit(top, null) === null) return null
-    const repo = repoFromGit(top, await run(['git', 'remote', 'get-url', 'origin']))
+    const repo = repoFromGit(top, await run(gitArgv('remote', 'get-url', 'origin')))
     return repo === null ? null : { repo, toplevel: repo.root }
   } catch {
     return null
@@ -139,10 +141,107 @@ async function isServed($: EngineInterface, host: string, cwd: string): Promise<
   }
 }
 
+// The pinned checkout deleted under the session (a finished worktree, a removed clone): the pin moves to a live
+// checkout of the same repo (#347). Preferred in order: the main working tree, another worktree, the sibling
+// clone itself. Candidates are the repo's root as the host knows it and the folders beside the dead root; every
+// probe is `git -C <path>` from `/`, never a spawn in the dead directory. null when nothing is left.
+const MAX_SIBLINGS = 100
+const parentOf = (path: string): string => path.replace(/\/+$/, '').replace(/\/[^/]*$/, '') || '/'
+
+async function checkoutOf($: EngineInterface, path: string, key: string): Promise<string | null> {
+  try {
+    const run = (args: string[]) => $.process.run(gitArgv('-C', path, ...args), { cwd: '/', timeoutMs: 5_000 })
+    const top = await run(['rev-parse', '--show-toplevel'])
+    if (top.exitCode !== 0 || !top.stdout.trim().startsWith('/')) return null
+    const origin = await run(['remote', 'get-url', 'origin'])
+    const id = remoteId(origin.exitCode === 0 ? origin.stdout : null)
+    return id !== null && `${id.host}/${id.slug}` === key ? top.stdout.trim() : null
+  } catch {
+    return null
+  }
+}
+
+async function exists($: EngineInterface, path: string): Promise<boolean> {
+  try {
+    return await $.fs.exists(path)
+  } catch {
+    return true // unreadable: do not move the pin on a guess
+  }
+}
+
+async function siblingsOf($: EngineInterface, dir: string): Promise<string[]> {
+  try {
+    const entries = await $.fs.list(dir)
+    return entries.filter(e => e.kind === 'dir' && !e.name.startsWith('.')).slice(0, MAX_SIBLINGS).map(e => `${dir.replace(/\/+$/, '')}/${e.name}`)
+  } catch {
+    return []
+  }
+}
+
+async function liveCheckout($: EngineInterface, pin: RepoPin): Promise<string | null> {
+  const key = pinKey(pin)
+  const seeds: string[] = []
+  try {
+    const host = await $.session.repo()
+    if (host !== null && host.root !== pin.root) seeds.push(host.root)
+  } catch {
+    // The host read failed: the neighbours still answer.
+  }
+  seeds.push(...(await siblingsOf($, parentOf(pin.root))))
+  for (const seed of seeds) {
+    if (seed === pin.root || !(await exists($, seed))) continue
+    const top = await checkoutOf($, seed, key)
+    if (top === null) continue
+    // The seed's own worktree list names the main tree first, then the others.
+    const listed = await $.process.run(gitArgv('-C', top, 'worktree', 'list', '--porcelain'), { cwd: '/', timeoutMs: 5_000 }).catch(() => null)
+    const paths = listed !== null && listed.exitCode === 0 ? parseWorktreeBranches(listed.stdout).map(w => w.path) : []
+    for (const path of [...paths, top]) {
+      if (path === pin.root || !(await exists($, path))) continue
+      const checkout = path === top ? top : await checkoutOf($, path, key)
+      if (checkout !== null) return checkout
+    }
+  }
+  return null
+}
+
+// The pin as it stands, or the live checkout of its repo when its root is gone. Both outcomes are cached per
+// repo and dead root, since the host's memoized repo keeps naming the dead root and every refresh asks again: a hit
+// is revalidated by one exists check, a miss is not searched again within RELOCATE_RETRY_MS (a search spawns git
+// per sibling). Reset at a session start.
+const RELOCATE_RETRY_MS = 60_000
+const missed = new Map<string, number>()
+const relocated = new Map<string, string>()
+const relocationKey = (pin: RepoPin): string => `${pinKey(pin)}|${pin.root}`
+
+export async function livePin($: EngineInterface, pin: RepoPin): Promise<RepoPin> {
+  if (await exists($, pin.root)) return pin
+  const key = relocationKey(pin)
+  const known = relocated.get(key)
+  if (known !== undefined) {
+    if (await exists($, known)) return { ...pin, root: known }
+    relocated.delete(key)
+  }
+  const now = await $.clock.now().catch(() => null)
+  const last = missed.get(key)
+  if (now !== null && last !== undefined && now - last < RELOCATE_RETRY_MS) return pin
+  const root = await liveCheckout($, pin).catch(() => null)
+  if (root === null) {
+    if (now !== null) missed.set(key, now)
+    return pin
+  }
+  missed.delete(key)
+  relocated.set(key, root)
+  return { ...pin, root }
+}
+
 // Checks the working copy now and pins what it finds; a failed read keeps the last pin. The host's
 // `session.repo()` can stay null for a repo created mid-session, so git in the cwd answers then (#299). A session
 // start begins from nothing: the pin of an earlier session is not this one's.
 export async function refreshPin($: EngineInterface, init: { isStart?: boolean; onMove?: (pin: RepoPin | null) => Promise<void> } = {}): Promise<RepoPin | null> {
+  if (init.isStart === true) {
+    missed.clear()
+    relocated.clear()
+  }
   const stored = await read($, repoPin)
   const current = init.isStart === true ? null : (stored ?? remembered)
   let repo: RepoRead | null = null
@@ -159,7 +258,9 @@ export async function refreshPin($: EngineInterface, init: { isStart?: boolean;
   } catch {
     // Unreadable repo: keep the last pin.
   }
-  const pin = nextPin(current, repo, toplevel)
+  const next = nextPin(current, repo, toplevel)
+  // The pin, kept or freshly read (the host's memoized repo can keep naming a deleted root), may be gone.
+  const pin = next === null ? null : await livePin($, next)
   remembered = pin
   if (!sameValue(stored, pin)) {
     // Right before the atom changes, whoever moves it, so what was read for the old pin goes no later than the change.

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

@@ -3,6 +3,7 @@
 // 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 { gitArgv } from './git-env'
 import { isMissing, parseWorkState } from './work-state-view'
 import { MAX_FAILURES, parseWorktreeBranches } from './worktree-porcelain'
 
@@ -91,7 +92,7 @@ async function nowOf($: EngineInterface): Promise<number | 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 })
+    const out = await $.process.run(gitArgv('worktree', 'list', '--porcelain'), { cwd: root, timeoutMs: LOOKUP_TIMEOUT_MS })
     return out.exitCode === 0 ? parseWorktreeBranches(out.stdout) : null
   } catch {
     return null

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 six Bash guards (commit, secret, install, search, body, labels)
-// instead of six: each Bash call pays a single node start-up. The guards keep
+// One process for the seven Bash guards (commit, secret, install, search, body, labels, test)
+// instead of seven: 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, labels).
+// evaluate(cmd) in a fixed order (commit, secret, install, search, body, labels, test).
 //   - 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 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
+//   - --guards=<name,...> picks the guards (default: all seven). The Codex install
+//     ships no search-guard and registers --guards=commit,secret,install,body,labels,test.
+//     A missing, empty, malformed or unknown-name list falls back to all seven, 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', 'labels'];
+const GUARD_ORDER = ['commit', 'secret', 'install', 'search', 'body', 'labels', 'test'];
 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 six.
+// well-formed list of known names means all seven.
 function parseGuardsArg(argv) {
   const arg = argv.find((a) => a.startsWith('--guards='));
   if (!arg) return GUARD_ORDER;

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

@@ -19,7 +19,7 @@ const eq = (name, actual, expected) => { assert.deepStrictEqual(actual, expected
 // Run the merged hook end-to-end: tool_input JSON on stdin, capture {code, out, err}.
 function runHook(command, { env = {}, args = [], hook = HOOK, cwd } = {}) {
   const input = JSON.stringify({ tool_input: { command }, ...(cwd ? { cwd } : {}) });
-  const r = spawnSync('node', [hook, ...args], { input, env: { ...process.env, ...env } });
+  const r = spawnSync('node', [hook, ...args], { input, env: { ...process.env, CLAUDE_CONFIG_DIR: NO_GLOBAL, ...env } });
   return { code: r.status, out: r.stdout.toString(), err: r.stderr.toString() };
 }
 const codeOf = (r) => (r.out ? JSON.parse(r.out).code : undefined);
@@ -31,9 +31,20 @@ const BAD_INSTALL = 'npm install left-pad';
 const BAD_SEARCH = 'cd x && grep y z';
 const BAD_BODY = 'gh issue edit 5 --body ""';
 const BAD_LABELS = 'gh issue create --title x --body y --label trailhead:bug';
+const BAD_TEST = 'npm test 2>&1 | tail -20';
+
+// A scratch trailhead repo whose config sets testing.full, and an empty global config dir so
+// the developer's own config never leaks into the probes.
+const SCRATCH = fs.mkdtempSync(path.join(os.tmpdir(), 'tb-test-guard-'));
+const TEST_REPO = path.join(SCRATCH, 'repo');
+fs.mkdirSync(path.join(TEST_REPO, '.git'), { recursive: true });
+fs.mkdirSync(path.join(TEST_REPO, '.trailhead'));
+fs.writeFileSync(path.join(TEST_REPO, '.trailhead', 'config.json'), JSON.stringify({ testing: { full: 'npm test' } }));
+const NO_GLOBAL = path.join(SCRATCH, 'no-global');
+fs.mkdirSync(NO_GLOBAL);
 
 // --- unit: constants ---
-eq('guard order is fixed', GUARD_ORDER, ['commit', 'secret', 'install', 'search', 'body', 'labels']);
+eq('guard order is fixed', GUARD_ORDER, ['commit', 'secret', 'install', 'search', 'body', 'labels', 'test']);
 ok('freshness window is 5s', MOD_GUARDS_FRESH_MS === 5000);
 
 // --- unit: parseModGuards ---
@@ -49,10 +60,10 @@ for (const bad of ['commit', '@123', 'commit@abc', ',@1', '', undefined, 'commit
 eq('unknown names are ignored', [...parseModGuards(`commit,bogus@${NOW}`, NOW)], ['commit']);
 
 // --- unit: parseGuardsArg ---
-eq('no --guards -> all six', parseGuardsArg([]), GUARD_ORDER);
+eq('no --guards -> all seven', parseGuardsArg([]), GUARD_ORDER);
 eq('valid subset keeps canonical order', parseGuardsArg(['--guards=body,commit']), ['commit', 'body']);
-eq('empty --guards -> all six', parseGuardsArg(['--guards=']), GUARD_ORDER);
-eq('malformed --guards -> all six', parseGuardsArg(['--guards=commit,,body']), GUARD_ORDER);
+eq('empty --guards -> all seven', parseGuardsArg(['--guards=']), GUARD_ORDER);
+eq('malformed --guards -> all seven', parseGuardsArg(['--guards=commit,,body']), GUARD_ORDER);
 eq('any unknown name invalidates the whole list', parseGuardsArg(['--guards=commit,secert']), GUARD_ORDER);
 
 // --- unit: runGuards with fake evaluators ---
@@ -66,7 +77,7 @@ const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block',
     evaluators: {
       commit: spy('commit', () => { throw new Error('boom'); }),
       secret: spy('secret', allow), install: spy('install', blocker('I')),
-      search: spy('search', blocker('S')), body: spy('body', allow), labels: spy('labels', allow),
+      search: spy('search', blocker('S')), body: spy('body', allow), labels: spy('labels', allow), test: spy('test', allow),
     },
   });
   eq('a throwing guard counts as allow and the next one still blocks', r.code, 2);
@@ -76,7 +87,7 @@ const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block',
 {
   const r = runGuards('x', {
     now: NOW, env: { TRAILHEAD_MOD_GUARDS: `commit@${NOW}` },
-    evaluators: { commit: blocker('C'), secret: allow, install: allow, search: allow, body: allow, labels: allow },
+    evaluators: { commit: blocker('C'), secret: allow, install: allow, search: allow, body: allow, labels: allow, test: allow },
   });
   eq('a fresh stamp skips the listed guard', r.code, 0);
 }
@@ -84,7 +95,7 @@ const blocker = (code) => () => ({ kind: 'block', payload: { decision: 'block',
   const adv = (t) => () => ({ kind: 'advise', stderr: `${t}\n`, payload: { hookSpecificOutput: { additionalContext: t } } });
   const r = runGuards('x', {
     now: NOW, env: {},
-    evaluators: { commit: adv('a'), secret: adv('b'), install: allow, search: allow, body: allow, labels: allow },
+    evaluators: { commit: adv('a'), secret: adv('b'), install: allow, search: allow, body: allow, labels: allow, test: allow },
   });
   eq('advisories exit 0', r.code, 0);
   eq('advisory stderr lines are all written', r.stderr, 'a\nb\n');
@@ -98,11 +109,13 @@ const { evaluate: evInstall } = require('./trailhead-install-guard.js');
 const { evaluate: evSearch } = require('./trailhead-search-guard.js');
 const { evaluate: evBody } = require('./trailhead-body-guard.js');
 const { evaluate: evLabels } = require('./trailhead-labels-guard.js');
+const { evaluate: evTest } = require('./trailhead-test-guard.js');
 for (const [name, cmd, ev] of [
   ['commit', BAD_COMMIT, evCommit], ['secret', BAD_SECRET, evSecret], ['install', BAD_INSTALL, evInstall],
   ['search', BAD_SEARCH, evSearch], ['body', BAD_BODY, evBody], ['labels', BAD_LABELS, evLabels],
+  ['test', BAD_TEST, (c) => evTest(c, { cwd: TEST_REPO, env: { CLAUDE_CONFIG_DIR: NO_GLOBAL } })],
 ]) {
-  const r = runHook(cmd);
+  const r = runHook(cmd, name === 'test' ? { cwd: TEST_REPO } : {});
   const want = ev(cmd);
   ok(`${name}: evaluator blocks the probe`, want.kind === 'block');
   eq(`${name}: exit 2`, r.code, 2);
@@ -171,19 +184,19 @@ for (const [name, cmd, ev] of [
     const hook = path.join(tmp, 'trailhead-bash-guards.js');
     fs.rmSync(path.join(tmp, 'trailhead-search-guard.js'));
 
-    const codex = runHook(BAD_SEARCH, { hook, args: ['--guards=commit,secret,install,body,labels'] });
+    const codex = runHook(BAD_SEARCH, { hook, args: ['--guards=commit,secret,install,body,labels,test'] });
     eq('--guards without search never loads search-guard', codex.code, 0);
     eq('--guards without search: no warning', codex.err, '');
-    const still = runHook(BAD_INSTALL, { hook, args: ['--guards=commit,secret,install,body,labels'] });
+    const still = runHook(BAD_INSTALL, { hook, args: ['--guards=commit,secret,install,body,labels,test'] });
     eq('--guards subset still blocks with its guards', still.code, 2);
     const only = runHook(BAD_INSTALL, { hook, args: ['--guards=commit'] });
     eq('unselected guards do not run', only.code, 0);
 
     for (const bad of ['--guards=', '--guards=commit,secert', '--guards=commit,,body']) {
       const r = runHook(BAD_INSTALL, { hook, args: [bad] });
-      eq(`${bad}: falls back to all six (install blocks)`, r.code, 2);
+      eq(`${bad}: falls back to all seven (install blocks)`, r.code, 2);
       const clean = runHook('git status', { hook, args: [bad] });
-      ok(`${bad}: all six are selected (the missing search module is reported)`, /search/.test(clean.err));
+      ok(`${bad}: all seven are selected (the missing search module is reported)`, /search/.test(clean.err));
     }
 
     const missing = runHook(`${BAD_BODY} && ${BAD_SEARCH}`, { hook });
@@ -217,13 +230,14 @@ for (const [name, cmd, ev] of [
 // Run from a scratch dir outside any trailhead repo: those suites open unlabelled issues, which
 // the labels guard (rightly) blocks inside a trailhead repo.
 const SUITE_CWD = fs.mkdtempSync(path.join(os.tmpdir(), 'tb-suites-'));
-for (const name of ['commit', 'secret', 'install', 'search', 'body', 'labels']) {
+for (const name of ['commit', 'secret', 'install', 'search', 'body', 'labels', 'test']) {
   const file = path.join(__dirname, `trailhead-${name}-guard.test.js`);
   const r = spawnSync('node', [file], { cwd: SUITE_CWD, env: { ...process.env, TRAILHEAD_GUARD_HOOK: HOOK } });
   if (r.status !== 0) process.stderr.write(r.stdout.toString() + r.stderr.toString());
   eq(`${name}-guard suite passes through the merged hook`, r.status, 0);
 }
 fs.rmSync(SUITE_CWD, { recursive: true, force: true });
+fs.rmSync(SCRATCH, { recursive: true, force: true });
 
 // --- registration: one Bash entry, one command (the merged hook) ---
 {

package/plugins/trailhead/hooks/trailhead-check-update.js

@@ -11,6 +11,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
+// Un GIT_DIR ereditato batterebbe -C: le chiamate git non lo seguono (#349).
+const { gitEnv } = require('./lib/trailhead-git-env.js');
 
 const REPO = 'ToRvaLDz/trailhead';
 const NPM_PKG = '@marcomigozzi/trailhead';
@@ -33,7 +35,7 @@ function readJSON(p) {
 }
 function run(cmd, args) {
   try {
-    return execFileSync(cmd, args, { encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return execFileSync(cmd, args, { encoding: 'utf8', env: gitEnv(), timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
   } catch { return ''; }
 }
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;

package/plugins/trailhead/hooks/trailhead-labels-guard.js

@@ -10,7 +10,7 @@
 //     prototype | build | bug | task, and exactly one of `trailhead:map-<n>` |
 //     `trailhead:whiteboard` (never both, never two maps). Non-ticket trailhead issues
 //     (`trailhead:map`, `trailhead:dashboard`, `trailhead:codebase`,
-//     `trailhead:conventions`, and `trailhead:fog` / `trailhead:unverified`) are exempt.
+//     `trailhead:conventions`, and `trailhead:fog` / `trailhead:needs-info` / `trailhead:unverified`) are exempt.
 //     State labels (blocked, seed, paused, ...) are allowed extras and never count
 //     toward the shape. This rule applies in any repo.
 //   - A create with NO `trailhead:*` label is blocked too, but only inside a trailhead
@@ -36,7 +36,7 @@ const { words, parseRedirects } = require('./lib/body-sources.js');
 
 const PLAIN_SENTINEL = /(?:^|\s)TRAILHEAD_PLAIN_ISSUE=1(?:\s|$)/;
 const TYPES = ['decision', 'research', 'prototype', 'build', 'bug', 'task'];
-const EXEMPT = ['trailhead:map', 'trailhead:dashboard', 'trailhead:codebase', 'trailhead:conventions', 'trailhead:fog', 'trailhead:unverified'];
+const EXEMPT = ['trailhead:map', 'trailhead:dashboard', 'trailhead:codebase', 'trailhead:conventions', 'trailhead:fog', 'trailhead:needs-info', 'trailhead:unverified'];
 const MAP_RE = /^trailhead:map-\d+$/;
 const WHITEBOARD = 'trailhead:whiteboard';
 const TYPE_LIST = TYPES.map((t) => `trailhead:${t}`).join(' | ');

package/plugins/trailhead/hooks/trailhead-labels-guard.test.js

@@ -104,7 +104,7 @@ ok('a seed without type is blocked', blocked(create(['trailhead:ticket', 'trailh
 }
 
 // --- non-ticket trailhead issues are exempt ---
-for (const l of ['trailhead:map', 'trailhead:dashboard', 'trailhead:codebase', 'trailhead:conventions', 'trailhead:fog', 'trailhead:unverified']) {
+for (const l of ['trailhead:map', 'trailhead:dashboard', 'trailhead:codebase', 'trailhead:conventions', 'trailhead:fog', 'trailhead:needs-info', 'trailhead:unverified']) {
   ok(`${l} create passes`, !blocked(create([l]), TH));
 }
 ok('map issue with extra labels passes', !blocked(create(['trailhead:map', 'trailhead:paused']), TH));

package/plugins/trailhead/hooks/trailhead-test-guard.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// trailhead-test-guard.js: PreToolUse(Bash) hook.
+// Several agent sessions share one machine, and each of them running the whole test
+// suite at once starves it. `testing.full` (project `.trailhead/config.json`, or the
+// global `<config dir>/trailhead/config.json`) names the full-suite command; the queue
+// helper `trailhead-test-run.js` serialises those runs. This guard blocks a Bash call
+// that runs the bare `testing.full` command outside the helper.
+//   - Off unless `testing.full` is a non-empty string (nested `{"testing":{"full":..}}`
+//     or flat `"testing.full"`, nested wins; the project value replaces the global one,
+//     the same rule as the helper). Unset, unreadable or invalid config -> allow.
+//   - `testing.full` and the command are both split into statements; each statement
+//     drops NAME=v prefixes, redirections and the wrappers an agent writes by mistake
+//     (`env`, `time`, `command`, `nice`, `timeout`). The command is blocked when it
+//     holds the statements of `testing.full` consecutively, every statement word-equal
+//     except the last, which may add only flag arguments (a token starting with `-`).
+//     A non-flag extra argument is a focused run (`npm test -- hooks/x.test.js`) and passes.
+//   - Compound matching compares statements, not the operators between them. A `cd` /
+//     `pushd` statement before the match means the working directory is unknown: allow.
+//   - The helper's own invocation (`node .../trailhead-test-run.js ...`) never matches.
+//   - Opaque forms (`bash -c`, `eval`) are not unwrapped: guards target accidental mistakes.
+// Blocks with exit 2 + {"decision":"block",...}; allows everything else.
+// Crash-safe: any error -> allow. Self-contained except for lib/shell-scan.js. Pure
+// functions are exported for tests and the merged trailhead-bash-guards.js; runs as a
+// hook when executed directly.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { splitStatements, tokenize, stripQuotes, stripRedirections, skipEnvPrefix } = require('./lib/shell-scan.js');
+
+const HELPER = 'trailhead-test-run.js';
+const ASSIGN_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const DURATION_RE = /^\d+(?:\.\d+)?[smhd]?$/;
+// timeout options that consume a value as the next token (when not glued).
+const TIMEOUT_VALUE_OPTS = new Set(['-s', '--signal', '-k', '--kill-after']);
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+
+// --- config ----------------------------------------------------------------
+
+function readJson(file) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return isObject(cfg) ? cfg : null;
+  } catch {
+    return null;
+  }
+}
+
+// The testing.full entry of one parsed config: { found, value }. Nested wins over flat.
+function pickFull(cfg) {
+  if (!cfg) return { found: false };
+  if (isObject(cfg.testing) && has(cfg.testing, 'full')) return { found: true, value: cfg.testing.full };
+  if (has(cfg, 'testing.full')) return { found: true, value: cfg['testing.full'] };
+  return { found: false };
+}
+
+// The git top level above `cwd` (first dir holding `.git`, dir or file), or null.
+function gitTop(cwd) {
+  try {
+    let dir = path.resolve(cwd || process.cwd());
+    for (;;) {
+      if (fs.existsSync(path.join(dir, '.git'))) return dir;
+      const up = path.dirname(dir);
+      if (up === dir) return null;
+      dir = up;
+    }
+  } catch {
+    return null;
+  }
+}
+
+// Su Codex lo script vive in <codexHome>/skills/trailhead/<dir>: la config globale sta lì, non in ~/.claude.
+const CODEX_INSTALL = /[\\/]skills[\\/]trailhead[\\/](?:hooks|templates)$/;
+const codexHome = () => (CODEX_INSTALL.test(__dirname) ? path.resolve(__dirname, '..', '..', '..') : null);
+
+function configDir(env) {
+  return codexHome() || (env && env.CLAUDE_CONFIG_DIR) || path.join((env && env.HOME) || os.homedir(), '.claude');
+}
+
+// The effective testing.full string, or null when the guard is off. The project value
+// replaces the global one even when it is invalid (then the guard is off).
+function readFull(cwd, env) {
+  const top = gitTop(cwd);
+  const layers = [
+    top ? readJson(path.join(top, '.trailhead', 'config.json')) : null,
+    readJson(path.join(configDir(env), 'trailhead', 'config.json')),
+  ];
+  for (const cfg of layers) {
+    const p = pickFull(cfg);
+    if (!p.found) continue;
+    return typeof p.value === 'string' && p.value.trim() !== '' ? p.value : null;
+  }
+  return null;
+}
+
+// --- statement normalisation -----------------------------------------------
+
+// One statement as a word list without env prefixes, redirections and wrappers, or [].
+function normalise(stmt) {
+  let toks = stripRedirections(tokenize(stmt)).map(stripQuotes);
+  for (let guard = 0; guard < 20; guard++) {
+    toks = toks.slice(skipEnvPrefix(toks));
+    if (toks.length === 0) return [];
+    const head = toks[0];
+    if (head === 'env') {
+      let i = 1;
+      while (i < toks.length) {
+        if (ASSIGN_RE.test(toks[i])) i++;
+        else if (toks[i] === '-u' || toks[i] === '-C') i += 2;
+        else if (toks[i].startsWith('-') && toks[i] !== '-') i++;
+        else break;
+      }
+      toks = toks.slice(i);
+    } else if (head === 'time') {
+      let i = 1;
+      while (i < toks.length && toks[i].startsWith('-')) i++;
+      toks = toks.slice(i);
+    } else if (head === 'command') {
+      let i = 1;
+      while (i < toks.length && toks[i].startsWith('-') && toks[i] !== '--') i++;
+      if (toks[i] === '--') i++;
+      toks = toks.slice(i);
+    } else if (head === 'nice') {
+      let i = 1;
+      if (toks[i] === '-n') i += 2;
+      else if (/^-n\d+$/.test(toks[i] || '') || /^-\d+$/.test(toks[i] || '')) i++;
+      toks = toks.slice(i);
+    } else if (head === 'timeout') {
+      let i = 1;
+      while (i < toks.length && toks[i].startsWith('-')) {
+        i += TIMEOUT_VALUE_OPTS.has(toks[i]) ? 2 : 1;
+      }
+      if (i < toks.length && DURATION_RE.test(toks[i])) i++;
+      toks = toks.slice(i);
+    } else {
+      return toks;
+    }
+  }
+  return toks;
+}
+
+const statementsOf = (text) => splitStatements(String(text)).map(normalise);
+
+const isCd = (words) => words[0] === 'cd' || words[0] === 'pushd';
+const isHelper = (words) => words.some((w) => path.basename(w) === HELPER);
+
+// Does `words` run the `want` statement; the last one may add only flag arguments?
+function matchesStatement(words, want, last) {
+  if (words.length < want.length) return false;
+  for (let i = 0; i < want.length; i++) if (words[i] !== want[i]) return false;
+  const extra = words.slice(want.length);
+  if (!last) return extra.length === 0;
+  return extra.every((w) => w.startsWith('-'));
+}
+
+// Does the command run the `full` statements, with a known working directory?
+function runsFull(cmdStmts, fullStmts) {
+  for (let start = 0; start + fullStmts.length <= cmdStmts.length; start++) {
+    if (cmdStmts.slice(0, start).some(isCd)) return false; // unknown cwd from here on
+    const hit = fullStmts.every((want, k) => {
+      const words = cmdStmts[start + k];
+      return !isHelper(words) && matchesStatement(words, want, k === fullStmts.length - 1);
+    });
+    if (hit) return true;
+  }
+  return false;
+}
+
+// --- reason ----------------------------------------------------------------
+
+function helperPath(env) {
+  const candidates = [path.join(__dirname, '..', 'templates'), path.join(configDir(env), 'trailhead', 'templates')];
+  const dir = candidates.find((d) => fs.existsSync(path.join(d, HELPER)));
+  return dir ? path.join(dir, HELPER) : HELPER;
+}
+
+function block(full, env, root) {
+  const reason =
+    `trailhead: this Bash call runs the full test suite (\`${full}\`) directly. Several sessions doing that at once starve the machine. ` +
+    'Run focused tests instead (pass only the test files you touched, or the `testing.targeted` command when it is set), ' +
+    `or queue the full run with the helper: \`node ${helperPath(env)} run --repo ${root || '<repo root>'}\`.`;
+  return { kind: 'block', payload: { decision: 'block', code: 'UNQUEUED_FULL_TEST_RUN', reason } };
+}
+
+// Pure verdict: null (allow), or { kind:'block', payload }. Never exits or writes; any
+// internal error allows.
+function evaluate(cmd, opts) {
+  try {
+    const cwd = opts && opts.cwd;
+    const env = (opts && opts.env) || process.env;
+    const full = readFull(cwd, env);
+    if (!full) return null;
+    const fullStmts = statementsOf(full);
+    if (fullStmts.length === 0 || fullStmts.some((s) => s.length === 0)) return null;
+    if (!runsFull(statementsOf(cmd), fullStmts)) return null;
+    return block(full, env, gitTop(cwd));
+  } catch {
+    return null; // a guard must never wedge the workflow
+  }
+}
+
+function run(data) {
+  let cmd = '';
+  let cwd;
+  try {
+    const input = JSON.parse(data);
+    cmd = (input.tool_input || {}).command || '';
+    cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : undefined;
+  } catch {
+    process.exit(0);
+  }
+  const v = evaluate(cmd, { cwd, env: process.env });
+  if (v && v.kind === 'block') {
+    process.stdout.write(JSON.stringify(v.payload));
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000); // stdin never ends -> give up
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}
+
+module.exports = { configDir, evaluate, readFull, normalise, runsFull };