@vibe-agent-toolkit/agent-skills 0.2.0-rc.1 → 0.2.0-rc.3

package/dist/skill-test/baseline-integrity.d.ts

@@ -0,0 +1,944 @@
+import { z } from 'zod';
+export declare function harnessNeedles(harnessRoot: string): PathNeedle[];
+/**
+ * Strip every channel by which the executor ENVIRONMENT would tell the skill-absent
+ * arm where the skill is staged.
+ *
+ * A path reaches a child process through four channels — prompt, argv, cwd, and
+ * env. The first three are handled at the call site; this is the fourth, and it is
+ * the one that is easy to miss because nothing at the spawn call mentions it: the
+ * run assembles ONE env and both arms were given it verbatim.
+ *
+ * Two rules, deliberately in this order:
+ *   1. drop {@link CONTROL_ARM_FORBIDDEN_ENV_KEYS} by name;
+ *   2. drop ANY entry whose value contains the harness root — which covers
+ *      adopter-declared `env:` values that interpolated `${stagedSkillDir}` or
+ *      `${harnessRoot}`, and, more importantly, covers the next such channel
+ *      somebody adds without knowing this function exists.
+ *
+ * Rule 2 is a value scan rather than a longer key list on purpose: a key list only
+ * ever knows about the leaks already found. It is accident-catching HYGIENE, not an
+ * adversarial control — a determined skill author splits the path across two vars
+ * (`A=/tmp/vat-skill-test` + `B=/<key>/…`) and the per-value scan never joins them.
+ * The adversarial control is that the path is not REACHABLE, not that it is unnamed.
+ *
+ * Rule 2 exempts {@link protectedEnvNames}, which is WIDER than the three names the
+ * paragraph below uses as its example: it is every process essential, the auth
+ * allowlist, every inference credential, the whole `CREDENTIAL_ROUTING_DENY` list,
+ * AND this run's `modelVars`. The model vars are the ones that matter most here and
+ * were missing until they were threaded in: dropping a model var because its value
+ * happens to sit under `--out` runs the control arm ON A DIFFERENT MODEL, which is
+ * a far worse confound than the missing PATH this exemption exists to prevent, and
+ * one no operator would think to look for.
+ *
+ * The three named below are the illustration. An `--out` under any of their values (e.g.
+ * `--out .` from a repo root, which puts `<repo>/node_modules/.bin` on PATH inside a
+ * `bun run`) would otherwise spawn the control arm with no PATH at all. That does not
+ * fail; it DEGRADES the control, which scores lower, which reports as skill lift. A
+ * scrub that manufactures the very delta the product sells is worse than the leak it
+ * closes, so a protected var that names the harness root is RETAINED and reported
+ * loudly instead — the operator can see it and move `--out`.
+ *
+ * `${fixturesDir}` resolves under the WORKSPACES root, not the harness root, so the
+ * control arm keeps its declared input files — the arms stay identical in
+ * everything except the skill itself.
+ *
+ * Pure. Returns the scrubbed env and three disjoint name lists for the transparency
+ * lines: the rule-1 drops, the rule-2 drops, and the protected names RETAINED
+ * despite naming the harness root.
+ *
+ * The two drop lists are separate because they mean opposite things to an operator.
+ * A rule-1 drop is routine — `CLAUDE_PLUGIN_ROOT` is withheld on every plugin-layout
+ * baseline run by design, and its value may name nothing in the harness at all (the
+ * installed-plugin-cache case). A rule-2 drop says the operator's OWN declared `env:`
+ * named the harness root, which is the one worth acting on. Merged into one list under
+ * one "naming the harness root" sentence, the routine drop was both mislabelled and
+ * loud enough to bury the interesting one.
+ */
+export declare function scrubControlArmEnv(env: NodeJS.ProcessEnv, harnessRoot: string, 
+/**
+ * This run's model env var names. REQUIRED, not defaulted: an omitted list
+ * silently narrows the exemption set, and the var it drops decides which model
+ * the control arm runs — a defect that reads as skill lift and is invisible in
+ * the output. Pass `[]` when the run genuinely has none.
+ */
+modelVars: readonly string[], 
+/**
+ * The platform whose env-name casing rules apply. Defaults to this process's.
+ * Threaded in ONLY so the win32 branch of {@link isProtectedName} is testable:
+ * without it the case-insensitive lookup this function deliberately uses instead
+ * of `protectedNames.has` was unexercised on every platform CI runs the unit
+ * suite on, and swapping the two was green.
+ */
+platform?: string): {
+    env: NodeJS.ProcessEnv;
+    /** Rule 1: dropped by NAME, whatever the value. */
+    droppedForbiddenKey: string[];
+    /** Rule 2: dropped because the VALUE names the harness root. */
+    droppedNamingRoot: string[];
+    retainedLeaks: string[];
+};
+export declare const BaselineContaminationHitSchema: z.ZodObject<{
+    /**
+     * What matched: a path under vat's harness root, a declared executable's name,
+     * the OTHER arm's workspace directory, or one of vat's private tmp dirs.
+     *
+     * `sibling-arm` is a materially different finding from the first two. Those mean
+     * the arm found a copy of the skill; this one means it read the treatment arm's
+     * live working directory, so the control may be echoing an answer the treatment
+     * produced seconds earlier rather than solving anything.
+     *
+     * `vat-private-dir` is worse than all of them. It means the arm reached the held
+     * eval suite (the `expected_output` ANSWER KEY) or the grader dir (the run's
+     * integrity nonce). Reaching a copy of the skill inflates the control arm;
+     * reaching the answer key inflates BOTH arms, so it does not even show up as a
+     * shrunken delta — see {@link vatPrivateDirNeedles}.
+     */
+    kind: z.ZodEnum<["harness-path", "declared-executable", "sibling-arm", "vat-private-dir", "skill-content"]>;
+    /**
+     * The matched token — a path SUFFIX, a verbatim skill line, or the executable
+     * basename.
+     *
+     * ⚠️ PATH MATCHES ARE TRUNCATED TO THEIR LAST TWO SEGMENTS ON PURPOSE, and that
+     * is not cosmetic. Needle sets run longest-first, so the needle that matches a
+     * full-path reach is the ENTIRE absolute root — on Windows
+     * `C:/Users/<username>/AppData/Local/Temp/vat-skill-test/<key>`, which puts the
+     * operator's login name in an artifact adopters attach to bug reports, in the one
+     * field that reads like a short opaque token. The last two segments identify the
+     * directory just as well (`vat-skill-test/<key>`) and name nobody. See
+     * {@link redactPathMatch}; the untruncated path is still visible in `excerpt`,
+     * which carries its own warning.
+     *
+     * A skill-content match is a verbatim line of the skill's own body and is NOT
+     * truncated — it has no `/`-separated structure to trim, and the whole point of
+     * that signal is that the operator can find the line in SKILL.md by eye.
+     */
+    match: z.ZodString;
+    /**
+     * A short excerpt of the transcript around the match, for triage.
+     *
+     * RAW TRANSCRIPT — the arm's own bytes, its own casing, its own separators,
+     * bounded and whitespace-collapsed. That is a promise this field has to keep to
+     * be worth anything: its only use is to be carried back to the transcript and
+     * searched for, and it once came from the NORMALIZED haystack instead, so
+     * `SKILL.md` was reported as `skill.md` and a JSON-escaped `\n` as `/n` — an
+     * operator grepping for the reported excerpt found nothing, in a field that
+     * exists solely so they can. The structured scan quotes the raw tool input; the
+     * flat and content scans map their match back through {@link ScanHaystack}.
+     * (Whitespace collapse is the one transform that survives, and it is stated here:
+     * grep for a distinctive WORD from the excerpt, not for the whole line.)
+     *
+     * NOT redacted. The most likely way a harness path reaches a transcript is an
+     * `env` dump, so this window can capture adjacent environment values —
+     * `GITHUB_TOKEN=…`, `HOME=/Users/<name>` have both been observed — and
+     * `baseline.json` is a file adopters attach to reports. Treat it as sensitive;
+     * `grading.json` already quotes transcripts verbatim, so this is the same
+     * exposure, not a new one.
+     */
+    excerpt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    match: string;
+    kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+    excerpt: string;
+}, {
+    match: string;
+    kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+    excerpt: string;
+}>;
+export type BaselineContaminationHit = z.infer<typeof BaselineContaminationHitSchema>;
+/** Per-eval contamination finding for the WITHOUT arm. */
+export declare const BaselineContaminationSchema: z.ZodObject<{
+    evalId: z.ZodString;
+    hits: z.ZodArray<z.ZodObject<{
+        /**
+         * What matched: a path under vat's harness root, a declared executable's name,
+         * the OTHER arm's workspace directory, or one of vat's private tmp dirs.
+         *
+         * `sibling-arm` is a materially different finding from the first two. Those mean
+         * the arm found a copy of the skill; this one means it read the treatment arm's
+         * live working directory, so the control may be echoing an answer the treatment
+         * produced seconds earlier rather than solving anything.
+         *
+         * `vat-private-dir` is worse than all of them. It means the arm reached the held
+         * eval suite (the `expected_output` ANSWER KEY) or the grader dir (the run's
+         * integrity nonce). Reaching a copy of the skill inflates the control arm;
+         * reaching the answer key inflates BOTH arms, so it does not even show up as a
+         * shrunken delta — see {@link vatPrivateDirNeedles}.
+         */
+        kind: z.ZodEnum<["harness-path", "declared-executable", "sibling-arm", "vat-private-dir", "skill-content"]>;
+        /**
+         * The matched token — a path SUFFIX, a verbatim skill line, or the executable
+         * basename.
+         *
+         * ⚠️ PATH MATCHES ARE TRUNCATED TO THEIR LAST TWO SEGMENTS ON PURPOSE, and that
+         * is not cosmetic. Needle sets run longest-first, so the needle that matches a
+         * full-path reach is the ENTIRE absolute root — on Windows
+         * `C:/Users/<username>/AppData/Local/Temp/vat-skill-test/<key>`, which puts the
+         * operator's login name in an artifact adopters attach to bug reports, in the one
+         * field that reads like a short opaque token. The last two segments identify the
+         * directory just as well (`vat-skill-test/<key>`) and name nobody. See
+         * {@link redactPathMatch}; the untruncated path is still visible in `excerpt`,
+         * which carries its own warning.
+         *
+         * A skill-content match is a verbatim line of the skill's own body and is NOT
+         * truncated — it has no `/`-separated structure to trim, and the whole point of
+         * that signal is that the operator can find the line in SKILL.md by eye.
+         */
+        match: z.ZodString;
+        /**
+         * A short excerpt of the transcript around the match, for triage.
+         *
+         * RAW TRANSCRIPT — the arm's own bytes, its own casing, its own separators,
+         * bounded and whitespace-collapsed. That is a promise this field has to keep to
+         * be worth anything: its only use is to be carried back to the transcript and
+         * searched for, and it once came from the NORMALIZED haystack instead, so
+         * `SKILL.md` was reported as `skill.md` and a JSON-escaped `\n` as `/n` — an
+         * operator grepping for the reported excerpt found nothing, in a field that
+         * exists solely so they can. The structured scan quotes the raw tool input; the
+         * flat and content scans map their match back through {@link ScanHaystack}.
+         * (Whitespace collapse is the one transform that survives, and it is stated here:
+         * grep for a distinctive WORD from the excerpt, not for the whole line.)
+         *
+         * NOT redacted. The most likely way a harness path reaches a transcript is an
+         * `env` dump, so this window can capture adjacent environment values —
+         * `GITHUB_TOKEN=…`, `HOME=/Users/<name>` have both been observed — and
+         * `baseline.json` is a file adopters attach to reports. Treat it as sensitive;
+         * `grading.json` already quotes transcripts verbatim, so this is the same
+         * exposure, not a new one.
+         */
+        excerpt: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        match: string;
+        kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+        excerpt: string;
+    }, {
+        match: string;
+        kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+        excerpt: string;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    evalId: string;
+    hits: {
+        match: string;
+        kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+        excerpt: string;
+    }[];
+}, {
+    evalId: string;
+    hits: {
+        match: string;
+        kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+        excerpt: string;
+    }[];
+}>;
+export type BaselineContamination = z.infer<typeof BaselineContaminationSchema>;
+/**
+ * The run-level `baselineIntegrity` block stamped into `baseline.json`.
+ *
+ * `contaminated: true` means at least one WITHOUT-arm eval demonstrably reached
+ * the skill; the A/B delta for the run is then NOT interpretable as skill lift.
+ * The block is written on EVERY baseline run, clean or not, so its absence
+ * always means "this baseline.json predates integrity checking" and never
+ * "checked and clean".
+ */
+/**
+ * A detector that can be ARMED for a run.
+ *
+ * Deliberately the SAME enum as a hit's `kind`, not a parallel list: each
+ * detector produces exactly one kind of hit, so two lists would be a drift
+ * hazard for no expressive gain. Which detectors were armed is the difference
+ * between "checked and clean" and "nothing was looking":
+ *
+ * - `harness-path` — vat's staged trees ({@link harnessNeedles}). Always armed.
+ * - `sibling-arm` — the other arm's live workspace. Armed only when there is one.
+ * - `vat-private-dir` — the held answer key and the grader dir
+ *   ({@link vatPrivateDirNeedles}).
+ * - `declared-executable` — the skill's executables by name. Armed ONLY for a
+ *   skill that ships executables; an instruction-only skill (the common case)
+ *   has no such name, so this signal is absent.
+ * - `skill-content` — verbatim lines of the staged SKILL.md
+ *   ({@link skillContentNeedles}). The one signal that does not need the arm to
+ *   name a path or an executable, and therefore the only cover an
+ *   instruction-only skill has. Unarmed when the body yields no line distinctive
+ *   enough to accuse anyone with, which is itself worth seeing.
+ */
+export declare const ContaminationSignalSchema: z.ZodEnum<["harness-path", "declared-executable", "sibling-arm", "vat-private-dir", "skill-content"]>;
+export type ContaminationSignal = z.infer<typeof ContaminationSignalSchema>;
+/** One eval whose two arms were graded against a different number of expectations. */
+export declare const BaselineArmSkewSchema: z.ZodObject<{
+    evalId: z.ZodString;
+    withTotal: z.ZodNumber;
+    withoutTotal: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    evalId: string;
+    withTotal: number;
+    withoutTotal: number;
+}, {
+    evalId: string;
+    withTotal: number;
+    withoutTotal: number;
+}>;
+export type BaselineArmSkew = z.infer<typeof BaselineArmSkewSchema>;
+/**
+ * One CONTROL-arm eval that produced no grade at all, and why.
+ *
+ * Distinct from {@link BaselineArmSkewSchema}, which describes two arms that both
+ * graded and disagreed about how deep. This describes an arm that never got as far
+ * as a verdict: its executor failed to spawn, stalled, hit the wall clock, or its
+ * grader exited non-zero / wrote no fragment / wrote something unparseable / echoed
+ * the wrong nonce / graded a different number of expectations than the eval declares.
+ *
+ * Every one of those used to propagate out of `runPipeline` and fail the WHOLE run
+ * (exit 1) — discarding fully-billed treatment work that was perfectly good, and
+ * writing no `grading.json` at all. The treatment arm still hard-fails that way,
+ * because without a treatment result there is nothing to salvage; the control arm
+ * does not, because the thing it feeds (the delta) has a way to say "I cannot be
+ * computed" and the thing the operator paid for (the treatment grading) does not.
+ *
+ * `detail` is the arm-named error message verbatim — it already carries the eval id
+ * and the failing stage, and it is the text an operator would otherwise have seen on
+ * stderr before the run died.
+ */
+export declare const BaselineControlArmFailureSchema: z.ZodObject<{
+    evalId: z.ZodString;
+    detail: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    detail: string;
+    evalId: string;
+}, {
+    detail: string;
+    evalId: string;
+}>;
+export type BaselineControlArmFailure = z.infer<typeof BaselineControlArmFailureSchema>;
+/**
+ * What ONE arm actually graded for ONE eval: how many expectations it was graded
+ * against, and how many of them passed.
+ *
+ * Deliberately ONE type feeding two consumers. {@link armExpectationSkew} reads only
+ * `total` — whether subtracting the arms is legal at all — while the delta block
+ * reads `passed` to do the subtraction. Deriving those from two separate shapes is
+ * exactly the drift this module keeps warning about: the two blocks would be free to
+ * disagree about what each arm graded, and the one that disagreed quietly would be
+ * believed. `passed` is carried here even though the parity check ignores it so that
+ * a single derivation at the call site feeds both.
+ */
+export interface ArmEvalGrade {
+    evalId: string;
+    passed: number;
+    total: number;
+}
+/**
+ * Evals whose two arms were graded against DIFFERENT numbers of expectations.
+ *
+ * `--baseline` sells a DELTA, and a delta between two differently-sized
+ * denominators is not a delta. vat computes each arm's `summary` from the
+ * fragments it received, so both reports are internally consistent by
+ * construction and `reconcileGrading` cannot see this — a grader that emitted 2
+ * entries for a 3-expectation eval on the control arm yields
+ * `baseline.summary = {passed:2,total:2}`, which reads as **100% without the
+ * skill**. That is the most damaging direction the number can be wrong in: it
+ * says the skill did nothing.
+ *
+ * Both directions count, and so does an eval graded on only one arm — the missing
+ * side is reported as 0 rather than dropped, since a silently absent eval skews
+ * the run total exactly as a short-graded one does.
+ *
+ * THE ONE-ARM CASE IS NOW THE LOAD-BEARING ONE, and it is why this function did not
+ * become redundant when the declared-count check landed. Both arms are pinned to the
+ * eval's DECLARED expectation count at the grader boundary
+ * (`assertExpectationCountDeclared` in eval-grader.ts), so two arms that both
+ * produced a fragment can no longer disagree about `total` — which reads like this
+ * check has nothing left to find. It has two live inputs it always had and only now
+ * carries alone:
+ *
+ * - an eval the CONTROL arm never graded at all, because its executor or grader
+ *   broke (see {@link BaselineControlArmFailureSchema}). That is not a hypothetical:
+ *   it is the routine outcome the run no longer aborts on, so it arrives here on
+ *   every such run.
+ * - an eval graded on one arm only for any other reason — a fragment lost, an arm
+ *   mislabelled, a future path that grades the arms from different suites.
+ *
+ * It is also the SINGLE AUTHORITY `computeBaselineDelta` consults before withholding
+ * (see baseline-delta.ts). Deleting it would leave the delta with no way to say
+ * "these two totals cannot be subtracted", which is the whole reason `null` exists.
+ *
+ * The declared-count check is the STRONGER cousin this docblock used to say was "NOT
+ * here … it needs the suite threaded into the merge". That premise was wrong: the
+ * declared list is already in hand at the grader boundary, one call before the
+ * fragment is returned, so no threading was needed and the check now lives there.
+ * It catches what parity structurally cannot — both graders drifting the SAME way,
+ * which keeps parity satisfied while every reported number is wrong.
+ */
+export declare function armExpectationSkew(withArm: readonly ArmEvalGrade[], withoutArm: readonly ArmEvalGrade[]): BaselineArmSkew[];
+/**
+ * Why one eval's scan could not run at full strength.
+ *
+ * The structured scan ({@link detectBaselineContamination}) needs three things the
+ * transcript is not contractually obliged to provide: parseable stream-json with no
+ * dropped lines, and a cwd it can follow from the arm's own workspace through every
+ * `cd`.
+ *
+ * ⚠️ THE TWO FAILURES ARE NOT THE SAME SHAPE, and treating them alike was a defect
+ * in its own right. An UNPARSEABLE transcript leaves nothing to walk, so the scan
+ * falls back to the flat text match this module used to be — which both over-reports
+ * (a `find` that PRINTS a path reads as a reach) and under-reports (a relative reach
+ * after a `cd` loses the leading slash a bare-name needle requires). An unevaluable
+ * `cd`, or a dropped line, leaves a HOLE instead: everything resolved before it is
+ * still validly resolved and is kept, and only what came after and needed a cwd is
+ * lost. Falling back for that case discarded good evidence AND reintroduced the flat
+ * scanner's over-reporting — one leading `cd $HOME` was enough to turn a pure
+ * directory listing into the "reached the answer key" verdict.
+ *
+ * A fallback that is not announced is the failure mode this whole module exists
+ * to prevent: `contaminated: false` from a degraded scan is written with exactly
+ * the same bytes as `contaminated: false` from a scan that actually looked.
+ * `signals` already separates "checked and clean" from "nothing was armed"; this
+ * separates "checked and clean" from "checked with the blunt instrument".
+ */
+export declare const BASELINE_SCAN_DEGRADATION_REASONS: readonly ["transcript-unparsed", "cwd-unknown", "cwd-untracked", "transcript-malformed", "glob-unexpanded"];
+export declare const BaselineScanDegradationSchema: z.ZodObject<{
+    reason: z.ZodEnum<["transcript-unparsed", "cwd-unknown", "cwd-untracked", "transcript-malformed", "glob-unexpanded"]>;
+    /** Human-readable specifics — the offending `cd`, or what the parse produced. */
+    detail: z.ZodString;
+    /** Which eval degraded. Absent on the value the detector returns; stamped by the caller. */
+    evalId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    detail: string;
+    reason: "transcript-unparsed" | "cwd-unknown" | "cwd-untracked" | "transcript-malformed" | "glob-unexpanded";
+    evalId?: string | undefined;
+}, {
+    detail: string;
+    reason: "transcript-unparsed" | "cwd-unknown" | "cwd-untracked" | "transcript-malformed" | "glob-unexpanded";
+    evalId?: string | undefined;
+}>;
+export type BaselineScanDegradation = z.infer<typeof BaselineScanDegradationSchema>;
+export declare const BaselineIntegritySchema: z.ZodObject<{
+    contaminated: z.ZodBoolean;
+    /**
+     * The evals whose scan did not run at full strength, and why. Empty means every
+     * eval got a complete structured scan — the only state in which
+     * `contaminated: false` means "looked properly and found nothing".
+     *
+     * NOT all the same failure: `transcript-unparsed` fell back to the flat text
+     * match, while `cwd-untracked` and `transcript-malformed` kept every reach they
+     * had resolved and lost only what came after the hole. See
+     * {@link BASELINE_SCAN_DEGRADATION_REASONS}.
+     */
+    degraded: z.ZodArray<z.ZodObject<{
+        reason: z.ZodEnum<["transcript-unparsed", "cwd-unknown", "cwd-untracked", "transcript-malformed", "glob-unexpanded"]>;
+        /** Human-readable specifics — the offending `cd`, or what the parse produced. */
+        detail: z.ZodString;
+        /** Which eval degraded. Absent on the value the detector returns; stamped by the caller. */
+        evalId: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        detail: string;
+        reason: "transcript-unparsed" | "cwd-unknown" | "cwd-untracked" | "transcript-malformed" | "glob-unexpanded";
+        evalId?: string | undefined;
+    }, {
+        detail: string;
+        reason: "transcript-unparsed" | "cwd-unknown" | "cwd-untracked" | "transcript-malformed" | "glob-unexpanded";
+        evalId?: string | undefined;
+    }>, "many">;
+    /**
+     * Whether the two arms were graded against the same expectations, and so
+     * whether subtracting one summary from the other means anything.
+     *
+     * Separate from `contaminated` because they fail differently: contamination
+     * says the control HAD the treatment, comparability says the two numbers were
+     * never measuring the same thing. A run can be clean and incomparable.
+     */
+    comparable: z.ZodBoolean;
+    /** The evals behind a `comparable: false`; empty when the arms agree. */
+    skew: z.ZodArray<z.ZodObject<{
+        evalId: z.ZodString;
+        withTotal: z.ZodNumber;
+        withoutTotal: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        evalId: string;
+        withTotal: number;
+        withoutTotal: number;
+    }, {
+        evalId: string;
+        withTotal: number;
+        withoutTotal: number;
+    }>, "many">;
+    /**
+     * Control-arm evals that produced no grade at all — see
+     * {@link BaselineControlArmFailureSchema}.
+     *
+     * A SEPARATE field from `skew` even though every entry here also produces a skew
+     * entry (an eval the control arm never graded has `withoutTotal: 0`), because the
+     * two say different things to an operator: skew says "the two graders disagreed
+     * about the job", this says "half the experiment did not run, and here is the
+     * spawn/grader failure that stopped it". Collapsing them would report a dead
+     * control arm as a grading-depth disagreement, which points triage at the grader
+     * prompt instead of at the timeout.
+     */
+    controlArmFailures: z.ZodArray<z.ZodObject<{
+        evalId: z.ZodString;
+        detail: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        detail: string;
+        evalId: string;
+    }, {
+        detail: string;
+        evalId: string;
+    }>, "many">;
+    /** Human-readable verdict, safe to print verbatim. */
+    summary: z.ZodString;
+    /**
+     * Which detectors were ARMED for this run.
+     *
+     * Without it, `contaminated: false` is written identically whether four signals
+     * were active or one, so a clean verdict cannot be told apart from a blind one
+     * — and the difference is large: the executable-name signal is the only one
+     * that sees an ambient copy of the skill in the adopter's own repo, and it does
+     * not exist for a skill that ships no executables.
+     *
+     * An empty array is the loudest case: nothing was looking, and `contaminated`
+     * says nothing at all.
+     */
+    signals: z.ZodArray<z.ZodEnum<["harness-path", "declared-executable", "sibling-arm", "vat-private-dir", "skill-content"]>, "many">;
+    findings: z.ZodArray<z.ZodObject<{
+        evalId: z.ZodString;
+        hits: z.ZodArray<z.ZodObject<{
+            /**
+             * What matched: a path under vat's harness root, a declared executable's name,
+             * the OTHER arm's workspace directory, or one of vat's private tmp dirs.
+             *
+             * `sibling-arm` is a materially different finding from the first two. Those mean
+             * the arm found a copy of the skill; this one means it read the treatment arm's
+             * live working directory, so the control may be echoing an answer the treatment
+             * produced seconds earlier rather than solving anything.
+             *
+             * `vat-private-dir` is worse than all of them. It means the arm reached the held
+             * eval suite (the `expected_output` ANSWER KEY) or the grader dir (the run's
+             * integrity nonce). Reaching a copy of the skill inflates the control arm;
+             * reaching the answer key inflates BOTH arms, so it does not even show up as a
+             * shrunken delta — see {@link vatPrivateDirNeedles}.
+             */
+            kind: z.ZodEnum<["harness-path", "declared-executable", "sibling-arm", "vat-private-dir", "skill-content"]>;
+            /**
+             * The matched token — a path SUFFIX, a verbatim skill line, or the executable
+             * basename.
+             *
+             * ⚠️ PATH MATCHES ARE TRUNCATED TO THEIR LAST TWO SEGMENTS ON PURPOSE, and that
+             * is not cosmetic. Needle sets run longest-first, so the needle that matches a
+             * full-path reach is the ENTIRE absolute root — on Windows
+             * `C:/Users/<username>/AppData/Local/Temp/vat-skill-test/<key>`, which puts the
+             * operator's login name in an artifact adopters attach to bug reports, in the one
+             * field that reads like a short opaque token. The last two segments identify the
+             * directory just as well (`vat-skill-test/<key>`) and name nobody. See
+             * {@link redactPathMatch}; the untruncated path is still visible in `excerpt`,
+             * which carries its own warning.
+             *
+             * A skill-content match is a verbatim line of the skill's own body and is NOT
+             * truncated — it has no `/`-separated structure to trim, and the whole point of
+             * that signal is that the operator can find the line in SKILL.md by eye.
+             */
+            match: z.ZodString;
+            /**
+             * A short excerpt of the transcript around the match, for triage.
+             *
+             * RAW TRANSCRIPT — the arm's own bytes, its own casing, its own separators,
+             * bounded and whitespace-collapsed. That is a promise this field has to keep to
+             * be worth anything: its only use is to be carried back to the transcript and
+             * searched for, and it once came from the NORMALIZED haystack instead, so
+             * `SKILL.md` was reported as `skill.md` and a JSON-escaped `\n` as `/n` — an
+             * operator grepping for the reported excerpt found nothing, in a field that
+             * exists solely so they can. The structured scan quotes the raw tool input; the
+             * flat and content scans map their match back through {@link ScanHaystack}.
+             * (Whitespace collapse is the one transform that survives, and it is stated here:
+             * grep for a distinctive WORD from the excerpt, not for the whole line.)
+             *
+             * NOT redacted. The most likely way a harness path reaches a transcript is an
+             * `env` dump, so this window can capture adjacent environment values —
+             * `GITHUB_TOKEN=…`, `HOME=/Users/<name>` have both been observed — and
+             * `baseline.json` is a file adopters attach to reports. Treat it as sensitive;
+             * `grading.json` already quotes transcripts verbatim, so this is the same
+             * exposure, not a new one.
+             */
+            excerpt: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            match: string;
+            kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+            excerpt: string;
+        }, {
+            match: string;
+            kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+            excerpt: string;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        evalId: string;
+        hits: {
+            match: string;
+            kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+            excerpt: string;
+        }[];
+    }, {
+        evalId: string;
+        hits: {
+            match: string;
+            kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+            excerpt: string;
+        }[];
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    summary: string;
+    contaminated: boolean;
+    degraded: {
+        detail: string;
+        reason: "transcript-unparsed" | "cwd-unknown" | "cwd-untracked" | "transcript-malformed" | "glob-unexpanded";
+        evalId?: string | undefined;
+    }[];
+    comparable: boolean;
+    skew: {
+        evalId: string;
+        withTotal: number;
+        withoutTotal: number;
+    }[];
+    controlArmFailures: {
+        detail: string;
+        evalId: string;
+    }[];
+    signals: ("harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content")[];
+    findings: {
+        evalId: string;
+        hits: {
+            match: string;
+            kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+            excerpt: string;
+        }[];
+    }[];
+}, {
+    summary: string;
+    contaminated: boolean;
+    degraded: {
+        detail: string;
+        reason: "transcript-unparsed" | "cwd-unknown" | "cwd-untracked" | "transcript-malformed" | "glob-unexpanded";
+        evalId?: string | undefined;
+    }[];
+    comparable: boolean;
+    skew: {
+        evalId: string;
+        withTotal: number;
+        withoutTotal: number;
+    }[];
+    controlArmFailures: {
+        detail: string;
+        evalId: string;
+    }[];
+    signals: ("harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content")[];
+    findings: {
+        evalId: string;
+        hits: {
+            match: string;
+            kind: "harness-path" | "declared-executable" | "sibling-arm" | "vat-private-dir" | "skill-content";
+            excerpt: string;
+        }[];
+    }[];
+}>;
+export type BaselineIntegrity = z.infer<typeof BaselineIntegritySchema>;
+/**
+ * One needle plus the string that is safe to REPORT when it matches.
+ *
+ * The two are separate because they answer different questions and a single string
+ * cannot do both: the needle has to be the arm's own spelling or it matches nothing,
+ * while `match` is quoted into bug reports and must name no person. Computing the
+ * report at CONSTRUCTION is also the only place the provenance is known — a
+ * suffix needle looks like a complete two-segment path by the time a hit is built,
+ * and that is exactly how it came to be emitted with no truncation marker.
+ */
+export interface PathNeedle {
+    /** Normalized; matched at a path boundary. */
+    needle: string;
+    /** Redacted, and marked `…/` whenever it is not the whole thing it came from. */
+    match: string;
+}
+export interface DetectBaselineContaminationInput {
+    /** The WITHOUT arm's captured stream-json transcript. */
+    transcript: string;
+    /**
+     * vat's harness root. Any mention of it in the control arm's transcript means
+     * the arm reached into vat's own staged trees — which, now that neither the
+     * prompt nor the cwd points there, it could only do by going looking.
+     */
+    harnessRoot: string;
+    /**
+     * The skill's declared executables as SKILL-RELATIVE PATHS, exactly as the
+     * packaging config spells them (`scripts/csvsum.py`), from
+     * `deriveDeclaredExecutableNames`.
+     *
+     * ⚠️ PATHS, NOT NAMES, and the difference is the whole signal — see
+     * {@link reachIsDeclaredExecutable}. This field used to carry the
+     * extension-stripped basename, which convicted a clean control arm for reading
+     * its own `/tmp/summary.txt`.
+     */
+    executablePaths?: readonly string[];
+    /**
+     * ⛔ NOT A FIELD — A TRIPWIRE. `executableNames` was the previous spelling and
+     * carried extension-stripped basenames; it is gone, and `never` is here so that a
+     * caller still passing it FAILS TO COMPILE.
+     *
+     * Declared because the renaming alone was silent. The harness builds this object
+     * with conditional SPREADS (`...(x === undefined ? {} : { executableNames: … })`),
+     * and a spread is not a fresh object literal, so TypeScript applies no
+     * excess-property check: dropping the old name simply left the property unread and
+     * the `declared-executable` signal unarmed on every run — reported as
+     * `contaminated: false` by a detector that was no longer looking. That is precisely
+     * the "silently clean" failure this module exists to prevent, so the rename gets a
+     * compile error rather than a comment.
+     */
+    executableNames?: never;
+    /**
+     * The control arm's OWN workspace root, so a path under it is recognised as the
+     * arm's own scratch file rather than a reach. The executor prompt states the
+     * working directory absolutely, so the arm reuses that absolute path routinely;
+     * without this every such mention would read as an escape.
+     *
+     * Absent → nothing is suppressed, which is the conservative direction for a
+     * caller that has not threaded it: the check gets noisier, never blinder.
+     */
+    armWorkspaceDir?: string;
+    /**
+     * The arm's actual STARTING working directory — the per-eval workspace
+     * `<armWorkspaceDir>/<evalId>`, which is what the executor is spawned in.
+     *
+     * Distinct from `armWorkspaceDir` on purpose, and the difference is one
+     * directory level that decides every relative reach in the transcript. The cwd
+     * walk anchors here; containment ("is this the arm's own file?") is judged
+     * against `armWorkspaceDir`, which covers the arm's whole tree. Anchoring the
+     * walk one level too high would resolve `cd ../../..` to the temp dir's PARENT,
+     * and every subsequent relative path — the entire class of reach this scan
+     * exists to catch — would land somewhere no needle can see, reporting clean.
+     *
+     * Defaults to `armWorkspaceDir` when absent, which is the closest anchor
+     * available and still better than none.
+     */
+    armCwd?: string;
+    /**
+     * Verbatim lines lifted from the staged SKILL.md by {@link skillContentNeedles}
+     * — the ONLY signal that sees an ambient copy of an instruction-only skill,
+     * which ships nothing this module could match by name or path.
+     */
+    skillContentNeedles?: readonly string[];
+    /**
+     * The OTHER arm's workspace directory — for a skill-absent eval, the treatment
+     * arm's live working directory.
+     *
+     * Not a path into vat's staged copies, so no harness needle can see it: the two
+     * arm dirs are siblings under one workspaces root, and `existsSync` on
+     * `../<sibling>/<id>/fixtures/input.md` from the control arm returns TRUE. Round 3
+     * gave each arm its own directory, which stopped them writing over each other; it
+     * did not stop one READING the other, and reading the treatment arm's output
+     * mid-run lets the control score like the treatment while producing a transcript
+     * with no harness path in it at all.
+     *
+     * Prevention is now the opaque per-arm token (the sibling's directory name is
+     * unguessable and no longer spells `with`), so this is the detection half: if the
+     * arm names it anyway — because it enumerated `..` — say so.
+     *
+     * The ABSOLUTE path to that directory; the needles are derived from it.
+     */
+    siblingArmDir?: string;
+    /**
+     * VAT's private tmp dirs for this run — the held eval suite (the answer key) and
+     * the grader dir (the integrity nonce). Absolute paths; see
+     * {@link vatPrivateDirNeedles} for why these need a detector of their own and
+     * why the useful needle is a name PREFIX rather than the token.
+     *
+     * Never pass the workspaces root here: it is the arm's own legitimate cwd, and a
+     * prefix needle built from it fires on every clean run.
+     */
+    vatPrivateDirs?: readonly (string | undefined)[];
+}
+/**
+ * The needles that mean "this transcript named the OTHER arm's workspace".
+ *
+ * Two: the full path, and the bare per-arm token. The token is 16 hex characters
+ * minted per run, so a boundary-anchored match on it is essentially free of false
+ * positives — the arm's own token is different, and nothing else on the machine
+ * spells it.
+ *
+ * The LEADING `/` requirement (via {@link needsLeadingBoundary}) is what keeps
+ * `ls ..` honest: listing the parent prints the sibling's directory name as a bare
+ * basename on its own line, which is "I looked around", not "I read the other arm".
+ * Every genuine reach — `cat ../<token>/e1/out.md`, an absolute path, `find ..
+ * -name '*.md'` printing `../<token>/…` — carries the slash.
+ */
+export declare function siblingArmNeedles(siblingArmDir: string): PathNeedle[];
+/**
+ * The needles that mean "this transcript reached a dir only VAT is supposed to
+ * see" — the held eval suite (`<tmp>/vat-skill-evals-<token>`, which holds the
+ * `expected_output` ANSWER KEY for a fetched-artifact subject) and the grader dir
+ * (`<tmp>/vat-skill-grade-<token>`, which holds the run's integrity nonce).
+ *
+ * These are a FOURTH reachable class the harness-path detector cannot see: they
+ * are siblings of the arm's cwd under the OS temp dir, contain no harness path,
+ * and are two hops (`ls ../..`) or one `$TMPDIR` expansion away. Worse than
+ * reaching the skill — reaching the answer key inflates BOTH arms, so it cannot
+ * show up as a shrunken delta at all.
+ *
+ * Three needles, longest-first: the full path, the whole dir NAME, and the
+ * dir-name prefix with the per-run token stripped (`vat-skill-evals-`).
+ *
+ * The prefix is what catches the reach an arm can actually type. The token is 16
+ * random hex it has no way to know, so it globs — `cat $TMPDIR/vat-skill-evals-&#42;/
+ * evals.json` — and that string contains neither the full path nor the name. (One
+ * `&#42;` defeating a needle that embeds a random key is the same trap that once
+ * made the whole harness-suffix scheme inert.)
+ *
+ * The prefix needle carries no `/`, so {@link needsLeadingBoundary} requires one
+ * before it — without that, `ls $TMPDIR` printing `vat-skill-evals-abc` on its own
+ * line stamps a clean run contaminated. That rule is also why this must NEVER be
+ * built for the workspaces root: `vat-skill-test-ws-` is the arm's own legitimate
+ * cwd and its absolute path is in the arm's own prompt, so the needle would fire
+ * on every single clean run.
+ */
+export declare function vatPrivateDirNeedles(dir: string): PathNeedle[];
+/**
+ * Verbatim lines from the skill body that mean "this transcript SAW the skill".
+ *
+ * THE GAP THIS FILLS. Every other signal in this module needs the arm to name a
+ * PATH or an executable. An instruction-only skill — the common case — ships no
+ * executable, and the two ambient classes vat cannot remove (the adopter's own
+ * repo/build output, the installed plugin cache) produce no harness path. So
+ * `grep -rl "<phrase>" .` → `Read` → answer was completely invisible, and
+ * `contaminated: false` meant "saw no evidence" while reading as "verified none".
+ * Content is the only thing that survives all three of those steps: a `grep` hit
+ * line, a `Read` echo, and an answer that quotes the skill with no path attached.
+ *
+ * Selection is deterministic and needs no corpus: LONGEST first, because length is
+ * rarity for free. A candidate must be plain body prose —
+ *
+ *   - frontmatter is skipped (the `name:` is the skill's own identifier and shows
+ *     up in ordinary config and prose; it is not distinctive enough to accuse
+ *     anyone with);
+ *   - fenced code is skipped, since a code block is often copied from a shared
+ *     upstream and is the same in every skill that wraps the same tool;
+ *   - headings, table rows and block quotes are skipped as structural.
+ *
+ * 📌 A rule that lines carrying `"` or `\` are unusable has been REMOVED. It was
+ * true while the haystack was the RAW stream-json, where such characters are
+ * escaped and {@link normalizeForMatch} then rewrites the escape, so the needle
+ * could never match its own text. The content signal now reads
+ * {@link contentHaystackFor} — the DECODED assistant text, tool inputs and tool
+ * results — where there is no escaping to defeat, so those lines are usable
+ * needles again, and dropping them was silently costing quote-heavy skills their
+ * only signal. Re-add the rule only if the content haystack goes back to raw JSON.
+ *
+ * `excludedText` is every channel through which VAT ITSELF hands the arm text:
+ * the run's eval prompts, its `expected_output`, its expectations, AND the
+ * contents of the input `files` fixtures VAT stages into the arm's workspace and
+ * tells it to work on. This is not optional care in any of the four. An adopter
+ * who quotes a sentence of their SKILL.md in a prompt — or ships a fixture that
+ * does — would otherwise stamp EVERY run contaminated, including the arm that
+ * merely read the input it was given, and the attached triage instruction
+ * ("uninstall the ambient copy of the plugin") would send the operator hunting
+ * something that does not exist. The skill's own words reaching the arm through
+ * vat are not the arm reaching the skill.
+ */
+export declare function skillContentNeedles(skillMarkdown: string, excludedText?: string): string[];
+/**
+ * What a tool call DOES with the paths in its input.
+ *
+ * `write` is the one that is not about reading at all, and it exists because its
+ * absence was a false-positive engine. {@link segmentReaches} used to stamp every
+ * path word in a segment with the segment's single intent, so the DESTINATION of a
+ * redirect or a copy inherited `retrieval` from the command that produced the
+ * bytes — and declared executable names are basenames minus extension, i.e.
+ * `summary`, `report`, `index`, `run`. `sort data.csv > /tmp/summary.txt`,
+ * `cp notes.md /tmp/summary.md` and `cat parts/*.json > /tmp/index.json` each
+ * reported `declared-executable`: the arm was accused of RUNNING the skill's tool
+ * on the strength of having written a file with an ordinary name. A write target
+ * is not evidence that anything ran.
+ */
+export type ToolIntent = 'retrieval' | 'enumeration' | 'write' | 'other';
+/** What a scan of one skill-absent transcript produced. */
+export interface BaselineContaminationScan {
+    /**
+     * Stable order: harness path, sibling arm, vat private dirs, skill content,
+     * then declared executables in declared order. At most one per group.
+     */
+    hits: BaselineContaminationHit[];
+    /** Present only when the structured scan could not run — see the schema. */
+    degraded?: BaselineScanDegradation;
+}
+/**
+ * Scan the skill-absent arm's transcript for proof it reached the skill.
+ *
+ * Pure + unit-testable. See the module-level block above {@link ToolIntent} for
+ * the architecture and for the two demonstrated defects that forced it.
+ */
+export declare function detectBaselineContamination(input: DetectBaselineContaminationInput): BaselineContaminationScan;
+/**
+ * Which contamination detectors are ARMED for a run, derived from the SAME input
+ * object handed to {@link detectBaselineContamination} so the two cannot disagree
+ * about what was checked. A signal counts as armed only when it has a non-empty
+ * needle set — a dir that was never threaded through produces no needles and must
+ * not be reported as "checked".
+ */
+export declare function activeContaminationSignals(input: DetectBaselineContaminationInput): ContaminationSignal[];
+/**
+ * Everything the run-level integrity block is assembled from.
+ *
+ * An OBJECT, and every field REQUIRED — no optionals, no defaults. Each of these
+ * five is a coverage claim, and every one of them is believed in the same
+ * direction: an absent `signals` reads as "checked by nothing", an absent
+ * `degraded` reads as "every scan was structured", an absent `controlArmFailures`
+ * reads as "both arms ran". A default on any of them lets a caller overclaim
+ * silently; a required field is a compile error the day a new call site appears.
+ *
+ * `degraded` was defaulted to `[]` for exactly one release and the harness never
+ * passed it, so `baseline.json` read identically whether the contamination scan
+ * walked the transcript or fell back blind. That is the whole reason the rule is
+ * written down here rather than assumed.
+ */
+export interface SummarizeBaselineIntegrityInput {
+    /** Per-eval contamination findings; empty on a clean run. */
+    findings: readonly BaselineContamination[];
+    /** Which detectors were ARMED for this run — see {@link activeContaminationSignals}. */
+    signals: readonly ContaminationSignal[];
+    /** Evals whose two arms are not comparable — see {@link armExpectationSkew}. */
+    skew: readonly BaselineArmSkew[];
+    /** Evals whose scan fell back to flat matching — see {@link BaselineScanDegradationSchema}. */
+    degraded: readonly BaselineScanDegradation[];
+    /** Control-arm evals that never produced a grade — see {@link BaselineControlArmFailureSchema}. */
+    controlArmFailures: readonly BaselineControlArmFailure[];
+    /**
+     * How many CONTROL-ARM evals were actually scanned for contamination.
+     *
+     * ⛔ REQUIRED, and for the same reason the other four are: every one of these is a
+     * coverage claim, and a default lets a caller overclaim silently in the direction
+     * where the claim gets believed. Confirmed on a real run where both control arms
+     * died on an executor timeout, so ZERO transcripts were scanned and `baseline.json`
+     * still opened with "No skill-absent eval was observed reaching the skill. The A/B
+     * delta is interpretable as instruction lift" — two false sentences, with the
+     * correction arriving third. A count of zero means nothing was looked at, which is
+     * not the same finding as looking and seeing nothing, and
+     * {@link summarizeBaselineIntegrity} now leads with the absence rather than
+     * burying it.
+     *
+     * Pass the number of control-arm evals whose transcript reached
+     * {@link detectBaselineContamination}, NOT the number of evals declared.
+     */
+    observedEvals: number;
+}
+/**
+ * Assemble the run-level integrity block from every WITHOUT-arm eval's findings.
+ * `findings` is empty on a clean run — the block is still emitted, with
+ * `contaminated: false`, so "checked and clean" is distinguishable from
+ * "never checked".
+ *
+ * `comparable` is derived from `skew` ALONE, deliberately, even though a
+ * `controlArmFailures` entry also means the arms cannot be subtracted. `skew` is
+ * the single authority `computeBaselineDelta` consults, and a second input to
+ * `comparable` here would let this block say "not comparable" while the delta block
+ * beside it printed a number — the exact two-blocks-disagreeing failure this module
+ * keeps warning about. It costs nothing: a control-arm failure removes that eval's
+ * control grade entirely, and {@link armExpectationSkew} reports a one-armed eval as
+ * skew by construction, so the two always agree. See the run-harness test that pins
+ * that derivation end to end rather than trusting this sentence.
+ */
+export declare function summarizeBaselineIntegrity(input: SummarizeBaselineIntegrityInput): BaselineIntegrity;
+//# sourceMappingURL=baseline-integrity.d.ts.map