@lannguyensi/harness 0.43.0 → 0.44.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,12 @@
 // 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.
 //
 // THE TRIGGER-MATCHING GAP THIS CLOSES: every `bash_match` policy trigger
 // (`src/cli/init/templates.ts`, `docs/examples/full-manifest.yaml`) is a
@@ -315,6 +359,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 +473,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 +757,149 @@ 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) {
+    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: segmentAndCanonicalize(command, AMP_BOUNDARY_RE, false).normalized,
+            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 };
+}
+/**
+ * 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.
+ */
+function segmentAndCanonicalize(command, boundaryRe, collectSegments) {
     const parts = [];
     const explicitTargets = new Set();
     let explicitTargetBase = null;
@@ -462,6 +907,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 +939,52 @@ 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 = 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,12 +1079,50 @@ 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] };
 }
 /**
@@ -723,7 +1255,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 +1322,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 +1337,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 +1358,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 +1432,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 +1714,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 +1836,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 +1869,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 +1883,6 @@ function peelGitGlobalOptions(tokens, startIdx) {
         }
         break;
     }
-    return { idx, targetDir, malformed: false };
+    return { idx, targetDir, relocateTargetDir, malformed: false };
 }
 //# sourceMappingURL=command-normalize.js.map