@yanlinglabs/winter-agent-runtime 0.0.41 → 0.0.44

package/dist/permissions/file-rules.d.ts

@@ -1,84 +1,56 @@
 export type FileRuleKind = "edit" | "read";
 /**
- * SV-7 (the router same-view test): claude's file-rule grammar has only TWO pattern kinds --
- * `Edit(...)` and `Read(...)`. Dump-confirmed: `ln`'s own dispatch switch has exactly two cases
- * (`case"edit":return tn;case"read":return wt`, each a SINGLE literal tool-name string `ub` filters
- * `ruleValue.toolName` against by exact equality) -- there is no third "write" kind anywhere in the
- * data model. Claude's own WRITE decision function (`zC`) ALWAYS consults `"edit"`-kind rules,
- * regardless of which literal write-shaped tool called it -- this is what makes an `Edit(...)` ask
- * rule fire before a **Write** on claude (the router's own SV-7 measurement), and what makes a
- * `Write(...)`-toolName rule a Winter-only spelling with no claude analogue at all: `ub` filtering
- * on the literal string "Write" never runs, because nothing ever calls it with that string.
- *
- * Every `FILE_RULE_TOOLS` member (grammar.ts) routes to exactly one kind, on every direction (allow,
- * ask, deny alike -- the ruling's own "for both ALLOW and DENY" instruction, extended to ask since
- * ask shares deny's conservative "cross tools" posture throughout this codebase already).
+ * File rules come in exactly two kinds, `edit` and `read`. Every write-shaped tool (Edit, Write,
+ * NotebookEdit) is checked against the `edit` kind and every read-shaped one (Read, Glob, Grep)
+ * against the `read` kind, on every direction (allow, ask, deny). So an `Edit(...)` ask rule fires
+ * before a Write, as it does in Claude Code.
  */
 export declare function fileRuleKindFor(toolName: string): FileRuleKind | undefined;
 /**
- * The ONE literal tool name a rule must be AUTHORED under to ever be consulted for `kind` -- claude's
- * own `ub` filters `ruleValue.toolName` by EXACT STRING EQUALITY against a single literal per kind
- * (`tn`/`"Edit"` for `"edit"`, `wt`/`"Read"` for `"read"`; dump-confirmed, `ln`'s own two-case
- * switch), never against every tool that happens to share the kind. This is what makes SV-7's
- * "reverse" finding true: a rule AUTHORED as `Write(...)`, `NotebookEdit(...)`, `Glob(...)` or
- * `Grep(...)` is dead code claude never reads for ANY call -- not even a call from that SAME literal
- * tool -- because `ub` was never invoked with that string. `Write`/`NotebookEdit`/`Glob`/`Grep`
- * remain valid rule-authoring tool names SYNTACTICALLY (grammar.ts's `FILE_RULE_TOOLS` still parses
- * them -- Winter does not forbid authoring one), but this function is what `findMatchingFileRuleEntry`
- * (evaluator.ts) filters CANDIDATES with, so only `Edit(...)`/`Read(...)`-authored rules ever reach
- * a group.
+ * The ONE tool name a rule must be written under to be consulted for `kind`: `Edit` for `edit`,
+ * `Read` for `read`. A rule written as `Write(...)`, `NotebookEdit(...)`, `Glob(...)` or `Grep(...)`
+ * still parses (grammar.ts's `FILE_RULE_TOOLS`), but is never consulted for any call -- not even one
+ * from that same tool -- matching Claude Code's rule grammar, where only `Edit(...)` and `Read(...)`
+ * rules are file rules. `findMatchingFileRuleEntry` (evaluator.ts) filters candidates with this.
  */
 export declare function canonicalFileRuleAuthoringToolName(kind: FileRuleKind): "Edit" | "Read";
-/** A sentinel distinct from `null` ("resolve against cwd"): a `/`-anchored rule with no resolvable settings-source directory is INERT, never falls back to cwd. */
+/** A sentinel distinct from `null` ("resolve against cwd"): a `/`-anchored rule with no settings-source directory is INERT, and never falls back to cwd. */
 declare const INERT_ANCHOR: unique symbol;
 export interface FileRuleAnchor {
     /** The pattern text, relative to `root`, in `ignore`-package (gitignore) grammar. */
     relativePattern: string;
-    /** `null` means "resolve against cwd" (`Ma`'s own `P ?? te()`, ported as `root ?? opts.cwd`); the sentinel means the anchor can never match anything. */
+    /** `null` means "resolve against cwd"; the sentinel means the rule can never match anything. */
     root: string | null | typeof INERT_ANCHOR;
 }
 /**
- * `jOe` (dump-confirmed): the FOUR anchor spellings WS-07 §3.1 documents, resolved to a
- * `{relativePattern, root}` pair -- ported exactly, including the leading-slash-KEPT behaviour on
- * the three anchored forms (`//x`, `~/x`, `/x`) that is what makes them root-anchored in gitignore
- * terms, and its ABSENCE on `./x`/bare `x` that is what lets `deny ./.env` reach `pkg/.env` (C-1's
- * own example) -- a bare pattern with no leading slash and no inner slash is exactly the shape the
- * `ignore` package's own `^(?=[^^])` -> `(?:^|\/)` replacer un-anchors.
- *
- * A bare `~` (no trailing slash) is NOT specially handled by claude's own `jOe` either -- it falls
- * through to the final else branch as a literal filename pattern `"~"`, cwd-anchored. Ported
- * faithfully rather than "fixed", matching this module's own "port what was measured" discipline.
- *
- * `sourceDir` is claude's `bl(source)` -- the settings-source-derived root for a `/`-anchored rule.
- * Since fix round 11 a settings-tier rule carries it (`SourcedRuleEntry.sourceDir`, set by
- * production-wiring.ts's `buildSettingsRuleSeed` per claude's `Wyt`), and a `/`-anchored rule resolves
- * against it. When it is absent -- a rule from Options, canUseTool or a plugin -- the rule is inert
- * (the `INERT_ANCHOR` root below, treated as "no group to match against" by `matchFileRulesGrouped`).
+ * Resolves a pattern's anchor spelling to the root it is relative to and the pattern text relative
+ * to that root:
+ *   - `//x`  -> root `/`, pattern `/x` (one slash dropped, the leading `/` KEPT);
+ *   - `~/x`  -> root `home`, pattern `/x` (the `~` dropped, the leading `/` KEPT);
+ *   - `/x`   -> root `sourceDir` (the directory of the settings file the rule came from), pattern
+ *               `/x` unchanged; with no `sourceDir` -- a rule from Options, canUseTool or a plugin --
+ *               the rule is INERT (`INERT_ANCHOR`) and matches nothing;
+ *   - `./x`  -> root cwd (`null`), pattern `x` (the `./` dropped, NO leading `/`);
+ *   - else   -> root cwd (`null`), pattern unchanged (a bare `~` included: it is a file named `~`).
+ * The kept leading `/` is what anchors a pattern to its root in gitignore terms; its absence is what
+ * lets `deny ./.env` also reach `pkg/.env`.
  */
 export declare function resolveFileRuleAnchor(pattern: string, opts: {
     home: string;
     sourceDir?: string | undefined;
 }): FileRuleAnchor;
 /**
- * WS-21 fix round 10, item C: a Read/Edit rule's own pattern, resolved to ONE absolute filesystem
- * path -- for the sandbox's own `subpath` rule (sandbox/profile.ts's `denyWritePaths`/
- * `denyReadPaths`/`writableRoots`), which has no glob grammar of its own to hand a pattern string
- * to; a real Seatbelt `subpath` already means "this directory and everything under it," so it needs
- * ONE real path, never a pattern.
+ * A Read/Edit rule's pattern resolved to ONE absolute filesystem path, for the sandbox's `subpath`
+ * rules (sandbox/profile.ts's `denyWritePaths`/`denyReadPaths`/`writableRoots`), which take a real
+ * path, not a pattern; `subpath` already means "this directory and everything under it".
  *
- * `undefined` in two cases, matching claude's own observable posture (dump-confirmed, `Jm`: `let{
- * allowOnly:t}=at.getFsWriteConfig();if(t.some(eg))return!0` -- ANY glob-shaped entry in the
- * write-allow set makes claude's OWN sandbox stop trying to restrict writes via that mechanism at
- * all, relying on the separate, glob-aware PERMISSION-RULE layer instead, which is unaffected by
- * this and stays the real enforcement point):
- *   - the pattern is INERT (a bare `/`-anchored rule with no resolvable settings-source root --
- *     `resolveFileRuleAnchor`'s own pre-existing posture, unchanged here);
- *   - the pattern is genuinely GLOB-SHAPED once a single TRAILING `/**` is stripped (redundant with
- *     `subpath`'s own "and everything under it" semantics, so it is not itself disqualifying --
- *     `Edit(//repo/secrets/**)` becomes the plain path `/repo/secrets`) -- a glob ANYWHERE else
- *     (`src/*.ts`, `[wip]`, `a?b`) cannot become one exact path at all.
- * A caller that gets `undefined` back simply does not add this rule to the sandbox's own filesystem
- * lists; the permission-rule layer (`evaluate()`) still enforces it in full, exactly as it always has.
+ * `undefined` when there is no such path:
+ *   - the pattern is INERT (a `/`-anchored rule with no settings-source directory);
+ *   - the pattern is still glob-shaped once ONE trailing `/**` is stripped (`Edit(//repo/secrets/**)`
+ *     becomes the plain path `/repo/secrets`; `src/*.ts`, `[wip]`, `a?b` cannot become one path).
+ * A glob-shaped write-ALLOW entry is simply left out of the sandbox, which then does not try to
+ * restrict writes through it; the permission-rule layer (`evaluate()`) still enforces the rule in
+ * full.
  */
 export declare function resolveFileRuleAbsolutePath(pattern: string, opts: {
     cwd: string;
@@ -86,155 +58,132 @@ export declare function resolveFileRuleAbsolutePath(pattern: string, opts: {
     sourceDir?: string;
 }): string | undefined;
 /**
- * WS-21 fix round 11 ("important" item): the sibling of `resolveFileRuleAbsolutePath` that does NOT
- * drop a genuinely glob-shaped pattern -- it resolves the SAME anchor/root as that function but
- * returns the absolute text WITH any remaining glob characters intact (a redundant trailing `/**` is
- * still stripped first, identically, since `subpath`'s/the recursive-regex-suffix's own "and
- * everything under it" semantics already cover it). `undefined` only for the one case that has no
- * absolute form at all -- an INERT `/`-anchored pattern with no resolvable settings-source root,
- * unchanged from `resolveFileRuleAbsolutePath`'s own posture.
+ * The sibling of `resolveFileRuleAbsolutePath` that KEEPS a glob-shaped pattern: the same anchor and
+ * root, the same stripping of one redundant trailing `/**`, but the absolute text comes back with any
+ * remaining glob characters intact. `undefined` only for an INERT pattern.
  *
- * Exists because claude's own deny-rendering path (`dR`, dump byte 15365699 region) does NOT drop a
- * glob-shaped deny the way `Jm`'s write-ALLOW-only short-circuit does (round 10's own `Jm` finding,
- * `resolveFileRuleAbsolutePath`'s own header) -- a glob-shaped DENY instead becomes an SBPL `(regex
- * ...)` clause (claude's `Li` (dump byte 15365905) / `Rt` (dump byte 15282610)) rather than being silently
- * unenforced by the sandbox layer. Callers check `isGlobShapedFileRulePattern` on the result to
- * decide `subpath` vs a `globToSbplRegexSource`/`recursiveGlobToSbplRegexSource` conversion; ALLOW
- * entries keep using `resolveFileRuleAbsolutePath` (glob-shaped dropped), per the controller's own
- * explicit ruling: "Dropping glob-shaped ALLOW rules stays as it is, because that's stricter."
+ * Used for DENY entries: a glob-shaped deny is not dropped from the sandbox but rendered as an SBPL
+ * `(regex ...)` clause. Callers test the result with `isGlobShapedFileRulePattern` to choose between
+ * `subpath` and `globToSbplRegexSource`/`recursiveGlobToSbplRegexSource`. ALLOW entries keep using
+ * `resolveFileRuleAbsolutePath` (glob-shaped ones dropped), which is the stricter choice.
  */
 export declare function resolveFileRuleAbsoluteGlobText(pattern: string, opts: {
     cwd: string;
     home: string;
     sourceDir?: string;
 }): string | undefined;
+/** True when `text` holds any of `* ? [ ]`. The sandbox deny split classifies with `scanDenyPathGlob` instead (below). */
+export declare function isGlobShapedFileRulePattern(text: string): boolean;
 /**
- * claude's own `Rt` (dump byte 15282610: `e.includes("*")||e.includes("?")||e.includes("[")||e.includes("]")`),
- * confirmed byte-equivalent to this module's own pre-existing glob-char test. Kept as the pure claude
- * primitive; the sandbox DENY split (`splitDenyPathsByGlobShape`/`globDenyEntriesOf`) classifies with
- * `scanDenyPathGlob` below instead (fix round 17, R.3 C-1).
+ * Whether a realpath result for a glob's fixed prefix should be REJECTED (and the prefix kept as
+ * written). Both sides are first tidied with POSIX `normalize` (which keeps a trailing slash).
+ *
+ * The written path stands for one or two acceptable spellings: itself, and, when it lies under
+ * `/tmp/` or `/var/`, the same path under `/private` (macOS's real location for both). A resolution
+ * is trusted only when it is one of those spellings, or sits strictly BELOW one of them, and is not
+ * also shallow (the root, `.`, or a single top-level name) or an ancestor of one of them. Anything
+ * else -- climbing up, moving sideways, landing somewhere unrelated -- is rejected. Plain string
+ * comparisons only; no case folding, no filesystem access.
  */
-export declare function isGlobShapedFileRulePattern(text: string): boolean;
+export declare function isSuspiciousRealpathResolution(original: string, resolved: string): boolean;
 /**
- * Fix round 12 ("Important" item, claude's own `ed`, dump byte 15367994, found in the SAME chunk as
- * `Ch`/`mR`/`pR` below): every ANCESTOR directory of `path`, walking up via `dirname` until reaching
- * `/` or a fixed point -- does NOT include `path` itself, nor `/`. Feeds the ancestor-rename-bypass
- * fix: claude's own write/read sandbox profiles additionally deny `file-write-unlink`/
- * `file-write-create` on every ancestor of a denied path (and of a glob deny's own fixed prefix), so
- * a sandboxed `mv <ancestor> <elsewhere> && <write inside where it used to be> && mv <elsewhere>
- * <ancestor>` cannot rename the ancestor out of the way and back to slip a write past the deny.
+ * Every ANCESTOR directory of `path`, nearest first: `path.dirname` applied repeatedly, starting from
+ * `path`'s parent and stopping before `/` or `.` (neither is included, nor is `path` itself), or when
+ * `dirname` stops changing the value.
+ *
+ * Feeds the sandbox's ancestor-rename fence: the profile also denies unlinking/creating every
+ * ancestor of a denied path (and of a glob deny's fixed prefix), so `mv <ancestor> <elsewhere>`,
+ * a write inside, and a rename back cannot slip a write past the deny.
  */
 export declare function ancestorDirectoriesOf(path: string): string[];
+/**
+ * An absolute glob as a whole-path SBPL regex. The fixed prefix is canonicalised first
+ * (`canonicalizedGlobFixedPrefix`) and spliced back as ESCAPED LITERAL text (`escapeRegexLiteralPath`);
+ * only the rest goes through `globToAnchoredRegex`. The prefix may hold `[`/`]` (it runs through
+ * one-character classes, `scanDenyPathGlob`), which must not become a class again. A glob-free text
+ * (reachable only by a direct call; the deny split sends it to `(subpath …)`) renders as the whole
+ * escaped, canonicalised literal.
+ */
 export declare function globToSbplRegexSource(absoluteGlob: string): string;
 /**
- * claude's own `td` (dump byte 15365977: `Po(e).slice(0,-1)+"(/.*)?$"`) -- `globToSbplRegexSource`'s
- * own whole-string match, WIDENED to also match "the pattern's own match point, optionally followed
- * by `/` and anything deeper" -- the regex equivalent of `subpath`'s own implicit recursive semantics
- * (a plain, non-glob deny already renders as `subpath`, which covers a directory AND everything under
- * it with no extra syntax). claude's own `dR` (the deny-clause builder, same dump region) always uses
- * this recursive form for a glob-shaped deny's OWN base clause -- never the bare `Li`/
- * `globToSbplRegexSource` form, which claude reserves for an ALLOW-carve-out entry nested inside a
- * deny (a feature this port does not carry -- see `resolveFileRuleAbsoluteGlobText`'s own header).
+ * `globToSbplRegexSource`, widened to also match everything BELOW a match: its final `$` is replaced
+ * by `(/.*)?$`. The regex counterpart of `subpath`'s "and everything under it"; a glob-shaped deny's
+ * own clause always uses this form.
  */
 export declare function recursiveGlobToSbplRegexSource(absoluteGlob: string): string;
 /**
- * WS-21 fix round 11: the ONE place a plain `sandbox.filesystem.denyWrite`/`denyRead` string list
- * (settings.json's own, user-typed, and `deriveSandboxPathsFromRules`'s own rule-derived denies,
- * which now may ALSO contain glob-shaped text -- see `resolveFileRuleAbsoluteGlobText`'s own header)
- * gets split by glob-shape before reaching `SeatbeltProfileInput`/`RunCommandOptions`: a non-glob
- * entry stays a plain path (`subpath`, unchanged); a glob-shaped one is converted via
- * `recursiveGlobToSbplRegexSource` (the recursive form, matching `subpath`'s own implicit
- * "and everything under it" semantics and claude's own `dR`, which always uses the recursive form for
- * a deny's own base clause). Called once per caller (tools/impl/bash.ts, tools/impl/monitor.ts) --
- * kept as one shared, tested primitive rather than two hand-copies, per this codebase's own
- * "a second copy would be exactly the kind of drift risk this whole phase's review lens exists to
- * catch" precedent (evaluator.ts's `extractCandidateWritePaths`, verbatim).
+ * The ONE place a plain `sandbox.filesystem.denyWrite`/`denyRead` list (settings.json's own,
+ * user-typed, and `deriveSandboxPathsFromRules`' rule-derived denies, which may be glob-shaped -- see
+ * `resolveFileRuleAbsoluteGlobText`) is split by glob shape before reaching `SeatbeltProfileInput`/
+ * `RunCommandOptions`: a non-glob entry stays a plain path (`subpath`); a glob-shaped one becomes a
+ * `recursiveGlobToSbplRegexSource` regex. Shared by tools/impl/bash.ts and tools/impl/monitor.ts
+ * rather than copied into each.
  *
- * Fix round 12: also returns `globFixedPrefixes` -- for each glob-shaped entry, its OWN canonicalized
- * fixed-prefix directory (claude's own `Rh(u)`, `undefined`/dropped when it resolves to `/`, matching
- * `Ch`'s own `if(p==="/")continue`). Feeds the ancestor-rename-bypass port
- * (`SeatbeltProfileInput.denyWriteGlobFixedPrefixes`/`denyReadGlobFixedPrefixes`, sandbox/profile.ts):
- * the plain `paths` entries need only their OWN ancestors walked (`ed`, `ancestorDirectoriesOf`
- * above) to close the bypass; a glob-shaped deny ALSO needs its fixed prefix walked, and the prefix
- * itself added as a literal deny target (claude's own `Ch` adds both).
+ * Also returns `globFixedPrefixes`: for each glob-shaped entry, its canonicalised fixed-prefix
+ * directory, dropped when it is `/`. The ancestor-rename fence
+ * (`SeatbeltProfileInput.denyWriteGlobFixedPrefixes`/`denyReadGlobFixedPrefixes`) walks a plain
+ * entry's own ancestors (`ancestorDirectoriesOf`); a glob-shaped deny also needs its fixed prefix
+ * walked, and the prefix itself denied as a literal target.
  *
- * Fix round 17 (R.3 C-1): classified by `scanDenyPathGlob`, not by claude's `Rt` alone -- an entry
- * whose only glob syntax is one-character bracket classes (`/x/[[]wip] app/.winter/skills`, a literal
- * path spelled for the glob grammar) lands in `paths` UNESCAPED (`/x/[wip] app/.winter/skills`), and a
- * glob entry's fixed prefix runs through such classes. Winter-only hardening (R.3 C-1); claude's
- * `Rt`/`Li` stop at the first `[` -- see `scanDenyPathGlob`'s own header.
+ * Classified by `scanDenyPathGlob`: an entry whose only glob syntax is one-character bracket classes
+ * (`/x/[[]wip] app/.winter/skills`) lands in `paths` UNESCAPED (`/x/[wip] app/.winter/skills`).
  */
 export declare function splitDenyPathsByGlobShape(paths: readonly string[]): {
     paths: string[];
     regexes: string[];
     globFixedPrefixes: string[];
 };
-/** One glob-shaped deny entry, its recursive SBPL regex source PAIRED with its own fixed-prefix
- * directory -- `splitDenyPathsByGlobShape`'s own `regexes`/`globFixedPrefixes` are two independently
- * FILTERED flat arrays (the latter drops a "/" prefix entirely) with no positional correspondence
- * once any entry is dropped from one but not the other; `fixedPrefix` here is NEVER dropped -- it is
- * always the literal string `"/"` in that case (claude's own `Rh` returns `"/"` too, and `fR`'s own
- * skip/ancestor logic reads that value directly rather than treating "no prefix" as a distinct case). */
+/** One glob-shaped deny entry: its recursive SBPL regex PAIRED with its own fixed-prefix directory.
+ * `splitDenyPathsByGlobShape`'s `regexes`/`globFixedPrefixes` are two independently filtered arrays
+ * (the latter drops a `/` prefix) with no positional correspondence; `fixedPrefix` here is never
+ * dropped -- it is the string `"/"` when there is no deeper prefix. */
 export interface GlobDenyEntry {
     regex: string;
     fixedPrefix: string;
 }
 /**
- * Fix round 13 ("Important" item 1, claude's own `fR`, dump byte 15367091): the PAIRED form
- * `buildReadDenyKeepInPlaceBlock` (sandbox/profile.ts) needs -- see `GlobDenyEntry`'s own header for
- * why `splitDenyPathsByGlobShape`'s own two flat arrays cannot answer this. Scoped to glob-shaped
- * entries only (a plain entry needs no pairing at all -- its own path IS both its recursive-clause
- * anchor and its ancestor-walk root, `buildReadDenyKeepInPlaceBlock` uses `paths` directly for that).
+ * The PAIRED form `buildReadDenyKeepInPlaceBlock` (sandbox/profile.ts) needs -- see `GlobDenyEntry`.
+ * Glob-shaped entries only (a plain entry's own path is both its clause anchor and its ancestor-walk
+ * root), classified by the same `scanDenyPathGlob` as `splitDenyPathsByGlobShape`.
  */
 export declare function globDenyEntriesOf(paths: readonly string[]): GlobDenyEntry[];
 /**
- * `xi` (dump-confirmed): collapses repeated slashes, and specially handles a LEADING BOM so it
- * cannot accidentally trigger gitignore's own `!`/`#` line-directive meaning (negation/comment). A
- * bare leading BOM with no `!`/`#` after it is DELETED outright (empirically verified: the first of
- * the two `.replace()` calls below always consumes a leading BOM, since `^` in its own regex
- * is unconditional and only the FOLLOWING `[!#]?` is optional -- the second `.replace(/^/,
- * "[]")` is therefore unreachable dead code in the pinned binary's own source whenever the
- * input genuinely starts with a BOM, ported here as harmless dead code too rather than "corrected"
- * into a change of behaviour this module was not asked to make). A leading BOM immediately followed
- * by `!` or `#` becomes an escaped literal `!`/`#` (so the directive character survives as TEXT to
- * match, not as a line-level instruction).
+ * Normalises a root-relative pattern before it reaches `ignore()`.
+ *
+ * Every run of slashes collapses to one. Then a leading byte-order mark (U+FEFF) is dealt with, one
+ * level deep, so it can neither vanish in a way that promotes the next character to a gitignore
+ * directive nor linger as an invisible first character:
+ *   - a pattern that is only whitespace (JS `\s`, which includes the BOM), optionally ending in
+ *     exactly `/**`, is left as it is;
+ *   - a BOM followed by `!` or `#` becomes a backslash, so the directive character stays literal;
+ *   - two BOMs become a one-character class holding a BOM (`[<BOM>]`), keeping the second literal;
+ *   - a lone BOM before anything else is dropped.
+ * A pattern with no leading BOM is returned after the slash collapse alone.
  */
 export declare function normalizeFileRulePattern(relativePattern: string): string;
 /**
- * `ki` (dump-confirmed): a pattern ending in `/**` is rewritten before being fed to `ignore()`.
- * - For DENY/ASK (`isAllow: false`): the trailing `/**` is simply dropped (`x/**` -> `x`), and the
- *   result is left UNANCHORED (no leading `/` added) whenever it already has an inner `/`, is not an
- *   allow rule, or already starts with `!`/`#` -- i.e. almost always for deny/ask. This is C-1's own
- *   "`ki` turns a deny `x/**` into an unanchored `x`" finding: the bare `x` then matches at ANY
- *   depth under the `ignore` package's own un-anchoring rule, covering everything under a directory
- *   named `x` anywhere, not merely the literal anchor-relative `x/`.
- * - For ALLOW, when the stripped form has NO inner `/` (a single segment) and does not start with
- *   `!`/`#`: the result is instead explicitly re-anchored (`x/**` -> `/x`), so `allow x/**` stays
- *   scoped to the anchor root rather than becoming an anywhere-match the way the deny/ask case does.
- *   This asymmetry is real and claude's own (not the allow-exact-only asymmetry the controller
- *   retired) -- it survives because it is measured, not invented.
- * - A pattern whose stripped form is empty or all-slashes (`/**`, `//**`) is left as `/**`.
- * - Any pattern that does NOT end in `/**` passes through unchanged.
+ * The trailing-`/**` rewrite, which differs by direction:
+ *   - a pattern NOT ending in `/**` is returned unchanged;
+ *   - if what precedes the `/**` is empty or only slashes, the result is `/**`;
+ *   - otherwise the `/**` is dropped. For DENY/ASK (`isAllow: false`) the rest is returned as it is:
+ *     a single segment `x` then matches a directory `x` at any depth and everything under it. For
+ *     ALLOW, a rest that is a single segment (no `/`) not starting with `!` or `#` gets a leading `/`
+ *     (`x/**` -> `/x`), so the allow stays scoped to the anchor root; a rest with a `/` in it, or
+ *     starting with `!`/`#`, is returned as it is.
  */
 export declare function unanchorTrailingDoubleStar(pattern: string, isAllow: boolean): string;
 export interface FileRuleCandidate<TEntry> {
     entry: TEntry;
-    /** The rule's own specifier text, exactly as authored (the `jOe`/`xi`/`ki` chain runs on this). */
+    /** The rule's own pattern text, exactly as written (anchor resolution, normalisation and the trailing-`/**` rewrite run on this). */
     pattern: string;
-    /** `bl(source)`'s stand-in for a `/`-anchored rule -- see `resolveFileRuleAnchor`'s own header. Absent = every `/`-anchored candidate is inert. */
+    /** The settings-source directory for a `/`-anchored rule -- see `resolveFileRuleAnchor`. Absent = every `/`-anchored candidate is inert. */
     sourceDir?: string | undefined;
 }
 /**
- * Item 2 (fix round 9), REVISED by round 10's own item-3 ruling: a malformed pattern's own compile
- * failure is a THROW out of `matchFileRulesGrouped`, not a direction-aware return value. Round 9
- * tried to resolve the failure INSIDE this function (denyAsk -> the broken group's first entry,
- * allow -> null); round 10's controller ruling is that this is not what claude does -- claude's own
- * `Ma` has no per-group catch at all (only the per-TOOL-CALL one far above it, at `d8t`/`ome`'s own
- * boundary), so ONE throwing group aborts the WHOLE permission check for that call, exactly the same
- * way regardless of which direction (deny/ask/allow) was being evaluated when it happened. This
- * class is what makes that propagation typed rather than "any thrown Error" -- caught exactly once,
- * at `evaluator.ts`'s own `evaluate()` (the "decide this one call" boundary), and turned into the
- * generic fail-closed deny `d8t`'s own hardcoded fallback produces.
+ * A malformed pattern's compile failure is a THROW out of `matchFileRulesGrouped`, the same on every
+ * direction: one broken group aborts the whole permission check for that call. This class makes that
+ * propagation typed; it is caught exactly once, at `evaluator.ts`'s `evaluate()` (the "decide this one
+ * call" boundary), and turned into a generic fail-closed deny.
  */
 export declare class FileRuleCompileError extends Error {
     constructor(message: string, options?: {
@@ -242,140 +191,91 @@ export declare class FileRuleCompileError extends Error {
     });
 }
 /**
- * `ln`+`Ma`, combined into one grouped match: builds ONE `ignore()` instance per anchor ROOT from
- * every candidate (see this module's header for why grouping is load-bearing, not cosmetic), then
- * tests `path` against each root's group in turn, returning the FIRST candidate's own `entry` whose
- * group matched -- `null` when nothing matched anywhere. `behavior` is `"allow"` or `"denyAsk"`,
- * mirroring `matchFileRule`'s own existing direction vocabulary (never allow AND denyAsk on the
- * page a caller passed to `ki`, exactly as `ln`'s `r==="allow"` check is exactly `behavior==="allow"`
- * here too).
- *
- * THROWS `FileRuleCompileError` (fix round 10, item 3) when any consulted anchor root's own
- * candidate patterns fail to compile into a real `ignore()` instance -- never resolved to `null`
- * or a particular entry here; see that class's own header for why, and `evaluator.ts`'s `evaluate()`
- * for the one place it is caught.
+ * Matches `path` against `candidates`, grouped by anchor root:
+ *   - each candidate's anchor is resolved (`resolveFileRuleAnchor`, with its own `sourceDir`); an
+ *     INERT candidate is skipped; a `null` root means `opts.cwd`;
+ *   - its pattern is normalised (`normalizeFileRulePattern`) and then rewritten
+ *     (`unanchorTrailingDoubleStar`, `isAllow` = `behavior === "allow"`);
+ *   - all candidates with the same root go into one case-insensitive `ignore()` instance, in candidate
+ *     order; the roots are kept in the order they first appear;
+ *   - for each root in that order, `path` is made relative to the root (`path.relative`). A relative
+ *     path that is empty, starts with `/`, `./` or `../`, or is exactly `.` or `..` is outside the
+ *     root, and that group is skipped -- the `ignore` package's own rule for an invalid path, so a
+ *     name that merely starts with `..` (`..x/evil.sh`) is inside;
+ *   - the first group that reports the path ignored decides: the result is the entry of the candidate
+ *     whose compiled pattern text the package names as the matching rule (when two candidates in a
+ *     group compiled to the same text, the LATER one); if that text maps to no entry, the next group
+ *     is tried;
+ *   - `null` when no group matches.
+ * THROWS `FileRuleCompileError` when the package fails while testing a group (a malformed pattern
+ * only fails then, on first use, never when it is added). The message names the group's root:
+ * `a file-rule pattern under <JSON-quoted root> failed to compile`, with the package's error as `cause`.
  */
 export declare function matchFileRulesGrouped<TEntry>(candidates: readonly FileRuleCandidate<TEntry>[], path: string, opts: {
     cwd: string;
     home: string;
 }, behavior: "allow" | "denyAsk"): TEntry | null;
 /**
- * `Smt`'s own job (round 5's `QCt`): rewrite a path through its REAL prefix (e.g. `/private/tmp/x`, what
- * `realpathSync` actually returns) back to the commonly-typed TRUSTED alias (`/tmp/x`) -- the
- * direction a real, resolved path needs to go to be compared against a rule an author wrote in the
- * short form. A path with no matching real prefix passes through unchanged.
+ * Rewrites a path that starts with one of macOS's real system directories back to the short symlink
+ * spelling users type: `/private/tmp` -> `/tmp`, `/private/var` -> `/var`, `/private/etc` -> `/etc`,
+ * `/usr/bin` -> `/bin`, `/usr/lib` -> `/lib`, `/usr/sbin` -> `/sbin`, checked in that order. A path
+ * matches a pair when it equals the real directory or starts with it followed by `/`. Each pair is
+ * VERIFIED once per process (`realpathSync(alias) === real`) rather than assumed, and a pair that
+ * does not resolve that way on this machine is never applied. Any other path is returned unchanged.
  */
 export declare function canonicalizeTrustedSymlinkPath(path: string): string;
 /**
- * SV-8 (the router same-view test on the 57e7fef binary): claude's own acceptEdits
- * working-directory boundary check is `sm` (dump-confirmed by content search) -- a plain RELATIVE-
- * PATH PREFIX test, never a compiled glob at all. Winter's own `isWithinBounds` (evaluator.ts) used
- * to reuse the general file-rule matcher with a `"**"` sentinel pattern -- harmless before SV-6/C-1,
- * but once the general matcher started interpreting `[`, `]`, `*` and `\` as glob metacharacters, a
- * cwd or additional-directory root containing any of them (e.g. `[wip] app`) made `"**"` fail to
- * compile the way the caller intended, and acceptEdits asked for every write inside that cwd instead
- * of auto-approving them.
- *
- * This function sidesteps the escaping question SV-8 raises entirely, the same way claude's own `sm`
- * does: a plain path-prefix test never interprets EITHER path as glob syntax, so a root containing a
- * glob-special character needs no escaping here at all -- unlike a real RULE pattern (I-G's own
- * concern), which does.
+ * The acceptEdits working-directory boundary: is `childPath` inside `rootPath`? A plain path-prefix
+ * test, never a glob, so a root containing `[`, `]`, `*` or `\` (a cwd named `[wip] app`) needs no
+ * escaping.
  *
- * Ported: `caseFold` (default `true`, matching `sm`'s own default and I-D's case-insensitivity
- * finding generally) folds BOTH paths before computing the relative path between them; the macOS
- * `/private/var` -> `/var` and `/private/tmp` -> `/tmp` aliasing is real-symlink-aware -- macOS
- * itself maintains both as symlinks to the `/private/...` originals, so a session cwd resolved
- * through one spelling and a root configured with the other name the SAME real directory (this
- * matters in practice: `os.tmpdir()` on macOS resolves through `/private/var/folders/...`, which is
- * exactly the shape every mkdtemp-based fixture in this codebase's own test suite produces). Not
- * ported: `sm`'s own `uncShapeParity` and `skipPrivateAlias` options (Windows-only concerns) and its
- * `Gn`/`Ha` UNC-path checks -- this codebase supports macOS only (CLAUDE.md's own "latest-OS
- * floors" rule).
- *
- * Fix round 6 (R5-2, the re-review against the pinned 2.1.250 dump): ONLY these TWO pairs -- round
- * 5 widened this to the full six-pair `ni()`/`Sl()` map (`/private/etc`, `/usr/bin`, `/usr/lib`,
- * `/usr/sbin` included), which was WRONG for `sm` specifically: content search against the pinned
- * 2.1.250 dump (not the 2.1.280 build round 5 was cited against) found `sm`'s own alias regexes
- * verbatim -- `g=r?/^\/private\/var\//i:/^\/private\/var\//,w=r?/^\/private\/tmp(\/|$)/i:/^\/private\/
- * tmp(\/|$)/` -- exactly these two, unconditionally, never the wider six-pair set. Reverted to match;
- * the six-pair map (`trustedSymlinkEquivalences`/`canonicalizeTrustedSymlinkPath`) stays, but is now
- * used ONLY by the allow-rule retry in evaluator.ts (`cqe`'s own scope, confirmed at the same dump
- * site), never by this function.
+ *   1. On each path (independently), a leading `/private/var/` becomes `/var/`, and a leading
+ *      `/private/tmp` followed by `/` or the end of the path becomes `/tmp` (case-sensitive tests);
+ *      macOS keeps both short spellings as symlinks, and `os.tmpdir()` resolves through
+ *      `/private/var/folders/...`.
+ *   2. With `caseFold` (default `true`), both are then lower-cased.
+ *   3. The answer comes from `path.relative(root, child)`: `""` is inside; `..` or anything starting
+ *      `../` is outside; otherwise inside unless the relative path is absolute.
  */
 export declare function isPathWithinRoot(childPath: string, rootPath: string, opts?: {
     caseFold?: boolean;
 }): boolean;
 /**
- * The traversal fence for a plugin MANIFEST's own declared component paths (`commands`/`agents`/
- * `skills`/`output-styles`/`workflows`/`hooks`).
- *
- * Fix round 6 (R5-1 + a promoted minor, the re-review against the PINNED 2.1.250 dump): claude's own
- * check here is `nV` (dump-confirmed by content search against the pinned dump directly, at the
- * scratchpad path the controller named -- superseding fix round 5's citation of `KGe`/`Aoe` against
- * the INSTALLED 2.1.280 binary, which this round's own ruling says is not the parity authority):
- * `nV(root,entry)` resolves `entry` against `root`, computes `u=path.relative(root,resolved)`, and
- * refuses (`return null`) when `u.startsWith("..")`. Three ways this DIFFERS from `isPathWithinRoot`/
- * `sm` above, all ported exactly rather than reused:
- *   1. CASE-SENSITIVE, always -- `nV`'s own body has no folding call anywhere (confirmed by reading
- *      it in full), unlike `sm`'s own `r?/.../i:/.../ ` case-fold branching. Fix round 5's own
- *      `resolvesWithinPluginRoot` wrongly delegated to `isPathWithinRoot`'s DEFAULT `caseFold:true`,
- *      so on a case-sensitive volume a manifest entry like `../FOO/agents` under a root
- *      `.../plugins/foo` was admitted (folded, `FOO` read as `foo`) where claude's own `nV` (and
- *      this rewrite) refuses it.
- *   2. NAIVE STRING-PREFIX, not segment-aware -- `u.startsWith("..")` is a bare string test, unlike
- *      `sm`'s own `uj` (`/(?:^|[\\/])\.\.(?:[\\/]|$)/`, confirmed by reading ITS full definition too),
- *      which requires a `..` SEGMENT bounded by a separator or a string edge. This means a component
- *      name that merely STARTS WITH the two characters `..` -- e.g. `"..x/agents"`, a real,
- *      non-escaping subdirectory name -- is REFUSED by claude too, not only a genuine `"../"` escape.
- *      Matched here rather than "fixed", per the ruling: claude's own inconsistency between its two
- *      path-safety mechanisms is not this codebase's to resolve by choosing the more correct one.
- *   3. NO trusted-symlink alias mapping at all -- `nV`'s own body never calls anything resembling
- *      `Smt`/`canonicalizeTrustedSymlinkPath`. Moot in practice here regardless, since both operands
- *      below are ALREADY realpath'd before this comparison runs (a real, resolved path from
- *      `/tmp`/`/var` already comes back in its long `/private/...` form either way).
- *
- * DISCLOSED DIVERGENCE FROM THE PINNED 2.1.250, kept as DELIBERATE HARDENING (the controller's own
- * explicit ruling): `nV` itself is PURELY LEXICAL -- 2.1.250 has no symlink-following/realpath step
- * for a plugin component path at all. This function still realpaths both the candidate and the
- * plugin root first (originally ported from the INSTALLED 2.1.280 binary's own `KGe`/`Aoe`, which DID
- * add this in a build newer than the pin), refusing a symlinked override that points outside the
- * plugin where 2.1.250 would load it -- the safe direction, and it matches claude's own newer
- * behaviour. `nV`'s own comparison shape (case-sensitive, naive-prefix, no alias) is then applied to
- * the REALPATH'D forms rather than to the raw ones `nV` itself compares. `resolveRealTarget` (paths.ts)
- * has the graceful "walk up to the nearest existing ancestor" fallback for a candidate that does not
- * exist YET, and rethrows a non-ENOENT failure (ELOOP on a symlink cycle, EACCES, ...), caught here
- * and treated as a refusal rather than letting a malformed manifest entry crash the whole
- * plugin-loading pass.
+ * Whether a path a plugin MANIFEST declares for a component (`commands`/`agents`/`skills`/
+ * `output-styles`/`workflows`/`hooks`) stays inside the plugin:
+ *   1. a candidate containing a backslash is refused;
+ *   2. both the candidate and the plugin root are resolved to their real targets
+ *      (`resolveRealTarget`, which walks up to the nearest existing ancestor for a path that does not
+ *      exist yet); any failure there (a symlink loop, a permission error) refuses;
+ *   3. `path.relative(realRoot, realCandidate)`: `""` is inside; ANY relative path starting with the
+ *      two characters `..` is refused -- `..x/agents` included, a naive string test kept on purpose;
+ *      otherwise inside unless the relative path is absolute.
+ * Case-sensitive, and with no `/tmp`-style alias mapping (both sides are already real paths).
+ * Resolving symlinks first refuses an override that points outside the plugin.
  */
 export declare function resolvesWithinPluginRoot(candidatePath: string, pluginRoot: string): boolean;
 /**
- * Fix round 4 (I-G): a real, resolved filesystem path (e.g. `resolve(winterHome)`) can legitimately
- * contain `[`, `]`, `*` or `\` -- none of which were glob-special under Winter's pre-fix-round-4
- * grammar, but all four are now, since `matchFileRulesGrouped` compiles every pattern through the
- * real `ignore` package. A caller building a rule PATTERN out of a real path (`buildBaselineDenyRules`,
- * engine.ts) must escape these four before interpolating the path into pattern text, or a home
- * directory literally named e.g. `/Users/name[wip]` would have its OWN floor's `[wip]` read back as
- * a character class instead of the four literal characters it names on disk.
+ * A real path (e.g. `resolve(winterHome)`) can contain `[`, `]`, `*` or `\`, all of which are glob
+ * syntax to `matchFileRulesGrouped`. A caller building a rule PATTERN from a real path
+ * (`buildBaselineDenyRules`, engine.ts) escapes it with this first, or a home named
+ * `/Users/name[wip]` would have its own floor's `[wip]` read back as a character class.
+ *
+ *   1. a backslash goes before every `[`, `]`, `*` and `\`;
+ *   2. then the trailing run of whitespace (`\s`), if any, gets a backslash before EACH of its
+ *      characters -- the `ignore` package trims unescaped trailing whitespace off a pattern, so a path
+ *      ending in a space would otherwise lose its own protection.
  *
- * `?` is DELIBERATELY LEFT RAW, per the controller's own ruling: claude's grammar has no working
- * escape for `?` at all (this module's own `unanchorTrailingDoubleStar`/`\?`-quirk sibling
- * documentation) -- an escaped `\?` would require a literal backslash the real path never has, so it
- * would never match the floor's own intended directory at all. A bare `?` in the pattern instead acts
- * as a single-character wildcard, which still MATCHES a real `?` in the path (a wildcard matches
- * anything, including the literal character) -- over-matching by one character class is the safe
- * direction for a DENY floor (WS-07 §3.1's own posture: a deny that reaches slightly too far is a
- * false-negative-avoiding cost, never a hole), where an escape that matches NOTHING would be a hole.
+ * `?` is deliberately left raw: the grammar has no working escape for it (`\?` would demand a literal
+ * backslash the real path never has, so it would match nothing). A raw `?` is a one-character
+ * wildcard, which still matches the real `?` -- over-matching by one character is the safe direction
+ * for a DENY floor, where an escape that matched nothing would be a hole.
  */
 export declare function escapeFileRulePathSegment(path: string): string;
 /**
- * A SINGLE pattern against a SINGLE path -- for a caller that is already iterating rule entries one
- * at a time for a reason unrelated to C-1/SV-7 (e.g. evaluator.ts's own cross-tool
- * `findFileDenyBlockingEdit`, a Winter-invented safety net with no claude analogue: claude's own
- * Write decision never consults `Read(...)` rules at all, so "a Read deny also blocks a Write" is
- * this codebase's own extension, not a ported behaviour). Grouping (this module's own header)
- * therefore does not apply across DIFFERENT callers' unrelated single-pattern checks the way it does
- * within one `matchFileRulesGrouped` call -- this is a thin, no-negation-support convenience, not a
- * second matching engine.
+ * A SINGLE pattern against a SINGLE path -- for a caller already iterating rule entries one at a time
+ * for its own reason (e.g. evaluator.ts's cross-tool `findFileDenyBlockingEdit`, a Winter-only safety
+ * net: a Read deny also blocks a Write). Grouping does not apply across such unrelated single checks;
+ * this is a thin convenience, not a second matching engine.
  */
 export declare function matchesSingleFileRulePattern(pattern: string, path: string, opts: {
     cwd: string;