@marcomigozzi/trailhead 0.14.0 → 0.15.0

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

@@ -66,6 +66,23 @@ const stableJson = (value: unknown): string => {
   return `{${keys.map(k => `${JSON.stringify(k)}:${stableJson(obj[k])}`).join(',')}}`
 }
 
+// The state belongs to this session (a state with no session counts as its own, like the orphan rule).
+const isOwn = (state: WorkState | null, session: string): boolean =>
+  state !== null && (state.session === null || state.session === session)
+
+// The ticket this session owns across a work-state file shared with other sessions. A state it wrote
+// sets it; one another session wrote leaves it; a missing file clears it only when the last state read
+// was this session's (its own Resolve), so another session's cleanup never drops the mark.
+export const nextOwnTicket = (
+  prev: number | null,
+  lastState: WorkState | null,
+  nextState: WorkState | null,
+  session: string,
+): number | null => {
+  if (nextState !== null) return isOwn(nextState, session) ? nextState.ticket : prev
+  return isOwn(lastState, session) ? null : prev
+}
+
 export const sameValue = (a: unknown, b: unknown): boolean => stableJson(a) === stableJson(b)
 
 export const statusLine = (state: WorkState | null, isOrphaned: boolean): string | undefined => {

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

@@ -8,14 +8,28 @@
 // package age, download counts, repo metadata) and checkpoint the human on a
 // suspicious result (block-and-ask). A vetted install proceeds by re-running the
 // command prefixed with the sentinel `TRAILHEAD_VERIFIED_INSTALL=1`.
-// Only a NAMED install is gated: lockfile/manifest installs (bare `npm install`,
-// `npm ci`, `pip install -r`, `cargo build`, `go mod download`, `bundle install`)
-// and local paths / URLs / VCS refs carry no typed name and pass through.
+// Only a NAMED install is gated: installs with no typed name (bare `npm install`,
+// `npm ci`, `install --frozen-lockfile` / `--immutable` with no package, `pip install -r`,
+// `cargo build`, `go mod download`, `bundle install`) and local paths / URLs /
+// VCS refs carry no typed name and pass through. A file-like name (`foo.txt`,
+// `x.tgz`) passes only when it is a path (`./x`, `sub/x`, `/x`, `~/x`) or exists
+// on disk (relative to the command's cwd); otherwise it is a typed name and is gated.
+// The on-disk check resolves against the hook's cwd; it does not follow a
+// preceding `cd` in the same command. Command wrappers (`sudo`, `time`, `env`,
+// `nohup`, `xargs`, `timeout`, `nice`, `stdbuf`, `setsid`, `ionice`, `doas`,
+// `command`, `exec`) are peeled, with their own flags, so `sudo npm install foo`
+// is gated like the bare form. Parsing is quote-aware (shared
+// lib/shell-scan.js): text inside quotes or a heredoc (`echo "x; npm i foo"`) is
+// never a command, and redirections (`2>&1`, `> log`) are never package names.
 // Blocks with exit 2 + {"decision":"block",...}; allows everything else.
 // Crash-safe: any error → exit 0 (never wedge the user's workflow).
-// Self-contained, no dependencies. Pure functions (incl. evaluate) exported for tests
+// Self-contained (its only dependency is the sibling lib/ module). Pure functions (incl. evaluate) exported for tests
 // and the merged trailhead-bash-guards.js; runs as a hook when executed directly.
 
+const fs = require('fs');
+const path = require('path');
+const { basename, splitStatements, tokenize, stripQuotes, stripRedirections } = require('./lib/shell-scan.js');
+
 const SENTINEL = /(?:^|\s)TRAILHEAD_VERIFIED_INSTALL=1(?:\s|$)/;
 
 // Per-ecosystem: the binaries that own it, and the install verbs that fetch a
@@ -37,22 +51,129 @@ const VALUE_FLAGS = new Set([
   '-t', '--target', '--prefix', '--root', '--python', '-d', '--dest',
   '-w', '--workspace', '--registry', '-C', '--directory', '--chdir',
   '--no-binary', '--only-binary',
+  '--filter', '-F', // pnpm workspace selector: its value is a project, not a package
 ]);
 
-function basename(p) {
-  const s = String(p).split('/');
-  return s[s.length - 1];
+// Command wrappers that run the rest of the line as a command, mapped to the
+// flags that consume a SEPARATE-TOKEN value (so it is not read as the command).
+// Attached forms (`-uroot`, `--user=root`, GNU xargs `-i`/`-e`/`-l`) need no entry.
+const WRAPPERS = {
+  sudo: new Set([
+    '-u', '--user', '-g', '--group', '-h', '--host', '-p', '--prompt', '-C', '--close-from',
+    '-U', '--other-user', '-r', '--role', '-t', '--type', '-D', '--chdir', '-R', '--chroot',
+    '-T', '--command-timeout',
+  ]),
+  env: new Set(['-u', '--unset', '-C', '--chdir', '-a', '--argv0']), // -S handled apart
+  time: new Set(['-f', '--format', '-o', '--output']),
+  nohup: new Set(),
+  xargs: new Set([
+    '-n', '--max-args', '-I', '-a', '--arg-file', '-d', '--delimiter', '-E', '-L', '--max-lines',
+    '-P', '--max-procs', '-s', '--max-chars',
+  ]),
+  timeout: new Set(['-s', '--signal', '-k', '--kill-after']), // + one DURATION operand
+  nice: new Set(['-n', '--adjustment']),
+  stdbuf: new Set(['-i', '-o', '-e', '--input', '--output', '--error']),
+  setsid: new Set(),
+  ionice: new Set(['-c', '--class', '-n', '--classdata']),
+  doas: new Set(['-a', '-C', '-u']),
+  command: new Set(), // -v / -V only look a name up: see isLookupFlag
+  exec: new Set(['-a']),
+};
+const ENV_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+// How a wrapper flag consumes its value. Returns { next } (value is the NEXT
+// token), { attached } (value is inside this token) or {} (flagless). A short
+// cluster is read like getopt: the first value-taking letter ends it, so `-nu root`
+// takes the next token and `-uroot` carries its value attached.
+function flagValue(f, valueFlags) {
+  if (f.startsWith('--')) {
+    const eq = f.indexOf('=');
+    if (eq !== -1) return { attached: f.slice(eq + 1) };
+    return valueFlags.has(f) ? { next: true } : {};
+  }
+  for (let k = 1; k < f.length; k++) {
+    if (!valueFlags.has('-' + f[k])) continue;
+    return k === f.length - 1 ? { next: true } : { attached: f.slice(k + 1) };
+  }
+  return {};
+}
+
+// `env -S` / `--split-string`: its payload IS the command line, not a flag value.
+function isSplitFlag(f) {
+  if (f.startsWith('--')) return f === '--split-string' || f.startsWith('--split-string=');
+  for (let k = 1; k < f.length; k++) {
+    if (f[k] === 'S') return true;
+    if ('uCa'.includes(f[k])) return false; // value letter first: S is part of its value
+  }
+  return false;
+}
+
+// `command -v` / `-V` (also inside a cluster like `-pv`) only describe a name and
+// execute nothing, so nothing follows that can be an install.
+function isLookupFlag(f) {
+  return !f.startsWith('--') && /[vV]/.test(f);
+}
+
+// The text of an `env -S` payload token. A double-quoted payload (outer quotes
+// stripped) also loses its bash escapes (`\$`, `\``, `\"`, `\\`); single-quoted
+// text is literal. Local on purpose: the shared stripQuotes is left as is.
+function payloadText(payload) {
+  const p = payload || '';
+  const stripped = stripQuotes(p);
+  const dq = p.length >= 2 && p.startsWith('"') && p.endsWith('"');
+  return dq ? stripped.replace(/\\([$`"\\])/g, '$1') : stripped;
+}
+
+// The real command, past leading `NAME=value` assignments and any (nested) wrapper
+// with its flags. Returns { toks, i }: toks may be rewritten when an `env -S`
+// payload is re-tokenized; i is toks.length when nothing is left.
+function skipWrappers(input) {
+  let toks = input;
+  let i = 0;
+  for (;;) {
+    while (i < toks.length && ENV_ASSIGN.test(toks[i])) i++;
+    const wrapper = basename(toks[i] || '');
+    const valueFlags = WRAPPERS[wrapper];
+    if (!valueFlags) return { toks, i };
+    i++; // past the wrapper
+    while (i < toks.length && toks[i].startsWith('-')) {
+      const f = toks[i++];
+      if (f === '--') break; // end of the wrapper's options
+      if (wrapper === 'env' && isSplitFlag(f)) {
+        const eq = f.indexOf('=');
+        const sIdx = f.indexOf('S');
+        let payload;
+        if (f.startsWith('--')) payload = eq !== -1 ? f.slice(eq + 1) : toks[i++];
+        else payload = sIdx === f.length - 1 ? toks[i++] : f.slice(sIdx + 1);
+        toks = [...tokenize(payloadText(payload)), ...toks.slice(i)];
+        i = 0; // the payload and the rest now form the command line
+        break;
+      }
+      if (wrapper === 'command' && isLookupFlag(f)) return { toks, i: toks.length };
+      if (flagValue(f, valueFlags).next) i++; // consume its separate-token value
+    }
+    if (wrapper === 'timeout' && i < toks.length) i++; // the DURATION operand
+  }
+}
+
+// A file-like name is local only when it is a path or exists on disk. A leading
+// `@` is a scoped npm name, never a path.
+function isLocalFile(t, opts) {
+  if (t.startsWith('@')) return false;
+  if (t.includes('/')) return true;
+  const exists = (opts && opts.exists) || fs.existsSync;
+  return exists(path.resolve((opts && opts.cwd) || process.cwd(), t));
 }
 
 // A positional that is NOT a public-registry name: local path, url, vcs ref, or a
 // file artifact. Go module paths (example.com/foo) look url-ish but ARE the named
 // module, so for go only a leading . / ~ disqualifies.
-function isLocalOrUrl(t, ecosystem) {
+function isLocalOrUrl(t, ecosystem, opts) {
   if (t.startsWith('.') || t.startsWith('/') || t.startsWith('~')) return true;
   if (ecosystem === 'go') return false; // a bare module path is the name; gate it
   if (t.includes('://')) return true;
   if (/^(?:git\+|file:|https?:|hg\+|svn\+|bzr\+)/.test(t)) return true;
-  if (/\.(?:tgz|tar\.gz|whl|gz|zip|txt|toml|lock|cfg)$/.test(t)) return true;
+  if (/\.(?:tgz|tar\.gz|whl|gz|zip|txt|toml|lock|cfg)$/.test(t)) return isLocalFile(t, opts);
   return false;
 }
 
@@ -70,12 +191,29 @@ function bareName(t) {
   return n;
 }
 
+// Positional package names among the arguments after the verb (redirections
+// already removed). Quotes are stripped so `"lodash"` is the name `lodash`.
+function collectPackages(args, ecosystem, opts) {
+  const packages = [];
+  for (let j = 0; j < args.length; j++) {
+    const t = args[j];
+    if (t.startsWith('-')) {
+      if (VALUE_FLAGS.has(t)) j++; // consume its separate-token value
+      continue;
+    }
+    const name = stripQuotes(t);
+    if (!name || name === '&' || isLocalOrUrl(name, ecosystem, opts)) continue;
+    const bare = bareName(name);
+    if (bare) packages.push(bare);
+  }
+  return packages;
+}
+
 // Detect a public-registry install that NAMES at least one package, in a single
-// shell segment. Returns { ecosystem, packages: [names] } or null.
-function detectSegment(cmd) {
-  const toks = String(cmd).trim().split(/\s+/).filter(Boolean);
-  let i = 0;
-  while (i < toks.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[i])) i++; // env prefix
+// shell statement. Returns { ecosystem, packages: [names] } or null.
+function detectSegment(stmt, opts) {
+  const { toks, i: start } = skipWrappers(tokenize(stmt));
+  let i = start; // env prefix + sudo/time/env/nohup/xargs
   if (i >= toks.length) return null;
 
   const bin = basename(toks[i]);
@@ -102,27 +240,21 @@ function detectSegment(cmd) {
   if (!ECOSYSTEMS[ecosystem].verbs.includes(verb)) return null;
   i++;
 
-  const packages = [];
-  for (let j = i; j < toks.length; j++) {
-    const t = toks[j];
-    if (t.startsWith('-')) {
-      if (VALUE_FLAGS.has(t)) j++; // consume its separate-token value
-      continue;
-    }
-    if (isLocalOrUrl(t, ecosystem)) continue;
-    packages.push(bareName(t));
-  }
+  const args = stripRedirections(toks.slice(i));
+  // A lockfile install (`--frozen-lockfile`, `--immutable`) carries no positional,
+  // so it yields no package here; a flag never excuses a name typed beside it.
+  const packages = collectPackages(args, ecosystem, opts);
   if (packages.length === 0) return null; // lockfile/manifest install: nothing typed
   return { ecosystem, packages };
 }
 
 // Agents chain commands (`cd app && npm install foo`), so check every shell
-// segment, not just the first. Split on the common separators (&& || ; | and
-// newlines); a registry name never contains one, so a stray split is harmless.
-// Returns the first segment's hit, or null.
-function detectInstall(cmd) {
-  for (const seg of String(cmd).split(/&&|\|\||;|\n|\|/)) {
-    const hit = detectSegment(seg);
+// statement, not just the first. splitStatements is quote- and heredoc-aware, so
+// a separator or install text inside quotes / a heredoc body is not a statement.
+// Returns the first statement's hit, or null.
+function detectInstall(cmd, opts) {
+  for (const stmt of splitStatements(cmd)) {
+    const hit = detectSegment(stmt, opts);
     if (hit) return hit;
   }
   return null;
@@ -147,10 +279,10 @@ function blockVerdict(hit) {
 
 // Pure verdict for one command: {kind:'allow'} or {kind:'block', payload}. Never
 // exits or writes; any internal error falls through to allow.
-function evaluate(cmd) {
+function evaluate(cmd, opts) {
   try {
     if (isVerified(cmd)) return { kind: 'allow' }; // agent has vetted these
-    const hit = detectInstall(cmd);
+    const hit = detectInstall(cmd, { cwd: opts && opts.cwd });
     if (hit) return blockVerdict(hit);
   } catch {
     // fall through to allow: a guard must never wedge the workflow
@@ -160,12 +292,15 @@ function evaluate(cmd) {
 
 function run(data) {
   let cmd = '';
+  let cwd;
   try {
-    cmd = (JSON.parse(data).tool_input || {}).command || '';
+    const input = JSON.parse(data);
+    cmd = (input.tool_input || {}).command || '';
+    cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : undefined;
   } catch {
     process.exit(0); // unparseable input: nothing to gate
   }
-  const v = evaluate(cmd);
+  const v = evaluate(cmd, { cwd });
   if (v.kind === 'block') {
     process.stdout.write(JSON.stringify(v.payload));
     process.exit(2);

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

@@ -4,10 +4,12 @@
 const assert = require('assert');
 const { execFileSync } = require('child_process');
 const path = require('path');
+const fs = require('fs');
+const os = require('os');
 
 // TRAILHEAD_GUARD_HOOK re-runs this suite through the merged trailhead-bash-guards.js.
 const HOOK = process.env.TRAILHEAD_GUARD_HOOK || path.join(__dirname, 'trailhead-install-guard.js');
-const { detectInstall, isVerified } = require('./trailhead-install-guard.js');
+const { detectInstall, isVerified, evaluate } = require('./trailhead-install-guard.js');
 
 let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };
@@ -86,6 +88,176 @@ ok('detects install after ; chain', (() => { const d = detectInstall('echo hi; p
 ok('detects install in a piped tail', (() => { const d = detectInstall('true | cargo add serde'); return d && d.packages.includes('serde'); })());
 ok('compound with no install stays null', detectInstall('cd app && npm run build && ls') === null);
 
+// --- unit: lockfile installs, redirections, quoted text (#239) ---
+const heredocDoc = ['cat > /tmp/x.md <<\'EOF\'', '| `pnpm install a 2>&1` | x |', 'EOF'].join('\n');
+const neg239 = [
+  'pnpm install --frozen-lockfile --offline 2>&1',
+  'cd app && pnpm install --frozen-lockfile --offline 2>&1 | tail -5',
+  'pnpm install --frozen-lockfile > /tmp/log',
+  'pnpm install --frozen-lockfile --filter web',
+  'pnpm install --frozen-lockfile',
+  'yarn install --immutable',
+  'bun install --frozen-lockfile',
+  'yarn install --frozen-lockfile',
+  'npm install 2>&1',
+  'echo "done; pnpm install lodash"',
+  'echo "a && npm install foo"',
+  'echo "next: pnpm install then build"',
+  'git commit -m "fix: pnpm install guard | npm i x"',
+  heredocDoc,
+];
+for (const cmd of neg239) {
+  ok(`ignores: ${cmd.split('\n')[0]}`, detectInstall(cmd) === null);
+}
+
+// Redirections and quoting must not hide a real named install, nor leak into the name.
+const pos239 = [
+  ['npm install lodash 2>&1', 'npm', ['lodash']],
+  ['pnpm add vite > /tmp/log', 'npm', ['vite']],
+  ['npm install "lodash"', 'npm', ['lodash']],
+  ['echo ok && npm install lodash', 'npm', ['lodash']],
+  ['echo ok; pip install requests', 'pip', ['requests']],
+  ['pnpm add --filter web vite', 'npm', ['vite']],
+];
+for (const [cmd, eco, names] of pos239) {
+  const d = detectInstall(cmd);
+  ok(`detects exactly: ${cmd}`, d && d.ecosystem === eco && JSON.stringify(d.packages) === JSON.stringify(names));
+}
+
+// A lockfile flag never excuses a typed name: the named package is still gated.
+const posLock = [
+  ['npm i --frozen-lockfile evilpkg', 'evilpkg'],
+  ['pnpm install --frozen-lockfile evilpkg', 'evilpkg'],
+  ['yarn install --immutable evilpkg', 'evilpkg'],
+  ['npm install evilpkg --frozen', 'evilpkg'],
+];
+for (const [cmd, name] of posLock) {
+  const d = detectInstall(cmd);
+  ok(`detects despite lockfile flag: ${cmd}`, d && d.packages.includes(name));
+  const r = runHook(cmd);
+  ok(`blocks despite lockfile flag: ${cmd}`, r.code === 2 && new RegExp(name).test(r.out));
+}
+
+// A bare `&` (background) is never listed as a package name.
+ok('background & is not a package', JSON.stringify((detectInstall('npm install lodash &') || {}).packages) === JSON.stringify(['lodash']));
+
+// --- unit: wrapped installs and file-like names (#255) ---
+const posWrap = [
+  ['sudo npm install lodash', 'lodash'],
+  ['time pip install requests', 'requests'],
+  ['env FOO=1 npm i lodash', 'lodash'],
+  ['nohup npm install lodash', 'lodash'],
+  ['xargs npm install lodash', 'lodash'],
+  ['sudo -u bob npm install lodash', 'lodash'],   // flag with a separate-token value
+  ['sudo -- npm i lodash', 'lodash'],
+  ['sudo -E npm i lodash', 'lodash'],
+  ['env -u HOME npm i lodash', 'lodash'],
+  ['env -C /tmp FOO=1 npm i lodash', 'lodash'],
+  ['time -p pip install requests', 'requests'],
+  ['time -o /tmp/t pip install requests', 'requests'],
+  ['xargs -n 1 npm install lodash', 'lodash'],
+  ['xargs -I {} pip install requests', 'requests'],
+  ['xargs --max-args=1 npm i lodash', 'lodash'],
+  ['sudo env FOO=1 nohup npm i lodash', 'lodash'],   // chain
+  ['FOO=1 sudo -u root time -p pip install requests', 'requests'],
+  ['cd app && sudo npm install lodash', 'lodash'],
+  ['/usr/bin/sudo npm install lodash', 'lodash'],
+  ['sudo -nu root npm i lodash', 'lodash'],      // bundled short flags, value flag last
+  ['sudo -Eu bob npm i lodash', 'lodash'],
+  ['sudo -iu root npm i lodash', 'lodash'],
+  ['sudo -uroot npm i lodash', 'lodash'],        // attached value
+  ['sudo -nE npm i lodash', 'lodash'],           // cluster with no value flag
+  ['env -S "npm i lodash"', 'lodash'],           // split-string payload is the command
+  ['env -S npm i lodash', 'lodash'],
+  ["env -S 'npm i lodash'", 'lodash'],
+  ['env --split-string="npm i lodash"', 'lodash'],
+  ['env --split-string npm i lodash', 'lodash'],
+  ['env -a name npm i lodash', 'lodash'],        // argv0 value, command follows
+  ['env -S "FOO=1 sudo npm i lodash"', 'lodash'],
+];
+for (const [cmd, name] of posWrap) {
+  const d = detectInstall(cmd);
+  ok(`detects wrapped: ${cmd}`, d && d.packages.includes(name));
+}
+const negWrap = [
+  'sudo npm install',
+  'sudo npm ci',
+  'time npm install --frozen-lockfile',
+  'env FOO=1 npm install',
+  'xargs echo npm install foo',     // xargs runs echo
+  'sudo -u bob ls',
+  'sudo',
+  'env',
+  'sudo -u',
+  'sudo -nu root ls',
+  'env -S "ls -la"',
+  'env -S "npm install"',
+];
+for (const cmd of negWrap) {
+  ok(`ignores wrapped: ${cmd}`, detectInstall(cmd) === null);
+}
+
+// A file-like suffix is local only for a path or an existing file.
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'install-guard-'));
+fs.writeFileSync(path.join(tmp, 'foo.tgz'), '');
+const inTmp = { cwd: tmp };
+const posFile = ['pip install foo.txt', 'npm install left-pad.toml', 'npm install nope.tgz', 'pip install pkg.whl'];
+for (const cmd of posFile) {
+  const d = detectInstall(cmd, inTmp);
+  ok(`gates absent file-like name: ${cmd}`, d && d.packages.length === 1);
+}
+const negFile = [
+  'pip install ./foo.txt',
+  'pip install sub/req.txt',
+  'pip install /abs/req.txt',
+  'pip install ~/req.txt',
+  'npm install foo.tgz',            // exists in cwd
+];
+for (const cmd of negFile) {
+  ok(`allows path or existing file: ${cmd}`, detectInstall(cmd, inTmp) === null);
+}
+ok('existing file resolved against cwd, not process cwd', detectInstall('npm install foo.tgz', { cwd: os.tmpdir() }) !== null);
+ok('injectable exists check', detectInstall('npm install x.tgz', { exists: () => true }) === null);
+ok('scoped name is never a path', (() => { const d = detectInstall('npm install @scope/pkg.zip', inTmp); return d && d.packages[0] === '@scope/pkg.zip'; })());
+ok('evaluate tolerates null opts', evaluate('npm install lodash', null).kind === 'block');
+const wf = evaluate('npm install foo.tgz', { cwd: tmp });
+ok('evaluate threads cwd (existing file allowed)', wf.kind === 'allow');
+ok('evaluate blocks absent file-like name', evaluate('pip install foo.txt', { cwd: tmp }).kind === 'block');
+const wrapRun = runHook('sudo npm install lodash');
+ok('blocks a sudo-wrapped install end-to-end (exit 2)', wrapRun.code === 2 && /lodash/.test(wrapRun.out));
+const cwdRun = (() => {
+  const input = JSON.stringify({ cwd: tmp, tool_input: { command: 'npm install foo.tgz' } });
+  try { return { code: 0, out: execFileSync('node', [HOOK], { input }).toString() }; } catch (e) { return { code: e.status }; }
+})();
+ok('hook honours input.cwd for the on-disk check (exit 0)', cwdRun.code === 0);
+fs.rmSync(tmp, { recursive: true, force: true });
+
+// Wrappers peeled with their flags: timeout (+ DURATION), nice, stdbuf, setsid, ionice, doas, command, exec.
+const wrapHits = [
+  'timeout 10 npm i x', 'timeout -s KILL 10 npm i x', 'timeout --signal=KILL 5s npm i x',
+  'timeout -k 1 10 npm i x', 'nice npm i x', 'nice -n 5 npm i x', 'nice -n5 npm i x', 'nice -5 npm i x',
+  'command npm i x', 'command -p npm i x', 'exec npm i x', 'exec -a foo npm i x',
+  'doas npm i x', 'doas -u root npm i x', 'setsid npm i x', 'setsid -w npm i x',
+  'ionice -c 3 npm i x', 'stdbuf -oL npm i x', 'stdbuf -o L npm i x',
+  'sudo timeout 10 nice npm i x', 'xargs timeout 10 npm i x', 'timeout -- 10 npm i x',
+  'env -S "env -S \\"npm i lodash\\""',
+  'env -S "env -S \\"env -S \\\\\\"npm i lodash\\\\\\"\\""',
+  "env -S 'npm i lodash'",
+];
+for (const c of wrapHits) ok(`wrapper hit: ${c}`, detectInstall(c) && detectInstall(c).packages.length > 0);
+const wrapMisses = [
+  'timeout 10 ls', 'nice ls', 'command -v npm', 'command -v npm i x', 'command -V npm i x',
+  'command -pv npm i x', 'exec 3>&1', 'exec -a npm ls', 'doas ls',
+  "env -S 'echo \"npm i lodash\"'", 'env -S "echo \\"npm i lodash\\""',
+];
+for (const c of wrapMisses) ok(`wrapper miss: ${c}`, detectInstall(c) === null);
+
+// Known unmodelled gaps (documented, NOT asserted): this guard reads one plain
+// command per statement plus the wrappers it peels, so an install behind
+// `bash -c "..."` / `sh -c "..."`, `$( )`, `eval`, other wrappers (`chrt`,
+// `taskset`, `flock`, `su -c`), or a GNU long-option prefix abbreviation
+// taking a separate value (`timeout --sig KILL 5 ...`) is not seen.
+
 // --- unit: isVerified ---
 ok('sentinel recognised', isVerified('TRAILHEAD_VERIFIED_INSTALL=1 npm install lodash'));
 ok('no sentinel', !isVerified('npm install lodash'));
@@ -107,6 +279,13 @@ ok('non-install allowed (exit 0)', a3.code === 0 && a3.out.trim() === '');
 const a4 = runHook('pip install -r requirements.txt');
 ok('requirements-file install allowed (exit 0)', a4.code === 0 && a4.out.trim() === '');
 
+const a5 = runHook('cd app && pnpm install --frozen-lockfile --offline 2>&1 | tail -5');
+ok('lockfile install with redirection allowed (exit 0)', a5.code === 0 && a5.out.trim() === '');
+const a6 = runHook('echo "done; pnpm install lodash"');
+ok('install text inside echo allowed (exit 0)', a6.code === 0 && a6.out.trim() === '');
+const b3 = runHook('npm install lodash 2>&1');
+ok('named install with redirection still blocks (exit 2)', b3.code === 2 && /lodash/.test(b3.out));
+
 // --- end-to-end: unparseable stdin allowed ---
 const u = (() => {
   try {

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

@@ -24,6 +24,21 @@
 // cannot see. Blocking a lone `cd` would be far too aggressive (a legitimate,
 // common shape) so it is deliberately left to the prose directive.
 //
+// Redirections are not reads of a relative path: before a verb's args are
+// walked, output redirections (`>`, `>>`, `2>`, `&>`, glued or with a separate
+// target), fd duplications (`2>&1`) and heredoc/herestring introducers are
+// dropped together with their target, so `cat /abs/a > out.txt` or
+// `tail /abs/log 2>/dev/null` are not reported. An input redirection `< f` IS a
+// read: only the operator is dropped and `f` stays in the arg list, so
+// `cd app && cat < rel.txt` still blocks while `wc -l < /abs/a` passes.
+//
+// cwd exemption: when the hook payload carries the session `cwd` (absolute), a
+// joined `cd X`/`pushd X` whose literal target resolves to exactly that cwd is
+// a no-op, so it does not make later relative reads non-static. Dynamic or
+// special targets (`$VAR`, backticks, `~`, `-`, a bare `cd`) always count as a
+// directory change, and an unknown cwd behaves as before. The exemption only
+// avoids ARMING: once a real cd has armed the guard, nothing disarms it.
+//
 // Blocks with exit 2 + {"decision":"block","code":...,"reason":...}; allows
 // everything else. Crash-safe: any error -> exit 0 (never wedge the user's
 // workflow). Self-contained (its own dependency is the sibling lib/ module,
@@ -36,12 +51,14 @@
 // machinery (SEARCH_VERB_CONFIG, scanArgsSkippingPattern) are shared with
 // trailhead-secret-read-guard.js via lib/shell-scan.js (#135 follow-up), so
 // the two guards can never drift into two divergent tokenizers.
+const path = require('path');
 const {
   basename,
   stripQuotes,
   splitStatements,
   tokenize,
   skipEnvPrefix,
+  stripRedirections,
   SEARCH_VERB_CONFIG,
   scanArgsSkippingPattern,
 } = require('./lib/shell-scan.js');
@@ -114,7 +131,7 @@ const VERB_CONFIG = {
 // Walk a verb's argument tokens (verb itself already stripped) for the first
 // relative FILE argument found, via the shared pattern/flag-skipping walker.
 function scanArgsForRelativeFile(args, config) {
-  return scanArgsSkippingPattern(args, config, isRelativeFileArg);
+  return scanArgsSkippingPattern(stripRedirections(args), config, isRelativeFileArg);
 }
 
 // `git grep`/`git log`/`git show`/`git diff` WITHOUT a `-C` (or --work-tree):
@@ -177,6 +194,22 @@ function isCdOrPushdStatement(stmt) {
   return bin === 'cd' || bin === 'pushd';
 }
 
+// Does this cd/pushd statement provably stay in the session cwd? Only with a
+// known absolute cwd and exactly one static literal target resolving to it.
+function cdTargetsSessionCwd(stmt, cwd) {
+  if (typeof cwd !== 'string' || !path.isAbsolute(cwd)) return false;
+  const tokens = normalizeStatementTokens(tokenize(stmt));
+  let i = skipEnvPrefix(tokens) + 1; // past cd/pushd
+  while (i < tokens.length && tokens[i].startsWith('-') && tokens[i] !== '-') {
+    if (tokens[i++] === '--') break; // option flags (-P/-L/--) before the target
+  }
+  if (i !== tokens.length - 1) return false; // bare cd goes to $HOME; extra targets are unsure
+  const target = stripQuotes(tokens[i]);
+  if (!target || target === '-' || target.startsWith('~')) return false;
+  if (target.includes('$') || target.includes('`')) return false;
+  return path.resolve(cwd, target) === path.resolve(cwd);
+}
+
 // `env -C <dir> <cmd> …`: the directory change and the read live in the SAME
 // statement (env execs its argument as a single command with that cwd), so
 // this is checked independently of the cross-statement `cwdChanged` flag.
@@ -215,7 +248,7 @@ function envDashCRelativeRead(stmt) {
 // with no path argument at all implicitly searches the (now-relative) cwd,
 // but adding that case risks false-positiving on legitimate stdin-reading
 // commands, so it is left to the prose directive.
-function detectSearchHygieneViolation(cmd) {
+function detectSearchHygieneViolation(cmd, { cwd } = {}) {
   const statements = splitStatements(cmd);
   let cwdChanged = false;
   for (let idx = 0; idx < statements.length; idx++) {
@@ -233,7 +266,7 @@ function detectSearchHygieneViolation(cmd) {
     // the sole statement) - a lone standalone `cd` is the known limitation
     // above and must never be blocked here.
     if (isCdOrPushdStatement(stmt) && idx < statements.length - 1) {
-      cwdChanged = true;
+      if (!cdTargetsSessionCwd(stmt, cwd)) cwdChanged = true;
     }
   }
   return null;
@@ -251,9 +284,9 @@ function blockVerdict(hit) {
 
 // Pure verdict for one command: {kind:'allow'} or {kind:'block', payload}. Never
 // exits or writes; any internal error falls through to allow.
-function evaluate(cmd) {
+function evaluate(cmd, { cwd } = {}) {
   try {
-    const hit = detectSearchHygieneViolation(cmd);
+    const hit = detectSearchHygieneViolation(cmd, { cwd });
     if (hit) return blockVerdict(hit);
   } catch {
     // fall through to allow: a guard must never wedge the workflow
@@ -263,12 +296,15 @@ function evaluate(cmd) {
 
 function run(data) {
   let cmd = '';
+  let cwd;
   try {
-    cmd = (JSON.parse(data).tool_input || {}).command || '';
+    const input = JSON.parse(data);
+    cmd = (input.tool_input || {}).command || '';
+    cwd = typeof input.cwd === 'string' && input.cwd ? input.cwd : undefined;
   } catch {
     process.exit(0); // unparseable input: nothing to gate
   }
-  const v = evaluate(cmd);
+  const v = evaluate(cmd, { cwd });
   if (v.kind === 'block') {
     process.stdout.write(JSON.stringify(v.payload));
     process.exit(2);