@wix/pathgrade 1.0.26 → 1.0.28

package/dist/reporting/core.js

@@ -5,23 +5,25 @@ export function buildPathgradeReport(input) {
     const consolidatedGroups = [];
     const traces = [];
     const summaries = [];
+    const attemptsRequested = input.attemptsRequested ?? 1;
+    const attemptsCompleted = input.attemptsCompleted ?? attemptsRequested;
     const builtGroups = input.groups.map(group => ({
         groupName: group.groupName,
         cases: group.cases.map(toBuiltCase),
     }));
     for (const group of builtGroups) {
-        for (const testCase of group.cases) {
+        for (const testCase of group.cases)
             warnings.push(...testCase.warnings);
-        }
     }
     const reportableGroups = builtGroups
-        .map(group => ({
-        ...group,
-        cases: group.cases.filter(reportableBuiltCase),
-    }))
+        .map(group => ({ ...group, cases: group.cases.filter(reportableBuiltCase) }))
         .filter(group => group.cases.length > 0);
     for (const group of reportableGroups) {
-        const report = buildEvalReport(group.groupName, group.cases);
+        const report = buildEvalReport(group.groupName, group.cases, {
+            attemptsRequested,
+            attemptsCompleted,
+            threshold: input.threshold,
+        });
         summaries.push(buildSummary(group.groupName, group.cases, report));
         const traceFile = `traces/${slug(group.groupName)}.json`;
         traces.push({ traceFile, trials: report.trials });
@@ -30,26 +32,25 @@ export function buildPathgradeReport(input) {
             return rest;
         });
         const { trials: _trials, ...rest } = report;
-        consolidatedGroups.push({
-            ...rest,
-            trials: strippedTrials,
-            trace_file: traceFile,
-        });
+        consolidatedGroups.push({ ...rest, trials: strippedTrials, trace_file: traceFile });
     }
-    const scores = reportableGroups.flatMap(group => group.cases
-        .filter(testCase => testCase.resultKind !== 'synthetic_no_evaluation')
-        .map(testCase => testCase.score)
-        .filter((score) => score !== undefined));
-    const overallPassRate = average(scores);
+    const scores = reportableGroups.flatMap(group => group.cases.flatMap(testCase => (testCase.attempts
+        .filter(attempt => attempt.resultKind !== 'synthetic_no_evaluation')
+        .map(attempt => attempt.score)
+        .filter((score) => score !== undefined))));
+    const overallMeanReward = average(scores);
     const status = input.threshold != null
-        ? (overallPassRate >= input.threshold ? 'pass' : 'fail')
+        ? (overallMeanReward >= input.threshold ? 'pass' : 'fail')
         : (reportableGroups.every(group => group.cases.every(testCase => testCase.state === 'passed')) ? 'pass' : 'fail');
     return {
         report: {
-            version: 1,
+            version: 2,
             timestamp: new Date().toISOString(),
             ...(input.threshold != null ? { threshold: input.threshold } : {}),
-            overall_pass_rate: overallPassRate,
+            attempts_requested: attemptsRequested,
+            attempts_completed: attemptsCompleted,
+            overall_mean_reward: overallMeanReward,
+            overall_pass_rate: overallMeanReward,
             status,
             groups: consolidatedGroups,
             ...(input.selection ? { selection: input.selection } : {}),
@@ -65,139 +66,216 @@ function reportableBuiltCase(testCase) {
     return testCase.state !== 'skipped' && testCase.state !== 'pending';
 }
 function toBuiltCase(testCase) {
-    if (testCase.evaluations === undefined) {
-        return fallbackCase(testCase, []);
-    }
-    if (testCase.evaluations.length === 0) {
-        return fallbackCase(testCase, [
-            `empty results for "${testCase.name}" — evaluate() may not have been called`,
-        ]);
+    const caseId = testCase.caseId ?? `case:${slug(testCase.name)}`;
+    const warnings = [];
+    const attempts = testCase.attempts?.map(attempt => buildAttempt({ testCase, caseId, attempt, warnings }))
+        ?? [buildAttempt({
+                testCase,
+                caseId,
+                attempt: {
+                    attemptId: `${caseId}:attempt-1`,
+                    attemptIndex: 1,
+                    outcome: outcomeForState(testCase.state),
+                    runnerDurationMs: testCase.runnerDurationMs,
+                    ...(testCase.evaluations !== undefined ? { evaluations: testCase.evaluations } : {}),
+                    ...(testCase.diagnostics ? { diagnostics: testCase.diagnostics } : {}),
+                },
+                warnings,
+            })];
+    return { caseId, name: testCase.name, state: testCase.state, attempts, reportable: testCase.reportable, warnings };
+}
+function buildAttempt(input) {
+    const { testCase, caseId, attempt } = input;
+    const evaluations = attempt.evaluations;
+    if (evaluations?.length === 0) {
+        input.warnings.push(`empty results for "${testCase.name}" — evaluate() may not have been called`);
     }
-    // A case can own multiple agents. Preserve the existing "last evaluation"
-    // rule among real evaluations without letting a later synthetic result from
-    // an unevaluated sibling agent erase a legitimate score.
-    const evaluation = testCase.evaluations.findLast(candidate => candidate.resultKind !== 'synthetic_no_evaluation') ?? testCase.evaluations[testCase.evaluations.length - 1];
-    const diagnostics = evaluation.diagnostics
+    const evaluation = terminalEvaluation(evaluations);
+    const diagnostics = evaluation?.diagnostics
+        ?? attempt.diagnostics
         ?? testCase.diagnostics
-        ?? (evaluation.resultKind === 'synthetic_no_evaluation'
-            ? buildDiagnosticsReport({
-                score: undefined,
-                warnings: ['evaluate() was not called; no evaluation score is available'],
-                log: [],
-            })
+        ?? (evaluation?.resultKind === 'synthetic_no_evaluation'
+            ? buildDiagnosticsReport({ score: undefined, warnings: ['evaluate() was not called; no evaluation score is available'], log: [] })
             : undefined);
+    const fallbackScore = attempt.outcome.kind === 'not-run'
+        ? undefined
+        : attempt.outcome.kind === 'passed' ? 1 : 0;
+    const score = evaluation?.score ?? fallbackScore;
     return {
-        name: testCase.name,
-        state: testCase.state,
-        score: evaluation.score,
-        runnerDurationMs: testCase.runnerDurationMs,
+        caseId,
+        attemptId: attempt.attemptId,
+        attemptIndex: attempt.attemptIndex,
+        outcome: attempt.outcome,
+        score: evaluation?.resultKind === 'synthetic_no_evaluation' ? undefined : score,
+        runnerDurationMs: attempt.runnerDurationMs,
         diagnostics,
-        reportable: testCase.reportable,
-        resultKind: evaluation.resultKind,
+        hasTerminalEvaluation: evaluation !== undefined && evaluation.resultKind !== 'synthetic_no_evaluation',
+        resultKind: evaluation?.resultKind,
         trial: normalizeTrial({
+            caseId,
+            attemptId: attempt.attemptId,
+            attemptIndex: attempt.attemptIndex,
             name: testCase.name,
-            score: evaluation.score,
-            runnerDurationMs: testCase.runnerDurationMs,
-            trial: evaluation.trial,
+            score,
+            runnerDurationMs: attempt.runnerDurationMs,
+            trial: evaluation?.trial,
             diagnostics,
-            resultKind: evaluation.resultKind,
-            scoringDurationMs: evaluation.scoringDurationMs,
-            recordedAt: evaluation.recordedAt,
-            agent: evaluation.agent,
+            resultKind: evaluation?.resultKind,
+            scoringDurationMs: evaluation?.scoringDurationMs,
+            recordedAt: evaluation?.recordedAt,
+            agent: evaluation?.agent,
+            runnerOutcome: attempt.outcome.kind,
         }),
-        warnings: [],
     };
 }
-function fallbackCase(testCase, warnings) {
-    const score = testCase.state === 'passed' ? 1 : 0;
-    return {
-        name: testCase.name,
-        state: testCase.state,
-        score,
-        runnerDurationMs: testCase.runnerDurationMs,
-        diagnostics: testCase.diagnostics,
-        reportable: testCase.reportable,
-        trial: normalizeTrial({
-            name: testCase.name,
-            score,
-            runnerDurationMs: testCase.runnerDurationMs,
-            diagnostics: testCase.diagnostics,
-        }),
-        warnings,
-    };
+function terminalEvaluation(evaluations) {
+    if (!evaluations || evaluations.length === 0)
+        return undefined;
+    return evaluations.findLast(candidate => candidate.resultKind !== 'synthetic_no_evaluation')
+        ?? evaluations[evaluations.length - 1];
 }
 function normalizeTrial(input) {
     const base = input.trial ?? {
-        trial_id: 1,
+        trial_id: input.attemptIndex,
         ...(input.score !== undefined ? { reward: input.score } : {}),
-        scorer_results: [],
-        duration_ms: input.runnerDurationMs,
-        n_commands: 0,
-        input_tokens: 0,
-        output_tokens: 0,
-        session_log: [],
+        scorer_results: [], duration_ms: input.runnerDurationMs, n_commands: 0,
+        input_tokens: 0, output_tokens: 0, session_log: [],
     };
     const skills = base.skills_used ?? extractSkillsFromLog(base.session_log);
     const { reward: existingReward, ...baseWithoutReward } = base;
     return {
         ...baseWithoutReward,
-        ...(input.resultKind === 'synthetic_no_evaluation'
-            ? {}
-            : { reward: existingReward ?? input.score }),
+        trial_id: input.attemptIndex,
+        case_id: input.caseId,
+        attempt_id: input.attemptId,
+        attempt_index: input.attemptIndex,
+        runner_outcome: input.runnerOutcome,
+        ...(input.resultKind === 'synthetic_no_evaluation' ? {} : { reward: existingReward ?? input.score }),
         name: input.name,
         duration_ms: base.duration_ms || input.runnerDurationMs,
         diagnostics: input.diagnostics ?? base.diagnostics,
         ...(input.resultKind ? { result_kind: input.resultKind } : {}),
-        ...(input.scoringDurationMs !== undefined
-            ? { scoring_duration_ms: input.scoringDurationMs }
-            : {}),
+        ...(input.scoringDurationMs !== undefined ? { scoring_duration_ms: input.scoringDurationMs } : {}),
         ...(input.recordedAt ? { recorded_at: input.recordedAt } : {}),
         ...(input.agent ? { agent: input.agent } : {}),
         ...(skills.length > 0 ? { skills_used: skills } : {}),
     };
 }
-function buildEvalReport(groupName, cases) {
-    const trials = cases.map((testCase, index) => ({
-        ...testCase.trial,
+function buildEvalReport(groupName, cases, run) {
+    const trials = cases.flatMap(testCase => testCase.attempts).map((attempt, index) => ({
+        ...attempt.trial,
         trial_id: index + 1,
     }));
-    const passRate = average(cases.map(testCase => testCase.state === 'passed' ? 1 : 0));
+    const rewards = cases.flatMap(testCase => testCase.attempts)
+        .filter(attempt => attempt.resultKind !== 'synthetic_no_evaluation')
+        .map(attempt => attempt.score)
+        .filter((score) => score !== undefined);
+    const meanReward = average(rewards);
+    const metrics = binaryMetrics(cases, run);
     const skills = new Set();
-    for (const trial of trials) {
-        for (const skill of trial.skills_used ?? []) {
+    for (const trial of trials)
+        for (const skill of trial.skills_used ?? [])
             skills.add(skill);
-        }
-    }
     return {
         task: groupName,
-        pass_rate: passRate,
-        pass_at_k: 1 - Math.pow(1 - passRate, trials.length),
-        pass_pow_k: Math.pow(passRate, trials.length),
+        status: run.threshold != null
+            ? (meanReward >= run.threshold ? 'pass' : 'fail')
+            : (cases.every(testCase => testCase.state === 'passed') ? 'pass' : 'fail'),
+        mean_reward: meanReward,
+        ...(metrics.successRate !== undefined ? { success_rate: metrics.successRate } : {}),
+        ...(metrics.passAtK ? {
+            pass_at_k: metrics.passAtK,
+            pass_at_k_method: 'finite_sample_unbiased',
+            eligible_case_count: metrics.eligibleCaseCount,
+            attempts_per_case: metrics.attemptsPerCase,
+        } : {}),
+        ...(metrics.unavailableReason ? { pass_at_k_unavailable_reason: metrics.unavailableReason } : {}),
         trials,
         skills_used: [...skills],
     };
 }
+function binaryMetrics(cases, run) {
+    if (run.attemptsCompleted !== run.attemptsRequested)
+        return { unavailableReason: 'incomplete_attempts' };
+    const successesPerCase = [];
+    for (const testCase of cases) {
+        if (testCase.attempts.length !== run.attemptsRequested)
+            return { unavailableReason: 'incomplete_attempts' };
+        let successes = 0;
+        for (const attempt of testCase.attempts) {
+            if (attempt.outcome.kind === 'not-run')
+                return { unavailableReason: 'incomplete_attempts' };
+            if (!attempt.hasTerminalEvaluation)
+                return { unavailableReason: 'incomplete_attempts' };
+            if (attempt.score !== undefined && attempt.score !== 0 && attempt.score !== 1) {
+                return { unavailableReason: 'non_binary_reward' };
+            }
+            if (attempt.outcome.kind === 'passed') {
+                if (attempt.score === undefined)
+                    return { unavailableReason: 'incomplete_attempts' };
+                if (attempt.score === 1)
+                    successes++;
+            }
+        }
+        successesPerCase.push(successes);
+    }
+    const n = run.attemptsRequested;
+    const passAtK = {};
+    for (let k = 1; k <= n; k++) {
+        passAtK[String(k)] = average(successesPerCase.map(successes => finiteSamplePassAtK(n, successes, k)));
+    }
+    const totalSuccesses = successesPerCase.reduce((sum, value) => sum + value, 0);
+    return {
+        successRate: cases.length === 0 ? 0 : totalSuccesses / (cases.length * n),
+        passAtK,
+        eligibleCaseCount: cases.length,
+        attemptsPerCase: n,
+    };
+}
+export function finiteSamplePassAtK(n, successes, k) {
+    if (k < 1 || k > n)
+        throw new RangeError(`k must be in [1, ${n}]`);
+    const failures = n - successes;
+    if (failures < k)
+        return 1;
+    let allFailures = 1;
+    for (let offset = 0; offset < k; offset++)
+        allFailures *= (failures - offset) / (n - offset);
+    return 1 - allFailures;
+}
 function buildSummary(groupName, cases, report) {
+    const attempts = cases.flatMap(testCase => testCase.attempts);
+    const casesById = new Map(cases.map(testCase => [testCase.caseId, testCase]));
     return {
         task: groupName,
-        pass_rate: report.pass_rate,
-        pass_at_k: report.pass_at_k,
-        pass_pow_k: report.pass_pow_k,
-        average_duration_ms: average(cases.map(testCase => testCase.runnerDurationMs)),
-        trial_count: cases.length,
-        diagnostics: cases.flatMap(testCase => testCase.diagnostics
-            ? [{ caseName: testCase.name, state: testCase.state, resultKind: testCase.resultKind, report: testCase.diagnostics }]
-            : []),
+        mean_reward: report.mean_reward ?? 0,
+        ...(report.success_rate !== undefined ? { success_rate: report.success_rate } : {}),
+        ...(typeof report.pass_at_k === 'object' ? { pass_at_k: report.pass_at_k } : {}),
+        ...(report.pass_at_k_unavailable_reason ? { pass_at_k_unavailable_reason: report.pass_at_k_unavailable_reason } : {}),
+        ...(report.attempts_per_case !== undefined ? { attempts_per_case: report.attempts_per_case } : {}),
+        ...(report.eligible_case_count !== undefined ? { eligible_case_count: report.eligible_case_count } : {}),
+        average_duration_ms: average(attempts.map(attempt => attempt.runnerDurationMs)),
+        trial_count: attempts.length,
+        diagnostics: attempts.flatMap(attempt => attempt.diagnostics ? [{
+                caseName: casesById.get(attempt.caseId)?.name ?? attempt.caseId,
+                state: casesById.get(attempt.caseId)?.state ?? 'failed',
+                resultKind: attempt.resultKind,
+                report: attempt.diagnostics,
+            }] : []),
     };
 }
+function outcomeForState(state) {
+    if (state === 'passed')
+        return { kind: 'passed' };
+    if (state === 'failed')
+        return { kind: 'failed' };
+    return { kind: 'not-run', reason: state };
+}
 function average(values) {
     if (values.length === 0)
         return 0;
     return values.reduce((sum, value) => sum + value, 0) / values.length;
 }
 function slug(value) {
-    return value
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '') || 'report';
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'report';
 }

package/dist/reporting/types.d.ts

@@ -1,10 +1,13 @@
 import type { DiagnosticsReport } from '../sdk/diagnostics.js';
 import type { AgentExecutionMetadata, EvaluationResultKind } from '../sdk/types.js';
+import type { AttemptOutcome } from '../runners/model.js';
 import type { PathgradeReport, PathgradeSelectionReport, TrialResult } from '../types.js';
 export type ReportCaseState = 'passed' | 'failed' | 'skipped' | 'pending';
 export interface ReportRunInput {
     threshold?: number;
     selection?: PathgradeSelectionReport;
+    attemptsRequested?: number;
+    attemptsCompleted?: number;
     groups: ReportGroupInput[];
 }
 export interface ReportGroupInput {
@@ -13,6 +16,7 @@ export interface ReportGroupInput {
 }
 export interface ReportCaseInput {
     caseId?: string;
+    repeatKey?: string;
     name: string;
     state: ReportCaseState;
     runnerDurationMs: number;
@@ -22,6 +26,15 @@ export interface ReportCaseInput {
     runnerCaseId?: string;
     reportable?: boolean;
     evaluations?: readonly ReportEvaluationInput[];
+    attempts?: readonly ReportAttemptInput[];
+    diagnostics?: DiagnosticsReport;
+}
+export interface ReportAttemptInput {
+    attemptId: string;
+    attemptIndex: number;
+    outcome: AttemptOutcome;
+    runnerDurationMs: number;
+    evaluations?: readonly ReportEvaluationInput[];
     diagnostics?: DiagnosticsReport;
 }
 export interface ReportEvaluationInput {
@@ -48,9 +61,12 @@ export interface ArtifactWriteResult {
 }
 export interface ReportSummaryGroup {
     task: string;
-    pass_rate: number;
-    pass_at_k: number;
-    pass_pow_k: number;
+    mean_reward: number;
+    success_rate?: number;
+    pass_at_k?: Record<string, number>;
+    pass_at_k_unavailable_reason?: import('../types.js').PassAtKUnavailableReason;
+    attempts_per_case?: number;
+    eligible_case_count?: number;
     average_duration_ms: number;
     trial_count: number;
     diagnostics: ReportSummaryDiagnostics[];

package/dist/runners/adapter-loader.js

@@ -6,6 +6,7 @@ import { createJestAdapter } from '../adapters/jest/runner-adapter.js';
 import { createNodeTestInvocationAdapter } from '../adapters/node-test/invocation-adapter.js';
 import { createVitestInvocationAdapter } from './vitest-invocation.js';
 import { resolveRunnerAdapter } from './selection.js';
+import { withRepeatedAttempts } from './repeated-invocation.js';
 export async function loadRunnerAdapter(input) {
     const name = input.adapterName ?? 'vitest';
     if (name === 'vitest' || name === 'node-test') {
@@ -24,20 +25,24 @@ export async function loadRunnerAdapter(input) {
 }
 export async function loadRunnerInvocationAdapter(input) {
     const name = input.adapterName ?? 'vitest';
+    let adapter;
     if (name === 'vitest')
-        return createVitestInvocationAdapter({ spawnVitest: input.spawnVitest });
-    if (name === 'node-test')
-        return createNodeTestInvocationAdapter({ config: input.config });
-    if (name === 'jest')
-        return createJestInvocationAdapter({ config: input.config });
-    const mod = await importExternalAdapter({
-        adapterName: name,
-        cwd: input.cwd ?? process.cwd(),
-    });
-    if (typeof mod.createPathgradeInvocationAdapter !== 'function') {
-        throw new Error(`Pathgrade adapter package "${adapterPackageSpecifier(name)}" must export createPathgradeInvocationAdapter().`);
+        adapter = createVitestInvocationAdapter({ spawnVitest: input.spawnVitest });
+    else if (name === 'node-test')
+        adapter = createNodeTestInvocationAdapter({ config: input.config });
+    else if (name === 'jest')
+        adapter = createJestInvocationAdapter({ config: input.config });
+    else {
+        const mod = await importExternalAdapter({
+            adapterName: name,
+            cwd: input.cwd ?? process.cwd(),
+        });
+        if (typeof mod.createPathgradeInvocationAdapter !== 'function') {
+            throw new Error(`Pathgrade adapter package "${adapterPackageSpecifier(name)}" must export createPathgradeInvocationAdapter().`);
+        }
+        adapter = mod.createPathgradeInvocationAdapter({ config: input.config });
     }
-    return mod.createPathgradeInvocationAdapter({ config: input.config });
+    return withRepeatedAttempts({ adapter, config: input.config });
 }
 function adapterPackageSpecifier(adapterName) {
     if (adapterName.startsWith('.') || path.isAbsolute(adapterName) || adapterName.includes('/')) {

package/dist/runners/direct-reporter-attempts.d.ts

@@ -0,0 +1 @@
+export declare function assertDirectReporterAttemptsSupported(attempts: number, env: Readonly<NodeJS.ProcessEnv>): void;

package/dist/runners/direct-reporter-attempts.js

@@ -0,0 +1,7 @@
+export function assertDirectReporterAttemptsSupported(attempts, env) {
+    const effectiveAttempts = Number(env.PATHGRADE_ATTEMPT_COUNT);
+    if (attempts <= 1 || effectiveAttempts === 1 || env.PATHGRADE_ATTEMPT_INDEX !== undefined)
+        return;
+    throw new Error(`Pathgrade attempts=${attempts} requires "pathgrade run"; `
+        + 'a direct test-runner reporter cannot restart Jest or Vitest.');
+}

package/dist/runners/invocation.d.ts

@@ -1,5 +1,7 @@
 export interface RunnerInvocationAdapter {
     readonly name: string;
+    readonly supportsRepeatedAttempts?: boolean;
+    readonly writeEmptyReport?: boolean;
     run(input: RunnerInvocationInput): Promise<number>;
 }
 export interface RunnerInvocationInput {

package/dist/runners/model-builders.js

@@ -36,6 +36,7 @@ export function buildNormalizedRunSnapshotFromReportGroups(run, groups) {
                 }));
                 return {
                     id: caseId,
+                    ...(testCase.repeatKey ? { repeatKey: testCase.repeatKey } : {}),
                     runId: `${run.adapterName}:run`,
                     unitId: unitId(group.groupName, groupIndex),
                     name: testCase.name,

package/dist/runners/model-validation.js

@@ -18,6 +18,37 @@ function validateRun(snapshot, completeness, errors) {
     if (!snapshot.model.run.adapterName) {
         errors.push({ path: 'model.run.adapterName', message: 'Run adapterName is required.' });
     }
+    const { attemptsRequested, attemptsCompleted } = snapshot.model.run;
+    if (attemptsRequested === undefined && attemptsCompleted !== undefined) {
+        errors.push({
+            path: 'model.run.attemptsRequested',
+            message: 'attemptsRequested is required when attemptsCompleted is present.',
+        });
+    }
+    if (attemptsCompleted === undefined && attemptsRequested !== undefined) {
+        errors.push({
+            path: 'model.run.attemptsCompleted',
+            message: 'attemptsCompleted is required when attemptsRequested is present.',
+        });
+    }
+    if (attemptsRequested !== undefined && (!Number.isSafeInteger(attemptsRequested) || attemptsRequested < 1)) {
+        errors.push({
+            path: 'model.run.attemptsRequested',
+            message: 'attemptsRequested must be a positive integer.',
+        });
+    }
+    if (attemptsCompleted !== undefined && (!Number.isSafeInteger(attemptsCompleted) || attemptsCompleted < 0)) {
+        errors.push({
+            path: 'model.run.attemptsCompleted',
+            message: 'attemptsCompleted must be a non-negative integer.',
+        });
+    }
+    if (attemptsRequested !== undefined && attemptsCompleted !== undefined && attemptsCompleted > attemptsRequested) {
+        errors.push({
+            path: 'model.run.attemptsCompleted',
+            message: 'attemptsCompleted cannot exceed attemptsRequested.',
+        });
+    }
     if (completeness === 'final' && snapshot.model.run.status === 'parked' && (snapshot.model.run.diagnostics ?? []).length === 0) {
         errors.push({ path: 'model.run.diagnostics', message: 'Final parked snapshots require diagnostics explaining why parked is terminal.' });
     }

package/dist/runners/model.d.ts

@@ -16,6 +16,8 @@ export interface RunRecord {
     id: string;
     adapterName: string;
     status: RunStatus;
+    attemptsRequested?: number;
+    attemptsCompleted?: number;
     diagnostics?: Diagnostic[];
     nativeReferences?: NativeReference[];
 }
@@ -39,6 +41,8 @@ export type ScoringPolicy = {
 };
 export interface RunCaseRecord {
     id: string;
+    /** Adapter-owned semantic identity used only to match this case across runner invocations. */
+    repeatKey?: string;
     runId: string;
     unitId?: string;
     name: string;

package/dist/runners/orchestrator.d.ts

@@ -8,6 +8,8 @@ export interface PathgradeRunOptions {
     runnerArgs: string[];
     env: NodeJS.ProcessEnv;
     artifactRoot: string;
+    /** Child-run handoff path. When set, write only the normalized snapshot. */
+    normalizedSnapshotPath?: string;
     reporterMode?: AdapterReporterMode;
     threshold?: number;
     selection?: PathgradeSelectionReport;

package/dist/runners/orchestrator.js

@@ -1,5 +1,7 @@
 import { buildPathgradeReport } from '../reporting/core.js';
 import { writePathgradeArtifacts } from '../reporting/artifacts.js';
+import path from 'node:path';
+import fs from 'fs-extra';
 import { projectNormalizedRunSnapshotToReportInput } from './report-projection.js';
 export async function runWithAdapter(input) {
     const { adapter, options } = input;
@@ -18,7 +20,15 @@ export async function runWithAdapter(input) {
             signal: options.signal,
         });
         const runExitCode = normalizeRunExitCode(run.status, run.exitCode);
-        const reportInput = projectNormalizedRunSnapshotToReportInput(await adapter.collectNormalizedRunSnapshot(run), { selection });
+        const snapshot = await adapter.collectNormalizedRunSnapshot(run);
+        if (options.normalizedSnapshotPath) {
+            // Projection performs the strict final-snapshot validation before handoff.
+            projectNormalizedRunSnapshotToReportInput(snapshot, { selection });
+            await fs.ensureDir(path.dirname(options.normalizedSnapshotPath));
+            await fs.writeJson(options.normalizedSnapshotPath, snapshot, { spaces: 2 });
+            return runExitCode;
+        }
+        const reportInput = projectNormalizedRunSnapshotToReportInput(snapshot, { selection });
         let built = buildPathgradeReport({
             threshold: options.threshold,
             ...reportInput,

package/dist/runners/repeated-attempts.d.ts

@@ -0,0 +1,7 @@
+import type { NormalizedRunSnapshot } from './model.js';
+export type RepeatAggregationFailure = 'incomplete_attempts' | 'case_identity_mismatch';
+export declare class RepeatAggregationError extends Error {
+    readonly reason: RepeatAggregationFailure;
+    constructor(reason: RepeatAggregationFailure, message: string);
+}
+export declare function mergeRepeatedRunSnapshots(snapshots: readonly NormalizedRunSnapshot[]): NormalizedRunSnapshot;