session-orchestrator 3.17.0 → 3.20.0

package/scripts/lib/scope-gate.mjs

@@ -14,6 +14,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
+import { tokenizeCommand, splitChainSegments, resolveSegmentVerb } from './command-blocker.mjs';
+
 /**
  * Find the wave-scope.json file for the given project root.
  *
@@ -223,6 +225,285 @@ export function assertFileScopeSubset(fileScope, allowedPaths) {
   return { ok: missing.length === 0, missing };
 }
 
+/**
+ * Default production→test sibling rules (#970). `source` is matched with
+ * {@link pathMatchesPattern}; `sibling` is a TEMPLATE expanded with `{basename}`
+ * (filename without its extension) and `{dir}` (dirname, no trailing slash).
+ *
+ * This repo's layout only. Consumer repos override via `opts.rules` — observed
+ * shapes there are `{ source: '**\/*.ts', sibling: '{dir}/{basename}.test.*' }`,
+ * `{ source: '**\/*.ts', sibling: '{dir}/__tests__/**' }` and
+ * `{ source: 'supabase/migrations/**', sibling: 'supabase/tests/**' }`.
+ *
+ * @type {ReadonlyArray<{source: string, sibling: string}>}
+ */
+export const DEFAULT_TEST_SIBLING_RULES = Object.freeze([
+  Object.freeze({ source: '**/*.mjs', sibling: 'tests/**/{basename}*.test.mjs' }),
+]);
+
+/**
+ * Patterns that identify an entry as ALREADY test-side. Used for the
+ * no-inverse-expansion rule and, transitively, for idempotency.
+ * @type {ReadonlyArray<string>}
+ */
+export const DEFAULT_TEST_PATH_PATTERNS = Object.freeze([
+  'tests/**',
+  'test/**',
+  '**/__tests__/**',
+  '**/*.test.*',
+  '**/*.spec.*',
+]);
+
+/**
+ * The wave roles for which test-sibling expansion (#970) fires. THE list — the
+ * prose in `skills/wave-executor/wave-loop.md` § Scope Manifest and
+ * `.cursor/rules/030-wave-execution.mdc` describes this constant; it does not
+ * restate it. Canonical casing; comparison is case-insensitive (see
+ * {@link testSiblingExpansionApplies}).
+ *
+ * Impl-Core / Impl-Polish are exactly where the incident occurred (an agent
+ * changes a production file and must update its test). Every other role is a
+ * documented non-expansion case: Discovery is deny-all `[]`, Quality phase 1
+ * (Simplification) MUST NOT gain test-write access, Quality phase 2 is already
+ * test-only (expansion is inert), Finalization writes no source.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const TEST_SIBLING_EXPANSION_ROLES = Object.freeze(['Impl-Core', 'Impl-Polish']);
+
+/** Lower-cased lookup set for {@link testSiblingExpansionApplies}. @type {ReadonlySet<string>} */
+const EXPANSION_ROLE_KEYS = new Set(TEST_SIBLING_EXPANSION_ROLES.map((r) => r.toLowerCase()));
+
+/**
+ * Does test-sibling expansion (#970) apply for these options? The SINGLE
+ * predicate behind both {@link expandTestSiblings} (which grants the siblings)
+ * and {@link assertTestSiblingCoverage} (which requires them). They must agree:
+ * a check that demands coverage the expander never produced blocks a dispatch
+ * for a requirement nobody was told to satisfy.
+ *
+ * Precedence — `enabled` (explicit, BOTH directions) > `role` > fail-closed:
+ *   1. `enabled === false` → NO. The unconditional opt-out; nothing overrides it.
+ *   2. `enabled === true`  → YES. Explicit opt-in, for callers whose role
+ *      vocabulary is not this repo's (consumer repos) and for focused tests.
+ *   3. `role` present → YES iff it is in {@link TEST_SIBLING_EXPANSION_ROLES}
+ *      (trimmed, case-insensitive — plans and `wave-scope.json` are written by
+ *      LLM prose, and `impl-core` vs `Impl-Core` must not silently change
+ *      behaviour).
+ *   4. Otherwise (role ABSENT, non-string, or UNRECOGNISED) → NO.
+ *
+ * ## Why absent-role fails CLOSED (the load-bearing choice)
+ * The two failure directions are not symmetric. Expansion wrongly OMITTED
+ * blocks an agent's write: it fails loudly, at the tool boundary, and the agent
+ * reports `blocked` — recoverable in one re-union. Expansion wrongly APPLIED
+ * silently hands write access to the test suite; in a Quality phase-1
+ * Simplification wave that is the "delete a dead export, then edit the test to
+ * match" failure mode, which defeats the very gate the wave exists to run.
+ * Silent-permissive is strictly worse than loud-restrictive, and this module's
+ * convention is already "cannot assert → treat as failure"
+ * (see {@link assertFileScopeSubset}). So a caller must NAME a role (or opt in
+ * explicitly); forgetting is not a grant.
+ *
+ * @param {{enabled?: boolean, role?: string}} [opts]
+ * @returns {boolean}
+ */
+export function testSiblingExpansionApplies(opts = {}) {
+  if (opts === null || typeof opts !== 'object') return false;
+  if (opts.enabled === false) return false;
+  if (opts.enabled === true) return true;
+  if (typeof opts.role !== 'string') return false;
+  return EXPANSION_ROLE_KEYS.has(opts.role.trim().toLowerCase());
+}
+
+/**
+ * Expand a wave scope list with the TEST SIBLING of every concrete production
+ * file it grants (#970).
+ *
+ * ## The bug this closes
+ * An `allowedPaths` / agent `fileScope` entry that lists a production file
+ * WITHOUT its test sibling mechanically prevents the agent from updating that
+ * test. Observed three times in one consumer-repo session: a SQL regression test
+ * that could not be written, a cross-tenant security test left unwritable while
+ * its subject file stayed red, and a suite left red because the importing test
+ * lay outside every agent's scope. The scope guard enforced exactly the
+ * inconsistency the quality gate exists to catch.
+ *
+ * ## Why a GLOB and not a computed path
+ * The emitted sibling is `tests/**\/{basename}*.test.mjs`, never a concrete
+ * path. Measured over all 430 tracked production `.mjs` in this repo:
+ * a naive 1:1 mirror (`scripts/lib/X.mjs → tests/lib/X.test.mjs`) is right
+ * 301/430 = 70.0% (`hooks/_lib` 0/5, `scripts/ci/` 0/1); a same-basename test
+ * ANYWHERE under `tests/` is right 368/430 = 85.6%. The glob takes the 85.6%
+ * form, and its failure mode is HARMLESS — it grants write access to files that
+ * may not exist. A computed concrete path is wrong 30% of the time AND still
+ * denies the real test, which is the original bug wearing a new face.
+ *
+ * ## Required behaviours (each is a nameable regression)
+ *  1. `[]` → `[]` STRUCTURALLY. Discovery waves use an empty scope as a
+ *     deliberate deny-all contract (#256 NO-OP); expansion must never be able to
+ *     resurrect a write there.
+ *  2. IDEMPOTENT — `expand(expand(x))` deep-equals `expand(x)`. The #796
+ *     re-union path rewrites the manifest mid-wave and the scope MUST NEVER
+ *     shrink, so expansion has to compose with a re-run. Guaranteed by (4): every
+ *     synthesized entry is itself a test path and is therefore inert on re-entry.
+ *  3. ABSOLUTE entries pass through untouched — a Gate-5b out-of-repo grant
+ *     (`/Users/…/vault/**`) must not sprout a synthetic `tests/**` sibling
+ *     outside the repo.
+ *  4. NO INVERSE EXPANSION — a test path never causes a production path to be
+ *     added. Quality phase 2's scope is already test-only; expansion is inert there.
+ *  5. ROLE-GATED, fail-closed — the wave's `role` decides, via the shared
+ *     predicate {@link testSiblingExpansionApplies}, and `opts.enabled` overrides
+ *     it in both directions. Quality phase 1 (Simplification) must NOT expand, or
+ *     simplification agents gain write access to the suite (the "delete a dead
+ *     export, then edit the test to match" failure mode). An absent or
+ *     unrecognised role does not expand — see the predicate for why.
+ *
+ * Glob source entries (`src/**`, `src/`) are NOT expanded: they have no single
+ * basename, and the incident shape is a concrete production FILE.
+ *
+ * APPEND-ONLY: the returned array starts with the input entries in their original
+ * order (deduplicated), then the synthesized siblings in first-seen order.
+ *
+ * Pure: no I/O, no filesystem probing, never throws. A non-array input returns `[]`.
+ *
+ * @param {string[]} paths — a wave `allowedPaths` union OR one agent's `fileScope`
+ * @param {{enabled?: boolean, role?: string,
+ *          rules?: ReadonlyArray<{source: string, sibling: string}>,
+ *          testPathPatterns?: ReadonlyArray<string>}} [opts]
+ * @returns {string[]} the input entries followed by synthesized test-sibling globs
+ */
+export function expandTestSiblings(paths, opts = {}) {
+  if (!Array.isArray(paths) || paths.length === 0) return []; // behaviour 1
+  const entries = paths.filter((e) => typeof e === 'string' && e.length > 0);
+  const seen = new Set(entries);
+  const out = [...new Set(entries)];
+  if (!testSiblingExpansionApplies(opts)) return out; // behaviour 5
+
+  for (const sibling of testSiblingsFor(entries, opts)) {
+    if (seen.has(sibling)) continue;
+    seen.add(sibling);
+    out.push(sibling);
+  }
+  return out;
+}
+
+/**
+ * The synthesized test-sibling globs for a scope list, in first-seen order —
+ * WITHOUT the original entries. Shared by {@link expandTestSiblings} and the
+ * `--assert-subset` coverage check so both agree on what a sibling is.
+ *
+ * @param {string[]} entries — already-filtered non-empty string entries
+ * @param {{rules?: ReadonlyArray<{source: string, sibling: string}>,
+ *          testPathPatterns?: ReadonlyArray<string>}} [opts]
+ * @returns {string[]}
+ */
+export function testSiblingsFor(entries, opts = {}) {
+  const rules = Array.isArray(opts.rules) ? opts.rules : DEFAULT_TEST_SIBLING_RULES;
+  const testPatterns = Array.isArray(opts.testPathPatterns)
+    ? opts.testPathPatterns
+    : DEFAULT_TEST_PATH_PATTERNS;
+  const out = [];
+  const seen = new Set();
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    if (typeof entry !== 'string' || entry.length === 0) continue;
+    if (path.isAbsolute(entry)) continue; // behaviour 3
+    if (isGlobScopeEntry(entry)) continue; // no single basename to mirror
+    if (isTestPathEntry(entry, testPatterns)) continue; // behaviours 2 + 4
+    for (const rule of rules) {
+      if (!rule || typeof rule.source !== 'string' || typeof rule.sibling !== 'string') continue;
+      if (!pathMatchesPattern(entry, rule.source)) continue;
+      const sibling = renderSiblingTemplate(rule.sibling, entry);
+      if (!sibling || seen.has(sibling)) continue;
+      seen.add(sibling);
+      out.push(sibling);
+    }
+  }
+  return out;
+}
+
+/**
+ * Is this entry already test-side? Behaviours 2 + 4 both reduce to this check.
+ * @param {string} entry
+ * @param {ReadonlyArray<string>} testPatterns
+ * @returns {boolean}
+ */
+function isTestPathEntry(entry, testPatterns) {
+  return testPatterns.some((p) => pathMatchesPattern(entry, p));
+}
+
+/**
+ * Expand `{basename}` / `{dir}` in a sibling template against a production path.
+ * `{basename}` is the filename with its final extension removed.
+ * @param {string} template
+ * @param {string} entry
+ * @returns {string}
+ */
+function renderSiblingTemplate(template, entry) {
+  const base = entry.slice(entry.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  const basename = dot > 0 ? base.slice(0, dot) : base;
+  const slash = entry.lastIndexOf('/');
+  const dir = slash === -1 ? '.' : entry.slice(0, slash);
+  return template.replaceAll('{basename}', basename).replaceAll('{dir}', dir);
+}
+
+/**
+ * Assert that the wave's `allowedPaths` union grants the TEST SIBLING of every
+ * concrete production file in an agent's declared `fileScope` (#970).
+ *
+ * Companion to {@link assertFileScopeSubset}, wired into
+ * `validate-wave-scope.mjs --assert-subset --expand-test-siblings`. That flag is
+ * the one mechanical, fail-closed enforcement point in the dispatch pipeline (it
+ * exits 1); a warn there would be decorative, since warnings in that script do
+ * not affect the exit code.
+ *
+ * DIRECTION MATTERS: this expands the AGENT'S fileScope and requires the union to
+ * cover the result. Expanding `allowedPaths` instead would WEAKEN
+ * `--assert-subset` — its value is that it is a conservative over-approximation,
+ * and growing the union makes more things trivially "covered". This only ever
+ * ADDS a requirement; a manifest that passed the plain subset check can now fail,
+ * never the reverse.
+ *
+ * A synthesized glob `G` counts as covered when ANY of:
+ *   1. `G` is present verbatim in allowedPaths;
+ *   2. some allowedPaths entry MATCHES `G` — the union already grants a concrete
+ *      file that IS a test sibling (`tests/lib/x.test.mjs` ⊨ `tests/**\/x*.test.mjs`);
+ *   3. `G`'s literal prefix is covered by an allowedPaths pattern — the same
+ *      glob rule {@link assertFileScopeSubset} uses (a broad `tests/**` grant).
+ *
+ * ROLE-GATED BY THE SAME PREDICATE as the expander
+ * ({@link testSiblingExpansionApplies}). This is not symmetry for its own sake:
+ * a Quality phase-1 union is production files with tests deliberately excluded,
+ * so an ungated assertion would demand coverage that phase must never grant and
+ * would hard-block its dispatch. When the gate is off the assertion adds NO
+ * requirement (`{ ok: true }`) rather than failing closed — "expansion did not
+ * fire here" and "the union is deficient" are different facts, and only the
+ * second is a dispatch blocker. Non-array inputs still fail closed
+ * (`{ ok: false }`), matching the module convention.
+ *
+ * @param {string[]} fileScope — one agent's declared file scope
+ * @param {string[]} allowedPaths — the wave's allowedPaths union
+ * @param {object} [opts] — same shape as {@link expandTestSiblings} (incl. `role`)
+ * @returns {{ok: boolean, missing: string[]}} missing = uncovered sibling globs
+ */
+export function assertTestSiblingCoverage(fileScope, allowedPaths, opts = {}) {
+  if (!Array.isArray(fileScope) || !Array.isArray(allowedPaths)) {
+    return { ok: false, missing: [] };
+  }
+  if (!testSiblingExpansionApplies(opts)) return { ok: true, missing: [] };
+  const missing = [];
+  for (const sibling of testSiblingsFor(fileScope, opts)) {
+    const prefix = literalScopePrefix(sibling);
+    const covered = allowedPaths.some(
+      (p) =>
+        typeof p === 'string' &&
+        p.length > 0 &&
+        (p === sibling || pathMatchesPattern(p, sibling) || pathMatchesPattern(prefix, p)),
+    );
+    if (!covered) missing.push(sibling);
+  }
+  return { ok: missing.length === 0, missing };
+}
+
 /**
  * Extract likely file-write TARGETS from a Bash command string (#800).
  *
@@ -262,6 +543,55 @@ export function assertFileScopeSubset(fileScope, allowedPaths) {
  * relatively, absolute where the command used an absolute path) and de-duplicated
  * in first-seen order. The caller relativises + matches against allowedPaths.
  *
+ * ## Lexing is DELEGATED to the shared tokenizer (#970)
+ *
+ * This function used to carry its OWN Bash lexer (`tokenizeShellForWrites`) —
+ * the third in this repo that had to know about quoting. It knew nothing about
+ * comments, here-doc BODIES or ANSI-C `$'…'` quotes, so it carried the exact
+ * quote-desync defect #965 fixed in `tokenizeCommand`: one apostrophe in an
+ * ordinary shell comment (`# don't`) wedged it in single-quote state and every
+ * later `>` became quoted text. Measured before the fix — `# don't\necho x >
+ * src/secret.ts` returned `[]`, i.e. an out-of-scope write was INVISIBLE to the
+ * wave-scope write guard. Two here-doc and ANSI-C variants did the same.
+ *
+ * It now delegates to `tokenizeCommand` from `./command-blocker.mjs`, which
+ * already emits the `>`/`>>`/`<<`/`;`/`|`/`&` operator tokens this pass needs
+ * and is the single place comment / here-doc / quote semantics live. Layering
+ * holds: `command-blocker.mjs` imports NOTHING (measured), so the edge
+ * scope-gate → command-blocker adds no cycle, and both stay pure/no-I/O-at-
+ * import for the hook hot path. The barrel `hardening.mjs` is not involved (a
+ * module importing the barrel WOULD cycle).
+ *
+ * Two deltas the shared token stream does not carry, handled locally below:
+ *   - `(`/`)`: `tokenizeCommand` keeps them inside word text (they are not
+ *     control operators for its purpose). {@link peelSubshellParens} splits them
+ *     back out as separators so `(echo x > y)` still yields `y` and
+ *     `> >(cat)` still yields nothing.
+ *   - here-doc BODY tokens arrive as ordinary quoted words. They are DATA, and a
+ *     body is multi-line, so the whitespace skip rule in
+ *     {@link shouldSkipWriteTarget} drops them. (The delimiter word itself now
+ *     emits no token at all — an improvement: `tee out.txt <<EOF` used to report
+ *     the literal `EOF` as a second write target.)
+ *
+ * ## Segment-first, wrapper-aware verb resolution (#996.2)
+ *
+ * The interpretation is SEGMENT-first: the token stream is split on shell chain
+ * operators / newlines by {@link splitChainSegments} BEFORE it is interpreted,
+ * and each segment's real command verb is resolved through the shared
+ * {@link resolveSegmentVerb} wrapper table. A lone `expectCommand` flag used to
+ * read the FIRST word of a segment as the command head, so a transparent wrapper
+ * (`sudo`, `env FOO=1`, `timeout 5`, `nice -n 10`, `command`, `/usr/bin/time`)
+ * consumed the head slot and the REAL verb (`tee`/`sed`/`dd`) landed in argument
+ * position where it was never matched — measured `sudo tee src/x.ts` → `[]`, a
+ * DETECTION LOSS. This is the same fail-open class #991 closed in the ledger
+ * guard, in a warn-only (#800) consumer. `resolveSegmentVerb` unwraps the
+ * wrappers and returns a BASENAME-normalized verb, so an absolute `/usr/bin/tee`
+ * resolves to `tee` for free. It ALSO reports wrapper-written file operands
+ * (`writesFile: true`, the #992 discriminator) — `/usr/bin/time -o FILE npm test`
+ * truncates FILE while the verb is `npm`, a write with no redirect operator and
+ * no tee/sed/dd head; those are harvested exactly as {@link extractRedirectTargets}
+ * does.
+ *
  * Hook-safe: pure, deterministic, no I/O. Never throws — a non-string / empty
  * input returns `[]`.
  *
@@ -271,83 +601,123 @@ export function assertFileScopeSubset(fileScope, allowedPaths) {
 export function extractBashWriteTargets(command) {
   if (typeof command !== 'string' || command.length === 0) return [];
 
-  const tokens = tokenizeShellForWrites(command);
-
   const out = [];
   const seen = new Set();
-  const add = (value, hadSpace) => {
-    if (shouldSkipWriteTarget(value, hadSpace)) return;
+  const add = (value) => {
+    if (shouldSkipWriteTarget(value)) return;
     const v = value.replace(/^\.\//, '');
     if (!v || seen.has(v)) return;
     seen.add(v);
     out.push(v);
   };
 
-  // Second pass: interpret the token stream. `mode` tracks a command-head that
-  // owns following args (tee/sed/dd); `pendingRedirect` marks that the NEXT word
-  // token is a redirect target.
-  let mode = null; // null | 'tee' | 'sed' | 'dd'
-  let pendingRedirect = false;
-  let expectCommand = true; // next word is the command head of this segment
-  let sedArgs = []; // { value } collected for a `sed` head
-  let sedInPlace = false;
+  // Segment-first (#996.2): split on shell chain operators / newlines BEFORE
+  // interpreting, then resolve each segment's REAL verb through the shared
+  // wrapper table. `out`/`seen`/`add` stay outside the loop so de-duplication
+  // and first-seen ordering hold across segments (`echo a > x; echo b >> x`).
+  for (const segment of splitChainSegments(tokenizeCommand(command))) {
+    // #996.2 namespace fix: resolve the verb in the SAME (paren-peeled,
+    // redirect-target-excluded) namespace the interpretation loop's `wordsSeen`
+    // counter walks below — see {@link verbResolutionSegment}. Passing the RAW
+    // segment mis-resolved a LEADING redirect (`> a.txt tee b.ts` → verb `>`) or a
+    // LEADING subshell paren (`(tee inner.ts)` → verb `(tee`): mode never became
+    // `tee`/`sed`/`dd` and the `index + 1` head-skip then swallowed the real
+    // write target. For A5's 10 wrapper forms (no leading redirect/paren) the view
+    // is a no-op, so verb/index/wrapperArgs — incl. the #992 `writesFile` marks —
+    // are byte-identical to the raw call.
+    const { verb, index, wrapperArgs } = resolveSegmentVerb(verbResolutionSegment(segment));
+    const tokens = classifyShellTokens(segment);
+
+    // A wrapper can WRITE a file through its OWN option, with no redirect and no
+    // tee/sed/dd verb: `/usr/bin/time -o src/report.txt npm test` truncates
+    // src/report.txt while the resolved verb is `npm`. `resolveSegmentVerb` marks
+    // exactly those operands `writesFile: true` (the #992 discriminator that
+    // keeps `nice -n 10` / `sudo -u root` operands OUT). Harvest them exactly as
+    // collectRedirectTargets does — the write is otherwise invisible to this pass.
+    for (const wa of wrapperArgs) {
+      if (wa.writesFile === true && typeof wa.value === 'string') add(wa.value);
+    }
+
+    // `mode` tracks a command-head that owns following args (tee/sed/dd). It is
+    // set ONCE per segment from the resolved verb, which `resolveSegmentVerb`
+    // returns basename-normalized — so an absolute `/usr/bin/tee` resolves to
+    // `tee` for free. `pendingRedirect` marks that the NEXT word is a redirect
+    // target; `heredocOpen` that a here-doc BODY word (DATA) follows.
+    const mode = verb === 'tee' || verb === 'sed' || verb === 'dd' ? verb : null;
+    let pendingRedirect = false;
+    let heredocOpen = false;
+    const sedArgs = []; // classified word tokens collected for a `sed -i` head
+    let sedInPlace = false;
+
+    // THE ONE CARE POINT of the #996.2 refactor: the first `index + 1` WORD
+    // tokens that REACH the `wordsSeen` counter are the wrapper chain + the verb
+    // itself, never file arguments. `index` now comes from
+    // {@link verbResolutionSegment}, which resolves the verb in the SAME namespace
+    // this loop walks — paren-peeled words with redirect targets removed — so
+    // `index` is 1:1 with the `word` tokens that reach the counter below (a
+    // leading redirect or subshell paren no longer shifts it out of alignment).
+    // `peelSubshellParens` emits AT MOST one `word` per raw token.
+    const headWordsToSkip = index + 1;
+    let wordsSeen = 0;
+
+    for (const tk of tokens) {
+      if (tk.type === 'redirect') {
+        pendingRedirect = true;
+        continue;
+      }
+      if (tk.type === 'heredoc') {
+        // here-doc: the delimiter emits no token; the BODY arrives later as data
+        pendingRedirect = false;
+        heredocOpen = true;
+        continue;
+      }
+      if (tk.type === 'in') {
+        // input redirect / here-string — not a write target
+        pendingRedirect = false;
+        continue;
+      }
+      if (tk.type === 'sep') {
+        // Within a segment the ONLY seps are peeled subshell parens — chain
+        // operators were already consumed by splitChainSegments. Reset only the
+        // pending redirect so `> >(cat)` stays inert (without it the peeled `cat`
+        // reads as the redirect target); mode/heredoc reset live at segment end.
+        pendingRedirect = false;
+        continue;
+      }
+      // word token
+      if (pendingRedirect) {
+        add(tk.value);
+        pendingRedirect = false;
+        continue;
+      }
+      if (wordsSeen < headWordsToSkip) {
+        wordsSeen++; // wrapper chain + verb head — not a file argument
+        continue;
+      }
+      // subsequent argument words, interpreted per active command-head mode
+      if (heredocOpen) continue; // DATA, not a file argument
+      if (mode === 'tee') {
+        if (!isShellFlag(tk.value)) add(tk.value);
+      } else if (mode === 'sed') {
+        if (/^-i/.test(tk.value)) sedInPlace = true;
+        sedArgs.push(tk);
+      } else if (mode === 'dd') {
+        if (tk.value.startsWith('of=')) add(tk.value.slice(3));
+      }
+    }
 
-  const flushSed = () => {
+    // Segment end: flush a pending `sed -i` file argument (last non-flag arg).
+    // Only reached once per segment now that each segment carries a single verb,
+    // so the former sep-branch / defensive flushes are unnecessary.
     if (mode === 'sed' && sedInPlace) {
       for (let i = sedArgs.length - 1; i >= 0; i--) {
         if (!isShellFlag(sedArgs[i].value)) {
-          add(sedArgs[i].value, sedArgs[i].hadSpace);
+          add(sedArgs[i].value);
           break;
         }
       }
     }
-    sedArgs = [];
-    sedInPlace = false;
-  };
-
-  for (const tk of tokens) {
-    if (tk.type === 'redirect') {
-      pendingRedirect = true;
-      continue;
-    }
-    if (tk.type === 'in') {
-      // input redirect / heredoc delimiter — not a write target
-      pendingRedirect = false;
-      continue;
-    }
-    if (tk.type === 'sep') {
-      flushSed();
-      mode = null;
-      pendingRedirect = false;
-      expectCommand = true;
-      continue;
-    }
-    // word token
-    if (pendingRedirect) {
-      add(tk.value, tk.hadSpace);
-      pendingRedirect = false;
-      continue;
-    }
-    if (expectCommand) {
-      expectCommand = false;
-      flushSed(); // flush any prior sed segment defensively
-      if (tk.value === 'tee') { mode = 'tee'; continue; }
-      if (tk.value === 'sed') { mode = 'sed'; continue; }
-      if (tk.value === 'dd') { mode = 'dd'; continue; }
-      mode = null;
-      continue;
-    }
-    // subsequent argument words, interpreted per active command-head mode
-    if (mode === 'tee') {
-      if (!isShellFlag(tk.value)) add(tk.value, tk.hadSpace);
-    } else if (mode === 'sed') {
-      if (/^-i/.test(tk.value)) sedInPlace = true;
-      sedArgs.push(tk);
-    } else if (mode === 'dd') {
-      if (tk.value.startsWith('of=')) add(tk.value.slice(3), tk.hadSpace);
-    }
   }
-  flushSed();
 
   return out;
 }
@@ -365,13 +735,15 @@ function isShellFlag(v) {
 /**
  * Skip-rule gate for a candidate write target — see the documented skip list on
  * {@link extractBashWriteTargets}. Returns true when the candidate must be dropped.
- * @param {string} value — unquoted target text
- * @param {boolean} hadSpace — true if the source token was quoted AND contained a space
+ * @param {string} value — unquoted target text (quotes already stripped by the lexer)
  * @returns {boolean}
  */
-function shouldSkipWriteTarget(value, hadSpace) {
+function shouldSkipWriteTarget(value) {
   if (typeof value !== 'string' || value.length === 0) return true;
-  if (hadSpace || value.includes(' ')) return true; // quoted-with-space (best-effort)
+  // Any embedded whitespace: a quoted-with-space path (best-effort — far more
+  // likely a quoting artefact than a real wave-scoped file) and, since #970, a
+  // multi-line here-doc BODY token that reached an argument slot as DATA.
+  if (/\s/.test(value)) return true;
   if (value.startsWith('$') || value.startsWith('~')) return true; // variable / expansion
   if (value.includes('$')) return true; // any embedded expansion (covers ${TMPDIR})
   if (value.includes('(') || value.includes(')')) return true; // process-sub remnants
@@ -380,99 +752,150 @@ function shouldSkipWriteTarget(value, hadSpace) {
   return false;
 }
 
+/** Unquoted `tokenizeCommand` operator texts that break the current command. */
+const SHELL_SEPARATOR_OPS = new Set([';', '|', '||', '&', '&&']);
+/** Write redirects: `>`, `>>`, `>|`, and fd-prefixed forms (`2>`, `2>>`). */
+const WRITE_REDIRECT_OP_RE = /^\d*(?:>>|>\|?)$/;
+/** Here-doc operators `<<` / `<<-` — a DATA body token follows at the next newline. */
+const HEREDOC_OP_RE = /^\d*<<-?$/;
+/** Other input redirects `<` / `<<<` (here-string) — never a write target, no body. */
+const INPUT_REDIRECT_OP_RE = /^\d*(?:<<<|<)$/;
+
 /**
- * Minimal quote-aware tokenizer for write-target extraction. Walks the command
- * left-to-right tracking single/double quote state; recognises redirect / input /
- * separator operators ONLY outside quotes, and emits everything else as `word`
- * tokens with the quotes stripped. Not a general shell tokenizer — it captures
- * exactly what {@link extractBashWriteTargets} needs.
+ * Split leading `(` / trailing `)` off an UNQUOTED word token into standalone
+ * separator tokens.
+ *
+ * `tokenizeCommand` does not treat parentheses as control operators (it does not
+ * need to), so `(echo x > y)` arrives as words `(echo` … `y)`. Without this the
+ * subshell's redirect target would read as the literal `y)` and be dropped by the
+ * paren skip rule in {@link shouldSkipWriteTarget} — a silent DETECTION LOSS
+ * versus the pre-#970 lexer. Peeling restores it, and process substitution
+ * `> >(cat)` still yields nothing because the peeled `cat` lands in command-head
+ * position rather than redirect-target position.
+ *
+ * Quoted tokens are never peeled: `echo '(' x` must keep its literal paren.
+ *
+ * @param {{text: string, quoted: boolean}} tok
+ * @returns {Array<{type: string, value?: string}>}
+ */
+function peelSubshellParens(tok) {
+  if (tok.quoted) return [{ type: 'word', value: tok.text }];
+  let text = tok.text;
+  const out = [];
+  while (text.startsWith('(')) { out.push({ type: 'sep' }); text = text.slice(1); }
+  const trailing = [];
+  while (text.endsWith(')')) { trailing.push({ type: 'sep' }); text = text.slice(0, -1); }
+  if (text.length > 0 || (out.length === 0 && trailing.length === 0)) {
+    out.push({ type: 'word', value: text });
+  }
+  return out.concat(trailing);
+}
+
+/**
+ * Re-shape the shared `tokenizeCommand` output into the redirect/in/sep/word
+ * stream {@link extractBashWriteTargets} interprets. Operator classification is
+ * applied ONLY to unquoted tokens, so `echo '>' x` keeps its `>` as literal text.
+ *
+ * `&>` is not a distinct token here: `tokenizeCommand` deliberately lexes it as
+ * `&` followed by `>` (#965 Risk C). That still works — the redirect branch of the
+ * interpretation loop is checked before the command-head branch, so `cmd &> log`
+ * yields `log`. `2>&1` likewise yields nothing: the `&` separator resets the
+ * pending redirect before `1` is read.
  *
  * Token shapes: { type: 'redirect' } | { type: 'in' } | { type: 'sep' }
- *             | { type: 'word', value: string, hadSpace: boolean }
+ *             | { type: 'word', value: string }
  *
- * @param {string} command
- * @returns {Array<{type:string, value?:string, hadSpace?:boolean}>}
+ * @param {Array<{text: string, quoted: boolean}>} tokens
+ * @returns {Array<{type: string, value?: string}>}
  */
-function tokenizeShellForWrites(command) {
-  const tokens = [];
-  const n = command.length;
-  let i = 0;
-  const isWs = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r';
-
-  while (i < n) {
-    const c = command[i];
-    const next = command[i + 1];
-
-    if (isWs(c)) { i++; continue; }
-
-    // `&>` / `&>>` — redirect stdout+stderr to a file (write target follows)
-    if (c === '&' && next === '>') {
-      i += 2;
-      if (command[i] === '>') i++;
-      tokens.push({ type: 'redirect' });
-      continue;
-    }
-    // `&&` / `&` — command separators
-    if (c === '&') {
-      i += next === '&' ? 2 : 1;
-      tokens.push({ type: 'sep' });
-      continue;
-    }
-    // `>&` — fd duplication (NOT a file target); consume the dup + trailing fd/`-`
-    if (c === '>' && next === '&') {
-      i += 2;
-      while (i < n && (/[0-9]/.test(command[i]) || command[i] === '-')) i++;
-      continue; // no token — dup carries no write target
-    }
-    // `>(` — process substitution: leave the `>` inert; `(` is emitted as a sep
-    if (c === '>' && next === '(') { i++; continue; }
-    // `>>` / `>` — write redirects
-    if (c === '>') {
-      i += next === '>' ? 2 : 1;
-      tokens.push({ type: 'redirect' });
-      continue;
-    }
-    // `<<` / `<` — input redirects / heredoc delimiters (never a write target)
-    if (c === '<') {
-      i += next === '<' ? 2 : 1;
-      tokens.push({ type: 'in' });
-      continue;
+function classifyShellTokens(tokens) {
+  const out = [];
+  for (const tok of tokens) {
+    if (!tok.quoted) {
+      if (SHELL_SEPARATOR_OPS.has(tok.text)) { out.push({ type: 'sep' }); continue; }
+      if (WRITE_REDIRECT_OP_RE.test(tok.text)) { out.push({ type: 'redirect' }); continue; }
+      if (HEREDOC_OP_RE.test(tok.text)) { out.push({ type: 'heredoc' }); continue; }
+      if (INPUT_REDIRECT_OP_RE.test(tok.text)) { out.push({ type: 'in' }); continue; }
     }
-    // `||` / `|` / `;` / `(` / `)` — separators (break the current command)
-    if (c === '|') { i += next === '|' ? 2 : 1; tokens.push({ type: 'sep' }); continue; }
-    if (c === ';') { i++; tokens.push({ type: 'sep' }); continue; }
-    if (c === '(' || c === ')') { i++; tokens.push({ type: 'sep' }); continue; }
-
-    // Otherwise: read a WORD, honouring single/double quotes (quotes stripped).
-    let value = '';
-    let quoted = false;
-    let hadSpace = false;
-    while (i < n) {
-      const ch = command[i];
-      if (ch === "'") {
-        quoted = true;
-        i++;
-        while (i < n && command[i] !== "'") { if (command[i] === ' ') hadSpace = true; value += command[i]; i++; }
-        i++; // closing quote (or EOF)
+    out.push(...peelSubshellParens(tok));
+  }
+  return out;
+}
+
+/**
+ * Project a raw chain segment into the token list used for VERB resolution,
+ * in the SAME namespace {@link extractBashWriteTargets}'s interpretation loop
+ * walks with its `wordsSeen` counter (#996.2 namespace fix).
+ *
+ * {@link resolveSegmentVerb} resolves argv[0] from RAW tokens. Two segment shapes
+ * put a NON-verb token in raw position 0 and so mis-resolve the command head,
+ * losing the write target the pre-#996.2 pass had detected:
+ *   - a LEADING write-redirect — `> a.txt tee b.ts` resolves the `>` operator as
+ *     the "verb" (mode never becomes `tee`), and the loop's `index + 1` head-skip
+ *     then swallows `tee`, dropping `b.ts`.
+ *   - a LEADING subshell paren — `(tee inner.ts)` keeps the raw token `(tee`
+ *     (`.replace(/^.*\//,'')` leaves it untouched, no `/`), so the wrapper table
+ *     never matches: verb is the literal `(tee`, again mode-less. The classified
+ *     stream peels the paren AFTER, so the raw verb index and the peeled word
+ *     stream diverge.
+ *
+ * The projection makes both namespaces agree: peel leading/trailing parens off
+ * each unquoted token (matching {@link peelSubshellParens}' WORD output) and drop
+ * every write-redirect operator together with its target word — exactly the
+ * tokens the interpretation loop keeps OUT of `wordsSeen` (redirect operators are
+ * not `word`s; their targets are consumed by the `pendingRedirect` branch before
+ * the counter). The resulting segment's verb INDEX is then 1:1 with `wordsSeen`,
+ * so `index + 1` skips the wrapper chain + verb and no more.
+ *
+ * A5's 10 transparent-wrapper forms carry neither a leading redirect nor a paren,
+ * so this is a NO-OP for them: `resolveSegmentVerb`'s verb/index/wrapperArgs (incl.
+ * the #992 `writesFile` operand marks) are byte-identical to the raw-segment call.
+ *
+ * @param {Array<{ text: string, quoted: boolean }>} segment
+ * @returns {Array<{ text: string, quoted: boolean }>}
+ */
+function verbResolutionSegment(segment) {
+  const out = [];
+  let pendingRedirectTarget = false;
+  for (const tok of segment) {
+    if (!tok.quoted) {
+      // A write redirect consumes the NEXT token as its target — neither the
+      // operator nor its target reaches `wordsSeen`, so both must be absent here
+      // to keep the verb index aligned.
+      if (WRITE_REDIRECT_OP_RE.test(tok.text)) {
+        pendingRedirectTarget = true;
         continue;
       }
-      if (ch === '"') {
-        quoted = true;
-        i++;
-        while (i < n && command[i] !== '"') { if (command[i] === ' ') hadSpace = true; value += command[i]; i++; }
-        i++; // closing quote (or EOF)
+      // heredoc / input-redirect operators carry no immediate target token that
+      // reaches `wordsSeen` (the here-doc delimiter emits nothing; an input target
+      // DOES reach the counter and so is kept) — drop only the operator itself.
+      if (HEREDOC_OP_RE.test(tok.text) || INPUT_REDIRECT_OP_RE.test(tok.text)) {
+        pendingRedirectTarget = false;
         continue;
       }
-      if (isWs(ch)) break;
-      // unquoted operator chars end the word
-      if (ch === '>' || ch === '<' || ch === '|' || ch === ';' || ch === '&' || ch === '(' || ch === ')') break;
-      value += ch;
-      i++;
+      // Within a segment the only separator that can appear is an fd-dup `&`
+      // (e.g. `2>&1`), which classifyShellTokens also treats as a `sep` that
+      // resets the pending redirect — mirror that so the target after it stays.
+      if (SHELL_SEPARATOR_OPS.has(tok.text)) {
+        pendingRedirectTarget = false;
+        continue;
+      }
+    }
+    if (pendingRedirectTarget) {
+      pendingRedirectTarget = false;
+      continue; // this token is the dropped write-redirect target
     }
-    tokens.push({ type: 'word', value, hadSpace, quoted });
+    if (tok.quoted) {
+      out.push(tok);
+      continue;
+    }
+    let text = tok.text;
+    while (text.startsWith('(')) text = text.slice(1);
+    while (text.endsWith(')')) text = text.slice(0, -1);
+    if (text.length === 0) continue; // pure paren = a separator, not a word
+    out.push({ text, quoted: false });
   }
-
-  return tokens;
+  return out;
 }
 
 /**