@lannguyensi/harness 0.43.0 → 0.45.0

package/dist/runtime/command-normalize.js

@@ -8,7 +8,14 @@
 // `bash_match` regex against the raw command first and, only on a raw
 // miss, against this normalised form too (raw-OR-normalised, never raw-
 // replaced-by-normalised), closing a class of silent trigger bypasses
-// (see below). `targetDir` / `targetBase` — the effective target
+// (see below) — and, only on a further miss of THIS form, against a
+// SECOND, independent, ampersand-aware normalisation pass (`AMP_BOUNDARY_RE`
+// / `normalizeCommandAmpAware` below, task aabbad63) that this header
+// otherwise never mentions; see that function's own comment for its scope
+// and why it carries no `targetDir`/`targetBase` of its own (fix round 1,
+// finding F5 — added so a reader of this header, the module's index,
+// learns a second pass exists at all instead of finding it only by
+// reading past this point). `targetDir` / `targetBase` — the effective target
 // directory of the command's own git invocation(s), when one can be
 // named unambiguously — are NOT WIRED TO ANY GATE. An earlier version of
 // this run used them to resolve the `${REPO}`/`${BRANCH}` policy
@@ -27,6 +34,38 @@
 // `98ad072f`. Nothing below describes gate wiring; it describes what
 // THIS MODULE computes, live or not.
 //
+// UPDATE (task `98ad072f`, run `2026-08-02-per-repo-gate-scoping-
+// redesign`, T-002): the per-segment foundation named above now EXISTS as
+// a real export — `segmentViewOf` / `CommandSegment`, defined below
+// `normalizeCommand` — instead of being only a design intention. It
+// exposes, per boundary-delimited segment, the canonicalised text, the
+// segment's OWN explicit target, and an EFFECTIVE target composed with the
+// last preceding `cd <path>` segment (see `CommandSegment`'s own doc
+// comment for the composition rules and its own not-covered list, which
+// is narrower in places than `targetDir`/`targetBase` above — e.g. no
+// `VAR=value cd <path>` tolerance). `normalizeCommand`'s own `targetDir`/
+// `targetBase` are UNCHANGED by this addition — byte-identical in every
+// pre-existing test.
+//
+// UPDATE (task `98ad072f`, T-003, this run): `segmentViewOf` /
+// `CommandSegment` — NOT `normalizeCommand`'s own `targetDir`/`targetBase`
+// above, which stay exactly as unwired as before this slice — IS now
+// wired to a gate: `src/runtime/intercept.ts`'s `attributeTriggerSegments`
+// re-tests a matched policy's own `bash_match` regex against each
+// segment's `text`, and, for a policy whose `requires:` uses
+// `${REPO}`/`${BRANCH}`/`at_head`, resolves those builtins (and
+// `currentHeadSha`) from the trigger-satisfying segment's
+// `effectiveTarget` instead of the event's cwd — lazily, memoised per
+// resolved path, never touching `resolverGit`/`riskContext`. Trust in
+// `effectiveTarget` is UNIFORM — no distinction between a segment's own
+// explicit target and one inherited from a preceding `cd` (orchestrator
+// decision D-010: an initial revision distinguished the two and was
+// rejected — bash itself draws no such distinction, a `cd <B> && <verb>`
+// chain genuinely runs `<verb>` inside B). See that module's own comments
+// (`attributeTriggerSegments`, `resolveAttributedContexts`) for the
+// consumption rules; this module's OWN extraction and ambiguity rules
+// below are unchanged by being consumed.
+//
 // MEASUREMENT RULE (task 47297478): before measuring THIS module's
 // extraction across builds with an ad-hoc corpus, read the per-arm-gate
 // design in scripts/measure-bash-prefix-parse.mjs — a corpus arm whose
@@ -35,7 +74,65 @@
 // Note the tool itself measures ONLY bash-prefix-parse.ts's `cdTarget`
 // extraction; this module's `normalized`/`targetDir`/`targetBase`
 // outputs have no instrument yet, so cross-build claims about them need
-// their own per-arm-gated measurement.
+// their own per-arm-gated measurement — that instrument now exists:
+// scripts/measure-command-normalize.mjs (groundwork for task aabbad63, the
+// BOUNDARY_RE bare-`&` fix below). It rebuilds a faithful superset of the
+// reverted fix's 140-form quoted-value regression corpus and gates arm A
+// on bash actually running the verb, per the same never-fold-into-a-zero
+// discipline.
+//
+// UPDATE (task cf3dff51): closes the quoted-shell-boundary residual named
+// in the "DELIBERATELY NOT SUPPORTED" list below (`VAR='a; b' git push` —
+// task 13e55484's pinned gap). A HALT criterion, written before any
+// implementation code, forced the closing mechanism into an ADDITIVE,
+// fully independent third normalisation pass (`normalizeCommandQuoteAware`
+// / `findNextBoundaryQuoteAware`, defined near `findNextBoundary` below)
+// rather than an in-place edit of `BOUNDARY_RE` / `segmentAndCanonicalize`
+// itself. First round of this task built and fully tested the new pass but
+// left it UNWIRED (the wiring — a `policyMatchesEvent` fourth disjunct in
+// `src/runtime/intercept.ts` — touched a file outside that round's
+// assigned scope). The orchestrator EXTENDED the scope for a second round
+// specifically to include that one wiring point (not a general re-open of
+// scope), so `normalizeCommandQuoteAware` IS now `policyMatchesEvent`'s
+// fourth arm, mirroring `normalizeCommandAmpAware`'s own wiring (task
+// aabbad63) exactly — see that function's own doc comment and
+// `src/runtime/intercept.ts`'s `policyMatchesEvent` for the wired shape.
+// UPDATE (task f561e44c): `src/cli/dry-run.ts`'s own, independently-copied
+// raw-OR-normalised-OR-amp-normalised matcher (the `harness dry-run` debug
+// verb, which predicts `policyMatchesEvent`'s verdict without running it)
+// was left out of the wiring above (named residual, not silently left
+// implicit) and, as a result, under-predicted the quote-aware family. This
+// follow-up task added the same fourth OR-arm to that matcher too, so
+// `harness dry-run` and `policy intercept` now agree on this family — see
+// that file's own comment for the fix and its parity-fixture test.
+//
+// THE HALT CRITERION (decided and written down before writing the first
+// line of this pass's implementation, mirroring 13e55484's own "ONE-
+// DIRECTIONAL GUARD" structure): quote-aware segmentation MUST be built as
+// a NEW, independent function — never as an in-place edit of the EXISTING,
+// already-wired primary pass (`BOUNDARY_RE` / `findNextBoundary` /
+// `segmentAndCanonicalize`'s behaviour for `normalizeCommand`). If closing
+// this residual is ever found to require editing that existing pass in
+// place instead of adding a new one, HALT and fall back to documentation-
+// only (pin the residual, as this header already does for its NOT-
+// SUPPORTED siblings) rather than risk a two-directional regression. This
+// is not a hypothetical: this task PROVED the trigger before writing any
+// code, by reading `tests/runtime/command-normalize.test.ts`'s pinned
+// "accepted over-block: a quoted assignment inside TEXT after a boundary
+// char now matches" case — `echo "a; VAR='x y' git push"` — which matches
+// TODAY only because `BOUNDARY_RE`'s quote-unawareness un-splits `VAR='x
+// y' git push` into its own segment. An in-place quote-aware edit of the
+// SAME pass would un-split it the other way (merge it back into the outer
+// `echo "..."` segment, which is not itself a recognised invocation) and
+// flip that already-accepted, already-WIRED pin from match to no-match —
+// a genuine lost match under this module's own no-lost-matches discipline
+// (see AMP_BOUNDARY_RE's own comment for why that discipline exists at
+// all), not merely a lost false positive. Building a separate, additive
+// pass instead means the existing primary pass — and every pin resting on
+// it, including that exact one — stays byte-for-byte untouched; see
+// `normalizeCommandQuoteAware`'s own comment for the differential
+// measurement that confirms this by construction rather than by
+// inspection alone.
 //
 // THE TRIGGER-MATCHING GAP THIS CLOSES: every `bash_match` policy trigger
 // (`src/cli/init/templates.ts`, `docs/examples/full-manifest.yaml`) is a
@@ -221,13 +318,33 @@
 //     agent writes and then executes.
 //   - `pushd`/`popd`, and a `cd` inside a nested subshell
 //     (`(cd X && ...)`) — mirrors `bash-prefix-parse.ts`'s own scope.
-//   - A shell-boundary character INSIDE a quoted assignment VALUE
-//     (`VAR='a; b' git push` — task 13e55484's pinned residual):
-//     `BOUNDARY_RE` splits segments BEFORE tokenisation and is quote-
-//     unaware, so the quoted value is cut at the `;` and neither
-//     resulting segment carries a recognisable invocation. Closing this
-//     means a quote-aware segmenter, a different (and riskier) change
-//     than the assignment-value continuation that task shipped.
+//   - CLOSED (was: a shell-boundary character INSIDE a quoted assignment
+//     VALUE — `VAR='a; b' git push`, task 13e55484's pinned residual, no
+//     longer belongs in a NOT-SUPPORTED list). Task cf3dff51: a quote-
+//     aware THIRD normalisation pass, `normalizeCommandQuoteAware`
+//     (defined near `findNextBoundary` below), built as a new, additive
+//     pass rather than an in-place edit of `BOUNDARY_RE` /
+//     `segmentAndCanonicalize` (see the module header's HALT CRITERION
+//     paragraph and that function's own comment for why), now wired as
+//     `policyMatchesEvent`'s FOURTH arm (`src/runtime/intercept.ts`,
+//     mirroring `normalizeCommandAmpAware`'s own wiring, task aabbad63).
+//     Closes `;`, `|`, `&&`, `(`, and a literal newline, each with an
+//     internal whitespace split inside the quoted value (the exact
+//     `VAR='a; b' git push` shape) — measured 12/12 at the real
+//     `runInterceptCli` hook entry point (isolated harness home,
+//     PATH-shim-verified bash execution, two gated verbs). Over-block
+//     surface: MEASURED, not assumed, against an adversarial probe —
+//     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 (the "master false positive" class already pinned
+//     elsewhere in the test file) was found. See `normalizeCommandQuoteAware`'s
+//     own doc comment for the full mechanism and reasoning. CLOSED (task
+//     f561e44c): `src/cli/dry-run.ts`'s independently-copied matcher was
+//     initially not extended to try this fourth form — named residual — but
+//     that follow-up task added the same fourth OR-arm there too, see that
+//     file's own comment.
 //   - A quoted assignment VALUE containing the literal word `git`/`gh`/
 //     `npm`/`harness` as its own token (`VAR='a git b' git push`): the
 //     continuation's one-directional guard abandons rather than risk
@@ -315,6 +432,28 @@
 // trips the gate, the same cost the dbc6d303 quoted/heredoc class
 // already carries.
 //
+// SAME CLASS, third member (task aabbad63, this run's own amp-aware
+// second pass): a WIDENING of the second member above, not a new class —
+// `AMP_BOUNDARY_RE` is quote-unaware in exactly the same way `BOUNDARY_RE`
+// is, so a bare `&` INSIDE a quoted string is now also a segment
+// boundary, and a wrapper spelling sitting behind it can be peeled and
+// canonicalised as though it were a real invocation. Measured on a
+// 160-form quoted-text corpus arbitrated by real bash (PATH-shimmed
+// verbs + a marker file the verb would touch if it actually ran): 144
+// spellings of `<text> & <wrapper> <gated verb>` INSIDE a quoted string
+// now match where the base (pre-aabbad63) build did not, and bash ran
+// the gated verb in 0 of them — a false alarm on a command that only
+// PRINTS the spelling, never a missed real gate. The wrapper-LESS
+// variant of the same shape (`echo 'a & git push'`) already false-
+// alarmed on the base build 16/16 via the RAW regex alone, because every
+// shipped `bash_match` trigger already anchors on a bare `&` (task
+// `d834a065`) — so this is a WIDENING of an already-accepted over-block
+// class to the wrapped spellings of it, not a new false-positive class
+// this task introduces. The opposite direction, measured on the general
+// (non-adversarial) corpus rather than this quoted-text one: of 276
+// matches this pass gains there, all 151 classifiable ones were TRUE
+// positives, 0 false alarms.
+//
 // `$(...)` command substitution is ACCIDENTALLY covered — not a
 // deliberate feature, and distinct from the backtick case above, which
 // is a genuine, deliberate gap. `BOUNDARY_RE` treats a bare `(` as a
@@ -407,26 +546,263 @@ export const MAX_NORMALIZE_LENGTH = 100_000;
  * starts with `&`), so there is no tie for the regex engine's leftmost-
  * match rule to break.
  *
- * DELIBERATELY MISSING: single `&`, even though bash starts a new
- * command after it and every shipped `bash_match` trigger now treats it
- * as a boundary (task `d834a065`). Adding it here was tried and
- * REVERTED after measurement: this regex is quote-unaware, `&` inside a
- * quoted assignment value is common, and the split lands mid-quote, so
- * the value continuation never engages and the wrapper is never peeled.
+ * DELIBERATELY MISSING, STILL: single `&`, even though bash starts a new
+ * command after it. Adding it HERE was tried and REVERTED after
+ * measurement: this regex is quote-unaware, `&` inside a quoted
+ * assignment value is common, and the split lands mid-quote, so the
+ * value continuation never engages and the wrapper is never peeled.
  * Measured against the pre-change build with a passing positive
  * control: 140 of 140 sampled `<wrapper> FOO='a&b' <gated verb>`
  * spellings LOST a gate they previously held, including the
- * `operator_only` kill-switch deny. The consequence of leaving it out
- * is that `A=x&env -C /tmp git status` stays ungated (the wrapper can
- * only be peeled after a recognised boundary); that gap is tracked
- * separately and needs a design that does not regress the quoted-value
- * case, not another character in this alternation.
+ * `operator_only` kill-switch deny. That evidence is why THIS alphabet
+ * stays byte-identical rather than growing a bare `&` alternative
+ * directly — see `scripts/measure-command-normalize.mjs`'s arm A for the
+ * regression corpus that keeps proving it stays byte-identical.
+ *
+ * TASK aabbad63 (this run): the bare-`&` family this alphabet cannot see
+ * (`A=x&env -C /tmp git status`, `echo hi & nice git status`) is now
+ * handled WITHOUT touching this regex at all — by a SECOND, independent
+ * boundary alphabet (`AMP_BOUNDARY_RE` below) driving a SECOND
+ * normalisation pass (`normalizeCommandAmpAware`) that
+ * `policyMatchesEvent` (`src/runtime/intercept.ts`) tries ONLY as a
+ * third, additional raw-OR-normalised-OR-amp-normalised disjunct — never
+ * a replacement for either of the first two arms. That construction is
+ * exactly what avoids re-triggering the 140/140 regression above: every
+ * command that matched via the raw test or via THIS (BOUNDARY_RE)
+ * normalised form keeps matching through those same two arms, byte-for-
+ * byte unchanged; the amp-aware arm can only ADD a match a spelling
+ * would otherwise have missed, so a quoted `FOO='a&b'` value that this
+ * alphabet already normalises correctly is never at risk of losing that
+ * gate to the new arm. See `AMP_BOUNDARY_RE`'s own comment for why it
+ * has to be a distinct regex object rather than a mutation of this one,
+ * and `normalizeCommandAmpAware`'s comment for why its return type
+ * carries no `targetDir`/`targetBase`.
  */
 const BOUNDARY_RE = /\n|&&|;|\||\(/g;
+/**
+ * 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 const AMP_BOUNDARY_RE = /\n|&&|&|;|\||\(/g;
 /** A target value starting with `~` — not expanded, treated as unparseable (F5). */
 function isTildeTarget(dir) {
     return dir.startsWith("~");
 }
+/**
+ * A target value `segmentViewOf`'s `CommandSegment.ownTarget` (task
+ * `98ad072f` groundwork) treats as unattributable even where the
+ * pre-existing per-segment machinery below (`canonicalizeSegment` /
+ * `peelGitGlobalOptions` / `peelEnv`) still captures SOME string for the
+ * OLD aggregate's `targetDir` — that extraction is UNCHANGED by this check
+ * (see the module header's STATUS/UPDATE note): the tokeniser is not
+ * quote-aware, so a quoted `-C` / `--work-tree` / `--git-dir` / `env -C`
+ * value is captured WITH its quote character(s) still attached
+ * (`git -C "/tmp/repoB" status` captures `"/tmp/repoB"`, quotes included —
+ * not a real path, and not `null` either under the pre-existing
+ * extraction) rather than being rejected outright. The same is true of a
+ * value containing a command-substitution marker (`$(` or a backtick) —
+ * this module never resolves substitutions, so a value carrying one names
+ * nothing this module can vouch for as a literal path. A
+ * whitespace-containing path needs no separate check here: the
+ * whitespace-splitting tokeniser never captures a value containing
+ * whitespace as ONE token in the first place — it becomes a different,
+ * unrecognised token sequence instead (see the module header's own
+ * "quoted directory arguments containing whitespace" note), which for
+ * `segmentViewOf` purposes simply fails to produce a recognised own target
+ * at all (see `parseCdSegmentTarget` below for the `cd` case).
+ *
+ * A value ENDING in a bare `$` is ALSO rejected, even though it does not
+ * literally contain the two-character `$(` marker: `BOUNDARY_RE` (this
+ * function is only ever reached through the primary, non-amp-aware pass —
+ * `segmentViewOf` never runs under `AMP_BOUNDARY_RE`) treats a bare `(` as
+ * a shell boundary UNCONDITIONALLY (needed for the leading-command case,
+ * module header), so `$(` can never survive as a substring WITHIN one
+ * token or segment in the first place — the `(` always splits it into its
+ * own boundary match first. A `cd` target ending in `$` is the tell-tale
+ * leftover of exactly that split (`cd $(pwd)/T && ...` tokenises this
+ * function's caller's OWN segment as literal `cd $`, a syntactically
+ * valid-LOOKING two-token `cd <path>` with `<path>` being the single
+ * character `$` — measured live, not hypothetical). Rejecting it here
+ * closes that gap without needing `parseCdSegmentTarget` (which has no
+ * visibility into what boundary token follows its own segment) to
+ * special-case it itself. The `-C`/`--work-tree`/`--git-dir`/`env -C` side
+ * of this module never has this specific gap: a value-capturing git
+ * global option additionally requires a SUBCOMMAND token after its value
+ * (`peelGitGlobalOptions`'s caller checks `gitOpts.idx >= tokens.length`),
+ * so `git -C $(pwd) status` already comes back `isGit: false` (no
+ * subcommand token survives the split) before this function is ever
+ * consulted for it — this extra check is `cd`-specific, `cd <path>` having
+ * no analogous "and then a subcommand" requirement.
+ */
+function isUnattributableTargetValue(value) {
+    return (value.includes("'") ||
+        value.includes('"') ||
+        value.includes("$(") ||
+        value.includes("`") ||
+        value.endsWith("$"));
+}
+function classifyCdSegment(segmentText) {
+    const tokens = tokenizeWithOffsets(segmentText);
+    if (tokens.length === 0)
+        return { kind: "none" };
+    const head = tokens[0].text;
+    if (head === "pushd" || head === "popd")
+        return { kind: "reset" };
+    if (head !== "cd")
+        return { kind: "none" };
+    if (tokens.length === 1)
+        return { kind: "reset" }; // bare `cd`, no argument
+    if (tokens.length > 2)
+        return { kind: "reset" }; // flagged cd: `cd -P /tmp/x`
+    const arg = tokens[1].text;
+    if (arg.length === 0 || arg.startsWith("-"))
+        return { kind: "reset" }; // `cd -`, `cd -P` alone
+    return { kind: "cd", arg };
+}
+/**
+ * Compute one segment's `ownTarget` / `effectiveTarget` (task `98ad072f`
+ * groundwork, `segmentViewOf` / `CommandSegment`) and the cd-basis to
+ * carry into the NEXT segment, from: this segment's own canonicalisation
+ * result (already computed by the shared walk — `identityTargetDir` /
+ * `identityTargetBase` / `isGit`, unmodified here; NOT the OLD aggregate's
+ * `targetDir`/`targetBase`, which still includes `--work-tree` — D-017,
+ * fix round 2), whether THIS segment is itself a recognised `cd <path>`
+ * segment, and the cd-basis carried in from whatever preceded it.
+ * Implements `CommandSegment.effectiveTarget`'s doc comment verbatim; see
+ * that comment for the consumer-facing statement of these rules.
+ */
+function computeSegmentTarget(segmentText, canon, incomingCdBasis) {
+    // Same-invocation `env -C`/`--chdir` base + a RELATIVE own git
+    // REPO-RELOCATING target (`-C`/`--git-dir` — orchestrator follow-up
+    // after the initial T-002 round, still task `98ad072f` groundwork):
+    // `canon.identityTargetBase` is non-null EXACTLY in this mixed case —
+    // see `canonicalizeSegment`'s own `identityTargetBase` computation,
+    // reused here unmodified, never when there is no wrapping `env -C` on
+    // the SAME invocation. `env -C /tmp/base git -C sub status` must NOT
+    // hand a future consumer `ownTarget`/`effectiveTarget: "sub"` (raw,
+    // relative): a naive consumer resolving a relative value against ITS
+    // OWN cwd (this module's documented fallback for the "no known basis"
+    // branch below) would land on a CONFIDENTLY WRONG repository whenever
+    // the caller's cwd differs from `/tmp/base` — precisely the "relative
+    // and `~` target dirs resolve to a confidently wrong repo" class named
+    // in the 07-27 review. Composing correctly to `/tmp/base/sub` would ALSO
+    // be correct but is deliberately NOT this module's job (real
+    // filesystem-shaped path joining — the same reason the cd-basis
+    // composition rule below refuses to compose `cd T && git -C sub` into
+    // `T/sub`); noted here as a possible LATER precision gain, not built in
+    // this slice. A bare git invocation with an `env -C` base and no
+    // relative own REPO-RELOCATING target (`env -C /abs git status`) is
+    // UNAFFECTED — the ordinary `canon.identityTargetDir` extraction below
+    // already folds that in (`gitOpts.relocateTargetDir ?? envTargetDir`),
+    // and `canon.identityTargetBase` stays `null` for that shape (no
+    // relative own repo-relocating target to be relative TO). A `--work-
+    // tree`-only invocation (no `-C`/`--git-dir` on the same call) is NEVER
+    // "mixed" here even when wrapped by `env -C`: `relocateTargetDir` is
+    // `null` for it, so `identityTargetDir` falls through to `envTargetDir`
+    // (or stays `null`) and `identityTargetBase` stays `null` — D-017, this
+    // is the fix. A `cd`-shaped segment never reaches this branch: it never
+    // matches `GIT_TOKEN_RE`, so `canon.isGit` is always `false` for one.
+    if (canon.isGit && canon.identityTargetBase !== null) {
+        return { ownTarget: null, effectiveTarget: null, outgoingCdBasis: incomingCdBasis };
+    }
+    const cdClass = classifyCdSegment(segmentText);
+    // D-014 (fix round, run 2026-08-02-per-repo-gate-scoping-redesign): a
+    // segment that GENUINELY changes directory to somewhere this module
+    // cannot name (bare `cd`, `cd -`, a flagged `cd`, `pushd`, `popd`)
+    // RESETS the running basis to `null` for every later segment, rather
+    // than the pre-fix behaviour of leaving it unchanged (silently
+    // INHERITING whatever preceded it, as though the shell had not moved at
+    // all). This segment names nothing itself either. A PRECISION fix, not
+    // the security fix: `src/runtime/intercept.ts`'s D-011 additive
+    // attribution rule means an inherited target always also demands the
+    // cwd context, so an over-cautious reset here can only make a LATER
+    // segment fall back to cwd-only evaluation — identical to the shipped
+    // baseline for an unattributable form (D-003), never a fail-open.
+    if (cdClass.kind === "reset") {
+        return { ownTarget: null, effectiveTarget: null, outgoingCdBasis: null };
+    }
+    const cdArg = cdClass.kind === "cd" ? cdClass.arg : null;
+    const rawOwn = cdArg !== null ? cdArg : canon.isGit ? canon.identityTargetDir : null;
+    const ownTarget = rawOwn !== null && !isTildeTarget(rawOwn) && !isUnattributableTargetValue(rawOwn)
+        ? rawOwn
+        : null;
+    let effectiveTarget;
+    if (ownTarget === null) {
+        // D-014: a recognised `cd <path>` segment whose OWN value came out
+        // unattributable (tilde/quoted/substitution) RESETS rather than
+        // inherits — the shell genuinely changed directory to somewhere this
+        // module cannot name, so silently keeping an earlier basis in place
+        // would be a confidently-wrong carry-forward, exactly the class this
+        // whole module exists to avoid. A segment that is NOT cd-shaped at
+        // all (`cdArg === null`, `cdClass.kind === "none"`) still inherits —
+        // this module has no evidence the shell moved, so it does not guess.
+        effectiveTarget = cdArg !== null ? null : incomingCdBasis;
+    }
+    else if (path.isAbsolute(ownTarget)) {
+        effectiveTarget = ownTarget;
+    }
+    else {
+        effectiveTarget = incomingCdBasis === null ? ownTarget : null;
+    }
+    // Only a recognised `cd <path>` segment updates the outgoing basis
+    // (whether or not its OWN value came out attributable — see
+    // `CommandSegment.effectiveTarget`'s doc comment for why an
+    // unattributable `cd` must still RESET the basis to `null`, not leave a
+    // stale earlier one in place). Every other segment — gated or not —
+    // never itself changes the shell's directory, so the incoming basis
+    // passes through unchanged.
+    const outgoingCdBasis = cdArg !== null ? effectiveTarget : incomingCdBasis;
+    return { ownTarget, effectiveTarget, outgoingCdBasis };
+}
 /**
  * Given a Bash command string, return its normalised form and the target
  * directory (and base, if relative) of its git invocation. Never throws:
@@ -454,7 +830,269 @@ export function normalizeCommand(command) {
         return { normalized: command, targetDir: null, targetBase: null, truncated: false };
     }
 }
+/**
+ * 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 function segmentViewOf(command) {
+    if (typeof command !== "string" || command.length === 0)
+        return [];
+    if (command.length > MAX_NORMALIZE_LENGTH)
+        return null;
+    try {
+        return segmentAndCanonicalize(command, BOUNDARY_RE, true).segments ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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 function normalizeCommandAmpAware(command) {
+    return normalizeWithGuards(command, (c) => segmentAndCanonicalize(c, AMP_BOUNDARY_RE, false).normalized);
+}
+/**
+ * Shared empty/length/throw guard clauses for a normalisation pass whose
+ * public return shape is exactly `{ normalized, truncated }` — no
+ * `targetDir`/`targetBase` (task cf3dff51 extraction: before this,
+ * `normalizeCommandAmpAware` and `normalizeCommandQuoteAware` carried
+ * byte-identical copies of this wrapper, which `npm run check:duplication`
+ * — a jscpd clone-count fitness function, see that script's own header
+ * comment for the precedent this follows — flagged as new duplication
+ * against the pinned baseline; extracted rather than raising the pin,
+ * per that script's own stated preference). `normalizeCommand` itself is
+ * NOT this shape (its return type also carries `targetDir`/`targetBase`)
+ * and keeps its own, separate guard clauses — deliberately not folded in
+ * here, since unifying THREE different return shapes behind one generic
+ * helper would obscure more than the ~10 duplicated lines it would save.
+ * `compute` is called only once `command` has passed both guards, so it
+ * never needs to re-check emptiness or the length bound itself.
+ */
+function normalizeWithGuards(command, compute) {
+    if (typeof command !== "string" || command.length === 0) {
+        return { normalized: typeof command === "string" ? command : "", truncated: false };
+    }
+    if (command.length > MAX_NORMALIZE_LENGTH) {
+        return { normalized: command, truncated: true };
+    }
+    try {
+        return { normalized: compute(command), truncated: false };
+    }
+    catch {
+        return { normalized: command, truncated: false };
+    }
+}
 function normalizeCommandInner(command) {
+    const { normalized, targetDir, targetBase } = segmentAndCanonicalize(command, BOUNDARY_RE, false);
+    return { normalized, targetDir, targetBase, truncated: false };
+}
+/**
+ * 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 function normalizeCommandQuoteAware(command) {
+    return normalizeWithGuards(command, (c) => segmentAndCanonicalize(c, BOUNDARY_RE, false, true).normalized);
+}
+/**
+ * The shared segmentation + canonicalisation engine behind BOTH
+ * normalisation passes (task aabbad63). Parameterised on the boundary
+ * alphabet (`boundaryRe`) instead of closing over a single module-level
+ * regex, so the primary pass (`BOUNDARY_RE`) and the ampersand-aware
+ * second pass (`AMP_BOUNDARY_RE`) never share regex scan state: each
+ * call is handed its OWN regex object, and `findNextBoundary` resets
+ * that object's own `lastIndex` before every use, so the two passes
+ * (even if a future change nested one inside the other, which nothing
+ * here does today) can never observe or clobber each other's position.
+ * `targetDir`/`targetBase` ARE still computed here regardless of which
+ * alphabet drove the segmentation — `normalizeCommandAmpAware` below
+ * simply never returns them to its own caller; see that function's
+ * comment for why exposing them would be wrong under the amp alphabet
+ * specifically. Fix round 1, finding F10: under the amp alphabet
+ * specifically, ALL of this function's target bookkeeping
+ * (`explicitTargets`, `explicitTargetBase`, `bareGitSegmentCount`,
+ * `leadingCd`'s full `parseBashPrefix` pass, and the whole G1 ambiguity
+ * resolution below) is knowingly computed and then discarded by
+ * `normalizeCommandAmpAware` ITSELF, which returns only
+ * `{ normalized, truncated }` — its own caller never sees these fields at
+ * all. This is the containment design's cost, not an oversight, so a
+ * future reader should not "fix" it by exposing these fields to a
+ * hypothetical amp-alphabet consumer.
+ *
+ * `collectSegments` (task `98ad072f` groundwork, T-002): when `true`, ALSO
+ * builds the per-segment view `segmentViewOf` returns (`CommandSegment[]`)
+ * inside this SAME walk — no SECOND walk INSIDE this one function call,
+ * just a bounded amount of extra work per segment already being visited
+ * (see `computeSegmentTarget`). Scoped claim only (D-015 correction, fix
+ * round, run 2026-08-02-per-repo-gate-scoping-redesign): this says nothing
+ * about a CALLER that invokes this function twice with different
+ * `collectSegments` values on the same string — see `segmentViewOf`'s own
+ * doc comment, corrected in the same fix round, for the measured cost of
+ * exactly that. `normalizeCommandInner` and
+ * `normalizeCommandAmpAware` both pass `false`: the OLD aggregate never
+ * needed this, and the amp-aware pass deliberately never exposes a segment
+ * view at all (see that function's own comment). `segments` is `null` on
+ * the returned object when `collectSegments` is `false`, an array
+ * (possibly empty) otherwise.
+ *
+ * `quoteAware` (task cf3dff51, default `false` — every PRE-EXISTING call
+ * site is unchanged, positionally omitting this parameter): selects
+ * `findNextBoundaryQuoteAware` instead of `findNextBoundary` as the one
+ * thing this walk asks to find the next segment split. Everything else in
+ * this function — `canonicalizeSegment`, the target-directory bookkeeping,
+ * the `collectSegments` per-segment view — is IDENTICAL either way; only
+ * WHERE a segment ends changes. Only `normalizeCommandQuoteAware` passes
+ * `true`; see that function's own comment for why this had to be a new
+ * parameter on the SHARED walk rather than a wholly separate function
+ * (reuse, same reasoning `AMP_BOUNDARY_RE`'s parameterisation on
+ * `boundaryRe` already established) and for the HALT CRITERION that ruled
+ * out editing `findNextBoundary` itself in place instead.
+ */
+function segmentAndCanonicalize(command, boundaryRe, collectSegments, quoteAware = false) {
     const parts = [];
     const explicitTargets = new Set();
     let explicitTargetBase = null;
@@ -462,6 +1100,14 @@ function normalizeCommandInner(command) {
     let bareGitSegmentCount = 0;
     let i = 0;
     const n = command.length;
+    // task `98ad072f` groundwork (T-002): the per-segment view's own,
+    // independent bookkeeping — a running cd-basis (see
+    // `computeSegmentTarget`) and the accumulated segments themselves.
+    // Entirely separate from `explicitTargets` / `bareGitSegmentCount` /
+    // `hasAmbiguousNonGitSegment` above, which stay exactly as they were:
+    // this never reads or writes them, and they never read or write this.
+    const segments = collectSegments ? [] : null;
+    let cdBasis = null;
     // A leading `cd <dir> &&|;` prefix, parsed ONCE up front (G1 fix,
     // review round 2, 2026-07-27) instead of the two separate calls the
     // size===1 and size===0 branches below each used to make on their own.
@@ -486,11 +1132,54 @@ function normalizeCommandInner(command) {
     // least one boundary token's length each iteration a boundary is
     // found, and the loop stops once none remain.
     for (;;) {
-        const boundary = findNextBoundary(command, i);
+        const boundary = quoteAware
+            ? findNextBoundaryQuoteAware(command, i, boundaryRe)
+            : findNextBoundary(command, i, boundaryRe);
         const segEnd = boundary ? boundary.start : n;
         const segmentText = command.slice(i, segEnd);
         const result = canonicalizeSegment(segmentText);
         parts.push(result.text);
+        if (segments !== null) {
+            // task `98ad072f` groundwork (T-002): O(1) extra work per segment
+            // already being visited — see `segmentAndCanonicalize`'s own doc
+            // comment for why this is not a second pass over `command`.
+            //
+            // D-014 (fix round, run 2026-08-02-per-repo-gate-scoping-redesign),
+            // two bash-truthfulness corrections applied around the call, not
+            // inside `computeSegmentTarget` itself (both are about WHICH basis
+            // crosses a BOUNDARY, not about one segment's own composition):
+            //
+            //   - a running cd-basis never crosses a bare `|` — each side of a
+            //     pipeline is bash's own subshell, so a `cd` on one side cannot
+            //     affect the other (measured bypass: `cd <forged> | git push`
+            //     really runs `git push` at the real cwd, never `<forged>`).
+            //     The segment immediately after a `|` is handed `null` as its
+            //     incoming basis, as though nothing preceded it.
+            //   - the OUTGOING basis resets to `null` whenever THIS segment's
+            //     own text contains a `)` (a subshell close riding along after
+            //     `BOUNDARY_RE`'s bare `(` boundary — this alphabet has no `)`
+            //     boundary of its own, see its header comment — so a subshell's
+            //     `cd` genuinely stops applying once the subshell exits: `(cd
+            //     <forged> ; echo hi) && git push` must not let `<forged>` reach
+            //     `git push`). THIS segment's own `effectiveTarget` is computed
+            //     from the UNCHANGED incoming basis first — a segment ending in
+            //     `)` (e.g. the `git status)` tail of `(cd A && git status)`)
+            //     still correctly attributes to A for itself, exactly as it
+            //     should while still inside the subshell; only what carries
+            //     FORWARD to the next segment is affected. A simple substring
+            //     check, not paren-depth tracking: conservative, precision-only
+            //     under D-011 (see `computeSegmentTarget`'s own D-014 note) — an
+            //     over-eager reset here can only make a later segment fall back
+            //     to cwd-only, never a fail-open.
+            const incomingBasis = precedingBoundaryToken === "|" ? null : cdBasis;
+            const seg = computeSegmentTarget(segmentText, result, incomingBasis);
+            segments.push({
+                text: result.text,
+                ownTarget: seg.ownTarget,
+                effectiveTarget: seg.effectiveTarget,
+            });
+            cdBasis = segmentText.includes(")") ? null : seg.outgoingCdBasis;
+        }
         if (result.isGit) {
             if (result.targetDir === null) {
                 bareGitSegmentCount += 1;
@@ -585,14 +1274,251 @@ function normalizeCommandInner(command) {
         // push-gate fail-open this closes).
         targetDir = null;
     }
-    return { normalized: parts.join(""), targetDir, targetBase, truncated: false };
+    return { normalized: parts.join(""), targetDir, targetBase, segments };
 }
-/** Find the earliest shell boundary token at or after `from`. Returns null when none remain. */
-function findNextBoundary(s, from) {
-    BOUNDARY_RE.lastIndex = from;
-    const m = BOUNDARY_RE.exec(s);
+/**
+ * Find the earliest shell boundary token at or after `from`, under the
+ * CALLER-SUPPLIED boundary alphabet. Takes `boundaryRe` as an explicit
+ * parameter rather than closing over a single module-level regex (task
+ * aabbad63) so the primary pass (`BOUNDARY_RE`) and the ampersand-aware
+ * second pass (`AMP_BOUNDARY_RE`) each carry their own `lastIndex` state.
+ *
+ * Fix round 1, finding F8 (corrects the prior wording here): resetting
+ * `lastIndex = from` on every call is NOT what stops the two passes from
+ * clobbering each other's scan position — they are two DISTINCT regex
+ * objects, so there is nothing shared for either to clobber, and
+ * `segmentAndCanonicalize`'s own loop always calls this with `from`
+ * already equal to where the previous match's `lastIndex` would have
+ * landed anyway. That is why removing this reset measured 0 output
+ * differences across the corpus and left the suite green (see
+ * `tests/runtime/command-normalize.test.ts`'s F8 note — the mutation was
+ * applied and reverted to confirm this, not merely reasoned about). The
+ * line is still a legitimate guard, just for a DIFFERENT reason:
+ * `BOUNDARY_RE` and `AMP_BOUNDARY_RE` are module-level `/g` objects
+ * shared by every call in the process, so their `lastIndex` outlives any
+ * single scan. If `canonicalizeSegment` THROWS partway through a scan,
+ * the top-level `catch` in `normalizeCommand` /
+ * `normalizeCommandAmpAware` returns a fallback but leaves that shared
+ * object's `lastIndex` wherever the last successful match landed — and
+ * the NEXT call, on a completely different command, would then start
+ * scanning from that stale offset. This reset re-anchors it.
+ *
+ * DO NOT DELETE THIS LINE ON THE STRENGTH OF ITS MUTATION-INERTNESS.
+ * Measured (fix round 2): with the reset removed and a throw forced into
+ * `canonicalizeSegment`, the FOLLOWING call to
+ * `normalizeCommandAmpAware("a | env git push origin master")` returned
+ * the un-normalised string, and `preflight-before-push` went from MATCH
+ * to NO-MATCH. That is a gate-losing fail-open, not a stylistic nit.
+ * The honest caveat, stated rather than implied: no throw is KNOWN to be
+ * reachable from real input — the leak above was demonstrated with a
+ * forced throw, which is why the line measures inert. The module's own
+ * top-level `catch` exists because a throw is treated as possible, and
+ * this reset is the other half of that same posture.
+ */
+function findNextBoundary(s, from, boundaryRe) {
+    boundaryRe.lastIndex = from;
+    const m = boundaryRe.exec(s);
     return m === null ? null : { start: m.index, token: m[0] };
 }
+/**
+ * Quote-aware sibling of `findNextBoundary` (task cf3dff51): the earliest
+ * boundary token at or after `from` that sits OUTSIDE any open single- or
+ * double-quoted run, under the SAME `boundaryRe` alphabet the caller
+ * already scans with — no new boundary characters, only quote-tracking
+ * around the existing ones. `null` when no such boundary exists (either
+ * none remain at all, or every remaining candidate sits inside quoting
+ * that never closes before the string ends — the same conservative "no
+ * further split" fallback `consumeAssignment`'s own unterminated-quote
+ * case already uses, restated here for whole-string segmentation instead
+ * of one token).
+ *
+ * TWO-PHASE, NOT a per-character regex probe (task cf3dff51, latency fix
+ * round — this replaces this function's first shipped implementation,
+ * which called a sticky-regex `.exec()` at EVERY character position;
+ * measured ~2x `normalizeCommand`'s own cost on a large, quote-free
+ * command, because a JS-to-native regex-engine round trip at every single
+ * character is far more expensive than the SAME regex engine's own
+ * internal forward scan across many characters in one call — exactly what
+ * `findNextBoundary` already does for the primary, non-quote-aware pass).
+ * This version instead COMPOSES `findNextBoundary` (unchanged, still the
+ * quote-UNAWARE fast forward scanner) with `QuoteScanner` (below): repeat
+ * — find the next quote-unaware CANDIDATE boundary via `findNextBoundary`
+ * (one native regex scan, however far away the candidate is), then walk
+ * ONLY the span between the previous position and that candidate,
+ * character-by-character, through `QuoteScanner` (below) to learn whether
+ * a quote is open at the candidate's position; if not, the candidate IS
+ * the real boundary — return it; if so, the candidate is inside a quote
+ * (exactly the `VAR='a; b' git push` shape this pass exists to see
+ * through), step through the candidate token's own characters too (never
+ * quote-relevant — `BOUNDARY_RE`'s alphabet contains no `'`/`"`/`\` — so
+ * this is a correctness no-op, only here so the running quote/escape
+ * state stays byte-for-byte identical to a full character-by-character
+ * walk) and continue the search from just past it. For a typical command
+ * (few boundary characters, most of them outside any quote) this pays
+ * for ONE `findNextBoundary` native scan per REAL segment plus one plain
+ * (non-regex) character walk of the same total length `findNextBoundary`
+ * would have scanned internally anyway — no longer one regex call per
+ * character. `null` when no such boundary exists (either none remain at
+ * all — `findNextBoundary` itself returns `null` — or every remaining
+ * candidate sits inside quoting that never closes before the string ends,
+ * the same conservative "no further split" fallback `consumeAssignment`'s
+ * own unterminated-quote case already uses, restated here for whole-
+ * string segmentation instead of one token).
+ *
+ * `QuoteScanner` (below) is the SAME quote/escape state machine
+ * `consumeAssignment`'s own per-token loop uses (three states — `""`,
+ * `'`, `"` — same POSIX approximation: outside quotes `\` escapes the
+ * next char, `'...'` closes only at an UNESCAPED-by-construction `'`
+ * (single quotes never honour backslash escapes at all), `"..."` closes
+ * at an unescaped `"`). Extracted into a shared class (task cf3dff51 fix
+ * round: `npm run check:duplication`'s jscpd scan flagged the two
+ * independently-written copies of this loop as new duplication against
+ * the pinned baseline; see that script's own header comment for why
+ * extraction, not raising the pin, is the stated preference) rather than
+ * duplicated a second time. Generalised from per-token to whole-string
+ * scope by THIS function, not by the scanner itself: `consumeAssignment`
+ * only ever sees one already-whitespace-tokenised segment at a time; this
+ * function walks the RAW command text directly, whitespace included, so
+ * it can tell whether a `;`/`|`/`&&`/`(`/`\n` character sits inside a
+ * quote that a later whitespace-delimited token will re-enter (exactly
+ * the shape `VAR='a; b' git push` needs: the space after `;` is itself
+ * INSIDE the quoted run, not a token boundary this function cares about
+ * at all — only the eventual UNQUOTED position matters).
+ *
+ * Reuses the MODULE-LEVEL `BOUNDARY_QUOTE_SCANNER` instance (`.reset()`
+ * at the top of each call — see that constant's and `reset()`'s own
+ * comments) instead of allocating a fresh `QuoteScanner` per call, and
+ * calls `findNextBoundary` with the CALLER-SUPPLIED `boundaryRe` object
+ * directly rather than a sticky clone — `findNextBoundary` already resets
+ * `lastIndex` itself on every call (its own comment documents exactly
+ * this discipline for the primary pass sharing the SAME `BOUNDARY_RE`
+ * object), so composing it here needs no extra care. Called once per
+ * segment (not once per character) by `segmentAndCanonicalize`'s loop;
+ * the character walk itself still visits each character in the
+ * `[from, end-of-match-or-string)` span exactly once IN TOTAL across all
+ * calls for one command (split across the phase-1 "verify" loop and the
+ * phase-2 "step through the false candidate" loop, never both for the
+ * same character), keeping the whole walk O(length), same complexity
+ * class `findNextBoundary`'s own comment establishes for the primary
+ * pass — this rewrite changes the CONSTANT factor, not the asymptotic
+ * class.
+ */
+function findNextBoundaryQuoteAware(s, from, boundaryRe) {
+    BOUNDARY_QUOTE_SCANNER.reset();
+    let pos = from;
+    const n = s.length;
+    for (;;) {
+        const candidate = findNextBoundary(s, pos, boundaryRe);
+        if (candidate === null)
+            return null;
+        // Phase 1: verify quote-safety by walking ONLY the span strictly
+        // BEFORE the candidate — mirrors the original per-character scan,
+        // which never steps through the boundary token's own characters
+        // before deciding whether to return it.
+        for (let i = pos; i < candidate.start; i++) {
+            BOUNDARY_QUOTE_SCANNER.step(s[i]);
+        }
+        if (BOUNDARY_QUOTE_SCANNER.state === "") {
+            return candidate;
+        }
+        // Phase 2: the candidate sits inside an open quote — not a real
+        // boundary. Step through ITS OWN characters too (a correctness
+        // no-op, see this function's own comment) so the running state stays
+        // exactly what a full character-by-character walk would have
+        // produced, then resume the search just past it.
+        const tokenEnd = candidate.start + candidate.token.length;
+        for (let i = candidate.start; i < tokenEnd; i++) {
+            BOUNDARY_QUOTE_SCANNER.step(s[i]);
+        }
+        if (tokenEnd >= n)
+            return null;
+        pos = tokenEnd;
+    }
+}
+/**
+ * Mutable single-/double-quote + backslash-escape state machine (task
+ * cf3dff51 extraction — see `findNextBoundaryQuoteAware`'s own comment for
+ * why this was pulled out of two independently-written copies rather than
+ * left duplicated). POSIX-approximated semantics, shared verbatim by both
+ * consumers: outside quotes `\` escapes the next character; `'...'`
+ * closes only at a literal `'` (single quotes never honour backslash
+ * escapes — the `escaped` branch below is unreachable whenever
+ * `state === "'"`, by construction: `step` checks `this.escaped` BEFORE
+ * checking `this.state`, so an escape flagged one character earlier is
+ * always consumed first, but nothing inside the `state === "'"` branch
+ * itself ever SETS `escaped`, so it can never observe a `\` as anything
+ * other than a literal character); `"..."` closes at an unescaped `"`. A
+ * mutable class rather than a pure step function returning a new state
+ * object: this module runs on every Bash/Edit/Write tool call (module
+ * header) and both consumers step through EVERY character of a segment or
+ * token, so one allocation per scan (not one per character) matters for
+ * the same "allocation-light" reason the module header states elsewhere.
+ */
+class QuoteScanner {
+    state = "";
+    escaped = false;
+    /** Advance the state machine by exactly one character. */
+    step(c) {
+        if (this.escaped) {
+            this.escaped = false;
+            return;
+        }
+        if (this.state === "'") {
+            if (c === "'")
+                this.state = "";
+            return;
+        }
+        if (this.state === '"') {
+            if (c === "\\")
+                this.escaped = true;
+            else if (c === '"')
+                this.state = "";
+            return;
+        }
+        // state === ""
+        if (c === "\\")
+            this.escaped = true;
+        else if (c === "'" || c === '"')
+            this.state = c;
+    }
+    /**
+     * Reset to the initial `""` / not-escaped state — behaviourally
+     * IDENTICAL to discarding this instance and constructing a fresh one
+     * (task cf3dff51, latency fix round: lets `findNextBoundaryQuoteAware`
+     * reuse ONE module-level instance across every segment of a command
+     * instead of allocating a new one per segment — see that function's own
+     * comment for the measured latency this closes).
+     */
+    reset() {
+        this.state = "";
+        this.escaped = false;
+    }
+    /**
+     * Clear a pending escape without consuming a character. Used only by
+     * `consumeAssignment`, at a whitespace-tokenised TOKEN boundary: a
+     * backslash pending at a token's end would otherwise escape the
+     * separating whitespace itself (task b093911d's class, deliberately
+     * NOT continued — see that function's own comment). `state` is never
+     * touched by this — an open quote genuinely stays open across
+     * whitespace, only a dangling escape does not.
+     */
+    resetEscape() {
+        this.escaped = false;
+    }
+}
+/**
+ * Module-level `QuoteScanner` instance reused by `findNextBoundaryQuoteAware`
+ * across every segment of every command (task cf3dff51, latency fix
+ * round) — `.reset()` at the top of each call makes reusing this single
+ * instance behaviourally IDENTICAL to `new QuoteScanner()` per call (see
+ * `reset()`'s own doc comment), just without the allocation. Placed here,
+ * textually AFTER `class QuoteScanner`, because a top-level `const`
+ * initialiser referencing a class runs in real module-evaluation order —
+ * `findNextBoundaryQuoteAware` itself sits ABOVE this point in the file
+ * but is a hoisted function declaration whose BODY only runs when called,
+ * by which time this line has already executed.
+ */
+const BOUNDARY_QUOTE_SCANNER = new QuoteScanner();
 /**
  * Consume one leading `VAR=value` assignment starting at `idx`, returning
  * the index of the first token AFTER it. Task 13e55484: the VALUE may be
@@ -653,40 +1579,19 @@ function findNextBoundary(s, from) {
  * pinned.
  */
 function consumeAssignment(tokens, idx) {
-    let state = "";
-    let escaped = false;
+    const quote = new QuoteScanner();
     for (let i = idx; i < tokens.length; i++) {
         const text = tokens[i].text;
         if (i > idx && (GIT_TOKEN_RE.test(text) || NON_GIT_HEAD_TOKENS.has(text))) {
             return idx + 1;
         }
         for (let k = 0; k < text.length; k++) {
-            const c = text[k];
-            if (escaped) {
-                escaped = false;
-                continue;
-            }
-            if (state === "'") {
-                if (c === "'")
-                    state = "";
-                continue;
-            }
-            if (state === '"') {
-                if (c === "\\")
-                    escaped = true;
-                else if (c === '"')
-                    state = "";
-                continue;
-            }
-            if (c === "\\")
-                escaped = true;
-            else if (c === "'" || c === '"')
-                state = c;
+            quote.step(text[k]);
         }
         // A backslash pending at a token's end would escape the separating
         // whitespace itself — b093911d's class, not continued here.
-        escaped = false;
-        if (state === "")
+        quote.resetEscape();
+        if (quote.state === "")
             return i + 1;
     }
     // Ran out of tokens with a quote still open: unterminated. Preserve the
@@ -723,7 +1628,14 @@ function tokenizeWithOffsets(s) {
 function canonicalizeSegment(segmentText) {
     const tokens = tokenizeWithOffsets(segmentText);
     if (tokens.length === 0) {
-        return { text: segmentText, targetDir: null, targetBase: null, isGit: false };
+        return {
+            text: segmentText,
+            targetDir: null,
+            targetBase: null,
+            identityTargetDir: null,
+            identityTargetBase: null,
+            isGit: false,
+        };
     }
     let idx = 0;
     let envTargetDir = null;
@@ -783,7 +1695,14 @@ function canonicalizeSegment(segmentText) {
     }
     const headTok = tokens[idx]?.text;
     if (headTok === undefined) {
-        return { text: segmentText, targetDir: null, targetBase: null, isGit: false };
+        return {
+            text: segmentText,
+            targetDir: null,
+            targetBase: null,
+            identityTargetDir: null,
+            identityTargetBase: null,
+            isGit: false,
+        };
     }
     if (GIT_TOKEN_RE.test(headTok)) {
         idx += 1; // consume the git token (whatever spelling matched GIT_TOKEN_RE)
@@ -791,7 +1710,14 @@ function canonicalizeSegment(segmentText) {
         if (gitOpts.malformed || gitOpts.idx >= tokens.length) {
             // Malformed global option (missing required value) or no subcommand
             // token left: nothing safe to canonicalise. Leave untouched.
-            return { text: segmentText, targetDir: null, targetBase: null, isGit: false };
+            return {
+                text: segmentText,
+                targetDir: null,
+                targetBase: null,
+                identityTargetDir: null,
+                identityTargetBase: null,
+                isGit: false,
+            };
         }
         const subcommandTok = tokens[gitOpts.idx];
         const rewritten = `git ${subcommandTok.text}${segmentText.slice(subcommandTok.end)}`;
@@ -805,7 +1731,50 @@ function canonicalizeSegment(segmentText) {
             !path.isAbsolute(gitOpts.targetDir)
             ? envTargetDir
             : null;
-        return { text: rewritten, targetDir, targetBase, isGit: true };
+        // D-017: the identity pair mirrors targetDir/targetBase's composition
+        // exactly, but is fed by `relocateTargetDir` (repo-relocating flags
+        // only — `-C`/`--git-dir`, never `--work-tree`) instead of
+        // `gitOpts.targetDir` (which still includes `--work-tree`).
+        //
+        // D-018 (fix round 3): a same-invocation wrapping `env -C`/`--chdir`
+        // PLUS the git invocation's OWN absolute repo-relocating flag are two
+        // repo-relocating options on one invocation, the same "more than one"
+        // class `noteRelocatingOption` (in `peelGitGlobalOptions`) closes for
+        // git's own flags — extended here across the `env -C` wrap. When they
+        // diverge (different resolved directories), git's own flag DOES
+        // deterministically win in reality, but this module deliberately does
+        // not encode that composition rule (`computeSegmentTarget`'s own
+        // comment on why path composition is out of scope) — `null` (cwd
+        // fallback, D-003) rather than keep preferring git's own flag as
+        // before this fix. An identical pair (`env -C X git -C X ...`) is the
+        // same idempotent-repeat allowance as `noteRelocatingOption`'s single-
+        // function case, so it stays `X`, not `null`. The pre-existing
+        // RELATIVE-own-target + env-base mix is untouched by this check —
+        // `identityTargetBase` below already resolves that class fully to
+        // `null` via `computeSegmentTarget`'s early return; this new check
+        // only has any effect when `gitOpts.relocateTargetDir` is ABSOLUTE
+        // (`path.isAbsolute` guards it out for the relative case, the same
+        // condition `identityTargetBase` below already uses).
+        const relocateEnvDiverges = gitOpts.relocateTargetDir !== null &&
+            envTargetDir !== null &&
+            path.isAbsolute(gitOpts.relocateTargetDir) &&
+            gitOpts.relocateTargetDir !== envTargetDir;
+        const identityTargetDir = relocateEnvDiverges
+            ? null
+            : (gitOpts.relocateTargetDir ?? envTargetDir);
+        const identityTargetBase = gitOpts.relocateTargetDir !== null &&
+            envTargetDir !== null &&
+            !path.isAbsolute(gitOpts.relocateTargetDir)
+            ? envTargetDir
+            : null;
+        return {
+            text: rewritten,
+            targetDir,
+            targetBase,
+            identityTargetDir,
+            identityTargetBase,
+            isGit: true,
+        };
     }
     if (NON_GIT_HEAD_TOKENS.has(headTok)) {
         // D-001 + fix round 2 (finding F2): `gh` / `npm` / `harness` get
@@ -836,15 +1805,36 @@ function canonicalizeSegment(segmentText) {
             // just the head would silently drop whatever wrapper preceded it for
             // no benefit. Leave untouched, same fail-safe shape as the git
             // malformed/no-subcommand case above.
-            return { text: segmentText, targetDir: null, targetBase: null, isGit: false };
+            return {
+                text: segmentText,
+                targetDir: null,
+                targetBase: null,
+                identityTargetDir: null,
+                identityTargetBase: null,
+                isGit: false,
+            };
         }
         const rewritten = tokens
             .slice(idx)
             .map((t) => t.text)
             .join(" ");
-        return { text: rewritten, targetDir: null, targetBase: null, isGit: false };
+        return {
+            text: rewritten,
+            targetDir: null,
+            targetBase: null,
+            identityTargetDir: null,
+            identityTargetBase: null,
+            isGit: false,
+        };
     }
-    return { text: segmentText, targetDir: null, targetBase: null, isGit: false };
+    return {
+        text: segmentText,
+        targetDir: null,
+        targetBase: null,
+        identityTargetDir: null,
+        identityTargetBase: null,
+        isGit: false,
+    };
 }
 /**
  * Peel `env`'s own leading flags and `VAR=value` assignments. The flag-
@@ -1097,36 +2087,121 @@ function parentIfDotGit(dir) {
  * adjacent to `git`), tracking the first `-C` / `--work-tree` /
  * `--git-dir` target directory encountered (excluding a `~`-prefixed
  * value — F5, treated as if absent, but still consumed as an option so
- * parsing continues past it). `malformed: true` means a value-requiring
- * option was missing its value — the caller bails without rewriting
- * rather than guess.
+ * parsing continues past it) as `targetDir` — the OLD, UNCONSUMED
+ * aggregate's own extraction (module header STATUS note), UNCHANGED by
+ * the fix below. `malformed: true` means a value-requiring option was
+ * missing its value — the caller bails without rewriting rather than
+ * guess.
+ *
+ * `relocateTargetDir` (D-017, fix round 2, run `2026-08-02-per-repo-
+ * gate-scoping-redesign`): a SEPARATE tracker, fed ONLY by the
+ * repo-relocating flags `-C` and `--git-dir` — NEVER `--work-tree`.
+ * `--work-tree` sets the working tree but does NOT relocate git's
+ * `--git-dir` search; `git push`/`log`/`status` under `--work-tree=<B>`
+ * alone still operate on whatever repo the CURRENT directory (or an
+ * actual `-C`/`--git-dir`) names, not `<B>`. Pass-2 review measured this
+ * as a live cross-repo fail-open once `--work-tree` was folded into the
+ * same `targetDir` bucket as `-C`/`--git-dir` and that bucket fed
+ * `CommandSegment.ownTarget`'s REPLACE attribution (`computeSegmentTarget`
+ * below, `src/runtime/intercept.ts`'s `resolveAttributedContexts`,
+ * D-011): `git --work-tree=<B> push`, cwd = A, was attributed to B alone,
+ * dropping the cwd demand a real `git push` there still has to satisfy.
+ * `relocateTargetDir` is what `computeSegmentTarget` now consults for a
+ * git segment's `ownTarget` — see that function and `canonicalizeSegment`
+ * below. Kept as a distinct field (a whitelist of repo-relocating flags),
+ * not a `--work-tree` special-case, so a future path-valued-but-repo-
+ * neutral git global option cannot silently reopen this class by being
+ * folded into `targetDir` the way `--work-tree` originally was.
+ *
+ * D-018 (fix round 3, pass-3 CRITICAL): `relocateTargetDir` is set ONLY
+ * when the invocation carries EXACTLY ONE recognised, fully-resolved
+ * repo-relocating option (a single `-C` or a single `--git-dir`/
+ * `--git-dir=`). Pass-3 review measured (against real git 2.34.1) that
+ * `git -C <forge> -C <realA> push` attributes to the FIRST `-C` here
+ * while git composes ALL of them cumulatively and actually operates in
+ * `<realA>` — the same first-token-wins gap spans `-C` combined with
+ * `--git-dir`. `noteRelocatingOption` below counts every RESOLVED
+ * (non-`~`) occurrence of either flag across the whole invocation; the
+ * second (or later) occurrence forces `relocateTargetDir` to `null` and
+ * LOCKS it there for the rest of this call — UNLESS its value is an
+ * exact repeat of the one already recorded (idempotent, e.g. `-C X -C
+ * X`), which is not new information and does not trigger the lock. This
+ * is a deliberate under-approximation of git's real `-C`-chains-relative-
+ * to-the-previous-`-C` composition rule (the module has never encoded
+ * that, by design — see `computeSegmentTarget`'s own comment on why
+ * composing paths is not this module's job): ANY invocation this module
+ * cannot resolve to a single, unambiguous flag falls back to `null` here,
+ * which downstream (`computeSegmentTarget`) means "no own target" and the
+ * cwd context is demanded instead — exactly the shipped, pre-this-run
+ * semantics, never a forged first-token guess.
+ *
+ * D-021 (UNIVERSAL-ADDITIVE, operator decision, run 2026-08-02-per-repo-
+ * gate-scoping-redesign): both the D-017 `--work-tree` exclusion and the
+ * D-018 multi-option lock above were originally the SAFETY mechanism
+ * (the thing standing between an attacker-composed invocation and a
+ * forged REPLACE attribution); under D-021, `src/runtime/intercept.ts`'s
+ * `resolveAttributedContexts` never replaces the cwd demand at all, so
+ * neither exclusion can be bypassed into a weaker-than-shipped gate any
+ * more — the cwd demand is never dropped regardless of what
+ * `relocateTargetDir` resolves to. Both stay in place as PRECISION
+ * (avoiding a spurious extra demand for an ambiguous or non-relocating
+ * target), not as the security boundary; see `resolveAttributedContexts`
+ * itself for where that boundary now lives.
  */
 function peelGitGlobalOptions(tokens, startIdx) {
     let idx = startIdx;
     let targetDir = null;
+    let relocateTargetDir = null;
+    let relocateResolvedCount = 0;
+    let relocateAmbiguous = false;
+    // D-018: record one repo-relocating flag's resolved value (`null` for a
+    // `~`-prefixed value, which — same as the pre-fix code — never sets or
+    // counts against `relocateTargetDir` at all, D-003's "treated as if
+    // absent"). The SECOND (or later) resolved occurrence nulls and LOCKS
+    // `relocateTargetDir`, unless it is an exact repeat of the value
+    // already recorded (idempotent, e.g. `-C X -C X` or `-C X --git-dir
+    // X/.git`), which stays a single value rather than tripping the lock —
+    // "im Zweifel null" still applies to every OTHER two-or-more case.
+    function noteRelocatingOption(resolved) {
+        if (resolved === null)
+            return;
+        relocateResolvedCount += 1;
+        if (relocateAmbiguous)
+            return;
+        if (relocateResolvedCount === 1) {
+            relocateTargetDir = resolved;
+            return;
+        }
+        if (resolved === relocateTargetDir)
+            return; // idempotent repeat
+        relocateTargetDir = null;
+        relocateAmbiguous = true;
+    }
     while (idx < tokens.length) {
         const t = tokens[idx].text;
         if (t === "-C") {
             const dir = tokens[idx + 1]?.text;
             if (dir === undefined)
-                return { idx, targetDir, malformed: true };
+                return { idx, targetDir, relocateTargetDir, malformed: true };
             if (targetDir === null && !isTildeTarget(dir))
                 targetDir = dir;
+            noteRelocatingOption(isTildeTarget(dir) ? null : dir);
             idx += 2;
             continue;
         }
         if (t === "-c") {
             if (tokens[idx + 1] === undefined)
-                return { idx, targetDir, malformed: true };
+                return { idx, targetDir, relocateTargetDir, malformed: true };
             idx += 2;
             continue;
         }
         if (t === "--git-dir") {
             const dir = tokens[idx + 1]?.text;
             if (dir === undefined)
-                return { idx, targetDir, malformed: true };
+                return { idx, targetDir, relocateTargetDir, malformed: true };
             if (targetDir === null && !isTildeTarget(dir))
                 targetDir = parentIfDotGit(dir);
+            noteRelocatingOption(isTildeTarget(dir) ? null : parentIfDotGit(dir));
             idx += 2;
             continue;
         }
@@ -1134,13 +2209,17 @@ function peelGitGlobalOptions(tokens, startIdx) {
             const dir = t.slice("--git-dir=".length);
             if (targetDir === null && !isTildeTarget(dir))
                 targetDir = parentIfDotGit(dir);
+            noteRelocatingOption(isTildeTarget(dir) ? null : parentIfDotGit(dir));
             idx += 1;
             continue;
         }
         if (t === "--work-tree") {
+            // D-017: `--work-tree` still feeds the OLD `targetDir` aggregate
+            // (unchanged, unconsumed by any gate) but deliberately NEVER
+            // `relocateTargetDir` — see this function's own doc comment.
             const dir = tokens[idx + 1]?.text;
             if (dir === undefined)
-                return { idx, targetDir, malformed: true };
+                return { idx, targetDir, relocateTargetDir, malformed: true };
             if (targetDir === null && !isTildeTarget(dir))
                 targetDir = dir;
             idx += 2;
@@ -1163,7 +2242,7 @@ function peelGitGlobalOptions(tokens, startIdx) {
         }
         if (t === "--namespace") {
             if (tokens[idx + 1] === undefined)
-                return { idx, targetDir, malformed: true };
+                return { idx, targetDir, relocateTargetDir, malformed: true };
             idx += 2;
             continue;
         }
@@ -1177,6 +2256,6 @@ function peelGitGlobalOptions(tokens, startIdx) {
         }
         break;
     }
-    return { idx, targetDir, malformed: false };
+    return { idx, targetDir, relocateTargetDir, malformed: false };
 }
 //# sourceMappingURL=command-normalize.js.map