vigiles 15.1.0 → 15.2.0

package/dist/core/bash-effects.d.ts

@@ -112,6 +112,26 @@ export interface NormalizedLeaf {
      * {@link LeafRedirect}. Empty for a command with no redirection.
      */
     readonly redirects: readonly LeafRedirect[];
+    /**
+     * The directory a chdir WRAPPER moved this leaf into before exec'ing it —
+     * `env -C dir`, `env --chdir=dir`, `sudo -D dir` — or `null` when there was
+     * none. Nested wrappers accumulate (`sudo -D a env -C b cmd` → `a/b`).
+     *
+     * The parser already READ this token in order to skip past it, then threw the
+     * value away — so every relative operand of the wrapped command resolved
+     * against the wrong directory for every consumer. Same shape as the
+     * redirection targets the leaf used to drop: the parser knew, the leaf did
+     * not carry it. `git -C` is deliberately NOT here — `git` is not a wrapper
+     * (it does not exec the rest of its argv as a command).
+     *
+     * ⚠️ ONE LEAF'S OWN WRAPPER, NOT A CWD MODEL. A directory changed by a
+     * PRECEDING statement (`cd x && …`, `pushd`, a subshell) is not reported:
+     * connectors do not survive leaf extraction, and `cd x; cmd` writes into the
+     * OLD directory when the `cd` fails — that is a model with failure semantics,
+     * not a field. A dynamic value (`env -C "$DIR" …`) is not resolvable and the
+     * whole leaf is already unnormalizable in that case.
+     */
+    readonly chdir: string | null;
 }
 /**
  * Extract every simple command as a {@link NormalizedLeaf} — the operation-level

package/dist/core/bash-effects.js

@@ -617,6 +617,38 @@ const WRAPPER_VALUE_OPTS = {
     ]),
     nohup: new Set(),
 };
+/**
+ * Per-wrapper options whose value is a DIRECTORY the wrapper chdirs into before
+ * exec'ing the command. A subset of {@link WRAPPER_VALUE_OPTS}, and keyed by head
+ * for a reason: `-C` is `--chdir` for `env` but `--close-from` (a file
+ * descriptor) for `sudo`, whose chdir is `-D`. One shared set would read a
+ * number as a directory.
+ */
+const WRAPPER_CHDIR_OPTS = {
+    env: new Set(["-C", "--chdir"]),
+    sudo: new Set(["-D", "--chdir"]),
+};
+/**
+ * The directory carried by an option WORD, when that word is one of this
+ * wrapper's chdir options — covering both spellings, since `--chdir=dir` is a
+ * single token that never reaches the separate-value table.
+ */
+function chdirValue(word, next, chdirOpts) {
+    if (chdirOpts.has(word))
+        return next; // `-C dir`, `--chdir dir`
+    const eq = word.indexOf("=");
+    return eq > 0 && chdirOpts.has(word.slice(0, eq))
+        ? word.slice(eq + 1) // `--chdir=dir`
+        : undefined;
+}
+/** Layer a wrapper's chdir onto the one an outer wrapper already applied. */
+function nestChdir(outer, inner) {
+    if (inner === undefined || inner === "")
+        return outer;
+    if (outer === null || inner.startsWith("/") || /^[A-Za-z]:\//.test(inner))
+        return inner;
+    return `${outer.replace(/\/+$/, "")}/${inner}`;
+}
 /** Count of leading NON-option positionals a wrapper consumes before the command (timeout DURATION). */
 const WRAPPER_SKIP_POSITIONALS = {
     timeout: 1,
@@ -640,12 +672,14 @@ function splitAssignmentWord(word) {
  */
 function stripWrappers(argv) {
     const envAssigns = new Map();
+    let chdir = null;
     let cur = argv;
     for (let guard = 0; guard < 8; guard++) {
         const head = cur[0];
         if (head === undefined || !WRAPPER_HEADS.has(head))
             break;
         const valueOpts = WRAPPER_VALUE_OPTS[head] ?? new Set();
+        const chdirOpts = WRAPPER_CHDIR_OPTS[head] ?? new Set();
         let positionalsToSkip = WRAPPER_SKIP_POSITIONALS[head] ?? 0;
         let i = 1; // start after the wrapper head
         let ended = false;
@@ -659,6 +693,11 @@ function stripWrappers(argv) {
                 break;
             }
             if (a.length > 1 && a.startsWith("-")) {
+                // The chdir value is CAPTURED before it is skipped. It was always read
+                // here — reading it is how the loop knows to skip past it — and then
+                // discarded, so every relative operand of the wrapped command resolved
+                // against the wrong directory downstream.
+                chdir = nestChdir(chdir, chdirValue(a, cur[i + 1], chdirOpts));
                 if (valueOpts.has(a))
                     i++; // skip this option's separate value too
                 continue;
@@ -682,7 +721,7 @@ function stripWrappers(argv) {
             break; // no progress → stop
         cur = next;
     }
-    return { argv: cur, envAssigns };
+    return { argv: cur, envAssigns, chdir };
 }
 /**
  * Extract every simple command as a {@link NormalizedLeaf} — the operation-level
@@ -1056,6 +1095,7 @@ function normalizeCallExpr(node, redirs) {
         assigns,
         hasAssign: (...names) => names.some((n) => assigns.has(n)),
         redirects: normalizeRedirects(redirs),
+        chdir: stripped.chdir,
     };
 }
 //# sourceMappingURL=bash-effects.js.map

package/dist/core/hook-program.d.ts

@@ -169,8 +169,33 @@ export interface CommandView {
      *
      * Deletion is a different question and is deliberately NOT reported here —
      * pair with `runs("rm")` if a gate cares about removal too.
+     *
+     * Exactly `writeTargets(prefixes).length > 0`, and implemented as that — reach
+     * for {@link writeTargets} when the gate needs to know WHICH file.
      */
     writesTo(prefixes: readonly string[]): boolean;
+    /**
+     * The write targets of this command that fall under one of the prefixes — the
+     * "WHICH file is written" counterpart to {@link writesTo}. Same two AST-backed
+     * sources (redirection targets + file-writing programs' argv positions), same
+     * denylist bias (an undecidable placement is INCLUDED).
+     *
+     * Spelling is as-written after normalization — quote-unwrapped,
+     * `$HOME`-canonicalized, and resolved against the leaf's own chdir wrapper
+     * (`env -C dir sed -i x` reports `dir/x`) — in order of appearance, exact
+     * duplicates collapsed. Filter by basename/suffix; never re-match the prefixes
+     * by hand, because hand-rolled prefix matching is the exact source of the
+     * trailing-slash, absolute-path and root-blindness defects this vocabulary
+     * exists to remove.
+     *
+     * An empty array ⇔ `writesTo(prefixes) === false`, so the natural
+     * `writeTargets(P).some(pred)` needs no emptiness check to behave correctly.
+     *
+     * `prefixes` is REQUIRED and there is no unfiltered overload: the raw list
+     * does not cross the API boundary, because a consumer holding it has to
+     * re-implement the matching that {@link prefixVerdict} exists to own.
+     */
+    writeTargets(prefixes: readonly string[]): readonly string[];
     /**
      * True iff the command pipes into a BARE shell interpreter (`curl … | sh`,
      * `… | bash -s`) — the remote-code-execution shape. High-signal: a shell leaf

package/dist/core/hook-program.js

@@ -440,6 +440,18 @@ function writeTargetsOf(leaf) {
             return [];
     }
 }
+/**
+ * A write target as it lands on disk, given the chdir wrapper the leaf ran under
+ * (`env -C migratsiya sed -i s/a/b/ papers/x.tex` writes `migratsiya/papers/x.tex`).
+ *
+ * Absolute targets and `~`-rooted ones already name their directory and are
+ * returned untouched. The join itself is {@link resolveRef} rather than a fresh
+ * `a + "/" + b`, because two functions normalising the same string differently is
+ * the defect class this file keeps finding.
+ */
+const underChdir = (target, chdir) => chdir === null || target === "" || target.startsWith("~")
+    ? target
+    : resolveRef(chdir, target);
 /**
  * An AST-backed view of a Bash command.
  *
@@ -457,10 +469,20 @@ function commandView(raw, root) {
     // The operation-normalized leaves carry the redirections (and quote-unwrapped,
     // wrapper-resolved argv) that `writesTo` needs; `leafCommands` cannot see them.
     const normalized = (0, bash_effects_js_1.leafCommandsNormalized)(raw);
-    const writeTargets = normalized.flatMap((leaf) => [
+    const allWriteTargets = normalized.flatMap((leaf) => [
+        // 🔴 A REDIRECTION IS NOT JOINED ONTO THE LEAF'S CHDIR, AND THAT IS THE
+        // SHELL'S RULE, NOT A SHORTCUT. `env -C dir cmd > out.txt` opens `out.txt`
+        // in the SHELL's directory — the redirection happens before `env` ever runs
+        // and `-C` only moves the process `env` execs. Joining here would report a
+        // file the command never writes.
         ...leaf.redirects.flatMap((r) => r.writes && r.target !== null ? [r.target] : []),
-        ...writeTargetsOf(leaf),
+        // The wrapped program's own operands DO resolve against it — see
+        // `NormalizedLeaf.chdir` for why the value was being read and discarded.
+        ...writeTargetsOf(leaf).map((t) => underChdir(t, leaf.chdir)),
     ]);
+    const matchedWriteTargets = (prefixes) => [
+        ...new Set(allWriteTargets.filter((t) => prefixes.some((p) => matchesPrefix(prefixVerdict(t, p, root), "match")))),
+    ];
     return {
         raw,
         runs(program, opts) {
@@ -501,7 +523,13 @@ function commandView(raw, root) {
             ? [tok, tok.slice(tok.indexOf("=") + 1)]
             : [tok])
             .some((tok) => prefixes.some((p) => matchesPrefix(prefixVerdict(tok, p, root), "match"))),
-        writesTo: (prefixes) => writeTargets.some((t) => prefixes.some((p) => matchesPrefix(prefixVerdict(t, p, root), "match"))),
+        // DERIVED, not a second implementation of the same rule. The boolean stays
+        // because `writesTo(secrets) ? deny() : allow()` is the common gate shape,
+        // but it is a PROJECTION of the list — one code path, so the two can never
+        // drift the way `runs()` and `writesTo` did (one reads raw leaves, the other
+        // normalized ones, and a gate built on both had a silent hole).
+        writesTo: (prefixes) => matchedWriteTargets(prefixes).length > 0,
+        writeTargets: matchedWriteTargets,
         pipesToShell: () => leaves.some(isBareShellLeaf),
     };
 }
@@ -1157,6 +1185,48 @@ function runHookProgram(hook, event, ctx = {}, root = event.cwd) {
 function isAbsoluteRef(ref) {
     return ref.startsWith("/") || /^[A-Za-z]:\//.test(ref);
 }
+/**
+ * Does this ROOT name a Windows filesystem? One predicate, because the two
+ * questions that ask it — how many segments `..` may not pop through, and
+ * whether a `//` leader is a share or a stutter — must never disagree about the
+ * same root. `//x` is caught by the second arm: too short to be a share, but
+ * still not something to read as POSIX.
+ */
+const namesWindowsFs = (root) => WINDOWS_ROOT.test(root) || root.startsWith("//");
+/**
+ * How many leading segments of a resolved path ARE its root — the floor a `..`
+ * must not pop through. `0` on POSIX, `1` for a drive (`C:`), `2` for a UNC
+ * share (`//server/share`), and 2/4 for the `//?/` spellings of those two.
+ *
+ * 🔴 A `//` LEADER IS THE ROOT'S ANSWER, NEVER THE OPERAND'S — the round-37
+ * lesson at a third site (after the case fold in {@link caseInsensitiveFs} and
+ * the UNC leader in {@link resolveRef}). Read from the string alone,
+ * `//repo/a/../src/x.ts` looks share-rooted, so a count taken off the operand
+ * would guard `repo/a` and stop `..` collapsing at all — under a POSIX root that
+ * doubled slash is a stutter, not a share. The `//` forms are therefore gated on
+ * the root, exactly as the leader is.
+ *
+ * ⚠️ A DRIVE LETTER IS THE ONE THING THAT NAMES A WINDOWS FILESYSTEM BY ITSELF,
+ * and that is not a second rule — {@link isAtOrUnder} already says it about a
+ * base (`WINDOWS_ROOT.test(rawBase)`), because `C:/x` has no POSIX reading the
+ * way `//x` does. It earns its place at a real call site rather than in the
+ * abstract: {@link absoluteSpelling} resolves a ROOTLESS absolute path against
+ * the literal `"/"`, so gating the drive on the root too would leave
+ * `C:/../repo/x` still losing its drive right there — the sibling call site a
+ * fix written only where the defect was found would have missed.
+ *
+ * The count itself is read off {@link WINDOWS_ROOT} rather than re-derived,
+ * because that regex already IS this file's single answer to "what is a Windows
+ * root"; the two forms and the `//?/` spelling are enumerated there, once.
+ */
+const rootSegmentCount = (joined, root) => {
+    const matched = WINDOWS_ROOT.exec(joined)?.[0];
+    if (matched === undefined)
+        return 0; // POSIX, or relative: no root inside `out`
+    if (/^[/\\]/.test(matched) && !namesWindowsFs(root))
+        return 0; // stutter, not share
+    return matched.split(/[/\\]+/).filter((s) => s !== "").length;
+};
 /**
  * Resolve a path reference against a root, without node:path (core stays
  * dependency-free). Mirrors `resolve(root, ref)`: an absolute ref wins, a
@@ -1178,12 +1248,27 @@ function resolveRef(root, ref) {
     const joined = isAbsoluteRef(r)
         ? r
         : `${slashes(root).replace(/\/+$/, "")}/${r}`;
+    // 🔴 `..` CLAMPS AT THE ROOT, IT DOES NOT EAT IT. A real filesystem holds
+    // still at the top: on Windows `C:/..` is `C:/`, on POSIX `/..` is `/`. An
+    // unconditional `out.pop()` popped the DRIVE LETTER out of `C:/../repo/src/x`,
+    // leaving the relative-looking `repo/src/x` — which then failed to resolve
+    // against `C:/repo`, so a gate stopped recognising a path naming its own
+    // repository. A UNC share went one worse: two `..` ate `share` and then
+    // `server`.
+    //
+    // ⚠️ POSIX WAS ALREADY CORRECT BY ACCIDENT, and the accident is worth naming
+    // so nobody "simplifies" it back: its leader `/` is held OUTSIDE `out` (see
+    // the leader below), so popping an empty array is already the clamp. The
+    // Windows forms broke precisely because their root lives INSIDE `out` —
+    // exactly the segments the loop treats as ordinary directories.
+    const floor = rootSegmentCount(joined, root);
     const out = [];
     for (const seg of joined.split("/")) {
         if (seg === "" || seg === ".")
             continue;
         if (seg === "..") {
-            out.pop();
+            if (out.length > floor)
+                out.pop();
             continue;
         }
         out.push(seg);
@@ -1201,8 +1286,7 @@ function resolveRef(root, ref) {
     // stutter, so preserving the pair unconditionally made it stop resolving
     // against a POSIX root and an allowlist gate denied a valid edit. Semantics
     // belong to the filesystem, and only the root knows which one that is.
-    const unc = joined.startsWith("//") &&
-        (WINDOWS_ROOT.test(root) || root.startsWith("//"));
+    const unc = joined.startsWith("//") && namesWindowsFs(root);
     const leader = unc ? "//" : joined.startsWith("/") ? "/" : "";
     return leader + out.join("/");
 }

package/dist/core/sidecar.d.ts

@@ -30,6 +30,22 @@ export declare function computePerFileHashes(inputFiles: string[], basePath: str
  * Recurses so that nested targets (e.g. `.github/copilot-instructions.md`,
  * which lives at `.vigiles/.github/copilot-instructions.md.inputs.json`)
  * are not silently skipped.
+ *
+ * 🔴 A DIRECTORY SYMLINK IS NOT DESCENDED INTO — this walk classified entries
+ * with a bare `statSync().isDirectory()`, which FOLLOWS a link, so a link inside
+ * `.vigiles/` pointing at a directory OUTSIDE it was walked (manifests from a
+ * foreign tree entering the audit under reconstructed target names), and a cycle
+ * — `.vigiles/loop -> .vigiles`, or a link to any ancestor — re-walked the same
+ * tree once per lap. Measured 2026-08-13 by reverting this call: ONE manifest was
+ * reported FORTY-ONE times, as `Real.md`, `loop/Real.md`, `loop/loop/Real.md` …
+ * until the kernel's link limit stopped it. Unlike the loader's walk it did not
+ * throw, and that is not a mitigation: the `catch` below swallowed the `ELOOP` and
+ * turned a crash into a silently multiplied audit. Third instance of the class in
+ * this repo; the decision is {@link entryOf} in `fs-walk.ts`, which carries the
+ * full rationale: a symlinked FILE is still read (it cannot recurse, and a
+ * manifest reached through one is a real manifest), termination is by
+ * construction rather than a visited-set, and an unreadable entry is `"skip"`
+ * rather than a throw — which is exactly what the `try`/`continue` here did.
  */
 export declare function iterateSidecars(basePath: string, fn: (target: string, manifest: SidecarManifest) => void): void;
 //# sourceMappingURL=sidecar.d.ts.map

package/dist/core/sidecar.js

@@ -18,6 +18,7 @@ exports.computePerFileHashes = computePerFileHashes;
 exports.iterateSidecars = iterateSidecars;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const fs_walk_js_1 = require("../fs-walk.js");
 const hash_js_1 = require("./hash.js");
 const SIDECAR_ROOT = ".vigiles";
 const MANIFEST_SUFFIX = ".inputs.json";
@@ -60,6 +61,22 @@ function computePerFileHashes(inputFiles, basePath) {
  * Recurses so that nested targets (e.g. `.github/copilot-instructions.md`,
  * which lives at `.vigiles/.github/copilot-instructions.md.inputs.json`)
  * are not silently skipped.
+ *
+ * 🔴 A DIRECTORY SYMLINK IS NOT DESCENDED INTO — this walk classified entries
+ * with a bare `statSync().isDirectory()`, which FOLLOWS a link, so a link inside
+ * `.vigiles/` pointing at a directory OUTSIDE it was walked (manifests from a
+ * foreign tree entering the audit under reconstructed target names), and a cycle
+ * — `.vigiles/loop -> .vigiles`, or a link to any ancestor — re-walked the same
+ * tree once per lap. Measured 2026-08-13 by reverting this call: ONE manifest was
+ * reported FORTY-ONE times, as `Real.md`, `loop/Real.md`, `loop/loop/Real.md` …
+ * until the kernel's link limit stopped it. Unlike the loader's walk it did not
+ * throw, and that is not a mitigation: the `catch` below swallowed the `ELOOP` and
+ * turned a crash into a silently multiplied audit. Third instance of the class in
+ * this repo; the decision is {@link entryOf} in `fs-walk.ts`, which carries the
+ * full rationale: a symlinked FILE is still read (it cannot recurse, and a
+ * manifest reached through one is a real manifest), termination is by
+ * construction rather than a visited-set, and an unreadable entry is `"skip"`
+ * rather than a throw — which is exactly what the `try`/`continue` here did.
  */
 function iterateSidecars(basePath, fn) {
     const root = (0, node_path_1.resolve)(basePath, SIDECAR_ROOT);
@@ -77,17 +94,15 @@ function walk(dir, root, basePath, fn) {
     }
     for (const entry of entries) {
         const fullPath = (0, node_path_1.resolve)(dir, entry);
-        let isDir;
-        try {
-            isDir = (0, node_fs_1.statSync)(fullPath).isDirectory();
-        }
-        catch {
-            continue;
-        }
-        if (isDir) {
+        const { kind } = (0, fs_walk_js_1.entryOf)(fullPath);
+        if (kind === "dir") {
             walk(fullPath, root, basePath, fn);
             continue;
         }
+        // "skip" covers what the old bare `statSync` handled by throwing (a dangling
+        // link, an unreadable entry) AND the symlinked directory it silently followed.
+        if (kind === "skip")
+            continue;
         if (!entry.endsWith(MANIFEST_SUFFIX))
             continue;
         // Reconstruct the target name from the path relative to .vigiles/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "15.1.0",
+  "version": "15.2.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",