@lannguyensi/harness 0.63.0 → 1.0.0

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

@@ -1,658 +0,0 @@
-export interface NormalizedCommand {
-    /**
-     * The command with wrapper prefixes peeled and git invocations
-     * canonicalised to `git <subcommand>`. Shell boundary characters
-     * (`\n ; | && ( )`) are preserved verbatim so a boundary-anchored
-     * regex still matches. Byte-identical to the input when nothing
-     * recognisable was found anywhere in the command.
-     */
-    normalized: string;
-    /**
-     * The effective target directory of the command's git invocation, or
-     * `null` when the command names none, the command names invocations
-     * that disagree, or the only named value is `~`-prefixed (see the
-     * module header's target-directory-extraction rules).
-     *
-     * STILL NOT WIRED TO ANY GATE (see the module header's STATUS
-     * paragraph): extracted and fully tested, but task `98ad072f`'s
-     * per-policy redesign (T-003) attributes a target from the per-segment
-     * `segmentViewOf` view below instead of this whole-command aggregate —
-     * a single per-event `targetDir` cannot express "this invocation
-     * targets repo B, but the gated verb after it runs in the caller's
-     * cwd," which is exactly the property the redesign needs.
-     */
-    targetDir: string | null;
-    /**
-     * When `targetDir` is a RELATIVE path, the directory it should be
-     * resolved against instead of the caller's own cwd — the wrapping
-     * `env -C` on the same invocation, or a leading `cd` prefix (see the
-     * module header). `null` when `targetDir` is absolute, `null` itself,
-     * or no more specific base was found.
-     *
-     * Same unconsumed status as `targetDir` above — see the module
-     * header's STATUS paragraph.
-     */
-    targetBase: string | null;
-    /**
-     * `true` when the input exceeded `MAX_NORMALIZE_LENGTH` and
-     * normalisation was skipped entirely (G4 fix, review round 2,
-     * 2026-07-27): the caller previously had no way to tell "nothing
-     * recognisable was found" apart from "normalisation never ran at all",
-     * so the skip carried no audit signal. `false` whenever the input WAS
-     * run through `normalizeCommandInner` (including when nothing
-     * recognisable was found there either — that case is still `false`,
-     * only the length-bound short-circuit sets this).
-     */
-    truncated: boolean;
-}
-/**
- * One boundary-delimited segment's canonicalised text plus its own and
- * "effective" target directory (task `98ad072f`, T-002 of run
- * `2026-08-02-per-repo-gate-scoping-redesign`) — attributes a target to
- * the SPECIFIC segment satisfying a policy's own `bash_match` trigger,
- * instead of the single, whole-command `targetDir` / `targetBase` on
- * `NormalizedCommand` above. Produced by `segmentViewOf`. WIRED as of
- * T-003, this run: `src/runtime/intercept.ts`'s `attributeTriggerSegments`
- * / `resolveAttributedContexts` are the consumer (see the module header's
- * STATUS/UPDATE note for the exact contract).
- */
-export interface CommandSegment {
-    /**
-     * This segment's canonicalised text — the same rewrite
-     * `NormalizedCommand.normalized` applies to the corresponding span,
-     * boundary tokens EXCLUDED (they sit between segments, never inside
-     * one). Every shipped `bash_match` pattern's boundary alternation
-     * includes a `^` branch, so testing such a pattern against THIS string
-     * alone (no leading boundary character) is well-defined — see
-     * `01-plan.md`'s Proposed Approach item 2 for how a future consumer
-     * uses this.
-     */
-    text: string;
-    /**
-     * D-021 (UNIVERSAL-ADDITIVE, run 2026-08-02-per-repo-gate-scoping-
-     * redesign): the only remaining consumer of this field is
-     * `computeSegmentTarget`'s own internal `effectiveTarget` derivation
-     * (below) — `src/runtime/intercept.ts`'s `resolveAttributedContexts`
-     * (the gate) reads `effectiveTarget` only and no longer consults
-     * `ownTarget` at all. Kept as a public, separately-populated field
-     * (part of the T-002 API) rather than folded away, since a future
-     * consumer distinguishing "this segment's OWN explicit target" from
-     * "the directory it composes to once an incoming `cd` basis is
-     * accounted for" is exactly what the two-field split exists for.
-     *
-     * This segment's OWN explicit target, named by ITS OWN invocation
-     * only — a git invocation's REPO-RELOCATING global option ONLY: `-C` /
-     * `--git-dir` (or the SAME invocation's wrapping `env -C`, git-own-
-     * target-prioritised the same way `NormalizedCommand.targetDir` already
-     * is) — or, for a recognised bare `cd <path>` segment, the parsed path.
-     * Deliberately EXCLUDES `--work-tree` (D-017, fix round 2, run
-     * `2026-08-02-per-repo-gate-scoping-redesign`): `--work-tree` sets a
-     * git invocation's working tree but does NOT relocate its `--git-dir`
-     * search, so `git --work-tree=<B> push`/`log`/`status` still operate on
-     * whatever repo the invocation's ACTUAL directory names, never `<B>`
-     * alone — folding it into this field as though it were repo-identity-
-     * bearing (the pre-fix behaviour) let `resolveAttributedContexts`
-     * (`src/runtime/intercept.ts`, D-011) REPLACE the cwd demand with `<B>`'s
-     * on the strength of a flag that never moved the invocation there,
-     * measured as a live cross-repo fail-open. `null` when this segment
-     * names no repo-relocating target of its own (not a git invocation, not
-     * a `cd` segment, a bare git invocation, or a git invocation whose ONLY
-     * target-bearing flag is `--work-tree`) OR the named value is one of
-     * this view's unattributable forms: `~`-prefixed, carrying a stray quote
-     * character (the tokeniser is not quote-aware — a quoted value is
-     * captured WITH its quote character(s) still attached, not a real
-     * path), containing a command-substitution marker (`$(` or a backtick),
-     * or — for `cd` specifically — a bare `cd` with no argument or a `cd`
-     * with a flag (`cd -P /x`, three tokens instead of two). ALSO `null`
-     * when the SAME invocation names a git target via BOTH a relative own
-     * `-C` / `--git-dir` AND a wrapping `env -C` / `--chdir` base (`env -C
-     * /tmp/base git -C sub status`) — a mixed, internally ambiguous
-     * composition, unattributable for the same reason a relative own target
-     * after a preceding `cd` is (see `effectiveTarget` below); this is the
-     * ONE case where `ownTarget` itself, not just `effectiveTarget`, is
-     * nulled by a composition rule rather than by the raw value being
-     * unrecognisable on its own. A relative value (including `-C .`) and an
-     * absolute value are both otherwise preserved here verbatim, unresolved
-     * against any cwd — that resolution is a future consumer's job, not
-     * this module's. `git --git-dir=<A>/.git --work-tree=<B> ...`: this
-     * field is `<A>` (the `.git` parent) — `--git-dir` wins regardless of
-     * which flag appears first in the invocation, because `--work-tree`
-     * never contributes to this field at all, not because of any ordering
-     * rule between the two.
-     *
-     * ALSO `null` (D-018, fix round 3, pass-3 CRITICAL) when the invocation
-     * carries MORE THAN ONE recognised, resolved repo-relocating option:
-     * two-or-more `-C`, `-C` combined with `--git-dir`, `--git-dir` twice,
-     * or a same-invocation `env -C`/`--chdir` wrap whose target diverges
-     * from git's own ABSOLUTE `-C`/`--git-dir` target. Real git composes
-     * every one of these cumulatively (a later absolute value wins); this
-     * module does not encode that composition (same "not this module's
-     * job" reasoning as the relative-mix case above) and instead falls back
-     * to unattributable rather than trust the first flag it saw — `git -C
-     * <forge> -C <realA> push` actually runs in `<realA>`, but a first-
-     * flag-wins reading named `<forge>`, letting an agent redirect a gate's
-     * demanded evidence away from the repo the verb truly targets (measured
-     * against real git 2.34.1). An EXACT repeat of the same already-
-     * recorded value (`-C X -C X`, `env -C X git -C X`) is not new
-     * information and does not trigger this — see `peelGitGlobalOptions`'s
-     * `noteRelocatingOption` for the precise counting rule.
-     *
-     * D-021 (UNIVERSAL-ADDITIVE, operator decision, run 2026-08-02-per-
-     * repo-gate-scoping-redesign): the D-017/D-018 exclusions above (only a
-     * SINGLE recognised repo-relocating flag sets this field; `--work-tree`
-     * never does) are PRECISION, not the safety mechanism, since
-     * `src/runtime/intercept.ts`'s `resolveAttributedContexts` no longer
-     * REPLACES the cwd demand with this field's value — it ADDS to it, and
-     * the cwd demand is never dropped regardless of what this field
-     * resolves to. What these exclusions still prevent is a SPURIOUS extra
-     * demand (over-attributing a target the invocation does not actually,
-     * unambiguously name), not a dropped one — see that function's own doc
-     * comment for the full D-021 rationale.
-     */
-    ownTarget: string | null;
-    /**
-     * The directory this segment's own invocation actually runs in, once
-     * composed with the LAST PRECEDING recognised `cd <path>` segment in the
-     * same command (not necessarily the immediately preceding segment — any
-     * non-`cd` segment in between leaves the running cd-basis unchanged, the
-     * same way a non-`cd` shell command never itself changes the directory).
-     * Composition rules (`01-plan.md`, Proposed Approach item 1, verbatim):
-     *   - `ownTarget === null` → inherits the incoming cd-basis as-is
-     *     (including `null` when nothing preceding named one either).
-     *   - `ownTarget` absolute → itself, unconditionally — an absolute
-     *     value is never "relative to" anything a preceding `cd` named.
-     *   - `ownTarget` relative AND a preceding `cd` basis is known
-     *     (non-`null`) → `null`. This is the K1 divergence case
-     *     (`docs/okf/quote-model-divergence.md`): `cd T && git -C sub
-     *     status` does NOT become `T/sub` here — that would need real
-     *     filesystem-shaped path joining this module deliberately does not
-     *     perform — so it is UNATTRIBUTABLE rather than guessed at.
-     *   - `ownTarget` relative AND no preceding `cd` basis is known → the
-     *     raw relative value itself (deferred to a future consumer to
-     *     resolve against the real cwd).
-     * A same-invocation mixed `env -C <base>` + relative own `-C`/
-     * `--git-dir` composition (see `ownTarget` above — `--work-tree` is
-     * EXCLUDED from this mix entirely, D-017: it never sets `ownTarget`, so
-     * it can never trigger this ambiguity either) is `null` here TOO —
-     * checked BEFORE the cd-basis rules above and
-     * independently of them: `env -C /tmp/base git -C sub status` never
-     * becomes `/tmp/base/sub` (real path joining, deliberately not this
-     * module's job — same reasoning as the cd-basis K1 case) NOR does it
-     * fall through to the "relative, no cd basis, stays raw" branch above
-     * (that would hand a future consumer resolving relatives against ITS
-     * OWN cwd a CONFIDENTLY WRONG repository whenever the caller's cwd
-     * differs from `/tmp/base` — the "relative and `~` target dirs resolve
-     * to a confidently wrong repo" class named in the 07-27 review). A bare
-     * `env -C <base> git status` (no relative own target) is UNAFFECTED —
-     * `ownTarget` is `<base>` as usual, composed the ordinary way below.
-     * A recognised `cd <path>` segment whose OWN value is one of the
-     * unattributable forms above (e.g. `cd ~`) still RESETS the running
-     * cd-basis to `null` for every LATER segment — a later segment must not
-     * silently keep inheriting whatever basis existed BEFORE that `cd`,
-     * since the shell genuinely changed directory to somewhere this module
-     * cannot name.
-     *
-     * FULL reset-trigger list (D-014, fix round, run 2026-08-02-per-repo-
-     * gate-scoping-redesign — corrects this comment, which previously named
-     * only the unattributable-`cd`-value case above): the running basis
-     * resets to `null` — rather than the pre-fix behaviour of silently
-     * carrying an earlier basis forward unchanged — for ALL of: a bare `cd`
-     * with no argument, `cd -`, any other flagged `cd` (`cd -P /tmp/x`),
-     * `pushd`, `popd` (see `classifyCdSegment`), and the unattributable-
-     * `cd`-value case documented above. TWO of the reset triggers are NOT
-     * decided by this per-segment composition at all — they depend on the
-     * BOUNDARY a segment sits behind, which only the caller
-     * (`segmentAndCanonicalize`'s own walk) can see: the basis never
-     * crosses a bare `|` (each side of a pipe is bash's own subshell), and
-     * it resets after any segment whose text contains a `)` (a subshell
-     * close — `BOUNDARY_RE` has no `)` boundary of its own, so this is a
-     * substring check on the segment that happens to end there, not paren-
-     * depth tracking). See `segmentAndCanonicalize`'s own comment at its
-     * `computeSegmentTarget` call site for those two. NOT covered by any of
-     * this (same ceiling as before this fix round, unchanged): a `cd`
-     * inside a NESTED subshell that never closes within the command
-     * string's visible boundaries, and any construct outside this module's
-     * documented NOT-SUPPORTED list in the module header.
-     */
-    effectiveTarget: string | null;
-}
-/**
- * The minimal shape `peelWrapperPrefixes` and every individual `peelX`
- * wrapper-peeler actually need — `.text` only, never `.start`/`.end`
- * (task d03af8f6, review round 3). Exported so
- * `src/runtime/deletion-target-resolve.ts` can hand these SAME peelers a
- * decoded token array of its own (built from ITS quote-aware tokenizer,
- * not this module's `tokenizeWithOffsets`) without fabricating fake
- * offsets: `Token` (with real offsets) is structurally assignable to
- * `WrapperPeelToken[]` already, so `canonicalizeSegment`'s own call sites
- * below need no change at all — this is a widening of the peelers'
- * PARAMETER types only, not a behaviour change (none of them ever read
- * `.start`/`.end`).
- */
-export interface WrapperPeelToken {
-    text: string;
-}
-/**
- * The `git` token itself, matched by BASENAME so a path-qualified
- * invocation (`/usr/bin/git`, `./git`) is recognised too (F4 fix).
- * Anchored to the WHOLE token (not a substring) so `mygit` / `git-foo`
- * still correctly fail to match — `\S*` only ever contributes characters
- * immediately before a literal `/`, never before `git` directly.
- * Exported (fix round 2, finding F3) so
- * `tests/runtime/bash-match-head-token-drift.test.ts` can couple this
- * module's covered set to what FULL_TEMPLATE's shipped `bash_match`
- * policies actually key on today, instead of a test-owned duplicate.
- */
-export declare const GIT_TOKEN_RE: RegExp;
-/**
- * git global options that this module's `peelGitGlobalOptions` skips over
- * to find the subcommand. Exported so `read-only-bash.ts` can share the same
- * source of truth; each module keeps its own decision about what a matched
- * option means.
- *
- * Flags that consume a value (separate token or glued via `=`): `-C`,
- * `--git-dir`, `--work-tree`, `-c`, `--namespace`.
- *
- * Flags without a value: `--no-pager`, `-p`, `--paginate`, `--exec-path`,
- * `--literal-pathspecs`, `--no-replace-objects`.
- */
-/**
- * git global options that take a value, excluding `-c` for security.
- * `-c KEY=VALUE` can inject arbitrary git config that executes code
- * (core.fsmonitor, core.pager, core.editor, protocol.*.allow run
- * arbitrary programs); fail-closed by not skipping it. read-only-bash.ts
- * uses this set to skip only the safe value-taking options.
- *
- * Flags: `-C`, `--git-dir`, `--work-tree`, `--namespace` (recognized both
- * standalone and glued with `=`).
- */
-export declare const GIT_GLOBAL_VALUE_TAKING_FLAGS: ReadonlySet<string>;
-/**
- * git global options that take no value.
- * Flags: `--no-pager`, `-p`, `--paginate`, `--exec-path`,
- * `--literal-pathspecs`, `--no-replace-objects`.
- */
-export declare const GIT_GLOBAL_NO_VALUE_FLAGS: ReadonlySet<string>;
-/**
- * The three OTHER head tokens this module covers (D-001, run
- * 2026-07-28-nongit-trigger-wrappers) — `gh` (`gh pr merge` / `gh pr
- * create`), `npm` (`npm publish`), `harness` (the kill-switch verbs). A
- * closed set, deliberately NOT a general "any head token" rule (see the
- * module header): matched by EXACT literal equality, unlike `GIT_TOKEN_RE`'s
- * basename match, so a path-qualified spelling of any of these three stays
- * out of scope (named residual, module header NOT-SUPPORTED list). This is
- * NOT the complete set of head tokens a shipped `bash_match` trigger keys
- * on — see the module header's "SHIPPED BUT NOT COVERED" paragraph (fix
- * round 2, finding F1) for the four that are NOT in this set (`env`,
- * `unset`, `tee`, `cp`) and why. Exported (fix round 2, finding F3) for the
- * same drift-guard reason as `GIT_TOKEN_RE` above.
- */
-export declare const NON_GIT_HEAD_TOKENS: ReadonlySet<string>;
-/**
- * Above this length, normalisation is skipped entirely and the command
- * is returned unchanged (F3 fix — see the module header for why command
- * SIZE must be bounded even after `findNextBoundary` was made linear).
- * 100k characters comfortably covers any command a human or agent would
- * plausibly type, while keeping the worst case a small constant instead
- * of scaling with whatever ends up pasted into a single Bash call.
- * Exported (G4 fix, review round 2) so a caller reporting the skip (see
- * `NormalizedCommand.truncated`) can reference the same number instead of
- * hand-copying it into a diagnostic message.
- */
-export declare const MAX_NORMALIZE_LENGTH = 100000;
-/**
- * Second boundary alphabet (task aabbad63): identical to `BOUNDARY_RE`
- * plus a bare `&` — bash's OWN "start a new command here" token, which
- * every shipped `bash_match` trigger regex has treated as one of its own
- * anchor characters since task `d834a065`, but which `BOUNDARY_RE` above
- * has never recognised as a NORMALISATION-time boundary (see its comment
- * for the reverted, measured-140/140-regression attempt to add it there
- * directly).
- *
- * ALTERNATION ORDER IS LOAD-BEARING: `&&` MUST be listed to the LEFT of
- * the bare `&` alternative. JS regex alternation is leftmost-FIRST, not
- * leftmost-longest — with `&` tried before `&&`, every `&&` in a command
- * would tokenise as TWO consecutive one-character `&` boundary MATCHES
- * instead of a single two-character `&&` boundary match.
- *
- * MEASURED, NOT ASSUMED (do not "simplify" the pin below to an
- * end-to-end `.normalized` string assertion): for THIS module's segment-
- * and-rejoin architecture specifically, that reordering is, perhaps
- * counter-intuitively, INVISIBLE in `normalizeCommandAmpAware`'s own
- * output string. Two adjacent single-`&` matches sandwich a genuinely
- * zero-length segment between them (the two `&` characters of a real
- * `&&` are, by definition, adjacent), `canonicalizeSegment("")` is a
- * verbatim no-op, and `parts.join("")` reassembles the exact same bytes
- * either way — verified directly (not merely reasoned about) by
- * temporarily swapping this alternation's order, rebuilding, and
- * diffing `normalizeCommandAmpAware(...).normalized` across several
- * `&&`-bearing commands (including this comment's own `git -C
- * /tmp/repoB status && git -C /tmp/repoB log` example): byte-identical
- * output both ways. So a test asserting on the OUTPUT STRING alone
- * cannot distinguish the two orderings for this architecture — the pin
- * in `tests/runtime/command-normalize.test.ts` therefore execs this
- * regex object DIRECTLY against a `&&`-bearing string and asserts the
- * match text is `"&&"`, not `"&"`, which DOES fail under a swap. The
- * order is still specified exactly as documented above (leftmost-first
- * is real JS semantics, and the internal `segmentAndCanonicalize`
- * bookkeeping this alphabet ALSO drives — `hasAmbiguousNonGitSegment`,
- * discarded by `normalizeCommandAmpAware` but not by a hypothetical
- * future consumer of `segmentAndCanonicalize` under this alphabet —
- * would still see a spurious extra "non-git segment" under the wrong
- * order), it just cannot be pinned through this module's ONE exposed
- * string alone.
- *
- * Used ONLY by `normalizeCommandAmpAware` below, which is consulted ONLY
- * as `policyMatchesEvent`'s third, additional matching arm — see that
- * function's own comment for why its result never carries a `targetDir`/
- * `targetBase`, and `src/runtime/intercept.ts` for the memoised-thunk
- * threading that keeps this off the common (raw-or-normalised-already-
- * matched) path. Exported (mirrors `GIT_TOKEN_RE` / `NON_GIT_HEAD_TOKENS`
- * / `MAX_NORMALIZE_LENGTH` above) solely so the ordering pin test can
- * exec it directly instead of re-declaring an equivalent regex literal
- * that would test JS semantics in general, not THIS source's actual
- * alternation.
- */
-export declare const AMP_BOUNDARY_RE: RegExp;
-/**
- * Given a Bash command string, return its normalised form and the target
- * directory (and base, if relative) of its git invocation. Never throws:
- * any internal failure (there should be none — this is a defensive
- * backstop matching the fail-safe shape used elsewhere in this codebase,
- * e.g. `policyMatchesEvent`'s `try/catch` around `new RegExp`) falls back
- * to the input unchanged.
- */
-export declare function normalizeCommand(command: string): NormalizedCommand;
-/**
- * Given a Bash command string, return its per-segment view (task
- * `98ad072f` groundwork, T-002) — see `CommandSegment`'s own doc comment
- * for the field-level composition rules. `null` when the input exceeded
- * `MAX_NORMALIZE_LENGTH` (mirrors `NormalizedCommand.truncated`, but as
- * the ABSENCE of a view rather than a boolean flag alongside one, since
- * there is no meaningful per-segment view to return for an input whose
- * normalisation itself was skipped). `[]` for an empty or non-string
- * command, and as the never-throws fallback (mirrors `normalizeCommand`'s
- * own defensive backstop — see its doc comment above).
- *
- * THIS function's OWN call into `segmentAndCanonicalize` (`collectSegments:
- * true`) is one walk, O(length) — the "no additional pass" claim is scoped
- * to that ONE call, not to a caller's total work. CORRECTED (D-015, fix
- * round, run 2026-08-02-per-repo-gate-scoping-redesign) — the prior wording
- * here read "no additional pass over the command string" without that
- * scoping, which a reader could take as "calling this costs nothing beyond
- * `normalizeCommand`'s own walk." Measured false: `normalizeCommand(cmd)`
- * and `segmentViewOf(cmd)` are two SEPARATE top-level calls, each running
- * its own full `segmentAndCanonicalize` pass over the SAME string — a
- * caller needing both (as `src/cli/policy/intercept.ts` does, for
- * `normalized`/`truncated` and the segment view respectively) pays TWO
- * walks, not one; measured +206% at the `MAX_NORMALIZE_LENGTH` bound
- * (2.73 → 8.36 ms), harmless against the 1000 ms hook budget but not free.
- * As of the same fix round, the one production caller only pays this
- * second walk lazily, when some matching policy actually needs it (see
- * `InterceptOptions.commandSegmentsThunk` in `src/runtime/intercept.ts`) —
- * but that laziness lives in the CALLER, not in this function, which still
- * does exactly one walk every time it runs. The ampersand-aware second pass
- * (`normalizeCommandAmpAware`) NEVER collects a segment view (always calls
- * `segmentAndCanonicalize` with `collectSegments: false`) — see that
- * function's own comment for why a directory extracted under the
- * ampersand-aware alphabet would be unreliable in the first place; the
- * same reasoning applies here, so this module offers no amp-aware variant
- * of this function at all.
- */
-export declare function segmentViewOf(command: string): CommandSegment[] | null;
-/**
- * Ampersand-aware sibling of `segmentViewOf` (task d03af8f6, review
- * round 3): the same per-segment view, but segmented under
- * `AMP_BOUNDARY_RE` (`BOUNDARY_RE` plus a bare `&`) instead of
- * `BOUNDARY_RE` — closing the same bare-`&` gap `normalizeCommandAmpAware`
- * closes for trigger matching (`echo hi & rm -rf /home/x`), but as a
- * segment VIEW rather than a rejoined string, for
- * `src/runtime/deletion-target-resolve.ts`'s multi-segment scan. Uses the
- * SAME shared walk (`segmentAndCanonicalize`, parameterised on
- * `boundaryRe` since task aabbad63) as every other pass in this module —
- * no new segmentation logic. `CommandSegment.effectiveTarget`'s own
- * composition rules are UNCHANGED by which alphabet drove the split; a
- * caller that only needs `.text` per segment (as the deletion resolver
- * does) is unaffected by the same directory-extraction reliability
- * caveat `normalizeCommandAmpAware`'s own comment names for `targetDir`/
- * `targetBase` — this function returns the FULL `CommandSegment` shape,
- * `effectiveTarget` included, so a future caller relying on THAT field
- * under this alphabet should read `normalizeCommandAmpAware`'s comment
- * first. `null` under the same `MAX_NORMALIZE_LENGTH` condition
- * `segmentViewOf` uses; `[]` for an empty/non-string command or the
- * never-throws fallback.
- */
-export declare function segmentViewOfAmpAware(command: string): CommandSegment[] | null;
-/**
- * Return type of `normalizeCommandAmpAware` — deliberately NOT
- * `NormalizedCommand` (task aabbad63, hard constraint). It carries only
- * `normalized`/`truncated`; there is no `targetDir`/`targetBase` field at
- * all, so a future caller cannot wire one up to a gate by mistake — see
- * `normalizeCommandAmpAware`'s own comment for why a directory extracted
- * under the ampersand-aware alphabet would be unreliable in the first
- * place, not merely "unwired today".
- */
-export interface AmpAwareNormalizedCommand {
-    /** Same contract as `NormalizedCommand.normalized`, under `AMP_BOUNDARY_RE`. */
-    normalized: string;
-    /** Same contract as `NormalizedCommand.truncated`. */
-    truncated: boolean;
-}
-/**
- * Ampersand-aware SECOND normalisation pass (task aabbad63). Segments the
- * command under `AMP_BOUNDARY_RE` (`BOUNDARY_RE` plus a bare `&`) instead
- * of `BOUNDARY_RE`, then canonicalises exactly like the primary pass
- * (same `canonicalizeSegment`, same wrapper-peeling rules, same
- * `MAX_NORMALIZE_LENGTH` bound). Closes the gap `BOUNDARY_RE`'s own
- * comment names: `A=x&env -C /tmp git status` and `echo hi & nice git
- * status` were ungated because a wrapper can only be peeled after a
- * recognised boundary, and a bare `&` was not one.
- *
- * Return type deliberately has NO `targetDir`/`targetBase` — not merely
- * "always null under this alphabet", genuinely ABSENT from the type, so
- * no consumer can read one by mistake. Reason: a bare `&` is ALSO how
- * bash spells a background job (`git -C /x push &`) and how a redirect
- * merges streams (`git -C /x log 2>&1`, `... &> out`). Under THIS
- * alphabet each of those splits into a spurious extra "segment", which
- * `segmentAndCanonicalize`'s own non-git-segment ambiguity rule (a
- * segment that starts a new command and is not itself a git invocation
- * forces `targetDir` to `null` — see its G1 comment) would turn into a
- * wrong-shaped loss for a case the PRIMARY pass still resolves correctly
- * today. Pinned in `tests/runtime/command-normalize.test.ts`'s "aabbad63
- * groundwork" describe block, which exercises ONLY `normalizeCommand`
- * (the primary pass), never this function — `targetDir`/`targetBase`
- * stay the primary pass's property alone.
- *
- * Only consulted by `policyMatchesEvent`'s third arm
- * (`src/runtime/intercept.ts`), and only when a policy's `bash_match`
- * regex has already missed BOTH the raw command and the primary
- * normalised form — see that module and `src/cli/policy/intercept.ts`
- * for the memoised-thunk threading that keeps this computation off the
- * common (already-matched) path.
- */
-export declare function normalizeCommandAmpAware(command: string): AmpAwareNormalizedCommand;
-/**
- * Return type of `normalizeCommandQuoteAware` — same shape and same
- * reasoning as `AmpAwareNormalizedCommand` above: no `targetDir`/
- * `targetBase`, so no consumer can read one extracted under quote-aware
- * segmentation by mistake. Unlike the amp-aware pass, THIS alphabet is
- * exactly `BOUNDARY_RE`'s own (no new boundary characters, only new
- * quote-tracking around the existing ones), so the reason for omitting
- * these fields is different: `computeSegmentTarget` / `classifyCdSegment`
- * / `canonicalizeSegment` all assume `tokenizeWithOffsets`'s whitespace
- * tokenisation lines up with the segment boundaries `findNextBoundary`
- * produces, which is still true for the boundary ALPHABET itself but is
- * now also entangled with `consumeAssignment`'s OWN, separate quote
- * tracking (per-token, inside one segment) once segments can be wider and
- * carry an unbalanced quote at their edges in new ways this task's own
- * corpus does not exhaustively characterise for `targetDir` purposes —
- * left unexplored rather than guessed at, mirroring the amp-aware pass's
- * own "not this task's job" scoping.
- */
-export interface QuoteAwareNormalizedCommand {
-    /** Same contract as `NormalizedCommand.normalized`, under quote-aware segmentation. */
-    normalized: string;
-    /** Same contract as `NormalizedCommand.truncated`. */
-    truncated: boolean;
-}
-/**
- * Quote-aware THIRD normalisation pass (task cf3dff51). Segments the
- * command under `BOUNDARY_RE`'s own alphabet — same characters as the
- * primary pass, no widening — but tracks single/double-quote state while
- * scanning (`findNextBoundaryQuoteAware` below) so a boundary character
- * sitting INSIDE a quoted assignment value is no longer treated as a real
- * segment split. Closes the gap the module header's "DELIBERATELY NOT
- * SUPPORTED" list and `BOUNDARY_RE`'s own comment both name: `VAR='a; b'
- * git push` (task 13e55484's pinned residual) — `BOUNDARY_RE` used to cut
- * the segment at the `;`, landing squarely between the two halves of one
- * quoted value, so neither resulting piece carried a recognisable
- * invocation and `consumeAssignment`'s own multi-token quote continuation
- * (built for exactly this shape) never got the chance to run: it operates
- * AFTER segmentation, on tokens WITHIN one segment, and the quoted value
- * was never in one segment to begin with. Once quote-aware segmentation
- * keeps the value whole, `consumeAssignment` needs no changes at all — it
- * already reconstructs a multi-token quoted value correctly; this pass
- * only fixes what gets handed to it as ONE segment in the first place.
- *
- * BUILT AS A NEW, INDEPENDENT PASS RATHER THAN AN IN-PLACE EDIT OF
- * `BOUNDARY_RE` / `segmentAndCanonicalize` — this is the module header's
- * HALT CRITERION, restated here at the point it governs: quote-aware
- * segmentation can MERGE a segment the primary pass currently splits, and
- * that merge cuts in BOTH directions — it can turn a previously-missed
- * bypass into a match (the fix), but it can just as easily turn a
- * previously-accepted, ALREADY-WIRED over-block into a miss (a
- * regression). Measured, not hypothetical: `tests/runtime/command-
- * normalize.test.ts`'s "accepted over-block: a quoted assignment inside
- * TEXT after a boundary char now matches" pin — `echo "a; VAR='x y' git
- * push"` — matches via `normalizeCommand` TODAY only because `BOUNDARY_RE`
- * splits it at the `;`, landing `VAR='x y' git push` at a segment start
- * where the assignment continuation turns it into a match. An in-place
- * quote-aware edit of THAT pass would un-split it back into the outer
- * `echo "..."` segment — not itself a recognised invocation — and flip
- * that pin to a lost match, in violation of the raw-OR-normalised-OR-amp-
- * aware-OR-(this) never-lose-a-match discipline every other pass in this
- * module already honours. Building this as a SEPARATE pass instead means
- * `normalizeCommand`'s own segmentation, and every test resting on it —
- * including that exact one — is untouched by this task; see this file's
- * own test suite for the differential proof (every case the first three
- * arms already matched still matches, by construction, because none of
- * those three arms' code changed at all).
- *
- * WIRED to `policyMatchesEvent` (`src/runtime/intercept.ts`) as its
- * FOURTH arm — same shape as `normalizeCommandAmpAware`'s own third-arm
- * wiring (task aabbad63): consulted only after the raw command,
- * `normalizedCommand`, and the amp-aware pass have all missed, via a
- * memoised thunk (`InterceptOptions.quoteNormalizedCommandThunk`,
- * `src/cli/policy/intercept.ts`'s `quoteNormalizedCommandThunk`) so the
- * segmentation cost is paid at most once per event, on the common
- * (already-matched) path it costs nothing at all. Wiring landed in a
- * SECOND round of this task, after the orchestrator extended the first
- * round's file scope specifically for this one wiring point — the first
- * round shipped this function fully built and tested but genuinely
- * unwired (an inert security fix, called out explicitly as the wrong
- * shipped state in that round's own report) — `src/cli/dry-run.ts`'s own,
- * independently-copied matcher was deliberately NOT extended in the same
- * round (out of the extended scope too) and stayed a named residual until
- * task f561e44c closed it by adding the same fourth OR-arm there too — see
- * that file's own comment.
- *
- * THIS PASS'S OWN OVER-BLOCK SURFACE is measured and named in the test
- * file rather than assumed — and the measurement CORRECTS an earlier,
- * pre-measurement guess that used to sit in this comment: it does NOT
- * reproduce the `echo "a; VAR='x y' git push"` accepted over-block named
- * above. Quote-aware merging keeps that whole `echo "..."` segment
- * together, starting with the unrecognised head token `echo`, so this
- * function's output for it is byte-identical to the raw input
- * (`normalizeCommand`'s OWN, separate, unchanged-by-this-task match for
- * that same string is unaffected either way). Measured against a broader
- * adversarial probe, both at this function's own level and again at
- * `policyMatchesEvent`'s wired level (a bash-shim-verified corpus of
- * chained/prefixed/subshell-wrapped genuine invocations plus candidate
- * over-block shapes — entirely quoted `echo`/`printf` arguments that only
- * PRINT the spelling): every additional match this pass adds beyond raw /
- * `normalizeCommand` / `normalizeCommandAmpAware` is a TRUE positive (a
- * real invocation bash would actually execute); no NEW over-block class
- * distinct from `consumeAssignment`'s own, already-reviewed precision
- * limits was found. This function shares `canonicalizeSegment` /
- * `consumeAssignment` completely unchanged with the other passes — only
- * the segmentation boundary decision differs — which is also the
- * structural reason a longer (merged) segment can only REVEAL a match
- * those functions would already accept from a shorter view, never
- * fabricate a new kind of one; see the module header's cf3dff51 UPDATE
- * paragraph for the fuller statement of this reasoning and its
- * "not a formal proof" caveat.
- */
-export declare function normalizeCommandQuoteAware(command: string): QuoteAwareNormalizedCommand;
-/** Return type of `peelWrapperPrefixes` — see that function's own comment. */
-export interface WrapperPeelResult {
-    /** Index of the first token after every recognised wrapper prefix this
-     *  loop peeled — the wrapped invocation's own head token, or (if
-     *  `tokens.length`) no head token survived at all. */
-    idx: number;
-    /**
-     * The `env -C <dir>` / `--chdir <dir>` target directory, when this
-     * chain peeled an `env` wrapper naming one (excluding a `~`-prefixed
-     * value — F5, treated as if absent). `null` when no `env -C`/`--chdir`
-     * was peeled. Consumed only by `canonicalizeSegment`'s own
-     * `targetDir`/`targetBase` bookkeeping —
-     * `src/runtime/deletion-target-resolve.ts` (the other caller, task
-     * d03af8f6, review round 3) has no analogous need and ignores it.
-     */
-    envTargetDir: string | null;
-}
-/**
- * Peel a leading wrapper-command chain: `VAR=value` tokens (any number,
- * in sequence), `env` (+ its own flags/assignments, capturing `-C`/
- * `--chdir`), `command` (+ its own flags), `nice` (+ its own flags),
- * `sudo` / `doas` / `time` / `timeout` / `stdbuf` / `setsid` / `exec` /
- * `nohup` (+ each one's own flags — F4 fix; `exec`/`nohup` added task
- * d03af8f6, review round 3). Bounded by `tokens.length` so a
- * pathological input cannot spin. Returns the cursor position of
- * whatever token (if any) survives the peel — the caller decides what to
- * do with it; this function never itself inspects the survivor.
- *
- * SHARED (task d03af8f6, review round 3) between `canonicalizeSegment`
- * below — this module's own `git`/`gh`/`npm`/`harness` trigger
- * recognition — and `src/runtime/deletion-target-resolve.ts`'s deletion-
- * verb recognition (`rm`/`find`/`git clean`), which used to hand-roll an
- * independent, narrower copy of this exact peeling vocabulary
- * (`peelWrapperHeads`, missing `-u`/`-i`/`-C` on `env`, the duration-
- * consuming shape of `timeout`, `nice`'s glued/`--adjustment=` forms,
- * and `exec`/`nohup` entirely). Reusing this ONE loop instead of
- * maintaining two means a future wrapper added here (or a flag fix to an
- * existing one) benefits both gates automatically, and
- * `npm run check:duplication`'s clone-count fitness function has one
- * fewer near-duplicate block to flag. `deletion-target-resolve.ts` hands
- * this a decoded token array built from ITS OWN quote-aware tokenizer
- * (`WrapperPeelToken[]`, `.text` only — see that interface's own
- * comment for why the offset-carrying `Token[]` this module's own
- * `tokenizeWithOffsets` produces is not required here), then layers its
- * own `xargs` handling on top (this loop deliberately does NOT recognise
- * `xargs` — see the module header's NOT-SUPPORTED list for why `xargs`
- * is architecturally different from every wrapper peeled here: its own
- * argv is not simply "the command to run").
- */
-export declare function peelWrapperPrefixes(tokens: readonly WrapperPeelToken[], startIdx?: number): WrapperPeelResult;
-/**
- * Generic "peel this wrapper's own flags" loop shared by the small,
- * bounded-vocabulary runners added for F4 (`sudo`, `doas`, `time`,
- * `stdbuf`, `setsid`, `exec`, `nohup`): consume `--`, any flag in
- * `valueFlags` (+ its following token), any glued short/long form
- * matching `gluedRe`, then any OTHER `-`-prefixed token treated as
- * boolean (mirrors `peelCommand` above — safe because an unrecognised
- * flag is either genuinely boolean, in which case this is correct, or
- * value-taking, in which case its VALUE token is left for the next
- * iteration and — not being `git`, a known wrapper, or another flag —
- * simply causes a clean, safe bail-out a token late rather than a false
- * match). Does NOT capture flag VALUES: none of these wrappers have a
- * "run in a different directory" semantic this module tracks as a
- * target directory — only `env -C`/`--chdir` does, and that stays
- * hand-written in `peelEnv`. Exported (task d03af8f6, review round 3) so
- * `src/runtime/deletion-target-resolve.ts` can reuse this SAME loop for
- * `xargs`'s own flags (`-0`, `-n1`, ...) instead of a third
- * independently-drifting copy — that module is the reason this needs no
- * value-flag vocabulary of its own either: `xargs`'s own value-taking
- * flags are not modelled there, matching this function's existing
- * effort level for the boolean-only wrappers above.
- */
-export declare function peelGenericFlags(tokens: readonly WrapperPeelToken[], startIdx: number, valueFlags: ReadonlySet<string>, gluedRe: RegExp | null): number;