vigiles 15.1.0 → 15.2.1

package/dist/adapters/claude-code/agent-result.d.ts

@@ -17,7 +17,7 @@
  * third `malformed` track for a worker that didn't honor its contract (no block,
  * bad JSON, or a shape that doesn't match the declared schema).
  */
-import type { OutputContract } from "../../core/spec.js";
+import type { OutputContract, OutputFieldType } from "../../core/spec.js";
 /** The outcome of parsing a worker's result block. */
 export type ParsedAgentResult<S = Record<string, unknown>, E = Record<string, unknown>> = {
     readonly kind: "ok";
@@ -29,6 +29,15 @@ export type ParsedAgentResult<S = Record<string, unknown>, E = Record<string, un
     readonly kind: "malformed";
     readonly reason: string;
 };
+/**
+ * Validate a parsed object against a contract track; null when it conforms.
+ *
+ * Exported because the EXPERIMENTAL emit channel (`src/experimental-emit.ts`)
+ * validates the SAME `OutputContract` on a different delivery. One contract, two
+ * deliveries, one validator — a second copy would drift, and the two rails
+ * disagreeing about what satisfies a contract is the worst outcome available.
+ */
+export declare function shapeError(obj: Record<string, unknown>, shape: Readonly<Record<string, OutputFieldType>>): string | null;
 /**
  * Parse the last `vigiles:ok` / `vigiles:err` block from a worker's output.
  *

package/dist/adapters/claude-code/agent-result.js

@@ -19,10 +19,15 @@
  * bad JSON, or a shape that doesn't match the declared schema).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.shapeError = shapeError;
 exports.parseAgentResult = parseAgentResult;
 // Capture every vigiles:ok / vigiles:err fenced block; the LAST one is the
 // worker's final answer (earlier ones may be illustrative in its reasoning).
-const BLOCK_RE = /```vigiles:(ok|err)[ \t]*\r?\n([\s\S]*?)```/g;
+// The CLOSING fence must own its line: a ``` inside a JSON string value sits
+// mid-line, so it no longer terminates the block (measured 2026-08-13 — a
+// contract field carrying a code snippet made every such answer `malformed`
+// even though the model's JSON was valid).
+const BLOCK_RE = /^[ \t]*```vigiles:(ok|err)[ \t]*\r?\n([\s\S]*?)\r?\n^[ \t]*```[ \t]*$/gm;
 /** Does a runtime value match a declared field type? */
 function fieldMatches(value, type) {
     switch (type) {
@@ -36,7 +41,14 @@ function fieldMatches(value, type) {
             return Array.isArray(value) && value.every((v) => typeof v === "string");
     }
 }
-/** Validate a parsed object against a contract track; null when it conforms. */
+/**
+ * Validate a parsed object against a contract track; null when it conforms.
+ *
+ * Exported because the EXPERIMENTAL emit channel (`src/experimental-emit.ts`)
+ * validates the SAME `OutputContract` on a different delivery. One contract, two
+ * deliveries, one validator — a second copy would drift, and the two rails
+ * disagreeing about what satisfies a contract is the worst outcome available.
+ */
 function shapeError(obj, shape) {
     for (const [field, type] of Object.entries(shape)) {
         if (!(field in obj))

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/dist/eval.js

@@ -981,7 +981,23 @@ async function executeTrial(spec, arm, trialIndex, runner, cfg) {
 }
 // A signal in the captured streams that the model call was rate-limited /
 // overloaded — worth a backoff + retry rather than counting as a real sample.
-const RATE_LIMIT_RE = /rate.?limit|\b429\b|overloaded|too many requests/i;
+//
+// 🔴 The separator is `[ -]?`, NOT `.?`, and that is load-bearing. Claude Code's
+// stream-json emits an INFORMATIONAL `{"type":"rate_limit_event","rate_limit_info":
+// {"status":"allowed",…}}` line on EVERY run (captured verbatim in
+// examples/experimental-emit/records/rate-limit-event.json). `rate.?limit` matched
+// `rate_limit_event`, because `.` matches `_` — so every trial looked rate-limited,
+// every trial was retried `retries + 1` = 4 times, and only the LAST attempt's cost
+// reached `maxCostUsd`. Measured 2026-08-13: 2 trials → 8 model runs, a budget cap
+// of $0.60 crossed at roughly $3, and the run reported one trial. `[ -]?` cannot
+// match `_`, so the telemetry line is no longer a match; a REAL limit still is,
+// because the API reports it as `rate_limit_error` / 429 / "overloaded".
+//
+// Known boundary, stated rather than hidden: a `rate_limit_event` whose `status`
+// is a rejection is no longer a match either. It never was one on its merits — the
+// old pattern fired on the event's NAME regardless of status, so status-aware
+// detection has never existed here.
+const RATE_LIMIT_RE = /rate[ -]?limit(?:ed)?\b|rate_limit_error|\b429\b|overloaded|too many requests/i;
 /** Whether a run's captured output looks like a rate-limit / overload. Pure. */
 function isRateLimited(out) {
     return RATE_LIMIT_RE.test(`${out.stderr ?? ""}\n${out.stdout}`);

package/dist/experimental-emit.d.ts

@@ -0,0 +1,163 @@
+/**
+ * ⚠️ EXPERIMENTAL — the EMIT delivery for a typed result: the skill CALLS a tool
+ * carrying its outcome instead of ENDING its turn with a fenced block.
+ *
+ * ## Why this exists
+ *
+ * A typed `output` (an `OutputContract`) is valid only on a forked skill: compile
+ * hard-errors `output-without-fork` on the other 31, because an inline skill is
+ * spliced into the conversation, has no call→return boundary, and therefore has
+ * no return value to type (`research/spec-syntax-and-railway-scope.md`).
+ *
+ * A TOOL CALL needs no return boundary. The skill does not return the structure —
+ * it EMITS it, mid-conversation, and the call lands in `Trace.toolCalls`. So the
+ * objection that grounds the exclusion does not apply to this delivery. Same
+ * `OutputContract`; a different way of getting it out.
+ *
+ * ## What is UNPROVEN (why the `experimental_` prefix is on every runtime export)
+ *
+ *  1. **N=8, one skill, one model.** Measured 2026-08-13 against `paper-status`
+ *     (unforked; `allowed-tools: Bash, Read, Grep, Glob`) on sonnet: 8 runs, 8
+ *     emits, all on the `ok` track, all parsing against the contract, none
+ *     repeated. That answers "does it land at all" and nothing about the rate —
+ *     8 of 8 bounds the true failure rate at about 31%, which is not evidence of
+ *     reliability. Raw arguments + the free re-scorer:
+ *     `examples/experimental-emit/`.
+ *  2. **Nobody depends on it.** Neither `compileSkill` nor `compileAgent` emits
+ *     this instruction; the caller pastes `.instruction` into a skill body and
+ *     serves `.tool` from their own MCP server by hand. There is no compile-time
+ *     path, so no skill in any corpus is typed by it yet.
+ *  3. **The transport is not part of the contract.** MCP is how the tool reached
+ *     the model in the measurement. Whether a plugin can hand the model a tool
+ *     WITHOUT a separate server process is untested, and the answer changes what
+ *     this surface should look like.
+ *  4. **The runtime does not enforce `required`.** Measured: Claude Code accepted a
+ *     call omitting three declared-required fields (raw proof in `mine`,
+ *     `vigiles/repro/output-contract-2026-08-13/mcp-arm/schema-probe-emitted.jsonl`).
+ *     `inputSchema` is DESCRIPTION for the model, not a runtime gate — which is
+ *     exactly why `experimental_parseEmitted` re-validates on the receiving side
+ *     and why "the API validates it for you" must not be claimed.
+ *
+ * ## What would have to be true to drop the prefix
+ *
+ *  - A rate, not an existence proof: ≥30 trials across ≥2 unforked skills and ≥2
+ *    models, with the emit-landing rate reported and its failure modes named.
+ *  - One consumer inside vigiles that compiles the instruction from the spec, so
+ *    the tool name and the shape cannot drift apart by hand.
+ *  - A measured answer to (3) — plugin-served tool vs external MCP server — since
+ *    an in-process tool would remove the standing-up cost this surface assumes.
+ *
+ * Until then: not covered by the stability guarantee, may change or be removed
+ * without a major bump. See `docs/../STABILITY.md` and `src/experimental.ts`.
+ *
+ * @experimental
+ * @module
+ */
+import type { OutputContract } from "./core/spec.js";
+import type { ToolCall } from "./core/harness-driver.js";
+import { type ParsedAgentResult } from "./adapters/claude-code/agent-result.js";
+/** A JSON-Schema fragment for one declared field. */
+export type EmitFieldSchema = {
+    readonly type: "string";
+} | {
+    readonly type: "number";
+} | {
+    readonly type: "boolean";
+} | {
+    readonly type: "array";
+    readonly items: {
+        readonly type: "string";
+    };
+};
+/** The `track` discriminator's schema — the only enum this surface emits. */
+export interface EmitTrackSchema {
+    readonly type: "string";
+    readonly enum: readonly ["ok", "err"];
+}
+/** Anything that can sit under `properties`: a field, the discriminator, a track. */
+export type EmitPropertySchema = EmitFieldSchema | EmitTrackSchema | EmitObjectSchema;
+/** A JSON-Schema object node — one track's payload, or the whole argument. */
+export interface EmitObjectSchema {
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, EmitPropertySchema>>;
+    readonly required: readonly string[];
+    readonly additionalProperties: false;
+}
+/** An MCP tool definition, in the shape a `tools/list` response carries. */
+export interface EmitToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: EmitObjectSchema;
+}
+/** What `experimental_emitTool` hands back: the tool, and the prose that asks for it. */
+export interface ExperimentalEmitTool {
+    /** Serve this from your MCP server's `tools/list`. */
+    readonly tool: EmitToolDefinition;
+    /**
+     * Markdown fragment for the skill body. The SAME contract rendered for the
+     * model — kept next to the schema so the two cannot drift when hand-wired.
+     */
+    readonly instruction: string;
+}
+/**
+ * ⚠️ EXPERIMENTAL. Derive an emit TOOL from an `OutputContract` — the same
+ * contract the fork rail renders as a `vigiles:ok` / `vigiles:err` fenced block.
+ *
+ *   const emit = experimental_emitTool(contract);
+ *   // emit.tool        → serve from your MCP server
+ *   // emit.instruction → paste into the (unforked) skill's body
+ *
+ * The two tracks are NESTED (`{ track, ok? , err? }`), not flattened into one bag
+ * of fields. That is deliberate: a flat union cannot say which fields are required
+ * on which track, so "success fields mixed with error fields" would be a
+ * well-formed call. Nested, it is not expressible.
+ *
+ * 🔴 `required` in the returned schema is DESCRIPTION, not enforcement — measured,
+ * see the module header (4). Validate what arrives with
+ * `experimental_parseEmitted`.
+ *
+ * @experimental
+ */
+export declare function experimental_emitTool(contract: OutputContract, options?: {
+    readonly name?: string;
+}): ExperimentalEmitTool;
+/**
+ * ⚠️ EXPERIMENTAL. Read the emitted result out of a run's tool calls, validated
+ * against the contract. Pure — returns the same `ParsedAgentResult` vocabulary the
+ * fenced rail's `parseAgentResult` returns, so an eval `measure` can use it as a
+ * metric and the assertion below can wrap it, without one dual-purpose function.
+ *
+ * Accepts `Trace["toolCalls"]`, `SubagentTrace["toolCalls"]` or an eval
+ * `ctx.toolCalls`. Names are matched bare (`emit_result`) or MCP-prefixed
+ * (`mcp__<server>__emit_result`).
+ *
+ * Differs from the fenced rail in ONE deliberate way: **more than one call is
+ * `malformed`, not last-one-wins.** The fenced parser takes the LAST block because
+ * an earlier block may be illustrative reasoning; a tool call is an action, never
+ * illustrative, so "exactly once" is checkable here and is not checkable there.
+ *
+ * @experimental
+ */
+export declare function experimental_parseEmitted(toolCalls: readonly ToolCall[], contract: OutputContract, options?: {
+    readonly name?: string;
+}): ParsedAgentResult;
+/**
+ * ⚠️ EXPERIMENTAL. Assert the run emitted a SUCCESS result, and return its value —
+ * the emit-channel counterpart of `assertAgentOk`, for a skill that has no return
+ * value to assert on.
+ *
+ * Throws on a missing emit, a repeated emit, an error track, or a payload that
+ * does not match the contract. The failure message names every tool the run DID
+ * call, because "the skill never emitted" and "the skill emitted the wrong shape"
+ * are different bugs and the tool list separates them at a glance.
+ *
+ * The error track is reachable through `experimental_parseEmitted`; a matching
+ * `…EmittedErr` is deliberately NOT shipped while the surface is this young —
+ * three exports is the whole prototype.
+ *
+ * @experimental
+ */
+export declare function experimental_assertEmittedOk(toolCalls: readonly ToolCall[], contract: OutputContract, options?: {
+    readonly name?: string;
+}): Record<string, unknown>;
+//# sourceMappingURL=experimental-emit.d.ts.map

package/dist/experimental-emit.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * ⚠️ EXPERIMENTAL — the EMIT delivery for a typed result: the skill CALLS a tool
+ * carrying its outcome instead of ENDING its turn with a fenced block.
+ *
+ * ## Why this exists
+ *
+ * A typed `output` (an `OutputContract`) is valid only on a forked skill: compile
+ * hard-errors `output-without-fork` on the other 31, because an inline skill is
+ * spliced into the conversation, has no call→return boundary, and therefore has
+ * no return value to type (`research/spec-syntax-and-railway-scope.md`).
+ *
+ * A TOOL CALL needs no return boundary. The skill does not return the structure —
+ * it EMITS it, mid-conversation, and the call lands in `Trace.toolCalls`. So the
+ * objection that grounds the exclusion does not apply to this delivery. Same
+ * `OutputContract`; a different way of getting it out.
+ *
+ * ## What is UNPROVEN (why the `experimental_` prefix is on every runtime export)
+ *
+ *  1. **N=8, one skill, one model.** Measured 2026-08-13 against `paper-status`
+ *     (unforked; `allowed-tools: Bash, Read, Grep, Glob`) on sonnet: 8 runs, 8
+ *     emits, all on the `ok` track, all parsing against the contract, none
+ *     repeated. That answers "does it land at all" and nothing about the rate —
+ *     8 of 8 bounds the true failure rate at about 31%, which is not evidence of
+ *     reliability. Raw arguments + the free re-scorer:
+ *     `examples/experimental-emit/`.
+ *  2. **Nobody depends on it.** Neither `compileSkill` nor `compileAgent` emits
+ *     this instruction; the caller pastes `.instruction` into a skill body and
+ *     serves `.tool` from their own MCP server by hand. There is no compile-time
+ *     path, so no skill in any corpus is typed by it yet.
+ *  3. **The transport is not part of the contract.** MCP is how the tool reached
+ *     the model in the measurement. Whether a plugin can hand the model a tool
+ *     WITHOUT a separate server process is untested, and the answer changes what
+ *     this surface should look like.
+ *  4. **The runtime does not enforce `required`.** Measured: Claude Code accepted a
+ *     call omitting three declared-required fields (raw proof in `mine`,
+ *     `vigiles/repro/output-contract-2026-08-13/mcp-arm/schema-probe-emitted.jsonl`).
+ *     `inputSchema` is DESCRIPTION for the model, not a runtime gate — which is
+ *     exactly why `experimental_parseEmitted` re-validates on the receiving side
+ *     and why "the API validates it for you" must not be claimed.
+ *
+ * ## What would have to be true to drop the prefix
+ *
+ *  - A rate, not an existence proof: ≥30 trials across ≥2 unforked skills and ≥2
+ *    models, with the emit-landing rate reported and its failure modes named.
+ *  - One consumer inside vigiles that compiles the instruction from the spec, so
+ *    the tool name and the shape cannot drift apart by hand.
+ *  - A measured answer to (3) — plugin-served tool vs external MCP server — since
+ *    an in-process tool would remove the standing-up cost this surface assumes.
+ *
+ * Until then: not covered by the stability guarantee, may change or be removed
+ * without a major bump. See `docs/../STABILITY.md` and `src/experimental.ts`.
+ *
+ * @experimental
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.experimental_emitTool = experimental_emitTool;
+exports.experimental_parseEmitted = experimental_parseEmitted;
+exports.experimental_assertEmittedOk = experimental_assertEmittedOk;
+const agent_result_js_1 = require("./adapters/claude-code/agent-result.js");
+/** The default tool name, when `options.name` is not given. */
+const DEFAULT_EMIT_TOOL = "emit_result";
+function fieldSchema(type) {
+    switch (type) {
+        case "string":
+            return { type: "string" };
+        case "number":
+            return { type: "number" };
+        case "boolean":
+            return { type: "boolean" };
+        case "string[]":
+            return { type: "array", items: { type: "string" } };
+    }
+}
+function trackSchema(shape) {
+    const properties = {};
+    for (const [field, type] of Object.entries(shape)) {
+        properties[field] = fieldSchema(type);
+    }
+    return {
+        type: "object",
+        properties,
+        required: Object.keys(shape),
+        additionalProperties: false,
+    };
+}
+/** Render a declared shape the way the fenced contract renders it, for the prose half. */
+function renderShape(shape) {
+    const fields = Object.entries(shape)
+        .map(([k, t]) => `"${k}": ${t}`)
+        .join(", ");
+    return fields ? `{ ${fields} }` : "{}";
+}
+/**
+ * ⚠️ EXPERIMENTAL. Derive an emit TOOL from an `OutputContract` — the same
+ * contract the fork rail renders as a `vigiles:ok` / `vigiles:err` fenced block.
+ *
+ *   const emit = experimental_emitTool(contract);
+ *   // emit.tool        → serve from your MCP server
+ *   // emit.instruction → paste into the (unforked) skill's body
+ *
+ * The two tracks are NESTED (`{ track, ok? , err? }`), not flattened into one bag
+ * of fields. That is deliberate: a flat union cannot say which fields are required
+ * on which track, so "success fields mixed with error fields" would be a
+ * well-formed call. Nested, it is not expressible.
+ *
+ * 🔴 `required` in the returned schema is DESCRIPTION, not enforcement — measured,
+ * see the module header (4). Validate what arrives with
+ * `experimental_parseEmitted`.
+ *
+ * @experimental
+ */
+function experimental_emitTool(contract, options = {}) {
+    const name = options.name ?? DEFAULT_EMIT_TOOL;
+    const tool = {
+        name,
+        description: "Emit this task's structured result. Call this exactly once. Set " +
+            '`track` to "ok" and fill `ok` on success, or "err" and fill `err` on ' +
+            "failure. Do not call it twice and do not fill both tracks.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                track: { type: "string", enum: ["ok", "err"] },
+                ok: trackSchema(contract.ok),
+                err: trackSchema(contract.err),
+            },
+            required: ["track"],
+            additionalProperties: false,
+        },
+    };
+    const instruction = [
+        "## Output contract",
+        "",
+        `Emit your result by calling the \`${name}\` tool exactly once, at the point`,
+        "you have the answer. Do not print it as a code block; the call IS the result.",
+        "",
+        `On success: \`track: "ok"\`, with \`ok\` =`,
+        "",
+        "```json",
+        renderShape(contract.ok),
+        "```",
+        "",
+        `On failure: \`track: "err"\`, with \`err\` =`,
+        "",
+        "```json",
+        renderShape(contract.err),
+        "```",
+    ].join("\n");
+    return { tool, instruction };
+}
+/** Does this observed tool name refer to `name` (bare, or MCP-prefixed)? */
+function isEmitCall(observed, name) {
+    return observed === name || observed.endsWith(`__${name}`);
+}
+/**
+ * ⚠️ EXPERIMENTAL. Read the emitted result out of a run's tool calls, validated
+ * against the contract. Pure — returns the same `ParsedAgentResult` vocabulary the
+ * fenced rail's `parseAgentResult` returns, so an eval `measure` can use it as a
+ * metric and the assertion below can wrap it, without one dual-purpose function.
+ *
+ * Accepts `Trace["toolCalls"]`, `SubagentTrace["toolCalls"]` or an eval
+ * `ctx.toolCalls`. Names are matched bare (`emit_result`) or MCP-prefixed
+ * (`mcp__<server>__emit_result`).
+ *
+ * Differs from the fenced rail in ONE deliberate way: **more than one call is
+ * `malformed`, not last-one-wins.** The fenced parser takes the LAST block because
+ * an earlier block may be illustrative reasoning; a tool call is an action, never
+ * illustrative, so "exactly once" is checkable here and is not checkable there.
+ *
+ * @experimental
+ */
+function experimental_parseEmitted(toolCalls, contract, options = {}) {
+    const name = options.name ?? DEFAULT_EMIT_TOOL;
+    const calls = toolCalls.filter((c) => isEmitCall(c.name, name));
+    if (calls.length === 0) {
+        return { kind: "malformed", reason: `no \`${name}\` tool call in the run` };
+    }
+    if (calls.length > 1) {
+        return {
+            kind: "malformed",
+            reason: `\`${name}\` was called ${String(calls.length)} times; the contract is exactly once`,
+        };
+    }
+    const input = calls[0].input;
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return {
+            kind: "malformed",
+            reason: `\`${name}\` call carried no object argument`,
+        };
+    }
+    const args = input;
+    const track = args.track;
+    if (track !== "ok" && track !== "err") {
+        return {
+            kind: "malformed",
+            reason: `\`${name}\` call has no \`track\` of "ok" or "err"`,
+        };
+    }
+    const payload = args[track];
+    if (typeof payload !== "object" ||
+        payload === null ||
+        Array.isArray(payload)) {
+        return {
+            kind: "malformed",
+            reason: `\`${name}\` call declared track "${track}" but carried no \`${track}\` object`,
+        };
+    }
+    const obj = payload;
+    const bad = (0, agent_result_js_1.shapeError)(obj, track === "ok" ? contract.ok : contract.err);
+    if (bad)
+        return { kind: "malformed", reason: `${track} payload: ${bad}` };
+    return track === "ok"
+        ? { kind: "ok", value: obj }
+        : { kind: "err", error: obj };
+}
+/**
+ * ⚠️ EXPERIMENTAL. Assert the run emitted a SUCCESS result, and return its value —
+ * the emit-channel counterpart of `assertAgentOk`, for a skill that has no return
+ * value to assert on.
+ *
+ * Throws on a missing emit, a repeated emit, an error track, or a payload that
+ * does not match the contract. The failure message names every tool the run DID
+ * call, because "the skill never emitted" and "the skill emitted the wrong shape"
+ * are different bugs and the tool list separates them at a glance.
+ *
+ * The error track is reachable through `experimental_parseEmitted`; a matching
+ * `…EmittedErr` is deliberately NOT shipped while the surface is this young —
+ * three exports is the whole prototype.
+ *
+ * @experimental
+ */
+function experimental_assertEmittedOk(toolCalls, contract, options = {}) {
+    const r = experimental_parseEmitted(toolCalls, contract, options);
+    if (r.kind === "ok")
+        return r.value;
+    const why = r.kind === "err"
+        ? `it emitted an error result: ${JSON.stringify(r.error)}`
+        : r.reason;
+    const observed = toolCalls.map((c) => c.name).join(", ") || "none";
+    throw new Error(`expected an emitted success result, but ${why} (tools called: ${observed})`);
+}
+//# sourceMappingURL=experimental-emit.js.map

package/dist/experimental.d.ts

@@ -10,8 +10,14 @@
  * NOT covered by the stability guarantee (STABILITY.md): the shape may change or
  * be removed WITHOUT a major-version bump. Do not depend on it in production.
  *
- * Current contents — the R3 disposable-service tier (real side-effect testing;
- * see docs/measuring-skills.md § Experimental and src/services.ts).
+ * Current contents:
+ *  - the R3 disposable-service tier (real side-effect testing; see
+ *    docs/measuring-skills.md § Experimental and src/services.ts);
+ *  - the EMIT delivery for a typed result (`src/experimental-emit.ts`) — a skill
+ *    that CALLS a tool with its outcome instead of ending its turn with a fenced
+ *    block, which is how an UNFORKED skill can carry an `OutputContract` at all.
+ *    Read that module's header before using it: it lists, by number, what is
+ *    unproven and what would have to be true to drop the prefix.
  *
  * ⚠️ SAFETY: R3 runs a model-driven skill FOR REAL. The disposable container is
  * the ONLY isolation vigiles provides — it does not confine the skill's filesystem
@@ -24,4 +30,5 @@
  */
 export { experimental_startServices, experimental_withServices, type ServiceSpec, type ServiceReady, type ServiceReset, type ServiceHandle, type ServiceSession, type ContainerRuntime, } from "./services.js";
 export { experimental_dockerRuntime, makeDockerRuntime, type DockerExec, type NetProbe, } from "./services-docker.js";
+export { experimental_emitTool, experimental_parseEmitted, experimental_assertEmittedOk, type EmitFieldSchema, type EmitObjectSchema, type EmitPropertySchema, type EmitTrackSchema, type EmitToolDefinition, type ExperimentalEmitTool, } from "./experimental-emit.js";
 //# sourceMappingURL=experimental.d.ts.map

package/dist/experimental.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = void 0;
+exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = void 0;
 /**
  * `vigiles/experimental` — ⚠️ EXPERIMENTAL, UNSTABLE public surface.
  *
@@ -13,8 +13,14 @@ exports.makeDockerRuntime = exports.experimental_dockerRuntime = exports.experim
  * NOT covered by the stability guarantee (STABILITY.md): the shape may change or
  * be removed WITHOUT a major-version bump. Do not depend on it in production.
  *
- * Current contents — the R3 disposable-service tier (real side-effect testing;
- * see docs/measuring-skills.md § Experimental and src/services.ts).
+ * Current contents:
+ *  - the R3 disposable-service tier (real side-effect testing; see
+ *    docs/measuring-skills.md § Experimental and src/services.ts);
+ *  - the EMIT delivery for a typed result (`src/experimental-emit.ts`) — a skill
+ *    that CALLS a tool with its outcome instead of ending its turn with a fenced
+ *    block, which is how an UNFORKED skill can carry an `OutputContract` at all.
+ *    Read that module's header before using it: it lists, by number, what is
+ *    unproven and what would have to be true to drop the prefix.
  *
  * ⚠️ SAFETY: R3 runs a model-driven skill FOR REAL. The disposable container is
  * the ONLY isolation vigiles provides — it does not confine the skill's filesystem
@@ -31,4 +37,8 @@ Object.defineProperty(exports, "experimental_withServices", { enumerable: true,
 var services_docker_js_1 = require("./services-docker.js");
 Object.defineProperty(exports, "experimental_dockerRuntime", { enumerable: true, get: function () { return services_docker_js_1.experimental_dockerRuntime; } });
 Object.defineProperty(exports, "makeDockerRuntime", { enumerable: true, get: function () { return services_docker_js_1.makeDockerRuntime; } });
+var experimental_emit_js_1 = require("./experimental-emit.js");
+Object.defineProperty(exports, "experimental_emitTool", { enumerable: true, get: function () { return experimental_emit_js_1.experimental_emitTool; } });
+Object.defineProperty(exports, "experimental_parseEmitted", { enumerable: true, get: function () { return experimental_emit_js_1.experimental_parseEmitted; } });
+Object.defineProperty(exports, "experimental_assertEmittedOk", { enumerable: true, get: function () { return experimental_emit_js_1.experimental_assertEmittedOk; } });
 //# sourceMappingURL=experimental.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "15.1.0",
+  "version": "15.2.1",
   "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",