@lannguyensi/harness 0.43.0 → 0.45.0

package/dist/runtime/command-normalize.d.ts

@@ -13,10 +13,13 @@ export interface NormalizedCommand {
      * that disagree, or the only named value is `~`-prefixed (see the
      * module header's target-directory-extraction rules).
      *
-     * NOT WIRED TO ANY GATE (see the module header's STATUS paragraph):
-     * extracted and fully tested, pending a redesign that attributes a
-     * target per-policy instead of per-event — follow-up task
-     * `98ad072f`.
+     * STILL NOT WIRED TO ANY GATE (see the module header's STATUS
+     * paragraph): extracted and fully tested, but task `98ad072f`'s
+     * per-policy redesign (T-003) attributes a target from the per-segment
+     * `segmentViewOf` view below instead of this whole-command aggregate —
+     * a single per-event `targetDir` cannot express "this invocation
+     * targets repo B, but the gated verb after it runs in the caller's
+     * cwd," which is exactly the property the redesign needs.
      */
     targetDir: string | null;
     /**
@@ -42,6 +45,177 @@ export interface NormalizedCommand {
      */
     truncated: boolean;
 }
+/**
+ * One boundary-delimited segment's canonicalised text plus its own and
+ * "effective" target directory (task `98ad072f`, T-002 of run
+ * `2026-08-02-per-repo-gate-scoping-redesign`) — attributes a target to
+ * the SPECIFIC segment satisfying a policy's own `bash_match` trigger,
+ * instead of the single, whole-command `targetDir` / `targetBase` on
+ * `NormalizedCommand` above. Produced by `segmentViewOf`. WIRED as of
+ * T-003, this run: `src/runtime/intercept.ts`'s `attributeTriggerSegments`
+ * / `resolveAttributedContexts` are the consumer (see the module header's
+ * STATUS/UPDATE note for the exact contract).
+ */
+export interface CommandSegment {
+    /**
+     * This segment's canonicalised text — the same rewrite
+     * `NormalizedCommand.normalized` applies to the corresponding span,
+     * boundary tokens EXCLUDED (they sit between segments, never inside
+     * one). Every shipped `bash_match` pattern's boundary alternation
+     * includes a `^` branch, so testing such a pattern against THIS string
+     * alone (no leading boundary character) is well-defined — see
+     * `01-plan.md`'s Proposed Approach item 2 for how a future consumer
+     * uses this.
+     */
+    text: string;
+    /**
+     * D-021 (UNIVERSAL-ADDITIVE, run 2026-08-02-per-repo-gate-scoping-
+     * redesign): the only remaining consumer of this field is
+     * `computeSegmentTarget`'s own internal `effectiveTarget` derivation
+     * (below) — `src/runtime/intercept.ts`'s `resolveAttributedContexts`
+     * (the gate) reads `effectiveTarget` only and no longer consults
+     * `ownTarget` at all. Kept as a public, separately-populated field
+     * (part of the T-002 API) rather than folded away, since a future
+     * consumer distinguishing "this segment's OWN explicit target" from
+     * "the directory it composes to once an incoming `cd` basis is
+     * accounted for" is exactly what the two-field split exists for.
+     *
+     * This segment's OWN explicit target, named by ITS OWN invocation
+     * only — a git invocation's REPO-RELOCATING global option ONLY: `-C` /
+     * `--git-dir` (or the SAME invocation's wrapping `env -C`, git-own-
+     * target-prioritised the same way `NormalizedCommand.targetDir` already
+     * is) — or, for a recognised bare `cd <path>` segment, the parsed path.
+     * Deliberately EXCLUDES `--work-tree` (D-017, fix round 2, run
+     * `2026-08-02-per-repo-gate-scoping-redesign`): `--work-tree` sets a
+     * git invocation's working tree but does NOT relocate its `--git-dir`
+     * search, so `git --work-tree=<B> push`/`log`/`status` still operate on
+     * whatever repo the invocation's ACTUAL directory names, never `<B>`
+     * alone — folding it into this field as though it were repo-identity-
+     * bearing (the pre-fix behaviour) let `resolveAttributedContexts`
+     * (`src/runtime/intercept.ts`, D-011) REPLACE the cwd demand with `<B>`'s
+     * on the strength of a flag that never moved the invocation there,
+     * measured as a live cross-repo fail-open. `null` when this segment
+     * names no repo-relocating target of its own (not a git invocation, not
+     * a `cd` segment, a bare git invocation, or a git invocation whose ONLY
+     * target-bearing flag is `--work-tree`) OR the named value is one of
+     * this view's unattributable forms: `~`-prefixed, carrying a stray quote
+     * character (the tokeniser is not quote-aware — a quoted value is
+     * captured WITH its quote character(s) still attached, not a real
+     * path), containing a command-substitution marker (`$(` or a backtick),
+     * or — for `cd` specifically — a bare `cd` with no argument or a `cd`
+     * with a flag (`cd -P /x`, three tokens instead of two). ALSO `null`
+     * when the SAME invocation names a git target via BOTH a relative own
+     * `-C` / `--git-dir` AND a wrapping `env -C` / `--chdir` base (`env -C
+     * /tmp/base git -C sub status`) — a mixed, internally ambiguous
+     * composition, unattributable for the same reason a relative own target
+     * after a preceding `cd` is (see `effectiveTarget` below); this is the
+     * ONE case where `ownTarget` itself, not just `effectiveTarget`, is
+     * nulled by a composition rule rather than by the raw value being
+     * unrecognisable on its own. A relative value (including `-C .`) and an
+     * absolute value are both otherwise preserved here verbatim, unresolved
+     * against any cwd — that resolution is a future consumer's job, not
+     * this module's. `git --git-dir=<A>/.git --work-tree=<B> ...`: this
+     * field is `<A>` (the `.git` parent) — `--git-dir` wins regardless of
+     * which flag appears first in the invocation, because `--work-tree`
+     * never contributes to this field at all, not because of any ordering
+     * rule between the two.
+     *
+     * ALSO `null` (D-018, fix round 3, pass-3 CRITICAL) when the invocation
+     * carries MORE THAN ONE recognised, resolved repo-relocating option:
+     * two-or-more `-C`, `-C` combined with `--git-dir`, `--git-dir` twice,
+     * or a same-invocation `env -C`/`--chdir` wrap whose target diverges
+     * from git's own ABSOLUTE `-C`/`--git-dir` target. Real git composes
+     * every one of these cumulatively (a later absolute value wins); this
+     * module does not encode that composition (same "not this module's
+     * job" reasoning as the relative-mix case above) and instead falls back
+     * to unattributable rather than trust the first flag it saw — `git -C
+     * <forge> -C <realA> push` actually runs in `<realA>`, but a first-
+     * flag-wins reading named `<forge>`, letting an agent redirect a gate's
+     * demanded evidence away from the repo the verb truly targets (measured
+     * against real git 2.34.1). An EXACT repeat of the same already-
+     * recorded value (`-C X -C X`, `env -C X git -C X`) is not new
+     * information and does not trigger this — see `peelGitGlobalOptions`'s
+     * `noteRelocatingOption` for the precise counting rule.
+     *
+     * D-021 (UNIVERSAL-ADDITIVE, operator decision, run 2026-08-02-per-
+     * repo-gate-scoping-redesign): the D-017/D-018 exclusions above (only a
+     * SINGLE recognised repo-relocating flag sets this field; `--work-tree`
+     * never does) are PRECISION, not the safety mechanism, since
+     * `src/runtime/intercept.ts`'s `resolveAttributedContexts` no longer
+     * REPLACES the cwd demand with this field's value — it ADDS to it, and
+     * the cwd demand is never dropped regardless of what this field
+     * resolves to. What these exclusions still prevent is a SPURIOUS extra
+     * demand (over-attributing a target the invocation does not actually,
+     * unambiguously name), not a dropped one — see that function's own doc
+     * comment for the full D-021 rationale.
+     */
+    ownTarget: string | null;
+    /**
+     * The directory this segment's own invocation actually runs in, once
+     * composed with the LAST PRECEDING recognised `cd <path>` segment in the
+     * same command (not necessarily the immediately preceding segment — any
+     * non-`cd` segment in between leaves the running cd-basis unchanged, the
+     * same way a non-`cd` shell command never itself changes the directory).
+     * Composition rules (`01-plan.md`, Proposed Approach item 1, verbatim):
+     *   - `ownTarget === null` → inherits the incoming cd-basis as-is
+     *     (including `null` when nothing preceding named one either).
+     *   - `ownTarget` absolute → itself, unconditionally — an absolute
+     *     value is never "relative to" anything a preceding `cd` named.
+     *   - `ownTarget` relative AND a preceding `cd` basis is known
+     *     (non-`null`) → `null`. This is the K1 divergence case
+     *     (`docs/okf/quote-model-divergence.md`): `cd T && git -C sub
+     *     status` does NOT become `T/sub` here — that would need real
+     *     filesystem-shaped path joining this module deliberately does not
+     *     perform — so it is UNATTRIBUTABLE rather than guessed at.
+     *   - `ownTarget` relative AND no preceding `cd` basis is known → the
+     *     raw relative value itself (deferred to a future consumer to
+     *     resolve against the real cwd).
+     * A same-invocation mixed `env -C <base>` + relative own `-C`/
+     * `--git-dir` composition (see `ownTarget` above — `--work-tree` is
+     * EXCLUDED from this mix entirely, D-017: it never sets `ownTarget`, so
+     * it can never trigger this ambiguity either) is `null` here TOO —
+     * checked BEFORE the cd-basis rules above and
+     * independently of them: `env -C /tmp/base git -C sub status` never
+     * becomes `/tmp/base/sub` (real path joining, deliberately not this
+     * module's job — same reasoning as the cd-basis K1 case) NOR does it
+     * fall through to the "relative, no cd basis, stays raw" branch above
+     * (that would hand a future consumer resolving relatives against ITS
+     * OWN cwd a CONFIDENTLY WRONG repository whenever the caller's cwd
+     * differs from `/tmp/base` — the "relative and `~` target dirs resolve
+     * to a confidently wrong repo" class named in the 07-27 review). A bare
+     * `env -C <base> git status` (no relative own target) is UNAFFECTED —
+     * `ownTarget` is `<base>` as usual, composed the ordinary way below.
+     * A recognised `cd <path>` segment whose OWN value is one of the
+     * unattributable forms above (e.g. `cd ~`) still RESETS the running
+     * cd-basis to `null` for every LATER segment — a later segment must not
+     * silently keep inheriting whatever basis existed BEFORE that `cd`,
+     * since the shell genuinely changed directory to somewhere this module
+     * cannot name.
+     *
+     * FULL reset-trigger list (D-014, fix round, run 2026-08-02-per-repo-
+     * gate-scoping-redesign — corrects this comment, which previously named
+     * only the unattributable-`cd`-value case above): the running basis
+     * resets to `null` — rather than the pre-fix behaviour of silently
+     * carrying an earlier basis forward unchanged — for ALL of: a bare `cd`
+     * with no argument, `cd -`, any other flagged `cd` (`cd -P /tmp/x`),
+     * `pushd`, `popd` (see `classifyCdSegment`), and the unattributable-
+     * `cd`-value case documented above. TWO of the reset triggers are NOT
+     * decided by this per-segment composition at all — they depend on the
+     * BOUNDARY a segment sits behind, which only the caller
+     * (`segmentAndCanonicalize`'s own walk) can see: the basis never
+     * crosses a bare `|` (each side of a pipe is bash's own subshell), and
+     * it resets after any segment whose text contains a `)` (a subshell
+     * close — `BOUNDARY_RE` has no `)` boundary of its own, so this is a
+     * substring check on the segment that happens to end there, not paren-
+     * depth tracking). See `segmentAndCanonicalize`'s own comment at its
+     * `computeSegmentTarget` call site for those two. NOT covered by any of
+     * this (same ceiling as before this fix round, unchanged): a `cd`
+     * inside a NESTED subshell that never closes within the command
+     * string's visible boundaries, and any construct outside this module's
+     * documented NOT-SUPPORTED list in the module header.
+     */
+    effectiveTarget: string | null;
+}
 /**
  * The `git` token itself, matched by BASENAME so a path-qualified
  * invocation (`/usr/bin/git`, `./git`) is recognised too (F4 fix).
@@ -81,6 +255,60 @@ export declare const NON_GIT_HEAD_TOKENS: ReadonlySet<string>;
  * hand-copying it into a diagnostic message.
  */
 export declare const MAX_NORMALIZE_LENGTH = 100000;
+/**
+ * Second boundary alphabet (task aabbad63): identical to `BOUNDARY_RE`
+ * plus a bare `&` — bash's OWN "start a new command here" token, which
+ * every shipped `bash_match` trigger regex has treated as one of its own
+ * anchor characters since task `d834a065`, but which `BOUNDARY_RE` above
+ * has never recognised as a NORMALISATION-time boundary (see its comment
+ * for the reverted, measured-140/140-regression attempt to add it there
+ * directly).
+ *
+ * ALTERNATION ORDER IS LOAD-BEARING: `&&` MUST be listed to the LEFT of
+ * the bare `&` alternative. JS regex alternation is leftmost-FIRST, not
+ * leftmost-longest — with `&` tried before `&&`, every `&&` in a command
+ * would tokenise as TWO consecutive one-character `&` boundary MATCHES
+ * instead of a single two-character `&&` boundary match.
+ *
+ * MEASURED, NOT ASSUMED (do not "simplify" the pin below to an
+ * end-to-end `.normalized` string assertion): for THIS module's segment-
+ * and-rejoin architecture specifically, that reordering is, perhaps
+ * counter-intuitively, INVISIBLE in `normalizeCommandAmpAware`'s own
+ * output string. Two adjacent single-`&` matches sandwich a genuinely
+ * zero-length segment between them (the two `&` characters of a real
+ * `&&` are, by definition, adjacent), `canonicalizeSegment("")` is a
+ * verbatim no-op, and `parts.join("")` reassembles the exact same bytes
+ * either way — verified directly (not merely reasoned about) by
+ * temporarily swapping this alternation's order, rebuilding, and
+ * diffing `normalizeCommandAmpAware(...).normalized` across several
+ * `&&`-bearing commands (including this comment's own `git -C
+ * /tmp/repoB status && git -C /tmp/repoB log` example): byte-identical
+ * output both ways. So a test asserting on the OUTPUT STRING alone
+ * cannot distinguish the two orderings for this architecture — the pin
+ * in `tests/runtime/command-normalize.test.ts` therefore execs this
+ * regex object DIRECTLY against a `&&`-bearing string and asserts the
+ * match text is `"&&"`, not `"&"`, which DOES fail under a swap. The
+ * order is still specified exactly as documented above (leftmost-first
+ * is real JS semantics, and the internal `segmentAndCanonicalize`
+ * bookkeeping this alphabet ALSO drives — `hasAmbiguousNonGitSegment`,
+ * discarded by `normalizeCommandAmpAware` but not by a hypothetical
+ * future consumer of `segmentAndCanonicalize` under this alphabet —
+ * would still see a spurious extra "non-git segment" under the wrong
+ * order), it just cannot be pinned through this module's ONE exposed
+ * string alone.
+ *
+ * Used ONLY by `normalizeCommandAmpAware` below, which is consulted ONLY
+ * as `policyMatchesEvent`'s third, additional matching arm — see that
+ * function's own comment for why its result never carries a `targetDir`/
+ * `targetBase`, and `src/runtime/intercept.ts` for the memoised-thunk
+ * threading that keeps this off the common (raw-or-normalised-already-
+ * matched) path. Exported (mirrors `GIT_TOKEN_RE` / `NON_GIT_HEAD_TOKENS`
+ * / `MAX_NORMALIZE_LENGTH` above) solely so the ordering pin test can
+ * exec it directly instead of re-declaring an equivalent regex literal
+ * that would test JS semantics in general, not THIS source's actual
+ * alternation.
+ */
+export declare const AMP_BOUNDARY_RE: RegExp;
 /**
  * Given a Bash command string, return its normalised form and the target
  * directory (and base, if relative) of its git invocation. Never throws:
@@ -90,3 +318,200 @@ export declare const MAX_NORMALIZE_LENGTH = 100000;
  * to the input unchanged.
  */
 export declare function normalizeCommand(command: string): NormalizedCommand;
+/**
+ * Given a Bash command string, return its per-segment view (task
+ * `98ad072f` groundwork, T-002) — see `CommandSegment`'s own doc comment
+ * for the field-level composition rules. `null` when the input exceeded
+ * `MAX_NORMALIZE_LENGTH` (mirrors `NormalizedCommand.truncated`, but as
+ * the ABSENCE of a view rather than a boolean flag alongside one, since
+ * there is no meaningful per-segment view to return for an input whose
+ * normalisation itself was skipped). `[]` for an empty or non-string
+ * command, and as the never-throws fallback (mirrors `normalizeCommand`'s
+ * own defensive backstop — see its doc comment above).
+ *
+ * THIS function's OWN call into `segmentAndCanonicalize` (`collectSegments:
+ * true`) is one walk, O(length) — the "no additional pass" claim is scoped
+ * to that ONE call, not to a caller's total work. CORRECTED (D-015, fix
+ * round, run 2026-08-02-per-repo-gate-scoping-redesign) — the prior wording
+ * here read "no additional pass over the command string" without that
+ * scoping, which a reader could take as "calling this costs nothing beyond
+ * `normalizeCommand`'s own walk." Measured false: `normalizeCommand(cmd)`
+ * and `segmentViewOf(cmd)` are two SEPARATE top-level calls, each running
+ * its own full `segmentAndCanonicalize` pass over the SAME string — a
+ * caller needing both (as `src/cli/policy/intercept.ts` does, for
+ * `normalized`/`truncated` and the segment view respectively) pays TWO
+ * walks, not one; measured +206% at the `MAX_NORMALIZE_LENGTH` bound
+ * (2.73 → 8.36 ms), harmless against the 1000 ms hook budget but not free.
+ * As of the same fix round, the one production caller only pays this
+ * second walk lazily, when some matching policy actually needs it (see
+ * `InterceptOptions.commandSegmentsThunk` in `src/runtime/intercept.ts`) —
+ * but that laziness lives in the CALLER, not in this function, which still
+ * does exactly one walk every time it runs. The ampersand-aware second pass
+ * (`normalizeCommandAmpAware`) NEVER collects a segment view (always calls
+ * `segmentAndCanonicalize` with `collectSegments: false`) — see that
+ * function's own comment for why a directory extracted under the
+ * ampersand-aware alphabet would be unreliable in the first place; the
+ * same reasoning applies here, so this module offers no amp-aware variant
+ * of this function at all.
+ */
+export declare function segmentViewOf(command: string): CommandSegment[] | null;
+/**
+ * Return type of `normalizeCommandAmpAware` — deliberately NOT
+ * `NormalizedCommand` (task aabbad63, hard constraint). It carries only
+ * `normalized`/`truncated`; there is no `targetDir`/`targetBase` field at
+ * all, so a future caller cannot wire one up to a gate by mistake — see
+ * `normalizeCommandAmpAware`'s own comment for why a directory extracted
+ * under the ampersand-aware alphabet would be unreliable in the first
+ * place, not merely "unwired today".
+ */
+export interface AmpAwareNormalizedCommand {
+    /** Same contract as `NormalizedCommand.normalized`, under `AMP_BOUNDARY_RE`. */
+    normalized: string;
+    /** Same contract as `NormalizedCommand.truncated`. */
+    truncated: boolean;
+}
+/**
+ * Ampersand-aware SECOND normalisation pass (task aabbad63). Segments the
+ * command under `AMP_BOUNDARY_RE` (`BOUNDARY_RE` plus a bare `&`) instead
+ * of `BOUNDARY_RE`, then canonicalises exactly like the primary pass
+ * (same `canonicalizeSegment`, same wrapper-peeling rules, same
+ * `MAX_NORMALIZE_LENGTH` bound). Closes the gap `BOUNDARY_RE`'s own
+ * comment names: `A=x&env -C /tmp git status` and `echo hi & nice git
+ * status` were ungated because a wrapper can only be peeled after a
+ * recognised boundary, and a bare `&` was not one.
+ *
+ * Return type deliberately has NO `targetDir`/`targetBase` — not merely
+ * "always null under this alphabet", genuinely ABSENT from the type, so
+ * no consumer can read one by mistake. Reason: a bare `&` is ALSO how
+ * bash spells a background job (`git -C /x push &`) and how a redirect
+ * merges streams (`git -C /x log 2>&1`, `... &> out`). Under THIS
+ * alphabet each of those splits into a spurious extra "segment", which
+ * `segmentAndCanonicalize`'s own non-git-segment ambiguity rule (a
+ * segment that starts a new command and is not itself a git invocation
+ * forces `targetDir` to `null` — see its G1 comment) would turn into a
+ * wrong-shaped loss for a case the PRIMARY pass still resolves correctly
+ * today. Pinned in `tests/runtime/command-normalize.test.ts`'s "aabbad63
+ * groundwork" describe block, which exercises ONLY `normalizeCommand`
+ * (the primary pass), never this function — `targetDir`/`targetBase`
+ * stay the primary pass's property alone.
+ *
+ * Only consulted by `policyMatchesEvent`'s third arm
+ * (`src/runtime/intercept.ts`), and only when a policy's `bash_match`
+ * regex has already missed BOTH the raw command and the primary
+ * normalised form — see that module and `src/cli/policy/intercept.ts`
+ * for the memoised-thunk threading that keeps this computation off the
+ * common (already-matched) path.
+ */
+export declare function normalizeCommandAmpAware(command: string): AmpAwareNormalizedCommand;
+/**
+ * Return type of `normalizeCommandQuoteAware` — same shape and same
+ * reasoning as `AmpAwareNormalizedCommand` above: no `targetDir`/
+ * `targetBase`, so no consumer can read one extracted under quote-aware
+ * segmentation by mistake. Unlike the amp-aware pass, THIS alphabet is
+ * exactly `BOUNDARY_RE`'s own (no new boundary characters, only new
+ * quote-tracking around the existing ones), so the reason for omitting
+ * these fields is different: `computeSegmentTarget` / `classifyCdSegment`
+ * / `canonicalizeSegment` all assume `tokenizeWithOffsets`'s whitespace
+ * tokenisation lines up with the segment boundaries `findNextBoundary`
+ * produces, which is still true for the boundary ALPHABET itself but is
+ * now also entangled with `consumeAssignment`'s OWN, separate quote
+ * tracking (per-token, inside one segment) once segments can be wider and
+ * carry an unbalanced quote at their edges in new ways this task's own
+ * corpus does not exhaustively characterise for `targetDir` purposes —
+ * left unexplored rather than guessed at, mirroring the amp-aware pass's
+ * own "not this task's job" scoping.
+ */
+export interface QuoteAwareNormalizedCommand {
+    /** Same contract as `NormalizedCommand.normalized`, under quote-aware segmentation. */
+    normalized: string;
+    /** Same contract as `NormalizedCommand.truncated`. */
+    truncated: boolean;
+}
+/**
+ * Quote-aware THIRD normalisation pass (task cf3dff51). Segments the
+ * command under `BOUNDARY_RE`'s own alphabet — same characters as the
+ * primary pass, no widening — but tracks single/double-quote state while
+ * scanning (`findNextBoundaryQuoteAware` below) so a boundary character
+ * sitting INSIDE a quoted assignment value is no longer treated as a real
+ * segment split. Closes the gap the module header's "DELIBERATELY NOT
+ * SUPPORTED" list and `BOUNDARY_RE`'s own comment both name: `VAR='a; b'
+ * git push` (task 13e55484's pinned residual) — `BOUNDARY_RE` used to cut
+ * the segment at the `;`, landing squarely between the two halves of one
+ * quoted value, so neither resulting piece carried a recognisable
+ * invocation and `consumeAssignment`'s own multi-token quote continuation
+ * (built for exactly this shape) never got the chance to run: it operates
+ * AFTER segmentation, on tokens WITHIN one segment, and the quoted value
+ * was never in one segment to begin with. Once quote-aware segmentation
+ * keeps the value whole, `consumeAssignment` needs no changes at all — it
+ * already reconstructs a multi-token quoted value correctly; this pass
+ * only fixes what gets handed to it as ONE segment in the first place.
+ *
+ * BUILT AS A NEW, INDEPENDENT PASS RATHER THAN AN IN-PLACE EDIT OF
+ * `BOUNDARY_RE` / `segmentAndCanonicalize` — this is the module header's
+ * HALT CRITERION, restated here at the point it governs: quote-aware
+ * segmentation can MERGE a segment the primary pass currently splits, and
+ * that merge cuts in BOTH directions — it can turn a previously-missed
+ * bypass into a match (the fix), but it can just as easily turn a
+ * previously-accepted, ALREADY-WIRED over-block into a miss (a
+ * regression). Measured, not hypothetical: `tests/runtime/command-
+ * normalize.test.ts`'s "accepted over-block: a quoted assignment inside
+ * TEXT after a boundary char now matches" pin — `echo "a; VAR='x y' git
+ * push"` — matches via `normalizeCommand` TODAY only because `BOUNDARY_RE`
+ * splits it at the `;`, landing `VAR='x y' git push` at a segment start
+ * where the assignment continuation turns it into a match. An in-place
+ * quote-aware edit of THAT pass would un-split it back into the outer
+ * `echo "..."` segment — not itself a recognised invocation — and flip
+ * that pin to a lost match, in violation of the raw-OR-normalised-OR-amp-
+ * aware-OR-(this) never-lose-a-match discipline every other pass in this
+ * module already honours. Building this as a SEPARATE pass instead means
+ * `normalizeCommand`'s own segmentation, and every test resting on it —
+ * including that exact one — is untouched by this task; see this file's
+ * own test suite for the differential proof (every case the first three
+ * arms already matched still matches, by construction, because none of
+ * those three arms' code changed at all).
+ *
+ * WIRED to `policyMatchesEvent` (`src/runtime/intercept.ts`) as its
+ * FOURTH arm — same shape as `normalizeCommandAmpAware`'s own third-arm
+ * wiring (task aabbad63): consulted only after the raw command,
+ * `normalizedCommand`, and the amp-aware pass have all missed, via a
+ * memoised thunk (`InterceptOptions.quoteNormalizedCommandThunk`,
+ * `src/cli/policy/intercept.ts`'s `quoteNormalizedCommandThunk`) so the
+ * segmentation cost is paid at most once per event, on the common
+ * (already-matched) path it costs nothing at all. Wiring landed in a
+ * SECOND round of this task, after the orchestrator extended the first
+ * round's file scope specifically for this one wiring point — the first
+ * round shipped this function fully built and tested but genuinely
+ * unwired (an inert security fix, called out explicitly as the wrong
+ * shipped state in that round's own report) — `src/cli/dry-run.ts`'s own,
+ * independently-copied matcher was deliberately NOT extended in the same
+ * round (out of the extended scope too) and stayed a named residual until
+ * task f561e44c closed it by adding the same fourth OR-arm there too — see
+ * that file's own comment.
+ *
+ * THIS PASS'S OWN OVER-BLOCK SURFACE is measured and named in the test
+ * file rather than assumed — and the measurement CORRECTS an earlier,
+ * pre-measurement guess that used to sit in this comment: it does NOT
+ * reproduce the `echo "a; VAR='x y' git push"` accepted over-block named
+ * above. Quote-aware merging keeps that whole `echo "..."` segment
+ * together, starting with the unrecognised head token `echo`, so this
+ * function's output for it is byte-identical to the raw input
+ * (`normalizeCommand`'s OWN, separate, unchanged-by-this-task match for
+ * that same string is unaffected either way). Measured against a broader
+ * adversarial probe, both at this function's own level and again at
+ * `policyMatchesEvent`'s wired level (a bash-shim-verified corpus of
+ * chained/prefixed/subshell-wrapped genuine invocations plus candidate
+ * over-block shapes — entirely quoted `echo`/`printf` arguments that only
+ * PRINT the spelling): every additional match this pass adds beyond raw /
+ * `normalizeCommand` / `normalizeCommandAmpAware` is a TRUE positive (a
+ * real invocation bash would actually execute); no NEW over-block class
+ * distinct from `consumeAssignment`'s own, already-reviewed precision
+ * limits was found. This function shares `canonicalizeSegment` /
+ * `consumeAssignment` completely unchanged with the other passes — only
+ * the segmentation boundary decision differs — which is also the
+ * structural reason a longer (merged) segment can only REVEAL a match
+ * those functions would already accept from a shorter view, never
+ * fabricate a new kind of one; see the module header's cf3dff51 UPDATE
+ * paragraph for the fuller statement of this reasoning and its
+ * "not a formal proof" caveat.
+ */
+export declare function normalizeCommandQuoteAware(command: string): QuoteAwareNormalizedCommand;