session-orchestrator 3.19.0 → 3.20.0

package/scripts/emit-session.mjs

@@ -27,6 +27,7 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { appendJsonl } from './lib/common.mjs';
+import { serializeSessionLineChecked } from './lib/session-schema/serializer.mjs';
 import {
   validateSession,
   ValidationError,
@@ -35,45 +36,7 @@ import {
   aliasLegacyEndedAt,
 } from './lib/session-schema.mjs';
 
-/**
- * Serialize `validated` to a single JSONL line and prove it round-trips:
- * the line MUST be JSON-parseable AND the parsed-back object MUST still pass
- * `validateSession`. This is the pre-write self-validation seam (#662) that
- * mirrors the `appendLearning` guard — it catches non-serializable values
- * (`undefined`, `NaN`, `Infinity`, `BigInt`, circular refs) that
- * `JSON.stringify` silently drops or that produce a line which won't parse
- * back to the same schema-valid shape.
- *
- * Throws ValidationError (consumed by the caller as a validation failure,
- * exit 1). Does not write — the caller appends only after this returns.
- *
- * @param {object} validated — already validated session entry
- * @returns {string} the verified JSONL line (newline-terminated)
- * @throws {ValidationError} when the serialized line does not round-trip
- */
-export function serializeSessionLineChecked(validated) {
-  let line;
-  try {
-    line = JSON.stringify(validated);
-  } catch (err) {
-    throw new ValidationError(`session is not JSON-serializable: ${err.message}`);
-  }
-  if (typeof line !== 'string' || line.length === 0) {
-    throw new ValidationError('session serialized to an empty line');
-  }
-  let reparsed;
-  try {
-    reparsed = JSON.parse(line);
-  } catch (err) {
-    throw new ValidationError(
-      `serialized session line does not parse back as JSON: ${err.message}`
-    );
-  }
-  // Re-validate the round-tripped shape — catches required fields that were
-  // present as `undefined`/`NaN` before stringify but vanished after.
-  validateSession(reparsed);
-  return line + '\n';
-}
+export { serializeSessionLineChecked };
 
 function parseArgs(argv) {
   const args = { file: '.orchestrator/metrics/sessions.jsonl', entry: null };
@@ -167,7 +130,7 @@ async function main() {
   // sessions.jsonl and only surface on the NEXT session's read. Treated as a
   // validation failure (exit 1); file is left untouched.
   try {
-    serializeSessionLineChecked(validated);
+    serializeSessionLineChecked(repaired);
   } catch (err) {
     if (err instanceof ValidationError) {
       process.stderr.write(

package/scripts/lib/command-blocker.mjs

@@ -450,13 +450,27 @@ export function tokenizeCommand(command) {
     if (ch === '\n' && pendingHeredocs.length > 0) {
       flush();
       let j = i + 1;
+      let lastTerm = false;
       while (pendingHeredocs.length > 0) {
         const { delim, stripTabs } = pendingHeredocs.shift();
         const { body, end, terminated } = readHeredocBody(command, j, delim, stripTabs);
-        if (!terminated) { pendingHeredocs.length = 0; break; }
+        // The reset is load-bearing: a first here-doc may terminate (lastTerm
+        // true) while a SECOND one on the same line does not — leaving lastTerm
+        // set would rewind onto the unterminated body's first char instead of a
+        // real newline (#999).
+        if (!terminated) { lastTerm = false; pendingHeredocs.length = 0; break; }
+        lastTerm = true;
         if (body.length > 0) tokens.push({ text: body, quoted: true });
         j = end;
       }
+      // `readHeredocBody` returns `end` pointing PAST the newline that closes the
+      // terminator line, so `j` sits at the first char of the NEXT command and
+      // the separating newline is swallowed. Rewind onto it (when there is one —
+      // a terminator at input-end has none) so the newline reaches the separator
+      // branch below and `cat <<EOF\nbody\nEOF\nrm -rf /tmp/ok` splits into two
+      // segments. Without this the trailing command glued into the here-doc
+      // verb's segment and an allowlisted rm target failed closed (#999 FP).
+      if (lastTerm && command[j - 1] === '\n') j -= 1;
       i = j - 1;
       continue;
     }
@@ -790,10 +804,25 @@ export const WRAPPER_UNWRAP = new Map([
  * Return contract (ADDITIVE — `wrapperArgs` was appended in #988 T3; existing
  * consumers destructuring `{ verb, index, payloads }` are unaffected):
  *
+ * DUAL PARSE (#1000). An unknown dash-flag is ambiguous: this table cannot know
+ * whether `env -Q x bash -c '…'` means "`-Q` is a boolean, `x` is the verb" or
+ * "`-Q` takes `x`, `bash` is the verb". The resolver therefore reads the
+ * segment TWICE — parse A treats unknown flags as booleans (byte-identical to
+ * the pre-#1000 behaviour, and still the primary result), parse B treats them
+ * as value-taking — and reports the second reading as `alt` when it disagrees.
+ * Both readings are then judged, so a deny in EITHER is a deny: the safe
+ * direction, since guessing wrong in the boolean direction silently hid an
+ * interpreter behind an unrecognised flag (the measured #1000 bypass).
+ * `alt` is present ONLY when an unknown flag was skipped AND the two readings
+ * resolve a different verb or index; it is never nested (no `alt.alt`).
+ *
  * @param {Array<{ text: string, quoted: boolean }>} segment
  * @returns {{ verb: string|null, index: number, payloads: string[],
  *             wrapperArgs: Array<{ wrapper: string, flag: string, value: string|null,
- *                                  writesFile?: true }> }}
+ *                                  writesFile?: true }>,
+ *             alt?: { verb: string|null, index: number, payloads: string[],
+ *                     wrapperArgs: Array<{ wrapper: string, flag: string,
+ *                                          value: string|null, writesFile?: true }> } }}
  *   verb — bare program basename (or synthetic `sh` for `sudo -i`/`-s`), null
  *   when the segment exhausts in wrappers; index — token index of the resolved
  *   verb (-1 when null); payloads — command strings a wrapper will execute;
@@ -810,15 +839,23 @@ export const WRAPPER_UNWRAP = new Map([
  *   the answer to the question the caller actually has ("is this operand a
  *   write target?"), which used to be re-derived from a second table
  *   (`WRAPPER_FILE_FLAGS` in hooks/pre-bash-sessions-ledger-guard.mjs). That
- *   copy is now REDUNDANT and can be replaced by `wa.writesFile` (#991
- *   follow-up) — the knowledge lives here, next to the grammar it belongs to.
+ *   copy was replaced by `wa.writesFile` in #996.1 — the knowledge lives here,
+ *   next to the grammar it belongs to.
  *   `/usr/bin/time -o <ledger> npm test` truncates `<ledger>` while the verb is
  *   `npm`; extractRedirectTargets surfaces exactly these entries so the
  *   redirect denylist sees them too.
+ *
+ *   `alt` (#1000) — the value-taking reading of the same segment, present only
+ *   under the conditions above. Consumers that judge (matchSegments,
+ *   collectRedirectTargets) must consider BOTH readings; consumers that need a
+ *   single token position (`parseRmTargets`, the scope gate) keep reading the
+ *   primary `verb`/`index` only — `alt.index` addresses a DIFFERENT reading of
+ *   the token stream and must never be fed to a positional walk.
  */
-export function resolveSegmentVerb(segment) {
+function resolveCore(segment, unknownFlagsTakeValue) {
   const payloads = [];
   const wrapperArgs = [];
+  let sawUnknownFlag = false;
   let i = 0;
   // Skip leading FOO=bar env assignments (unquoted).
   while (i < segment.length && !segment[i].quoted && ENV_ASSIGN_RE.test(segment[i].text)) {
@@ -875,13 +912,48 @@ export function resolveSegmentVerb(segment) {
           wrapperArgs.push(entry);
         }
       }
-      i++; // unknown / boolean / attached-value flag — one token
+      // Unknown / boolean / attached-value flag. A dash token that survived
+      // envAssignments, `--`, the non-dash break, splitString, shellFlags,
+      // argFlags AND the attached-`=` form is one this table does not know —
+      // the ONLY place the two readings differ (#1000). No wrapperArgs entry is
+      // recorded in the value-taking reading: an unknown flag is by
+      // construction absent from fileArgFlags, so `writesFile` can never be
+      // invented for it.
+      sawUnknownFlag = true;
+      i += (unknownFlagsTakeValue && i + 1 < segment.length) ? 2 : 1;
     }
     for (let p = spec.positionals ?? 0; p > 0 && i < segment.length; p--) i++;
-    if (sawShellFlag) return { verb: 'sh', index: i, payloads, wrapperArgs };
+    if (sawShellFlag) return { verb: 'sh', index: i, payloads, wrapperArgs, sawUnknownFlag };
   }
-  if (i >= segment.length) return { verb: null, index: -1, payloads, wrapperArgs };
-  return { verb: segment[i].text.replace(/^.*\//, ''), index: i, payloads, wrapperArgs };
+  if (i >= segment.length) return { verb: null, index: -1, payloads, wrapperArgs, sawUnknownFlag };
+  return {
+    verb: segment[i].text.replace(/^.*\//, ''),
+    index: i,
+    payloads,
+    wrapperArgs,
+    sawUnknownFlag,
+  };
+}
+
+/**
+ * Strip the internal `sawUnknownFlag` marker from a resolveCore result, leaving
+ * the public shape. The key must be ABSENT (not undefined-valued) so a strict
+ * `toEqual` on an unambiguous resolution keeps passing.
+ *
+ * @param {{ verb: string|null, index: number, payloads: string[],
+ *           wrapperArgs: object[], sawUnknownFlag: boolean }} r
+ * @returns {{ verb: string|null, index: number, payloads: string[], wrapperArgs: object[] }}
+ */
+function stripCore(r) {
+  return { verb: r.verb, index: r.index, payloads: r.payloads, wrapperArgs: r.wrapperArgs };
+}
+
+export function resolveSegmentVerb(segment) {
+  const a = resolveCore(segment, false); // parse A — byte-identical to pre-#1000
+  if (!a.sawUnknownFlag) return stripCore(a); // unambiguous → no `alt` key at all
+  const b = resolveCore(segment, true); // parse B — unknown flags take a value
+  if (b.verb === a.verb && b.index === a.index) return stripCore(a);
+  return { ...stripCore(a), alt: stripCore(b) };
 }
 
 /**
@@ -938,6 +1010,45 @@ function quotedTokensMatch(segment, re) {
   return false;
 }
 
+/**
+ * How far a redirect token's syntax reaches: the index of the LAST token this
+ * redirect owns, starting at the redirect token itself (#1002).
+ *
+ * The grammar rule, stated ONCE (it was coded three times independently before
+ * this export existed):
+ *   - `dup` (`2>&1`) carries its target INLINE in the operator token — it owns
+ *     no following word.
+ *   - `heredoc` (`<<EOF`) consumes its delimiter as SYNTAX inside the lexer. A
+ *     terminated body arrives as a QUOTED token; an UNTERMINATED here-doc
+ *     leaves real command tokens behind, which must stay visible to the caller
+ *     — skipping a word here would eat the next real command (#970).
+ *   - EVERY other mode — `truncate` (`>`), `append` (`>>`), `read` (`<`) and
+ *     `herestring` (`<<<`) — owns the next word. `herestring` deliberately so:
+ *     in `rm -rf /tmp/x <<< /etc/passwd` the word after `<<<` is inline data
+ *     for the redirect, not an `rm` operand, and reading it as one would
+ *     invent a deletion target the command never had.
+ *   - A next token that is ITSELF a redirect is never an operand (`> >> x`):
+ *     the dangling redirect owns nothing.
+ *
+ * This does NOT answer "does this redirect name a filesystem target" — that is
+ * a SEPARATE rule, owned by collectRedirectTargets, which additionally excludes
+ * `herestring` (inline data names no file). Operand OWNERSHIP and target
+ * REPORTABILITY are different questions with different answers for `<<<`.
+ *
+ * @param {Array<{ text: string, quoted: boolean, redirect?: { mode: string } }>} segment
+ * @param {number} i — index of the redirect token
+ * @returns {number} `i` when the redirect owns no operand word, else `i + 1`
+ */
+export function redirectSpanEnd(segment, i) {
+  const tok = segment[i];
+  if (!tok || !tok.redirect) return i;
+  const hasOperandWord = tok.redirect.mode !== 'dup' && tok.redirect.mode !== 'heredoc';
+  if (hasOperandWord && i + 1 < segment.length && !segment[i + 1].redirect) {
+    return i + 1;
+  }
+  return i;
+}
+
 /**
  * Test whether a blocked pattern occurs OUTSIDE quoted tokens within a segment.
  * Reconstructs the unquoted skeleton (quoted tokens replaced by a single space
@@ -961,14 +1072,10 @@ function unquotedSegmentMatch(segment, re) {
     const tok = segment[i];
     if (tok.redirect) {
       parts.push(' ');
-      // `dup` (2>&1) has its target inline; `heredoc` consumes its delimiter in
-      // the lexer and its body arrives as a separate QUOTED token — neither has
-      // an operand word to skip, and skipping would eat the next real command.
-      const hasOperandWord = tok.redirect.mode !== 'dup' && tok.redirect.mode !== 'heredoc';
-      if (hasOperandWord && i + 1 < segment.length && !segment[i + 1].redirect) {
-        parts.push(' ');
-        i++; // operand word belongs to the redirect — skip it too
-      }
+      // Operand-span rule lives in redirectSpanEnd (#1002) — one grammar, one
+      // place. `end > i` is exactly the old inline predicate.
+      const end = redirectSpanEnd(segment, i);
+      if (end > i) { parts.push(' '); i = end; } // operand word belongs to the redirect
       continue;
     }
     parts.push(tok.quoted ? ' ' : tok.text);
@@ -985,6 +1092,42 @@ function unquotedSegmentMatch(segment, re) {
 const MAX_PAYLOAD_DEPTH = 3;
 const MAX_PAYLOAD_EVALUATIONS = 32;
 
+/**
+ * Build the DE-DUPLICATED payload set for a segment: the UNION of the primary
+ * reading's payloads and the ambiguous alt reading's payloads (#1000).
+ *
+ * The dual-parse union MUST be de-duped BEFORE budget accounting so an ambiguous
+ * segment is charged against the shared MAX_PAYLOAD_EVALUATIONS budget ONCE per
+ * DISTINCT payload — never the (primary + alt) sum (HIGH-1 remediation (a)). The
+ * pre-#1000 zero-charge for a non-interpreter primary verb is preserved
+ * naturally: when the alt reading adds no new distinct payload the set stays
+ * empty and no budget is consumed.
+ *
+ * Both matchSegments AND collectRedirectTargets consume this single helper so the
+ * union is applied IDENTICALLY on the match surface and the redirect surface. A
+ * redirect-recursion that walked parse A only was a denylist bypass
+ * (`env -Q x bash -c 'echo pwned > CLAUDE.md'` resolved to non-interpreter `x` in
+ * parse A, so its redirect target was never collected — HIGH-2).
+ *
+ * @param {Array<{ text: string, quoted: boolean }>} segment
+ * @param {{ verb: string|null, index: number, payloads: string[],
+ *           alt?: { verb: string|null, index: number, payloads: string[] } }} resolved
+ * @returns {string[]} distinct payload strings (insertion-ordered)
+ */
+function dedupedSegmentPayloads(segment, resolved) {
+  const payloadSet = new Set(resolved.payloads);
+  if (resolved.verb && DASH_C_SHELLS.has(resolved.verb)) {
+    for (const p of dashCPayloads(segment, resolved.index)) payloadSet.add(p);
+  }
+  if (resolved.alt) {
+    for (const p of resolved.alt.payloads) payloadSet.add(p);
+    if (resolved.alt.verb && DASH_C_SHELLS.has(resolved.alt.verb)) {
+      for (const p of dashCPayloads(segment, resolved.alt.index)) payloadSet.add(p);
+    }
+  }
+  return [...payloadSet];
+}
+
 /**
  * Match a blocked-pattern regex against tokenized chain segments — the shared
  * core of commandMatchesBlocked, recursion-capable for `-c` payloads (#982).
@@ -1012,21 +1155,35 @@ function matchSegments(segments, re, depth, budget) {
     const resolved = resolveSegmentVerb(segment);
 
     // 2) Quoted occurrence → only a match when the segment verb is an interpreter
-    //    that executes its quoted payload.
+    //    that executes its quoted payload. EITHER reading of an ambiguous
+    //    unknown flag counts (#1000): `env -Q x bash -c 'rm -rf /etc'` resolves
+    //    to the non-interpreter `x` in parse A and to `bash` in parse B.
     if (quotedTokensMatch(segment, re)) {
-      if (resolved.verb && SHELL_EXEC_INTERPRETERS.has(resolved.verb)) return true;
+      const isInterp = (v) => Boolean(v) && SHELL_EXEC_INTERPRETERS.has(v);
+      if (isInterp(resolved.verb) || isInterp(resolved.alt?.verb)) return true;
       // else: inert literal inside quotes for a non-interpreter verb → no match
       // for THIS segment; keep scanning other segments.
     }
 
-    // 3) `-c`/`env -S` payload recursion (depth-capped, budgeted).
+    // 3) `-c`/`env -S` payload recursion (depth-capped, budgeted). The payload
+    //    set is the de-duplicated UNION over both readings (dedupedSegmentPayloads)
+    //    so an ambiguous segment cannot double-charge the shared evaluation budget.
     if (depth < MAX_PAYLOAD_DEPTH) {
-      const payloads = resolved.payloads;
-      if (resolved.verb && DASH_C_SHELLS.has(resolved.verb)) {
-        payloads.push(...dashCPayloads(segment, resolved.index));
-      }
-      for (const payload of payloads) {
-        if (budget.remaining <= 0) break;
+      for (const payload of dedupedSegmentPayloads(segment, resolved)) {
+        // FAIL-VISIBLE cut-off (HIGH-1 remediation (b)). A silent `break` here
+        // was fail-OPEN: an attacker prepends 32 inert `env -Q x sh -c 'echo N'`
+        // filler segments — each charging one alt-reading payload against the
+        // shared 32-eval budget (#1000) — then the real deny-capable payload
+        // (`env -S 'rm -rf /'`) arrives with budget exhausted and the old `break`
+        // returned false → ALLOW (coordinator-measured deny-loss vs 1be450a).
+        // This matcher returns a boolean with no unresolved channel, so an
+        // UNJUDGED deny-capable payload is treated as a MATCH (fail-closed),
+        // mirroring collectRedirectTargets' budget-exhausted marker (#988 T2).
+        // A realistic benign command never approaches the budget (depth-capped
+        // at 3); only pathological width reaches exhaustion, and denying a
+        // command that also carries a blocked pattern in the raw string is the
+        // safe direction.
+        if (budget.remaining <= 0) return true;
         budget.remaining -= 1;
         const subTokens = tokenizeCommand(
           normalizeShellWhitespaceExpansions(payload, { expandSingleQuoted: true }),
@@ -1057,11 +1214,15 @@ function collectRedirectTargets(segments, out, depth, budget) {
       // Deliberate boundary: only file-operand modes are reported. `dup`
       // (`2>&1`) targets a file descriptor, `heredoc`/`herestring` operands
       // are inline data/delimiters — none names a filesystem target.
+      // NOTE: this mode filter is a SEPARATE rule from operand ownership
+      // (redirectSpanEnd) — `herestring` OWNS its next word but names no file,
+      // so it is excluded here and included there. Do not merge the two.
       if (mode === 'dup' || mode === 'heredoc' || mode === 'herestring') continue;
-      const operand = (i + 1 < segment.length && !segment[i + 1].redirect)
-        ? segment[i + 1]
-        : null;
-      if (operand) i++; // operand word belongs to this redirect
+      // Past the filter `hasOperandWord` is unconditionally true, so the shared
+      // span rule reduces to the old inline predicate (#1002).
+      const end = redirectSpanEnd(segment, i);
+      const operand = end > i ? segment[end] : null;
+      if (operand) i = end; // operand word belongs to this redirect
       if (!operand || /[$`]/.test(operand.text)) {
         // Variable indirection (`> "$X"`), command substitution (`> $(cmd)` /
         // backticks), or a missing operand: fail-visible, never guess (#983).
@@ -1088,9 +1249,25 @@ function collectRedirectTargets(segments, out, depth, budget) {
     // consumes — to buy back a false-positive class that is empty in practice
     // (nobody appends a timing report to a policy-protected file). An
     // under-report here is a bypass; this over-report is a nuisance at worst.
-    for (const wa of resolved.wrapperArgs) {
+    //
+    // Both readings of an ambiguous unknown flag contribute (#1000), UNIONED
+    // and never replaced: `env -Q x /usr/bin/time -o CLAUDE.md npm test` hides
+    // the operand from parse A (which reads `x` as the verb) and surfaces it in
+    // parse B, while `sudo -n /usr/bin/time -o report.txt npm test` is the
+    // mirror case — parse B swallows `/usr/bin/time` as `-n`'s operand and
+    // reports nothing. Replacement would lose one of the two.
+    const seenWrapperTargets = new Set();
+    const altWrapperArgs = resolved.alt ? resolved.alt.wrapperArgs : [];
+    for (const wa of [...resolved.wrapperArgs, ...altWrapperArgs]) {
       if (wa.writesFile !== true) continue;
       if (typeof wa.value !== 'string') continue;
+      // De-dup key is the OPERAND plus the mode, which for a resolved entry is
+      // exactly `target + ':' + mode`; using the operand keeps two distinct
+      // unresolved spellings (`"$OUT"` vs `"$X"`) distinct rather than
+      // collapsing them onto a shared `null` target.
+      const key = `${wa.value}:truncate`;
+      if (seenWrapperTargets.has(key)) continue;
+      seenWrapperTargets.add(key);
       if (/[$`]/.test(wa.value)) {
         // Same fail-visible rule as a redirect operand (#983): never guess at a
         // variable or a command substitution, but never silently drop it either.
@@ -1100,10 +1277,15 @@ function collectRedirectTargets(segments, out, depth, budget) {
       out.push({ target: wa.value, mode: 'truncate', fd: null });
     }
 
-    const payloads = [...resolved.payloads];
-    if (resolved.verb && DASH_C_SHELLS.has(resolved.verb)) {
-      payloads.push(...dashCPayloads(segment, resolved.index));
-    }
+    // Both readings of an ambiguous unknown flag contribute payloads (#1000),
+    // UNIONED and de-duped (HIGH-2). Walking parse A only let
+    // `env -Q x bash -c 'echo pwned > CLAUDE.md'` — which resolves to the
+    // non-interpreter `x` in parse A — bypass the redirect denylist entirely
+    // (coordinator-measured: `bash -c '… > CLAUDE.md'` DENY, `env -Q x bash -c
+    // '… > CLAUDE.md'` ALLOW). The same helper matchSegments uses guarantees the
+    // deduped-before-charging rule holds on this surface too, so the redirect
+    // recursion cannot be starved any differently than the match recursion.
+    const payloads = dedupedSegmentPayloads(segment, resolved);
     if (payloads.length === 0) continue;
 
     // A cap that drops payloads SILENTLY is a bypass, not a cap: 33 filler
@@ -1181,6 +1363,16 @@ export function extractRedirectTargets(command) {
  * duplicated locally because this module is hook-hot-path pure (no imports
  * beyond node built-ins, no I/O at import time; see header invariant).
  *
+ * CASE-INSENSITIVE (#994 R2): the returned RegExp carries the `i` flag
+ * UNCONDITIONALLY — no platform detection. Detection is unsafe in both
+ * directions (macOS can run case-sensitive APFS; Linux can mount
+ * case-insensitive volumes via ext4 casefold / ciopfs / CIFS), and a correct
+ * per-path answer would need filesystem I/O this module forbids (header
+ * invariant). The cost is asymmetric: a MISS truncates CLAUDE.md
+ * unrecoverably, whereas an over-block is a visible deny with two escapes
+ * (`>>`, the Write tool). So `> claude.md` / `> Claude.md` — the same inode as
+ * `CLAUDE.md` on a case-insensitive volume — deny like the canonical spelling.
+ *
  * @param {string} pattern
  * @returns {RegExp}
  */
@@ -1208,26 +1400,40 @@ function redirectGlobToRegExp(pattern) {
       i++;
     }
   }
-  return new RegExp(`^${re}$`);
+  return new RegExp(`^${re}$`, 'i');
 }
 
 /**
- * Collapse the macOS `/private` alias prefix: `/private/tmp` and `/private/var`
- * name the SAME directories as `/tmp` and `/var` (the short forms are symlinks
- * into `/private`). Without this, one location has two spellings that compare
- * unequal — a repo checked out under `/tmp/...` (CI runners, worktrees) would
- * not recognise its own root in a command that spells it `/private/tmp/...`.
+ * Collapse the macOS same-inode path aliases so one location has one spelling.
+ *
+ * Two independent alias classes, applied in order:
+ *   1. `/System/Volumes/Data/...` — the firmlink onto the Data volume: on APFS
+ *      `/System/Volumes/Data/repo` and `/repo` are the SAME inode. Stripped
+ *      FIRST so a `/System/Volumes/Data/private/tmp/...` spelling then also runs
+ *      through the `/private` strip below.
+ *   2. `/private/{tmp,var,etc}/...` — the short forms `/tmp`, `/var`, `/etc` are
+ *      symlinks into `/private`. Without this, a repo checked out under
+ *      `/tmp/...` (CI runners, worktrees) would not recognise its own root in a
+ *      command that spells it `/private/tmp/...`.
+ *
+ * A strip that would empty the path (`/System/Volumes/Data` itself) is guarded
+ * with `|| '/'` so the result stays an absolute path.
  *
  * Deliberately STATIC: no `realpathSync` on user input. Resolving an
  * attacker-supplied path at guard time is its own risk class, and this module
- * is I/O-free by header invariant. Only the two known macOS aliases collapse;
- * every other path is returned byte-identical.
+ * is I/O-free by header invariant. Only the known aliases collapse; every other
+ * path is returned byte-identical.
  *
  * @param {string} p — an absolute, already-normalized path
  * @returns {string}
  */
-function stripPrivateAlias(p) {
-  return /^\/private\/(?:tmp|var)(?:\/|$)/.test(p) ? p.slice('/private'.length) : p;
+function stripPathAliases(p) {
+  const dataStripped =
+    (/^\/System\/Volumes\/Data(?:\/|$)/.test(p) ? p.slice('/System/Volumes/Data'.length) : p) ||
+    '/';
+  return /^\/private\/(?:tmp|var|etc)(?:\/|$)/.test(dataStripped)
+    ? dataStripped.slice('/private'.length) || '/'
+    : dataStripped;
 }
 
 /**
@@ -1258,10 +1464,55 @@ function expandLeadingHome(target, home) {
   return home + target.slice(1);
 }
 
+/**
+ * Relativize an ABSOLUTE target against an absolute repoRoot to the repo-relative
+ * POSIX form the denylist globs use, or `null` when the target names the root
+ * itself or lies outside it.
+ *
+ * Both paths are alias-collapsed (`stripPathAliases`) and case-folded before the
+ * containment comparison (#994 R3): a case-insensitive volume makes `/REPO` and
+ * `/repo` the same directory, so the comparison that decides in-vs-out must fold
+ * too — otherwise an absolute spelling in the wrong case escapes the root and is
+ * silently allowed. Folding uses `toLocaleLowerCase('en-US')` explicitly (same
+ * rationale as scripts/lib/path-utils.mjs:46 — avoids the Turkish-İ divergence a
+ * locale-default `toLowerCase` carries). The returned path is therefore
+ * lowercased; it is matched against the denylist regexes, which carry the `i`
+ * flag (#994 R2), so the fold and the match agree.
+ *
+ * Shared by BOTH branches of `repoRelativeRedirectTarget` (absolute + relative)
+ * so the two can never drift again (#994 R1 structural fix).
+ *
+ * @param {string} absTarget — absolute, resolved target path
+ * @param {string} repoRoot — absolute repo root
+ * @returns {string|null}
+ */
+function relativizeAgainstRoot(absTarget, repoRoot) {
+  const fold = (p) => p.toLocaleLowerCase('en-US');
+  const rel = path.relative(
+    fold(stripPathAliases(path.normalize(repoRoot))),
+    fold(stripPathAliases(path.normalize(absTarget))),
+  );
+  // '' = the root itself (a directory, not a file target); '..'-prefixed or
+  // absolute = outside the repo, which the repo-relative denylist never covers.
+  if (rel === '' || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    return null;
+  }
+  return path.posix.normalize(rel).replace(/^(\.\/)+/, '');
+}
+
 /**
  * Reduce a raw redirect target to the repo-relative POSIX form the denylist
  * globs are written in, or `null` when it cannot name a file inside the repo.
  *
+ * A RELATIVE target (#994 R1) is interpreted as REPO-ROOT-relative, not
+ * shell-cwd-relative: after lexical normalization, a target that stays inside
+ * the root (no leading `..`) is already the repo-relative form and returned
+ * as-is; a target that climbs out (`../repo/CLAUDE.md`, `./a/../../repo/…`) is
+ * resolved against `repoRoot` and re-relativized through the SAME
+ * `relativizeAgainstRoot` the absolute branch uses. Without a usable `repoRoot`
+ * the pre-#994 lexical form is returned verbatim — byte-identical for
+ * optionless callers.
+ *
  * @param {string} raw — resolved target text (quotes already stripped)
  * @param {string|null} repoRoot — absolute repo root, or null (no resolution)
  * @param {string|undefined} home
@@ -1271,21 +1522,20 @@ function repoRelativeRedirectTarget(raw, repoRoot, home) {
   const expanded = expandLeadingHome(raw, home);
 
   if (!path.isAbsolute(expanded)) {
-    return path.posix.normalize(expanded).replace(/^(\.\/)+/, '');
+    const lexical = path.posix.normalize(expanded).replace(/^(\.\/)+/, '');
+    // Post-normalization, a leading `..` is the ONLY way a relative target
+    // leaves the root; anything else is already the repo-relative form (this
+    // also preserves the `~other/...` another-account spelling untouched).
+    if (!lexical.startsWith('../')) return lexical;
+    // A relative target that climbs out — resolve it against repoRoot. Without a
+    // usable root, return the pre-#994 lexical form (byte-identical contract).
+    if (!repoRoot || !path.isAbsolute(repoRoot)) return lexical;
+    return relativizeAgainstRoot(path.resolve(repoRoot, expanded), repoRoot);
   }
   // Absolute target: only judgeable against a known repo root. Without one the
   // pre-#988 behaviour stands (no match) rather than a guess.
   if (!repoRoot || !path.isAbsolute(repoRoot)) return null;
-  const rel = path.relative(
-    stripPrivateAlias(path.normalize(repoRoot)),
-    stripPrivateAlias(path.normalize(expanded)),
-  );
-  // '' = the root itself (a directory, not a file target); '..'-prefixed or
-  // absolute = outside the repo, which the repo-relative denylist never covers.
-  if (rel === '' || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
-    return null;
-  }
-  return path.posix.normalize(rel).replace(/^(\.\/)+/, '');
+  return relativizeAgainstRoot(expanded, repoRoot);
 }
 
 /**
@@ -1304,12 +1554,22 @@ function repoRelativeRedirectTarget(raw, repoRoot, home) {
  * so `> /abs/path/to/repo/CLAUDE.md` and `> ~/repo/CLAUDE.md` matched NOTHING
  * and were silently allowed (probe-measured `rule abs: false`, `rule tilde:
  * false` against `rule rel: true`). Pass `{ repoRoot }` and such a target is
- * tilde-expanded, `/private`-alias-collapsed and made repo-relative before the
- * globs run; a target outside the repo yields no match. WITHOUT `repoRoot`
- * (the default) an absolute target still never matches — identical to the
- * pre-#988 contract, so existing callers keep their exact behaviour. This
- * function stays I/O-free: `~` resolves from `process.env.HOME` (overridable
- * via `home`), never via a filesystem lookup.
+ * tilde-expanded, alias-collapsed and made repo-relative before the globs run;
+ * a target outside the repo yields no match. WITHOUT `repoRoot` (the default)
+ * an absolute target still never matches — identical to the pre-#988 contract,
+ * so existing callers keep their exact behaviour. This function stays I/O-free:
+ * `~` resolves from `process.env.HOME` (overridable via `home`), never via a
+ * filesystem lookup.
+ *
+ * Relative spellings and case (#994). A RELATIVE target is interpreted as
+ * REPO-ROOT-relative, NOT shell-cwd-relative: one that climbs out with `..`
+ * (`> ../repo/CLAUDE.md`) is resolved against `repoRoot` and re-relativized, so
+ * it is caught when it lands back inside the root and allowed when it does not
+ * (without `repoRoot`, such a target keeps its pre-#994 lexical form). The
+ * denylist globs and the absolute-containment comparison are BOTH
+ * case-insensitive, because a case-insensitive volume makes `> claude.md` the
+ * same inode as `CLAUDE.md`; the alias-collapse also covers `/System/Volumes/Data`
+ * and `/private/etc` alongside `/private/{tmp,var}`.
  *
  * Deliberate boundary (#641 FP class): `unresolved: true` entries (variable
  * indirection, command substitution) are NEVER matched — blocking on a guess

package/scripts/lib/hardening.mjs

@@ -3,18 +3,21 @@
  *
  * The original 691-line module bundled THREE structurally-independent concerns.
  * They now live in dedicated modules (Epic A4 split); this file is a pure
- * re-export barrel that preserves the original import surface (all 11 symbols)
+ * re-export barrel that preserves the surviving import surface (9 symbols)
  * so existing importers keep working UNCHANGED:
- *   - hooks/enforce-commands.mjs, hooks/enforce-scope.mjs,
- *     hooks/post-edit-validate.mjs, hooks/pre-bash-destructive-guard.mjs,
+ *   - hooks/enforce-commands.mjs, hooks/enforce-scope.mjs (both bind the barrel
+ *     via armGuard), hooks/post-bash-write-verify.mjs, hooks/post-edit-validate.mjs,
  *     hooks/pre-bash-memory-propose-audit.mjs, hooks/wave-scope-commit-guard.mjs
- *   - scripts/lib/io.mjs, scripts/lib/pre-dispatch-check.mjs,
- *     scripts/lib/worktree-freshness.mjs
+ *   - scripts/lib/pre-dispatch-check.mjs, scripts/lib/worktree-freshness.mjs
  *
  * Concern split:
  *   A) Env / runtime checks                → ./env-check.mjs
  *   B) Scope / pattern primitives          → ./scope-gate.mjs
- *   C) Command-blocking tokenizer + matcher → ./command-blocker.mjs
+ *   C) Command-blocking tokenizer + matcher → ./command-blocker.mjs. The
+ *      command-blocker primitives (tokenizeCommand, commandMatchesBlocked,
+ *      suggestForCommandBlock) were re-exported through this barrel until #996.3;
+ *      consumers now import them DIRECTLY from ./command-blocker.mjs, so this
+ *      barrel no longer touches concern C.
  *
  * The new modules MUST NOT import from this barrel (would cycle).
  *
@@ -38,6 +41,3 @@ export {
   extractBashWriteTargets,
   suggestForScopeViolation,
 } from './scope-gate.mjs';
-
-// C) Command-blocking tokenizer + matcher
-export { tokenizeCommand, commandMatchesBlocked, suggestForCommandBlock } from './command-blocker.mjs';