@vibe-agent-toolkit/agent-skills 0.2.0-rc.7 → 0.2.0-rc.8

package/dist/skill-test/run-harness.js

@@ -3,7 +3,7 @@
  *
  * Implements the full harness sequence as a pure async function (no process.exit):
  *   lock → assert safe workdir + harness root → stage → resolve staged-subject
- *   eval path → bootstrap-check (scaffold template + exit 3 if absent)
+ *   eval path → bootstrap-check (scaffold template + exit 2 with `Reason: bootstrap` if absent)
  *   → preflight (return early exitCode 2 on failure) → ack enforcement
  *   → dry-run short-circuit → build per-eval work items → run the vat-owned
  *   executor→grader pipeline (bounded-parallel) → merge grader fragments →
@@ -15,7 +15,8 @@ import { existsSync, lstatSync, readFileSync, readdirSync, renameSync, rmSync, w
 import { homedir } from 'node:os';
 import { basename, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { mkdirSyncReal, normalizedTmpdir, resolveAssetReference, safePath, toForwardSlash, } from '@vibe-agent-toolkit/utils';
+import { ExitCode } from '@vibe-agent-toolkit/schema';
+import { direntKind, isPathAbsentError, mkdirSyncReal, normalizedTmpdir, prefixMessageOnce, resolveAssetReference, safePath, toForwardSlash, } from '@vibe-agent-toolkit/utils';
 import { getToolVersion, safeExecResult, } from '@vibe-agent-toolkit/utils/process';
 import { killAllActiveClaudeChildren, probeAuthStatus, } from '@vibe-agent-toolkit/utils/skill-test';
 import { resolveSkillSource } from '../skill-source/resolve-skill-source.js';
@@ -23,12 +24,12 @@ import { BaselineArtifactSchema, computeBaselineDelta, formatBaselineDeltaLine,
 import { activeContaminationSignals, armExpectationSkew, detectBaselineContamination, scrubControlArmEnv, skillContentNeedles, summarizeBaselineIntegrity, } from './baseline-integrity.js';
 import { assembleChildEnv, assertKnownEnvTokens, computeEnvTokens, resolveInjectEnv } from './declared-env.js';
 import { runExecutorForEval } from './eval-executor.js';
-import { runGraderForEval } from './eval-grader.js';
+import { GRADER_FRAGMENT_UNPARSEABLE, GraderFragmentUnparseableError, runGraderForEval } from './eval-grader.js';
 import { armDirSegment, EvalInputError, parseEvalSuite, stageEvalWorkspaces, } from './eval-inputs.js';
 import { lintEvalExpectations, lintToolExpectationExecutables } from './eval-lint.js';
 import { DEFAULT_EVALS_SUBPATH } from './eval-suite-isolation.js';
 import { writeEvalsTemplate } from './evals-template.js';
-import { BootstrapNeededError, DuplicateStagedSkillError, InternalHarnessError, SkillTestExitCode, } from './exit-codes.js';
+import { BootstrapNeededError, DuplicateStagedSkillError, InternalHarnessError, } from './failure-reason.js';
 import { mergeFragmentsToFriction, mergeFragmentsToGrading, mergeFragmentsToToolEval } from './fragment-merge.js';
 import { FrictionReportSchema } from './friction-schema.js';
 import { DEFAULT_CONCURRENCY, DEFAULT_GRADER_MODEL } from './grader-model.js';
@@ -55,7 +56,7 @@ import { verifyVendoredManifest } from './vendor-manifest.js';
 const VENDORED_SKILL_CREATOR_DIR = safePath.resolve(dirname(fileURLToPath(import.meta.url)), '../../vendor/skill-creator');
 /**
  * Absolute path to the vendored skill-creator grader rubric each per-eval grader
- * spawn is told to judge against (issue #145). Lives inside
+ * spawn is told to judge against. Lives inside
  * {@link VENDORED_SKILL_CREATOR_DIR}, whose hash manifest is verified during
  * preflight — so the rubric the grader uses is the pinned, integrity-checked copy.
  */
@@ -88,28 +89,30 @@ export const SKILL_TEST_BUILTIN_CAPS = {
 };
 /**
  * Resolve the effective PER-EVAL wall-clock timeout (ms). Each executor and
- * grader spawn is an independent, bounded-parallel unit (issue #145), so the
+ * grader spawn is an independent, bounded-parallel unit, so the
  * budget is a flat per-spawn ceiling — NOT scaled by the suite size the way the
  * old single serial run's budget was. An explicit `--timeout` (seconds)
  * wins; otherwise the flat {@link DEFAULT_TIMEOUT_MS} default applies.
  */
-export function resolveTimeoutMs(opts) {
+function resolveTimeoutMs(opts) {
     return opts.timeout === undefined ? DEFAULT_TIMEOUT_MS : opts.timeout * 1000;
 }
 /**
  * Map an eval verdict to a process exit code. Default behavior (fail-closed): a
- * failing verdict escalates to EvalFailure (4) — distinct from the harness-broke
- * codes (1/2/3) so a CI consumer can `case $? in 0);; 4) tolerate;; *) hard fail;; esac`.
+ * failing verdict is `FINDINGS` — the harness ran to completion and what it
+ * examined did not pass, exactly as `vat skills validate` reports an
+ * error-severity finding — while a harness that could not run is `ERROR`, so a
+ * CI consumer can `case $? in 0);; 1) tolerate;; *) hard fail;; esac`.
  * When `tolerateEvalFailure` is set (interactive opt-out), a failing verdict is
- * downgraded to Ok (0) and the count lives only in the summary/grading.json.
+ * downgraded to `OK` and the count lives only in the summary/grading.json.
  */
 export function verdictExitCode(allPassed, tolerateEvalFailure) {
-    return !allPassed && !tolerateEvalFailure ? SkillTestExitCode.EvalFailure : SkillTestExitCode.Ok;
+    return !allPassed && !tolerateEvalFailure ? ExitCode.FINDINGS : ExitCode.OK;
 }
-export function resolveStallMs(opts) {
+function resolveStallMs(opts) {
     return opts.stall === undefined ? undefined : opts.stall * 1000;
 }
-export function resolveKnobs(opts) {
+function resolveKnobs(opts) {
     const result = {
         maxTurns: opts.maxTurns ?? DEFAULT_MAX_TURNS,
         maxBudgetUsd: opts.maxBudgetUsd ?? DEFAULT_MAX_BUDGET_USD,
@@ -129,13 +132,13 @@ export function resolveKnobs(opts) {
  * sources (npm/url/vendored/workspace) have no local source tree to walk, so they
  * are always staged flat (returns undefined). undefined → flat staging.
  */
-export function detectItemPluginLayout(source, repoRoot) {
+function detectItemPluginLayout(source, repoRoot) {
     if (!('path' in source))
         return undefined;
     const sourceDir = resolveAssetReference(source.path, repoRoot);
     return detectPluginLayout(sourceDir, existsSync) ?? undefined;
 }
-export function makeStageItem(name, source, repoRoot, role, optional) {
+function makeStageItem(name, source, repoRoot, role, optional) {
     const pluginLayout = detectItemPluginLayout(source, repoRoot);
     return {
         name,
@@ -149,14 +152,14 @@ export function makeStageItem(name, source, repoRoot, role, optional) {
  * Build the full set of items `stageHarness` will stage: the subject, every
  * REQUIRED `--with` companion, and every OPTIONAL `--with-optional` companion.
  * Both `with` and `optional` STAGE the named companion and make it invocable —
- * they differ only in required-vs-optional resolution (issue #153; a `--with`
- * name that named no positional skill used to be silently dropped, never staged,
- * no manifest trace). Fail-closed on a DUPLICATE staged name (subject / `with` /
+ * they differ only in required-vs-optional resolution (a `--with` name that
+ * names no positional skill must never be silently dropped — unstaged, with no
+ * manifest trace). Fail-closed on a DUPLICATE staged name (subject / `with` /
  * `optional` all share one namespace): the first repeat throws
  * {@link DuplicateStagedSkillError} rather than silently letting a later item
  * clobber an earlier one under the same staged slot.
  */
-export function buildStageItems(opts, repoRoot) {
+function buildStageItems(opts, repoRoot) {
     const items = [];
     const seen = new Set();
     const pushItem = (item) => {
@@ -179,7 +182,7 @@ export function buildStageItems(opts, repoRoot) {
     }
     return items;
 }
-export function buildResolveCtx(harnessRoot, repoRoot) {
+function buildResolveCtx(harnessRoot, repoRoot) {
     return {
         repoRoot,
         stagingRoot: safePath.joinUnderRoot(harnessRoot, 'staged'),
@@ -194,7 +197,7 @@ export function buildResolveCtx(harnessRoot, repoRoot) {
  * of each other (`--max-turns` / `--max-turns-per-eval` would collide). Neither
  * side of the token may be a letter or a dash.
  */
-export function helpTextDeclaresFlag(helpText, flag) {
+function helpTextDeclaresFlag(helpText, flag) {
     // A scan rather than a built regex: the flag is data (it comes from a list a
     // future edit will extend), and building a pattern from data is both a lint
     // error here and the kind of thing that silently changes meaning when someone
@@ -211,7 +214,7 @@ export function helpTextDeclaresFlag(helpText, flag) {
  * as a NEGATIVE CONTROL: if the probe reports this as supported, the probe is
  * broken and its answer about every other flag is worthless.
  */
-export const FLAG_PROBE_SENTINEL = '--vat-probe-flag-that-cannot-exist';
+const FLAG_PROBE_SENTINEL = '--vat-probe-flag-that-cannot-exist';
 /**
  * Build a token-free flag-support probe from `claude --help`.
  *
@@ -232,12 +235,25 @@ export const FLAG_PROBE_SENTINEL = '--vat-probe-flag-that-cannot-exist';
  * outright — the probe reports EVERY flag unsupported rather than every flag
  * supported. A probe that cannot tell must fail closed and be seen; the defect it
  * replaces failed open and was invisible.
- */
-export function buildFlagParseProbe(runHelp = defaultClaudeHelp) {
-    const helpText = runHelp();
-    // No help output, or a sentinel "match" ⇒ the probe is not trustworthy.
-    const usable = helpText !== null && !helpTextDeclaresFlag(helpText, FLAG_PROBE_SENTINEL);
-    return (flag) => usable && helpTextDeclaresFlag(helpText ?? '', flag);
+ *
+ * `--help` runs on the FIRST flag query, not when the probe is built. Building
+ * it is part of assembling preflight's input, and a preflight that never asks
+ * (a stubbed one, or one that fails an earlier check) must not have already
+ * paid for a subprocess: with the spawn at build time every harness run cost
+ * one real `claude --help` — 75 ms where the CLI is installed, an instant
+ * ENOENT where it is not — which read as a 10× platform split in a test that
+ * had injected a fake spawn and stubbed preflight precisely so no process
+ * would start.
+ */
+function buildFlagParseProbe(runHelp = defaultClaudeHelp) {
+    let helpText;
+    return (flag) => {
+        if (helpText === undefined)
+            helpText = runHelp();
+        // No help output, or a sentinel "match" ⇒ the probe is not trustworthy.
+        const usable = helpText !== null && !helpTextDeclaresFlag(helpText, FLAG_PROBE_SENTINEL);
+        return usable && helpTextDeclaresFlag(helpText ?? '', flag);
+    };
 }
 /** Run `claude --help` once, returning its combined output (null if unreachable). */
 function defaultClaudeHelp() {
@@ -272,7 +288,7 @@ function defaultClaudeHelp() {
  * reachable: a reachable estimate that says "1 evals × 2 config" is worse than a
  * silent one, because it is quotable.
  */
-export function buildPreflightInput(evalsPath, pluginDirs, opts, knobs) {
+function buildPreflightInput(evalsPath, pluginDirs, opts, knobs) {
     const costEstimate = {
         evalCount: 1,
         // `configurations` IS the A/B dimension: `--baseline` runs every eval under two
@@ -304,7 +320,7 @@ export function buildPreflightInput(evalsPath, pluginDirs, opts, knobs) {
         preflightOpts.requireAuth = opts.requireAuth;
     return preflightOpts;
 }
-export function renderPreflightSummary(checks) {
+function renderPreflightSummary(checks) {
     const failed = checks.filter(c => !c.passed);
     return failed.length > 0
         ? failed.map(c => `  [FAIL] ${c.name}: ${c.message}`).join('\n')
@@ -349,27 +365,34 @@ export function formatFrictionReport(items) {
 /**
  * Read the run's friction.json (if present + valid) and echo a concise report to
  * STDERR so users don't miss packaging-fidelity friction VAT merged from the grader
- * fragments (it is otherwise only written to disk). Best-effort: a missing, unparseable, or
- * empty report emits nothing. Never touches stdout (which stays machine-readable).
- * Accepts `undefined` (a no-op) so the harness `finally` can call it unconditionally
- * even when a throw preempted assignment of the friction path.
+ * fragments (it is otherwise only written to disk). Best-effort: a missing or empty
+ * report emits nothing. A report that is there but cannot be read or does not parse
+ * emits a one-line warning instead — this runs from the harness `finally`, so it
+ * must not throw, but vat is the sole writer of friction.json and a file it wrote
+ * that it cannot read back is worth a line. Never touches stdout (which stays
+ * machine-readable). Accepts `undefined` (a no-op) so the harness `finally` can
+ * call it unconditionally even when a throw preempted assignment of the path.
  */
 function emitFrictionReport(frictionPath) {
     if (frictionPath === undefined)
         return;
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
     if (!existsSync(frictionPath))
         return;
     let raw;
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
         raw = JSON.parse(readFileSync(frictionPath, 'utf-8'));
     }
-    catch {
+    catch (err) {
+        process.stderr.write(`warning: could not read the friction report at ${frictionPath}: ` +
+            `${err instanceof Error ? err.message : String(err)}\n`);
         return;
     }
     const parsed = FrictionReportSchema.safeParse(raw);
-    if (!parsed.success || parsed.data.items.length === 0)
+    if (!parsed.success) {
+        process.stderr.write(`warning: the friction report at ${frictionPath} does not match its schema: ${parsed.error.message}\n`);
+        return;
+    }
+    if (parsed.data.items.length === 0)
         return;
     process.stderr.write(`\nPackaging friction (${parsed.data.items.length}):\n`);
     process.stderr.write(formatFrictionReport(parsed.data.items) + '\n');
@@ -395,7 +418,8 @@ function emitBaselineReport(report) {
 function emitSkippedOptionalWarning(skippedOptional) {
     if (skippedOptional.length === 0)
         return;
-    process.stderr.write(`warning: optional companion skill(s) not staged (source unresolvable): ${skippedOptional.join(', ')}\n`);
+    const named = skippedOptional.map((item) => `${item.name} (${item.reason})`).join(', ');
+    process.stderr.write(`warning: optional companion skill(s) not staged: ${named}\n`);
 }
 /**
  * Resolve the PERSISTENT location where a bootstrap scaffold should be written
@@ -404,7 +428,7 @@ function emitSkippedOptionalWarning(skippedOptional) {
  * that real source dir; otherwise we anchor under the repo root by skill name.
  */
 /** The subject skill's display name (trailing segment of the subject arg). */
-export function subjectSkillName(opts) {
+function subjectSkillName(opts) {
     return basename(toForwardSlash(opts.subject)) || opts.subject;
 }
 /**
@@ -429,7 +453,7 @@ export function subjectSkillName(opts) {
  * into `<skillDir>/<path>`, which does not exist — so the run did not fail, it
  * bootstrapped a starter template at the bogus location and graded that.
  */
-export function resolveScaffoldEvalsPath(opts, repoRoot, evalsRef) {
+function resolveScaffoldEvalsPath(opts, repoRoot, evalsRef) {
     const resolveFrom = (baseDir) => evalsRef === undefined
         ? safePath.join(baseDir, DEFAULT_EVALS_SUBPATH)
         : resolveAssetReference(evalsRef, baseDir);
@@ -448,7 +472,7 @@ export function resolveScaffoldEvalsPath(opts, repoRoot, evalsRef) {
     return resolveFrom(sourceDir);
 }
 /**
- * Bootstrap (exit 3) — called when the eval suite is absent everywhere. A real run
+ * Bootstrap (exit 2, `Reason: bootstrap`) — called when the eval suite is absent everywhere. A real run
  * writes a persistent template at the source scaffold location and reports it; a dry
  * run must never touch the filesystem, so it reports where a real run *would*
  * scaffold and writes nothing. Both surface the same exit-3 BootstrapNeededError.
@@ -469,7 +493,7 @@ function bootstrapEvalSuite(opts, repoRoot, evalsRef) {
  * is performing. Created 0700 and removed in the run's cleanup, exactly like
  * {@link resolveGraderOutDir}. Pure (derives a path only).
  */
-export function resolveEvalSuiteHoldDir(dirToken) {
+function resolveEvalSuiteHoldDir(dirToken) {
     return safePath.join(normalizedTmpdir(), `vat-skill-evals-${dirToken}`);
 }
 /**
@@ -482,14 +506,13 @@ export function resolveEvalSuiteHoldDir(dirToken) {
  * 2. **The vat-only hold dir**, when staging harvested a suite that exists nowhere
  *    else (a fetched artifact). Its layout mirrors an authored evals dir, so
  *    `fixtures/` resolve relative to it unchanged.
- * 3. Neither → `undefined`, and the caller bootstraps a template (exit 3).
+ * 3. Neither → `undefined`, and the caller bootstraps a template (exit 2, `Reason: bootstrap`).
  *
  * Returns the suite's absolute path; its `dirname` is the base for each eval's
  * declared input `files`.
  */
-export function resolveEvalSuitePath(input) {
+function resolveEvalSuitePath(input) {
     const authored = resolveScaffoldEvalsPath(input.opts, input.repoRoot, input.evalsRef);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- authored source path resolved from opts
     if (existsSync(authored))
         return authored;
     if (!input.subjectEvalSuiteHeld)
@@ -510,7 +533,7 @@ export function resolveEvalSuitePath(input) {
  * Named by an unpredictable token, like the other vat-only dirs, and removed by
  * the same cleanup. Pure (derives a path only).
  */
-export function resolveWorkspacesRoot(dirToken) {
+function resolveWorkspacesRoot(dirToken) {
     return safePath.join(normalizedTmpdir(), `vat-skill-test-ws-${dirToken}`);
 }
 /** Parse the staged eval suite and materialize each eval's input `files` into
@@ -530,11 +553,11 @@ export function resolveWorkspacesRoot(dirToken) {
  * 8 bytes is ample for "not guessable within a run that lasts minutes"; these are
  * blinding/anti-enumeration tokens, not secrets protecting data at rest.
  */
-export function mintArmWorkspaceDirs(baseline) {
+function mintArmWorkspaceDirs(baseline) {
     const token = () => randomBytes(8).toString('hex');
     return baseline ? { with: token(), without: token() } : { with: token() };
 }
-export function stageWorkspacesForRun(evalsPath, workspacesRoot, armDirs) {
+function stageWorkspacesForRun(evalsPath, workspacesRoot, armDirs) {
     rmSync(workspacesRoot, { recursive: true, force: true });
     // 0700, matching the harness root. These dirs hold each eval's declared input
     // files, which with an out-of-tree suite may be data that was never in the repo
@@ -547,7 +570,6 @@ export function stageWorkspacesForRun(evalsPath, workspacesRoot, armDirs) {
     // directory and nothing ever re-checks. Cheap: the leaf sits directly under the
     // trusted tmp boundary, so the ancestry walk degrades to one lstat + stat.
     assertSafeHarnessRoot(workspacesRoot, process.getuid?.() ?? -1);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- evalsPath is our staged-subject path
     const suite = parseEvalSuite(readFileSync(evalsPath, 'utf-8'));
     return {
         workspacesRoot: stageEvalWorkspaces({
@@ -580,7 +602,8 @@ function attemptStageWorkspaces(evalsPath, harnessRoot, workspacesRoot, armDirs)
         if (e instanceof EvalInputError) {
             return {
                 harnessPath: harnessRoot,
-                exitCode: SkillTestExitCode.Preflight,
+                exitCode: ExitCode.ERROR,
+                reason: 'preflight',
                 summary: `Eval input error:\n  ${e.message}`,
             };
         }
@@ -590,8 +613,8 @@ function attemptStageWorkspaces(evalsPath, harnessRoot, workspacesRoot, armDirs)
 /**
  * Advisory (never-fatal) lint pass over the parsed suite: nudges authors away
  * from presence-only expectations ("mentions/includes …") that a hallucinated
- * or wrong-for-the-right-reason answer could still satisfy (issue #145
- * follow-up). Purely additive stderr noise, emitted before any spawn — never
+ * or wrong-for-the-right-reason answer could still satisfy.
+ * Purely additive stderr noise, emitted before any spawn — never
  * affects exitCode. Extracted so the Step 5.5 call site stays a single line
  * (keeps the orchestrator's cognitive complexity budget).
  */
@@ -765,7 +788,7 @@ export function buildDryRunSummary(input) {
  * evict staged untrusted skill bytes and prompts from OS tmp; `results/` is the
  * opposite — it is the run's product, written solely by vat.
  */
-export const RETAINED_RESULTS_DIRNAME = 'results';
+const RETAINED_RESULTS_DIRNAME = 'results';
 /**
  * Remove the harness directory's staged contents after a run so untrusted skill
  * bytes and prompts do not accumulate in OS tmp. No-op when the user asked to keep
@@ -793,20 +816,20 @@ export const RETAINED_RESULTS_DIRNAME = 'results';
  * the run and cleanup is left in place rather than followed — `rmSync(recursive)`
  * could otherwise delete the symlink's target outside tmp.
  */
-export function cleanupHarness(harnessRoot, opts) {
+function cleanupHarness(harnessRoot, opts) {
     if (opts.keep || !opts.created)
         return;
     // Best-effort: cleanup runs from a `finally`, so a TOCTOU race (the dir is
     // reaped between checks) or a permission error must never throw out and mask
-    // the run's real outcome. Worst case is a leftover 0700 tmp dir, not a failure.
-    try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived harness root
+    // the run's real outcome. Worst case is a leftover 0700 tmp dir, not a failure —
+    // but a leftover the operator was never told about is staged untrusted bytes
+    // sitting in tmp with nothing to connect them to this run, so the failure is
+    // REPORTED on stderr ({@link swallowCleanupFailure}), not swallowed silently.
+    swallowCleanupFailure(() => {
         if (!existsSync(harnessRoot))
             return;
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived harness root
         if (lstatSync(harnessRoot).isSymbolicLink())
             return;
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived harness root
         const entries = readdirSync(harnessRoot);
         // Nothing to retain — a run that ended before Step 7 (preflight refusal, lock
         // failure, a throw during staging) has no results/, so leaving an empty 0700
@@ -820,10 +843,7 @@ export function cleanupHarness(harnessRoot, opts) {
                 continue;
             rmSync(safePath.joinUnderRoot(harnessRoot, entry), { recursive: true, force: true });
         }
-    }
-    catch {
-        // Swallow: a failed cleanup is not a run failure.
-    }
+    });
 }
 /**
  * Build the per-eval work items for a set of evals (one tier's worth, or a whole
@@ -833,7 +853,7 @@ export function cleanupHarness(harnessRoot, opts) {
  * (see {@link partitionFragmentsByArm}) and never drives tier gating. Pure +
  * unit-testable.
  */
-export function buildEvalWorkItems(evals, baseline) {
+function buildEvalWorkItems(evals, baseline) {
     const items = [];
     for (const entry of evals) {
         items.push({ entry, arm: 'with' });
@@ -848,7 +868,7 @@ export function buildEvalWorkItems(evals, baseline) {
  * fragment with no `arm` (or `arm: 'with'`) is a WITH-arm fragment. Pure +
  * unit-testable.
  */
-export function partitionFragmentsByArm(fragments) {
+function partitionFragmentsByArm(fragments) {
     const withArm = [];
     const withoutArm = [];
     for (const fragment of fragments) {
@@ -879,7 +899,7 @@ export function partitionFragmentsByArm(fragments) {
  * container; that is tracked as a follow-up (see CHANGELOG "Security" notes) and
  * is the only thing that closes the residual race outright.
  */
-export function resolveGraderOutDir(dirToken) {
+function resolveGraderOutDir(dirToken) {
     return safePath.join(normalizedTmpdir(), `vat-skill-grade-${dirToken}`);
 }
 /**
@@ -903,7 +923,7 @@ export function resolveGraderOutDir(dirToken) {
  * told the control arm it was the control, and `../with/e1` told it where to look.
  * See {@link mintArmWorkspaceDirs}. Pure + unit-testable.
  */
-export function resolvePerEvalWorkspaceDir(entry, workspacesRoot, arm, armDirs) {
+function resolvePerEvalWorkspaceDir(entry, workspacesRoot, arm, armDirs) {
     return safePath.joinUnderRoot(armWorkspaceRoot(workspacesRoot, armDirs, arm), String(entry.id));
 }
 /**
@@ -949,7 +969,7 @@ function armWorkspaceRoot(workspacesRoot, armDirs, arm) {
  * could not be removed will break the NEXT run with a "busy" error, and an operator
  * who saw nothing here has no way to connect the two.
  */
-export function swallowCleanupFailure(step) {
+function swallowCleanupFailure(step) {
     try {
         step();
     }
@@ -957,25 +977,24 @@ export function swallowCleanupFailure(step) {
         process.stderr.write(`warning: harness cleanup step failed (the run's result stands): ${err instanceof Error ? err.message : String(err)}\n`);
     }
 }
-export function removeVatOnlyDir(dir) {
+/**
+ * Remove one vat-only temp dir. Same discipline as {@link cleanupHarness}: a failed
+ * removal is not a run failure, and it is reported rather than swallowed.
+ */
+function removeVatOnlyDir(dir) {
     if (dir === undefined)
         return;
-    try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived vat-only tmp dir
+    swallowCleanupFailure(() => {
         if (!existsSync(dir))
             return;
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived vat-only tmp dir
         if (lstatSync(dir).isSymbolicLink())
             return;
         rmSync(dir, { recursive: true, force: true });
-    }
-    catch {
-        // Swallow: a failed cleanup is not a run failure.
-    }
+    });
 }
 /**
  * Run ONE work item: the blind executor spawn, then the grader spawn over its
- * captured transcript (issue #145). Returns the grader fragment tagged with the
+ * captured transcript. Returns the grader fragment tagged with the
  * item's arm. The WITHOUT arm runs the executor with `pluginDirs: []` (skill
  * absent). Grader fragments are written under a PER-ARM subdir of the vat-only
  * grader dir so a WITH and WITHOUT run of the same eval id cannot collide.
@@ -983,7 +1002,7 @@ export function removeVatOnlyDir(dir) {
  * Throws, and the caller ({@link runEvalWorker}) decides what a throw costs — see
  * its docblock for why that depends on the arm. An executor CLEAN failure is NOT
  * thrown on either arm: its transcript flows into the grader, whose failing
- * fragment surfaces as an eval failure (exit 4 via the verdict), never exit 1.
+ * fragment surfaces as an eval failure (exit FINDINGS via the verdict), never ERROR.
  */
 /**
  * The executor env for ONE eval.
@@ -1130,11 +1149,11 @@ async function gradeOneArm(item, ctx) {
  * TREATMENT arm: rethrow. `grading.json` is the treatment arm, the verdict is
  * computed from it, and a run that cannot produce one has produced nothing — there
  * is no partial result worth writing, so the throw propagates through `runPipeline`
- * to `mapErrorToExitCode` exactly as before (exit 1).
+ * to `skillTestFailureReason` exactly as before (`ERROR`, reason `internal`).
  *
  * CONTROL arm: record and continue. Every failure mode of this arm — executor spawn
  * error, stall, wall-timeout, grader non-zero exit, grader wrote no fragment,
- * fragment is not valid JSON, nonce mismatch, and (newest) a grader that returned a
+ * fragment unparseable twice, nonce mismatch, and a grader that returned a
  * different number of expectations than the eval declares — used to propagate out of
  * `runPipeline` and annihilate the treatment work already completed and billed. A
  * two-eval probe was measured doing precisely that: both treatment executors ran,
@@ -1160,11 +1179,46 @@ async function runEvalWorker(item, ctx) {
         return { fragment: await gradeOneArm(item, ctx) };
     }
     catch (err) {
-        if (err instanceof RateLimitSignal || item.arm === 'with')
+        if (err instanceof RateLimitSignal)
+            throw nameTheArm(err, item.arm);
+        if (item.arm === 'with') {
+            if (err instanceof GraderFragmentUnparseableError)
+                return { fragment: unparseableGradingFragment(item, ctx, err) };
             throw nameTheArm(err, item.arm);
+        }
         return recordControlFailure(item, err);
     }
 }
+/**
+ * The TREATMENT arm's outcome for a grader that could not write valid JSON twice
+ * ({@link GraderFragmentUnparseableError}): this eval FAILS, in the same fragment
+ * shape a grader's own failing verdict takes, so it merges, counts and gates
+ * exactly like one — `FAIL n/m`, `FINDINGS` unless `--allow-eval-failure`, the other
+ * evals reported. Every declared expectation is marked failed with the reason as
+ * its `evidence`; a `tool` verdict is NOT invented, because none was produced —
+ * the eval already fails on the output channel, and `tool-eval.json` omitting it
+ * is the truth. Not `InternalHarnessError`: the harness ran the grader twice and
+ * it was the model that could not produce strict JSON.
+ *
+ * Treatment only. On the control arm the same error is recorded as a control
+ * failure (delta withheld) — a synthesized control `fail` would read as lift.
+ */
+function unparseableGradingFragment(item, ctx, err) {
+    process.stderr.write(`\n⚠️  [${ARM_LABEL[item.arm]}] ${err.message}\n` +
+        `   Eval "${err.evalId}" is reported as FAILED (${GRADER_FRAGMENT_UNPARSEABLE}); the run continues.\n`);
+    return {
+        runNonce: ctx.runNonce,
+        evalId: err.evalId,
+        arm: item.arm,
+        expectations: item.entry.expectations.map((text) => ({
+            // Suite text enters an artifact here without a grader's echo in between, so
+            // it takes the same sanitizer a grader's echo would have.
+            text: sanitizeGraderText(text),
+            passed: false,
+            evidence: `${GRADER_FRAGMENT_UNPARSEABLE}: ${err.detail}`,
+        })),
+    };
+}
 /**
  * The control arm ran out of rate-limit retries — record it and let the run live.
  *
@@ -1182,7 +1236,7 @@ async function runEvalWorker(item, ctx) {
  * Wired as the pipeline's `onRetriesExhausted`, and `--baseline` — which doubles the
  * spawn count — is the run most likely to need it.
  */
-export function rateLimitExhaustedOutcome(item, error) {
+function rateLimitExhaustedOutcome(item, error) {
     if (item.arm === 'with')
         throw nameTheArm(error, item.arm);
     return recordControlFailure(item, error);
@@ -1227,7 +1281,7 @@ const VAT_ATTACHED_FRAGMENT_KEYS = ['contamination', 'degraded'];
  * scanned properly, and an operator who learns to ignore that warning stops reading
  * the real ones.
  */
-export function withoutGraderContamination(fragment) {
+function withoutGraderContamination(fragment) {
     if (VAT_ATTACHED_FRAGMENT_KEYS.every((key) => fragment[key] === undefined))
         return fragment;
     const copy = { ...fragment };
@@ -1251,8 +1305,8 @@ const ARM_LABEL = {
 /**
  * Prefix a worker error's message with the arm it came from, IN PLACE.
  *
- * Mutating rather than re-wrapping is deliberate. `mapErrorToExitCode` dispatches on
- * the error's CLASS, and so does the run's own regression test for a forged grader
+ * Mutating rather than re-wrapping is deliberate. `skillTestFailureReason` reads the
+ * error's own declared reason, and the run's regression test for a forged grader
  * nonce (`rejects.toThrow(GradingNonceError)`); wrapping every failure in a fresh
  * `InternalHarnessError` to get a better message would flatten
  * `EvalFragmentError`/`GradingNonceError`/`RateLimitSignal` into one class and lose
@@ -1262,9 +1316,7 @@ const ARM_LABEL = {
  * must not accumulate prefixes.
  */
 function nameTheArm(err, arm) {
-    const prefix = `[${ARM_LABEL[arm]}] `;
-    if (err instanceof Error && !err.message.startsWith(prefix))
-        err.message = `${prefix}${err.message}`;
+    prefixMessageOnce(err, `[${ARM_LABEL[arm]}] `);
     return err;
 }
 /**
@@ -1288,13 +1340,14 @@ function nameTheArm(err, arm) {
  * Fixtures are read from the STAGED workspace rather than the suite directory, for
  * the same reason the SKILL.md is: that is byte-for-byte what the arm was handed.
  *
- * Returns `[]` when the file cannot be read. A missing SKILL.md is not this
+ * Returns `[]` when there is no staged SKILL.md. A missing SKILL.md is not this
  * function's error to raise (staging has already validated the subject), and an
- * unarmed signal is reported as unarmed rather than claimed as clean. An
- * unreadable FIXTURE is skipped for the same reason, and errs the safe way: a
- * fixture we could not exclude can only make the signal noisier, never blinder.
+ * unarmed signal is reported as unarmed rather than claimed as clean. A SKILL.md
+ * that is THERE but refused is a different thing — `[]` would silently disarm the
+ * contamination signal for the whole run — so a refusal propagates. The same split
+ * applies to fixtures: see {@link collectFixtureText}.
  */
-export function resolveSkillContentNeedles(subjectStagedDir, evals, 
+function resolveSkillContentNeedles(subjectStagedDir, evals, 
 /**
  * Where the staged fixtures live, as the two inputs an arm root is DERIVED from
  * rather than as the pre-joined path itself — see {@link armWorkspaceRoot}. Taking
@@ -1309,11 +1362,12 @@ workspaces) {
     const skillMdPath = safePath.join(subjectStagedDir, 'SKILL.md');
     let markdown;
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path derived from vat's own staged dir
         markdown = readFileSync(skillMdPath, 'utf8');
     }
-    catch {
-        return [];
+    catch (err) {
+        if (isPathAbsentError(err))
+            return [];
+        throw err;
     }
     const excluded = evals
         .flatMap((entry) => [
@@ -1326,7 +1380,8 @@ workspaces) {
     return skillContentNeedles(markdown, excluded);
 }
 /**
- * The text of one eval's staged input files. Unreadable/binary fixtures are skipped.
+ * The text of one eval's staged input files. A declared fixture that was never
+ * staged is skipped; one that is there but cannot be read propagates.
  *
  * A declared `files[]` entry is legitimately a DIRECTORY — staging does `existsSync`
  * then a recursive `cpSync` — so this walks one. It used to call `readFileSync` on
@@ -1339,9 +1394,11 @@ workspaces) {
  *
  * The `catch`'s old claim that skipping "errs the safe way: noisier, never blinder"
  * is BACKWARDS for this signal. Over-reporting is the harm here, because a false
- * `contaminated: true` is actioned by discarding a run that was fine. A fixture that
- * cannot be read is still skipped — there is nothing else to do with it — but that
- * is a cost, not a safety margin.
+ * `contaminated: true` is actioned by discarding a run that was fine. So only an
+ * ABSENT fixture is skipped (staging does `existsSync` then `cpSync`, so a declared
+ * file missing at the source is simply not in the workspace); a fixture that is
+ * there and refused throws, because an exclusion set vat could not compute is a
+ * signal vat cannot stand behind.
  */
 function readStagedFixtures(stagedWorkspaceRoot, entry) {
     const texts = [];
@@ -1353,33 +1410,44 @@ function readStagedFixtures(stagedWorkspaceRoot, entry) {
 }
 /** Depth cap on the fixture walk — a symlink loop must not hang the run's setup. */
 const MAX_FIXTURE_WALK_DEPTH = 32;
-/** Append `path`'s text, recursing when it is a directory. Never throws. */
-function collectFixtureText(path, into, depth = 0) {
-    if (depth > MAX_FIXTURE_WALK_DEPTH)
-        return;
-    let entries;
+/**
+ * Append the declared fixture's text — the file's, or every file's under it when
+ * it is a directory. `lstat` first, so the ONE absence case (`ENOENT`, or `ENOTDIR`
+ * for a path routed through a file) is the only thing skipped; a symlink at the
+ * declared path is skipped too, for the same reason the walk below skips one.
+ */
+function collectFixtureText(path, into) {
+    let kind;
     try {
-        // `withFileTypes` on the DIRECTORY is one syscall for the whole level, and
-        // `lstat`-shaped: a symlinked entry reports as a link rather than as whatever it
-        // points at, so the walk stays inside the bytes vat actually staged.
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is contained under vat's own staged workspace
-        entries = readdirSync(path, { withFileTypes: true });
+        kind = lstatSync(path);
     }
-    catch {
-        // Not a directory (the common case: a plain file fixture), or unreadable.
-        try {
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is contained under vat's own staged workspace
-            into.push(readFileSync(path, 'utf8'));
-        }
-        catch {
-            // Unreadable or binary — nothing to exclude, and not this function's error to raise.
-        }
-        return;
+    catch (err) {
+        if (isPathAbsentError(err))
+            return;
+        throw err;
     }
-    for (const child of entries) {
-        if (!child.isFile() && !child.isDirectory())
+    if (kind.isFile())
+        into.push(readFileSync(path, 'utf8'));
+    else if (kind.isDirectory())
+        walkFixtureDir(path, into, 0);
+}
+/** Append every file's text under `dir`, recursing. Symlinked entries are skipped. */
+function walkFixtureDir(dir, into, depth) {
+    if (depth > MAX_FIXTURE_WALK_DEPTH)
+        return;
+    // `withFileTypes` on the DIRECTORY is one syscall for the whole level, and
+    // `lstat`-shaped: a symlinked entry reports as a link rather than as whatever it
+    // points at, so the walk stays inside the bytes vat actually staged.
+    for (const child of readdirSync(dir, { withFileTypes: true })) {
+        const childPath = safePath.joinUnderRoot(dir, child.name);
+        const kind = direntKind(child);
+        // A link is skipped by design (see above): the walk reads only staged bytes.
+        if (kind === 'symlink')
             continue;
-        collectFixtureText(safePath.joinUnderRoot(path, child.name), into, depth + 1);
+        if (kind === 'file')
+            into.push(readFileSync(childPath, 'utf8'));
+        else if (kind === 'directory')
+            walkFixtureDir(childPath, into, depth + 1);
     }
 }
 /**
@@ -1411,7 +1479,7 @@ function collectFixtureText(path, into, depth = 0) {
  * not to run. That is the same shape as the dropped `armCwd` that anchored the whole
  * walk one directory too high, also green.
  */
-export function buildContaminationInput(transcript, ctx, evalId) {
+function buildContaminationInput(transcript, ctx, evalId) {
     return contaminationInput(transcript, ctx, evalId);
 }
 /**
@@ -1419,7 +1487,7 @@ export function buildContaminationInput(transcript, ctx, evalId) {
  * once per run with no transcript and no eval — so it can honestly supply neither,
  * and `armCwd` is correctly absent rather than accidentally dropped.
  */
-export function buildContaminationSignalsInput(ctx) {
+function buildContaminationSignalsInput(ctx) {
     return contaminationInput('', ctx, undefined);
 }
 function contaminationInput(transcript, ctx, evalId) {
@@ -1500,7 +1568,7 @@ function contaminationSignalsFor(ctx) {
 }
 /**
  * Run evals TIER by TIER (ascending), bounded-parallel WITHIN each tier, with a
- * GATE between tiers (issue #145 Phase G). After a tier completes, apply the
+ * GATE between tiers. After a tier completes, apply the
  * default gate policy ({@link shouldGateAfterTier}) over that tier's WITH-arm
  * fragments: if any eval in the tier did not fully pass, do NOT launch the higher
  * (more expensive) tiers — their evals are recorded as SKIPPED (a distinct state,
@@ -1540,7 +1608,7 @@ async function runEvalsTiered(input) {
 /** Resolve the run's grading/friction/baseline/tool-eval artifact paths under
  *  `resultsDir`. Single source of truth for the filenames (used by the
  *  pre-pipeline stale wipe AND the post-merge writer). */
-export function resolveArtifactPaths(resultsDir) {
+function resolveArtifactPaths(resultsDir) {
     return {
         gradingOut: safePath.join(resultsDir, 'grading.json'),
         frictionOut: safePath.join(resultsDir, 'friction.json'),
@@ -1557,7 +1625,7 @@ export function resolveArtifactPaths(resultsDir) {
  * run's. Wiping all three up front closes that cross-run leak. Best-effort
  * (`force: true`) — a missing file is fine.
  */
-export function wipeStaleArtifacts(paths) {
+function wipeStaleArtifacts(paths) {
     for (const path of [paths.gradingOut, paths.frictionOut, paths.baselineOut, paths.toolEvalOut]) {
         rmSync(path, { force: true });
         // ...and the quarantined copy a PRIOR run's failed gate set aside. It is just as
@@ -1589,7 +1657,6 @@ function openResultsDir(input) {
     // input files ends up here as text — and unlike the workspaces, results/ SURVIVES
     // `--keep` by design.
     mkdirSyncReal(input.resultsDir, { recursive: true, mode: 0o700 });
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
     writeFileSync(input.provenancePath, JSON.stringify(input.provenance, null, 2) + '\n', 'utf-8');
 }
 /**
@@ -1602,7 +1669,7 @@ function openResultsDir(input) {
  * a maintainer needs in order to see which refine tripped, and a name ending in
  * `.rejected` cannot be mistaken for the artifact a reader came for.
  */
-export function rejectedArtifactPath(path) {
+function rejectedArtifactPath(path) {
     return `${path}.rejected`;
 }
 /**
@@ -1632,7 +1699,7 @@ export function rejectedArtifactPath(path) {
  * everything it declared, so the two fields were numerically identical in all of
  * them and the ONE thing this function exists to keep distinct was unpinned.
  */
-export function gradedCounts(fragments) {
+function gradedCounts(fragments) {
     return fragments.map((f) => ({
         evalId: f.evalId,
         passed: f.expectations.filter((e) => e.passed).length,
@@ -1716,7 +1783,7 @@ function deltaTruncationFor(skipped) {
  * on a run where they can be. A contaminated delta is also diagnostic in its own
  * right: it collapses toward zero, which is corroboration, not noise.
  */
-export function formatBaselineReport(delta, integrity) {
+function formatBaselineReport(delta, integrity) {
     const line = `\n${formatBaselineDeltaLine(delta)}\n`;
     // Any of the three makes the delta unusable-as-stated, and all three are only
     // visible on stderr — nobody opens baseline.json unprompted.
@@ -1724,20 +1791,24 @@ export function formatBaselineReport(delta, integrity) {
         return line;
     return `${line}\n⚠️  ${integrity.summary}\n\n`;
 }
+const IN_PLACE_SUBJECT_FRICTION = {
+    severity: 'low',
+    category: 'path-assumption',
+    message: 'In-place skill (publish: false) — staged from source; links that leave the skill directory are not ' +
+        'present in the harness, so an eval that depends on them tests the skill without them.',
+};
 function writeRunArtifactsAndReconcile(input) {
     const { fragments, runNonce, paths, signals, controlFailures } = input;
     const { withArm, withoutArm } = partitionFragmentsByArm(fragments);
     let baselineReport;
     const grading = mergeFragmentsToGrading(withArm, runNonce, 'with');
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
     writeFileSync(paths.gradingOut, JSON.stringify(grading, null, 2) + '\n', 'utf-8');
-    const friction = mergeFragmentsToFriction(fragments);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
+    const merged = mergeFragmentsToFriction(fragments);
+    const friction = input.subjectInPlace ? { items: [IN_PLACE_SUBJECT_FRICTION, ...merged.items] } : merged;
     writeFileSync(paths.frictionOut, JSON.stringify(friction, null, 2) + '\n', 'utf-8');
     // Tool verdicts come from the WITH arm ONLY — the WITHOUT/skill-absent arm never
     // carries toolExpectations, so its fragments have no `tool` body to merge.
     const toolEval = mergeFragmentsToToolEval(withArm);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
     writeFileSync(paths.toolEvalOut, JSON.stringify(toolEval, null, 2) + '\n', 'utf-8');
     // `controlFailures` is the second disjunct, and it is load-bearing: when EVERY
     // control eval died there are no WITHOUT-arm fragments at all, and gating on the
@@ -1817,7 +1888,6 @@ function writeRunArtifactsAndReconcile(input) {
         // qualifies it would also mean a reader who wants only the lift has to
         // understand the contamination vocabulary first. (GradingReportSchema is
         // .passthrough(), so both extra keys are contract-legal — see the comment above.)
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
         writeFileSync(paths.baselineOut, JSON.stringify({ ...baseline, baselineIntegrity: integrity, baselineDelta: delta }, null, 2) + '\n', 'utf-8');
         // RETURNED, not written. The delta line and the ⚠️ banner must not be separated
         // from each other by the friction report: `emitFrictionReport` runs from the
@@ -1839,28 +1909,28 @@ function writeRunArtifactsAndReconcile(input) {
     };
 }
 /**
- * The COMPOSITE run verdict (issue #145 Phase T): the run passes only when BOTH
+ * The COMPOSITE run verdict: the run passes only when BOTH
  * the prose-expectation grading passed AND every tool-expectation verdict passed.
  * Tool verdicts live in tool-eval.json (a SEPARATE channel — C2); this combines
  * the two at the exit-code layer WITHOUT mixing the channels' data. When no eval
  * declared `toolExpectations`, `toolEval.evals` is empty and this equals
  * `outputAllPassed`. Pure + unit-testable.
  */
-export function computeCompositeVerdict(outputAllPassed, toolEval) {
+function computeCompositeVerdict(outputAllPassed, toolEval) {
     return outputAllPassed && toolEval.evals.every((v) => v.passed);
 }
 /**
  * The run's final pass/fail after cost-tiered fail-fast: the {@link
  * computeCompositeVerdict} of the tiers that RAN, AND no tiers were skipped. A
  * fail-fast run that gated higher tiers is NEVER a pass (skipped ≠ passed) — this
- * forces `false` so the exit code is EvalFailure (4), never downgraded to 0 by the
+ * forces `false` so the exit code is FINDINGS, never downgraded to 0 by the
  * composite path alone. Pure + unit-testable.
  */
-export function resolveCompositeAllPassed(outputAllPassed, toolEval, skipped) {
+function resolveCompositeAllPassed(outputAllPassed, toolEval, skipped) {
     return computeCompositeVerdict(outputAllPassed, toolEval) && skipped === undefined;
 }
 /** Fold one session's `total_cost_usd` into the accumulator; a non-number (mock spawn / missing result) is ignored. */
-export function recordSessionCost(acc, totalCostUsd) {
+function recordSessionCost(acc, totalCostUsd) {
     if (typeof totalCostUsd !== 'number' || !Number.isFinite(totalCostUsd))
         return;
     acc.totalUsd += totalCostUsd;
@@ -1871,7 +1941,7 @@ export function recordSessionCost(acc, totalCostUsd) {
  * when no session reported a cost (e.g. every spawn was a test mock) so the suffix
  * never adds noise to a run with no cost signal. Pure + unit-testable.
  */
-export function formatRunCostSuffix(cost) {
+function formatRunCostSuffix(cost) {
     if (cost === undefined || cost.sessions === 0)
         return '';
     return ` | ≈$${cost.totalUsd.toFixed(2)} across ${cost.sessions} session${cost.sessions === 1 ? '' : 's'}`;
@@ -1883,7 +1953,7 @@ export function formatRunCostSuffix(cost) {
  * verdict failed, a `(N tool)` suffix names how many — so a composite FAIL whose
  * OUTPUT counts look all-green (e.g. `FAIL 3/3 (1 tool)`) is self-explaining. Pure.
  */
-export function buildRunSummary(verdict, toolEval, compositeAllPassed) {
+function buildRunSummary(verdict, toolEval, compositeAllPassed) {
     const base = `${compositeAllPassed ? 'PASS' : 'FAIL'} ${verdict.passed}/${verdict.total}`;
     const toolFailures = toolEval.evals.filter((v) => !v.passed).length;
     return toolFailures > 0 ? `${base} (${toolFailures} tool)` : base;
@@ -1895,7 +1965,7 @@ export function buildRunSummary(verdict, toolEval, compositeAllPassed) {
  * tiers ALWAYS reads FAIL (skipped ≠ passed forces `compositeAllPassed` false at
  * the call site), so the base line is already FAIL when the note is present.
  */
-export function buildRunSummaryWithSkips(verdict, toolEval, compositeAllPassed, skipped, cost) {
+function buildRunSummaryWithSkips(verdict, toolEval, compositeAllPassed, skipped, cost) {
     // The spend suffix rides the verdict line (like `(N tool)`); the skipped-tiers
     // note stays on its own following line.
     const base = buildRunSummary(verdict, toolEval, compositeAllPassed) + formatRunCostSuffix(cost);
@@ -1909,13 +1979,11 @@ export function buildRunSummaryWithSkips(verdict, toolEval, compositeAllPassed,
  * safe precisely because vat always writes these after the merge succeeds.
  */
 function assertVatWroteArtifact(path, validate, label) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
     if (!existsSync(path)) {
         throw new InternalHarnessError(`vat did not write ${label} at ${path} after the merge — harness bug.`);
     }
     let raw;
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
         raw = JSON.parse(readFileSync(path, 'utf-8'));
     }
     catch (err) {
@@ -1938,23 +2006,28 @@ function assertVatWroteArtifact(path, validate, label) {
  * failing, and a cleanup that replaces the real diagnosis with a rename error would
  * be strictly worse than a file left in place. If the rename fails the file is
  * removed instead — an absent artifact reads as "vat wrote nothing", which is at
- * least not a false claim of authority.
+ * least not a false claim of authority. If THAT fails too, the file is still there
+ * under its authoritative name, and the returned clause says so with both errors:
+ * the operator is about to read a CI archive, and a bare '' told them nothing.
  */
 function quarantineArtifact(path) {
     const rejected = rejectedArtifactPath(path);
+    let renameFailure;
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- our own derived results path
         renameSync(path, rejected);
         return `; moved aside to ${rejected} so it is not read as authoritative`;
     }
-    catch {
-        try {
-            rmSync(path, { force: true });
-            return '; removed so it is not read as authoritative';
-        }
-        catch {
-            return '';
-        }
+    catch (err) {
+        renameFailure = err instanceof Error ? err.message : String(err);
+    }
+    try {
+        rmSync(path, { force: true });
+        return '; removed so it is not read as authoritative';
+    }
+    catch (err) {
+        return (`; it could not be moved aside (${renameFailure}) or removed ` +
+            `(${err instanceof Error ? err.message : String(err)}), so it is STILL THERE under its ` +
+            'authoritative name — do not read it as authoritative');
     }
 }
 /**
@@ -1977,7 +2050,7 @@ function quarantineArtifact(path) {
  * baseline and wrote nothing), which is exactly what a fail-CLOSED gate must not do.
  * A non-baseline run writes no baseline.json at all and is not asked about one.
  */
-export function assertVatWroteArtifacts(paths, baselineRun) {
+function assertVatWroteArtifacts(paths, baselineRun) {
     assertVatWroteArtifact(paths.gradingOut, (raw) => { GradingReportSchema.parse(raw); }, 'grading.json');
     assertVatWroteArtifact(paths.frictionOut, (raw) => { FrictionReportSchema.parse(raw); }, 'friction.json');
     assertVatWroteArtifact(paths.toolEvalOut, (raw) => { ToolEvalReportSchema.parse(raw); }, 'tool-eval.json');
@@ -2008,7 +2081,7 @@ export function assertVatWroteArtifacts(paths, baselineRun) {
  * `harnessCreated` is true only for the derived-under-OS-tmp case; an explicit
  * `--out` or `--workdir` is a location the user owns and is never auto-removed.
  */
-export function resolveHarnessLocation(opts) {
+function resolveHarnessLocation(opts) {
     if (opts.out !== undefined && opts.workdir !== undefined) {
         throw new HarnessLocationError('--out and --workdir are mutually exclusive: --out names the harness root exactly, ' +
             '--workdir names the base it is derived under. Pass one.');
@@ -2184,7 +2257,6 @@ export async function runSkillTestHarness(opts) {
         // "can the executor reach the answer key" is not to write it there.
         // Same predicate as `resolveEvalSuitePath`'s rule 1, so the two cannot disagree
         // about which copy this run uses.
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- authored source path resolved from opts
         const authoredSuiteExists = existsSync(resolveScaffoldEvalsPath(opts, repoRoot, evalsRef));
         const stageResult = await stageHarness({
             harnessRoot,
@@ -2204,7 +2276,7 @@ export async function runSkillTestHarness(opts) {
         // staged tree — the answer key must never be reachable by the executor — so this
         // resolves to the AUTHORED source copy, or to the vat-only hold dir when the
         // suite existed nowhere but inside a fetched artifact. Absent from both →
-        // bootstrap a template at the source scaffold and exit 3, so an authored suite
+        // bootstrap a template at the source scaffold and exit 2 with `Reason: bootstrap`, so an authored suite
         // is never overwritten.
         const evalsPath = resolveEvalSuitePath({
             opts,
@@ -2222,7 +2294,8 @@ export async function runSkillTestHarness(opts) {
             const summary = renderPreflightSummary(preflightResult.checks);
             return {
                 harnessPath: harnessRoot,
-                exitCode: SkillTestExitCode.Preflight,
+                exitCode: ExitCode.ERROR,
+                reason: 'preflight',
                 summary: `Preflight failed:\n${summary}`,
             };
         }
@@ -2242,7 +2315,8 @@ export async function runSkillTestHarness(opts) {
         if (!isAcknowledged(opts)) {
             return {
                 harnessPath: harnessRoot,
-                exitCode: SkillTestExitCode.Preflight,
+                exitCode: ExitCode.ERROR,
+                reason: 'preflight',
                 summary: 'Security acknowledgment required. Pass --i-understand-this-runs-skill-code to proceed.',
             };
         }
@@ -2301,7 +2375,7 @@ export async function runSkillTestHarness(opts) {
         if (isDryRun) {
             return {
                 harnessPath: harnessRoot,
-                exitCode: SkillTestExitCode.Ok,
+                exitCode: ExitCode.OK,
                 summary: buildDryRunSummary({
                     wouldBuild: opts.wouldBuild === true,
                     ...(opts.dryRunStagedExistingDist === undefined
@@ -2374,7 +2448,7 @@ export async function runSkillTestHarness(opts) {
             ...(opts.declaredExecutables === undefined ? {} : { declaredExecutables: opts.declaredExecutables }),
             ...(opts.spawn === undefined ? {} : { spawn: opts.spawn }),
         };
-        // Tier-ordered, cost-tiered fail-fast (issue #145 Phase G): run evals tier by
+        // Tier-ordered, cost-tiered fail-fast: run evals tier by
         // tier (ascending / cheapest first), bounded-parallel WITHIN each tier, and
         // gate BETWEEN tiers — once a cheaper tier fails a gating expectation, the
         // higher (more expensive) tiers are SKIPPED (never graded, never passed), so a
@@ -2382,10 +2456,13 @@ export async function runSkillTestHarness(opts) {
         // Each tier is one runPipeline: bounded-parallel, retrying a RateLimitSignal
         // per item. An InternalHarnessError thrown by a TREATMENT-arm executor/grader
         // (timeout/stall/spawn-error, grader failure, missing fragment, nonce mismatch,
-        // declared-count mismatch) propagates OUT unhandled → mapErrorToExitCode →
-        // exit 1; a spawn or grader break is never laundered into a pass/fail verdict
-        // (R1 no-laundering). The same break on the CONTROL arm is recorded and the run
-        // continues — see runEvalWorker for why the two arms are not symmetric.
+        // declared-count mismatch) propagates OUT unhandled → skillTestFailureReason →
+        // ERROR/internal; a spawn or grader break is never laundered into a pass/fail verdict
+        // (R1 no-laundering). The one grader outcome that IS a verdict — a fragment the
+        // model could not write as valid JSON even after one re-grade — fails that eval
+        // (see unparseableGradingFragment). The same break on the CONTROL arm is
+        // recorded and the run continues — see runEvalWorker for why the two arms are
+        // not symmetric.
         const { fragments, controlFailures, skipped } = await runEvalsTiered({
             evals: suite.evals,
             baseline: opts.baseline === true,
@@ -2404,7 +2481,7 @@ export async function runSkillTestHarness(opts) {
         // tool-eval.json (and baseline.json for a baseline run), then reconciles the
         // authoritative prose-expectation verdict from the WITH-arm per-expectation
         // `passed` flags — NOT any self-reported summary. An executor CLEAN failure
-        // reaches here as a FAILing fragment → composite verdict → exit 4.
+        // reaches here as a FAILing fragment → composite verdict → exit FINDINGS.
         const { verdict, toolEval, baselineReport } = writeRunArtifactsAndReconcile({
             fragments,
             runNonce,
@@ -2414,6 +2491,7 @@ export async function runSkillTestHarness(opts) {
             // `skipped` was in scope here and simply not passed, which is how the delta
             // block and its printed line came to describe a truncated run as a complete one.
             skipped,
+            subjectInPlace: opts.subjectInPlace,
         });
         // D2 fail-closed gate: vat is the SOLE writer of results/, so a missing/unparseable/
         // invalid grading.json, friction.json, tool-eval.json — or, on a baseline run,
@@ -2433,10 +2511,10 @@ export async function runSkillTestHarness(opts) {
         emitBaselineReport(baselineReport);
         // Composite verdict: the run passes only when BOTH output expectations AND every
         // tool-expectation verdict passed — so an output all-pass where a `mustRun` never
-        // ran yields FAIL → exit 4. Tool verdicts stay in tool-eval.json (C2); the composite
+        // ran yields FAIL → exit FINDINGS. Tool verdicts stay in tool-eval.json (C2); the composite
         // combines the two channels only here, at the exit-code layer. A fail-fast run
         // that SKIPPED higher tiers is never a pass: skipped ≠ passed forces allPassed
-        // false → exit 4 (never downgraded to 0 by the composite path).
+        // false → exit FINDINGS (never downgraded to 0 by the composite path).
         const allPassed = resolveCompositeAllPassed(verdict.allPassed, toolEval, skipped);
         const summary = buildRunSummaryWithSkips(verdict, toolEval, allPassed, skipped, costAccumulator);
         return {
@@ -2466,4 +2544,62 @@ export async function runSkillTestHarness(opts) {
         cleanup();
     }
 }
+/**
+ * The test-facing seam — every helper the unit tests reach that is NOT part of
+ * this module's API.
+ *
+ * These used to be forty-four separate `export`s, indistinguishable at the export
+ * keyword from the seven names the skill-test barrel actually publishes, so
+ * "is this API?" was a question for a JSDoc rather than a grep. Now it is a
+ * grep: a name here is reachable by a test and by nothing else. Nothing under
+ * `src/` imports `__internal` and no barrel re-exports it — a dev-tools test
+ * holds both lines. Types stay exported on their own: an object cannot carry
+ * them, and a type is not a call site.
+ */
+export const __internal = {
+    assertVatWroteArtifacts,
+    buildContaminationInput,
+    buildContaminationSignalsInput,
+    buildEvalWorkItems,
+    buildFlagParseProbe,
+    buildPreflightInput,
+    buildResolveCtx,
+    buildRunSummary,
+    buildRunSummaryWithSkips,
+    computeCompositeVerdict,
+    detectItemPluginLayout,
+    emitFrictionReport,
+    FLAG_PROBE_SENTINEL,
+    formatBaselineReport,
+    formatRunCostSuffix,
+    gradedCounts,
+    helpTextDeclaresFlag,
+    makeStageItem,
+    mintArmWorkspaceDirs,
+    partitionFragmentsByArm,
+    recordSessionCost,
+    rejectedArtifactPath,
+    removeVatOnlyDir,
+    renderPreflightSummary,
+    resolveArtifactPaths,
+    resolveCompositeAllPassed,
+    resolveHarnessLocation,
+    resolveKnobs,
+    resolvePerEvalWorkspaceDir,
+    resolveScaffoldEvalsPath,
+    resolveSkillContentNeedles,
+    resolveStallMs,
+    resolveTimeoutMs,
+    resolveWorkspacesRoot,
+    RETAINED_RESULTS_DIRNAME,
+    stageWorkspacesForRun,
+    subjectSkillName,
+    swallowCleanupFailure,
+    wipeStaleArtifacts,
+    withoutGraderContamination,
+    cleanupHarness,
+    buildStageItems,
+    resolveGraderOutDir,
+    resolveEvalSuitePath,
+};
 //# sourceMappingURL=run-harness.js.map