synergyspec-selfevolving 1.4.0 → 2.1.0

package/dist/core/self-evolution/reward-agent.js

@@ -0,0 +1,940 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { runHeadlessAgent } from './host-harness.js';
+import { readEpisode, episodeDir, writeDiagnosis, advanceEpisodeStage, } from './episode-store.js';
+import { scrub } from '../trajectory/scrub.js';
+export class RewardAgentOutputInvalid extends Error {
+    constructor(message) {
+        super(`reward agent output invalid: ${message}`);
+        this.name = 'RewardAgentOutputInvalid';
+    }
+}
+export class RewardAgentInvocationError extends Error {
+    constructor(stderr) {
+        super(`reward agent invocation failed: ${stderr}`);
+        this.name = 'RewardAgentInvocationError';
+    }
+}
+// ── bounding ───────────────────────────────────────────────────────────────
+// Mirror how learn.ts/skeleton bound things: cap each excerpt so a huge
+// transcript or artifact cannot blow the judge's context. Bounds are generous
+// but finite; truncation appends a visible marker.
+const MAX_TRANSCRIPT_CHARS = 24_000;
+const MAX_ARTIFACT_CHARS = 12_000;
+const TRUNCATION_MARKER = '\n…[truncated]…';
+// P5: transcript bound is HEAD+TAIL (not head-only) so the decisive FINAL test
+// outcome at the end of a long run survives. head + tail = MAX_TRANSCRIPT_CHARS.
+const TRANSCRIPT_HEAD_CHARS = 14_000;
+const TRANSCRIPT_TAIL_CHARS = MAX_TRANSCRIPT_CHARS - TRANSCRIPT_HEAD_CHARS;
+function boundExcerpt(text, max) {
+    if (text.length <= max)
+        return text;
+    return text.slice(0, max - TRUNCATION_MARKER.length) + TRUNCATION_MARKER;
+}
+/**
+ * P5: keep the FIRST {@link TRANSCRIPT_HEAD_CHARS} and the LAST
+ * {@link TRANSCRIPT_TAIL_CHARS} of a transcript with an explicit elision marker
+ * in between — the head-only bound silently dropped the final runner result,
+ * the single most decisive region for a final-verdict judge. Same total budget.
+ */
+function boundTranscriptExcerpt(text) {
+    if (text.length <= MAX_TRANSCRIPT_CHARS)
+        return text;
+    const elided = text.length - TRANSCRIPT_HEAD_CHARS - TRANSCRIPT_TAIL_CHARS;
+    const marker = `\n…[${elided} chars elided]…\n`;
+    // Charge the marker to the tail so head + marker + tail ≤ MAX_TRANSCRIPT_CHARS
+    // exactly (the marker is no longer free overage on top of the budget).
+    const tailLen = Math.max(0, TRANSCRIPT_TAIL_CHARS - marker.length);
+    return text.slice(0, TRANSCRIPT_HEAD_CHARS) + marker + text.slice(text.length - tailLen);
+}
+const PRELUDE = [
+    'You are the 奖励智能体 REWARD AGENT — an LLM AS JUDGE for one episode of a',
+    'self-evolution loop run as in-context RL. Two arms ran the SAME change:',
+    '  - MAIN ARM     — 主智能体 MAIN AGENT, the frozen actor on the current policy vN+1.',
+    '  - BASELINE ARM — CRITIC AGENT（基线智能体 baseline agent）, an agent with the',
+    '                   SAME input/output as the main agent that reran the LAST',
+    '                   episode\'s policy vN on the SAME change.',
+    '',
+    'Your job:',
+    '- CALCULATE 算分 reward(主臂) and reward(基线臂), each a number in [0,1],',
+    '  ANCHORED on the OBJECTIVE EVIDENCE below (tests · health · 轨迹度量 trajectory',
+    '  metrics). The anchors guide the score; the score itself is YOUR judgment.',
+    '- advantage ＝ reward(主臂) − reward(基线臂).',
+    '- FIND errors and NAME gaps, each with a suggested direction — together the',
+    '  文本梯度 textual gradient: a short instruction for how the policy (the design',
+    '  template) should change to close the gap.',
+    '- You NEVER edit any file. You only score and diagnose.',
+    '- 弃权 ABSTAIN when there is NO nameable gap: set "abstained": true, leave',
+    '  "gaps" empty and "textualGradient" null, and give a one-line "abstainReason".',
+    '  Otherwise "abstained" must be false and "textualGradient" must be non-empty.',
+    '',
+    'SCORING RUBRIC — score each arm against these dimensions, in priority order:',
+    '  1. CORRECTNESS (dominant) — does the code pass its tests? A LOWER pass rate',
+    '     CANNOT be outscored by a cleaner/shorter solution. Correctness is a GATE,',
+    '     not one term among many: if one arm has a strictly lower pass rate, its',
+    '     reward MUST be lower and the advantage must point AWAY from it.',
+    '  2. CODE HEALTH — structural erosion (complexity/nesting/duplication).',
+    '  3. VERBOSITY / COMPRESSION — prefer the arm that is NOT bloated or redundant;',
+    '     do NOT reward length. A longer transcript or artifact is not "more thorough".',
+    '  4. TRAJECTORY ECONOMY — fewer wasted tool calls / dead ends, all else equal.',
+    '',
+    'REFERENCE-GROUND your scores: the OBJECTIVE EVIDENCE block below carries the',
+    'measured loss/passRate/health for each arm. Your reward ordering MUST track',
+    'that evidence — if the anchors say one arm is clearly better on correctness,',
+    'your reward for it must be higher. Do NOT let presentation order or length',
+    'move the score.',
+    '',
+    'DROP UNEXPLAINABLE FAILURES: only blame an arm for a failure you can tie to a',
+    'verbatim quoted span in a real file. A failure you cannot explain (flaky,',
+    'environmental, or unrelated to the change) must NOT lower that arm\'s reward.',
+    'But an EXPLAINED failure is still a failure: a real, reproduced test failure',
+    'must lower the arm\'s reward even when its error message makes it understandable.',
+    '',
+    'WEAKNESS-CLASS each gap (optional but encouraged): "forgetting" (the baseline',
+    'did this right and the main arm lost it), "boundary" (edge/limit case),',
+    '"rare" (low-frequency scenario), "logic" (outright wrong), "verbosity"',
+    '(bloat to prune), or "other"; plus a "severity" of "high"|"medium"|"low".',
+    '',
+    'Output contract: emit EXACTLY ONE fenced block tagged `json:diagnosis` and',
+    'nothing else, of the form:',
+    '',
+    '```json:diagnosis',
+    '{"rewardMain": <0..1>, "rewardBaseline": <0..1 | null>,',
+    ' "advantage": <rewardMain − rewardBaseline | null>,',
+    ' "verdict": "main-better"|"baseline-better"|"tie"|"insufficient-signal"|"no-gap",',
+    ' "confidence": <0..1 | null>,',
+    ' "errors": [{"arm": "main"|"baseline", "description": "<what is wrong>",',
+    '             "evidence": {"file": "<path>", "quote": "<verbatim span>"}}],',
+    ' "gaps": [{"file": "<target file>", "section": "<heading | *>",',
+    '           "description": "<the nameable gap>",',
+    '           "weaknessClass": "forgetting"|"boundary"|"rare"|"logic"|"verbosity"|"other",',
+    '           "severity": "high"|"medium"|"low"}],',
+    ' "textualGradient": "<one-paragraph direction | null>",',
+    ' "abstained": <true|false>, "abstainReason": "<only when abstained>"}',
+    '```',
+    '',
+    '"verdict", "confidence", and the per-gap "weaknessClass"/"severity" are',
+    'OPTIONAL — omit any you are unsure of; never invent a value to fill a slot.',
+].join('\n');
+/**
+ * Assemble the 奖励智能体 REWARD AGENT prompt. Pure (no I/O); exported for golden
+ * tests. Ordered blocks:
+ *   1. PRELUDE — the judge contract.
+ *   2. MAIN ARM (主智能体, policy vN+1) — skeleton + bounded transcript excerpt.
+ *   3. BASELINE ARM (CRITIC AGENT（基线智能体）, policy vN) — same; OMITTED
+ *      ENTIRELY when the baseline arm was skipped (a one-line note replaces it,
+ *      demanding null rewardBaseline/advantage).
+ *   4. ARTIFACTS — the 5 artifacts + test-report.md, bounded excerpts.
+ *   5. OBJECTIVE EVIDENCE — both arms' anchors verbatim (the on-disk loss/health
+ *      numbers that anchor the score).
+ */
+export function assembleRewardAgentPrompt(input) {
+    const parts = [PRELUDE, ''];
+    parts.push(`# EPISODE: change=${input.changeName} target=${input.targetId} ` +
+        `policy(main=${fmtVersion(input.policyVersions.main)}, baseline=${fmtVersion(input.policyVersions.baseline)})`, '');
+    // ④ Tamper signal (when computed upstream) — stated BEFORE the arms so the
+    // judge reads it while scoring. Omitted entirely when absent or not suspected.
+    if (input.integrityHint && input.integrityHint.suspected) {
+        parts.push('# ⚠ INTEGRITY SIGNAL — possible test tampering on the MAIN ARM', 'A pre-scoring check flagged that the main arm may have weakened its own', 'tests (e.g. deleted assertions, hard-coded expecteds, skips):', ...input.integrityHint.flags.map((f) => `  - ${f}`), 'Do NOT reward passing tests that were weakened. If the green is bought by', 'gutting the test, the main arm\'s reward must reflect that, not the pass rate.', '');
+    }
+    // 2/3. The two arm blocks, in the requested presentation order (③ order-swap).
+    const mainBlock = () => {
+        const out = [
+            `# MAIN ARM (主智能体 MAIN AGENT, policy v${fmtVersion(input.policyVersions.main)})`,
+            ...renderArmBody(input.mainArm),
+            '',
+        ];
+        return out;
+    };
+    const baselineBlock = () => {
+        if (input.baselineArm === null) {
+            return [
+                '# BASELINE ARM — SKIPPED',
+                'The CRITIC AGENT（基线智能体 baseline agent）did NOT run for this episode',
+                '(no prior policy version in the 版本账本 ledger, or skipped by policy).',
+                'NO comparison is possible: set "rewardBaseline" to null and "advantage" to',
+                'null. Score ONLY the main arm and diagnose against the artifacts below.',
+                '',
+            ];
+        }
+        return [
+            `# BASELINE ARM (CRITIC AGENT（基线智能体 baseline agent）, policy v${fmtVersion(input.policyVersions.baseline)})`,
+            ...renderArmBody(input.baselineArm),
+            '',
+        ];
+    };
+    if (input.armOrder === 'baseline-first') {
+        parts.push(...baselineBlock(), ...mainBlock());
+    }
+    else {
+        parts.push(...mainBlock(), ...baselineBlock());
+    }
+    // P1: the failing-test CONTRAST — which tests each arm failed and the set MAIN
+    // fails that BASELINE passed (the literal regression signal), with a
+    // renamed/edited-test caveat. Order-independent (always after both arms).
+    parts.push(...renderFailingTestContrast(input));
+    // 4. ARTIFACTS ──────────────────────────────────────────────────────────
+    parts.push('# ARTIFACTS (the 5 artifacts + test-report.md, from the change dir)');
+    if (input.artifacts.length === 0) {
+        parts.push('(no artifacts were readable in the change dir)');
+    }
+    else {
+        for (const a of input.artifacts) {
+            parts.push(`<<FILE: ${a.file}>>`, boundExcerpt(a.content, MAX_ARTIFACT_CHARS), '<<END FILE>>', '');
+        }
+    }
+    // 5. OBJECTIVE EVIDENCE ───────────────────────────────────────────────────
+    parts.push('# OBJECTIVE EVIDENCE (anchors — tests · health · 轨迹度量; lower loss is better)');
+    parts.push('main arm objective.json:');
+    parts.push(jsonBlock(scrubObjectiveForPrompt(input.mainArm.objective)));
+    if (input.baselineArm === null) {
+        parts.push('baseline arm objective.json: (none — baseline arm was skipped; rewardBaseline=null, advantage=null)');
+    }
+    else {
+        parts.push('baseline arm objective.json:');
+        parts.push(jsonBlock(scrubObjectiveForPrompt(input.baselineArm.objective)));
+    }
+    parts.push('');
+    parts.push('anchors (mapped):');
+    parts.push(jsonBlock(input.anchors));
+    return parts.join('\n');
+}
+function fmtVersion(v) {
+    return v === null ? 'unknown' : String(v);
+}
+function jsonBlock(value) {
+    return `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
+}
+function renderArmBody(arm) {
+    const out = [];
+    // Score-vs-diagnosis firewall: everything in this arm body (verification line,
+    // skeleton, error tails, plan/effort signals, transcript) is DIAGNOSTIC CONTEXT
+    // for naming gaps — NOT a scoring input. Correctness is set by the passRate /
+    // loss / health anchors in OBJECTIVE EVIDENCE below; an arm with a strictly
+    // lower pass rate must score lower no matter how legible or "deliberate" its
+    // trajectory looks. A high event count is flailing, not thoroughness.
+    out.push('context for the DIAGNOSIS only (does NOT change the correctness gate — anchor scores on OBJECTIVE EVIDENCE):');
+    // P2: verification provenance + truncation magnitude — lets the judge calibrate
+    // confidence on the pass-rate anchor (observed vs self-reported) and discount
+    // trajectory-economy on a truncated long run instead of reading it as flailing.
+    out.push(renderVerificationLine(arm));
+    if (arm.skeleton !== null) {
+        out.push('skeleton.json (action sequence, error tails, plan/effort signals — diagnostic only):');
+        out.push(jsonBlock(arm.skeleton));
+    }
+    else {
+        out.push('skeleton.json: (none)');
+    }
+    if (arm.transcript !== null && arm.transcript.length > 0) {
+        // Scrub the BOUNDED excerpt (cheaper than scrubbing a 200K raw transcript and
+        // the budget is already enforced on the bounded text).
+        out.push('transcript excerpt (secrets redacted):');
+        out.push('```', scrub(boundTranscriptExcerpt(arm.transcript)), '```');
+    }
+    else {
+        out.push('transcript: (none captured)');
+    }
+    return out;
+}
+/** P2: one-line verification + truncation-magnitude summary for an arm. */
+function renderVerificationLine(arm) {
+    const o = arm.objective;
+    const observed = o.testRunObserved === true ? 'yes' : o.testRunObserved === false ? 'no' : 'unknown';
+    const status = o.observedStatus ?? 'null';
+    const verified = o.verified === true ? 'yes' : o.verified === false ? 'no' : 'unknown';
+    const mag = skeletonMagnitude(arm.skeleton);
+    const skel = mag
+        ? mag.truncated
+            ? `${mag.shown} of ${mag.pre} events (truncated)`
+            : `${mag.shown} events`
+        : 'none';
+    const tx = arm.transcript === null || arm.transcript.length === 0
+        ? 'none'
+        : arm.transcript.length > MAX_TRANSCRIPT_CHARS
+            ? `${MAX_TRANSCRIPT_CHARS} of ${arm.transcript.length} chars (head+tail)`
+            : `${arm.transcript.length} chars`;
+    return `verification: tests OBSERVED=${observed} · observedStatus=${status} · passRate VERIFIED=${verified} · skeleton=${skel} · transcript=${tx}`;
+}
+/** Structural read of an arm's persisted ActionSkeleton (typed as opaque object here). */
+function skeletonMagnitude(skeleton) {
+    if (!skeleton || typeof skeleton !== 'object')
+        return null;
+    const s = skeleton;
+    const shown = Array.isArray(s.events) ? s.events.length : 0;
+    const pre = typeof s.preTruncationEventCount === 'number' ? s.preTruncationEventCount : shown;
+    return { shown, pre, truncated: s.truncated === true };
+}
+/**
+ * Redact secrets out of an objective before its JSON is dumped into the prompt —
+ * the only free-text field is `observedFailures` (testId/assertion parsed from
+ * raw runner output, which can echo a credential). Numeric/enum fields are left
+ * as-is. Returns the same object unchanged when there is nothing to scrub.
+ */
+function scrubObjectiveForPrompt(obj) {
+    if (!obj.observedFailures || obj.observedFailures.length === 0)
+        return obj;
+    return {
+        ...obj,
+        observedFailures: obj.observedFailures.map((f) => ({
+            testId: scrub(f.testId),
+            ...(f.file !== undefined ? { file: f.file } : {}),
+            ...(f.assertion !== undefined ? { assertion: scrub(f.assertion) } : {}),
+        })),
+    };
+}
+/** POSIX file paths the arm EDITED, read from its persisted skeleton's file-edit events. */
+function editedFilesFromSkeleton(skeleton) {
+    const set = new Set();
+    if (!skeleton || typeof skeleton !== 'object')
+        return set;
+    const events = skeleton.events;
+    if (!Array.isArray(events))
+        return set;
+    for (const ev of events) {
+        if (ev && typeof ev === 'object') {
+            const e = ev;
+            if (e.kind === 'file-edit' && typeof e.file === 'string')
+                set.add(e.file);
+        }
+    }
+    return set;
+}
+/**
+ * P1: a CONTRASTED failing-test block — the literal regression signal a paired
+ * judge needs. Lists each arm's parsed failing tests and the set MAIN fails that
+ * BASELINE passed, with a renamed/edited-test CAVEAT (a main-only failure whose
+ * test file the main arm edited is a LEAD, not a confirmed regression). Rendered
+ * only when at least one arm parsed failures (keeps the prompt stable otherwise).
+ */
+function renderFailingTestContrast(input) {
+    const main = input.mainArm.objective.observedFailures ?? [];
+    const baseline = input.baselineArm?.objective.observedFailures ?? [];
+    if (main.length === 0 && baseline.length === 0)
+        return [];
+    // testIds + assertion lines come from raw runner output — scrub them too (a
+    // parametrized id or an assertion echoing a credential could otherwise leak).
+    const ids = (fs) => fs.length > 0 ? fs.map((f) => scrub(f.testId)).join(', ') : '(none)';
+    const out = [
+        '# FAILING-TEST CONTRAST (parsed from OBSERVED runner output — may be incomplete)',
+        'Diagnostic context only: this sharpens the gap you name; it must NOT soften the correctness penalty.',
+        'An explained, reproduced failure is still a failure — a strictly lower pass rate must score lower.',
+        `MAIN failing tests (${main.length}): ${ids(main)}`,
+    ];
+    if (input.baselineArm === null) {
+        out.push('BASELINE failing tests: (baseline arm skipped — no contrast possible)');
+        out.push('');
+        return out;
+    }
+    out.push(`BASELINE failing tests (${baseline.length}): ${ids(baseline)}`);
+    const baselineIds = new Set(baseline.map((f) => f.testId));
+    const editedByMain = editedFilesFromSkeleton(input.mainArm.skeleton);
+    const newlyFailing = main.filter((f) => !baselineIds.has(f.testId));
+    if (newlyFailing.length === 0) {
+        out.push('newly-failing in MAIN: (none — nothing fails in main that the baseline passed)');
+    }
+    else {
+        out.push('newly-failing in MAIN (possible regression vs the baseline):');
+        for (const f of newlyFailing) {
+            const renamed = f.file !== undefined && editedByMain.has(f.file);
+            const caveat = renamed
+                ? ' (⚠ this test file was EDITED by the main arm — possibly renamed/changed, NOT a confirmed regression)'
+                : '';
+            out.push(`  - ${scrub(f.testId)}${caveat}${f.assertion ? ` — ${scrub(f.assertion)}` : ''}`);
+        }
+    }
+    out.push('');
+    return out;
+}
+/**
+ * Parse the judge's `json:diagnosis` block with a strict one-block discipline:
+ * exactly one fenced block, well-formed JSON, then fail-closed shape + range
+ * validation.
+ *
+ * Throws {@link RewardAgentOutputInvalid} on any violation (the repair loop
+ * re-prompts with the concrete message appended).
+ */
+export function parseRewardAgentResponse(text) {
+    const fenceRe = /```json:diagnosis\s*([\s\S]*?)```/g;
+    const matches = [];
+    let m;
+    while ((m = fenceRe.exec(text)) !== null)
+        matches.push(m[1]);
+    if (matches.length === 0) {
+        throw new RewardAgentOutputInvalid('no `json:diagnosis` fenced block found in response');
+    }
+    if (matches.length > 1) {
+        throw new RewardAgentOutputInvalid(`expected exactly 1 \`json:diagnosis\` block, found ${matches.length}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(matches[0].trim());
+    }
+    catch (err) {
+        throw new RewardAgentOutputInvalid(`failed to parse JSON inside diagnosis block: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new RewardAgentOutputInvalid('diagnosis block must be a JSON object');
+    }
+    const o = parsed;
+    const rewardMain = requireReward(o.rewardMain, 'rewardMain');
+    const rewardBaseline = requireRewardOrNull(o.rewardBaseline, 'rewardBaseline');
+    const advantage = requireFiniteOrNull(o.advantage, 'advantage');
+    const errors = parseErrors(o.errors);
+    const gaps = parseGaps(o.gaps);
+    const textualGradient = parseTextualGradient(o.textualGradient);
+    if (typeof o.abstained !== 'boolean') {
+        throw new RewardAgentOutputInvalid('"abstained" must be a boolean');
+    }
+    const abstained = o.abstained;
+    let abstainReason;
+    if (o.abstainReason !== undefined) {
+        if (typeof o.abstainReason !== 'string') {
+            throw new RewardAgentOutputInvalid('"abstainReason" must be a string when present');
+        }
+        abstainReason = o.abstainReason;
+    }
+    const verdict = parseVerdict(o.verdict);
+    const confidence = parseConfidence(o.confidence);
+    // Abstain semantics: abstained ⇒ no gaps and no gradient; not abstained ⇒
+    // a non-empty gradient is required (a score with no direction is useless).
+    if (abstained) {
+        if (gaps.length > 0) {
+            throw new RewardAgentOutputInvalid('abstained=true requires an EMPTY "gaps" array (no nameable gap)');
+        }
+        if (textualGradient !== null) {
+            throw new RewardAgentOutputInvalid('abstained=true requires "textualGradient": null (no direction when abstaining)');
+        }
+    }
+    else {
+        if (textualGradient === null || textualGradient.length === 0) {
+            throw new RewardAgentOutputInvalid('abstained=false requires a non-empty "textualGradient"');
+        }
+    }
+    return {
+        rewardMain,
+        rewardBaseline,
+        advantage,
+        errors,
+        gaps,
+        textualGradient,
+        abstained,
+        ...(abstainReason !== undefined ? { abstainReason } : {}),
+        ...(verdict !== undefined ? { verdict } : {}),
+        ...(confidence !== undefined ? { confidence } : {}),
+    };
+}
+const VERDICT_VALUES = [
+    'main-better',
+    'baseline-better',
+    'tie',
+    'insufficient-signal',
+    'no-gap',
+];
+function parseVerdict(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'string' || !VERDICT_VALUES.includes(raw)) {
+        throw new RewardAgentOutputInvalid(`"verdict" must be one of ${VERDICT_VALUES.map((v) => `'${v}'`).join(', ')} when present`);
+    }
+    return raw;
+}
+function parseConfidence(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === null)
+        return null;
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0 || raw > 1) {
+        throw new RewardAgentOutputInvalid('"confidence" must be a number in [0,1] or null when present');
+    }
+    return raw;
+}
+function requireReward(v, field) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new RewardAgentOutputInvalid(`"${field}" must be a finite number in [0,1]`);
+    }
+    if (v < 0 || v > 1) {
+        throw new RewardAgentOutputInvalid(`"${field}" must be within [0,1], got ${v}`);
+    }
+    return v;
+}
+function requireRewardOrNull(v, field) {
+    if (v === null)
+        return null;
+    return requireReward(v, field);
+}
+function requireFiniteOrNull(v, field) {
+    if (v === null)
+        return null;
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new RewardAgentOutputInvalid(`"${field}" must be a finite number or null`);
+    }
+    return v;
+}
+function parseErrors(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new RewardAgentOutputInvalid('"errors" must be an array');
+    }
+    return raw.map((e, i) => {
+        if (!e || typeof e !== 'object') {
+            throw new RewardAgentOutputInvalid(`errors[${i}] must be an object`);
+        }
+        const arm = e.arm;
+        if (arm !== 'main' && arm !== 'baseline') {
+            throw new RewardAgentOutputInvalid(`errors[${i}].arm must be 'main' or 'baseline'`);
+        }
+        const description = e.description;
+        if (typeof description !== 'string' || description.length === 0) {
+            throw new RewardAgentOutputInvalid(`errors[${i}].description must be a non-empty string`);
+        }
+        const evidence = e.evidence;
+        if (!evidence || typeof evidence !== 'object') {
+            throw new RewardAgentOutputInvalid(`errors[${i}].evidence must be an object`);
+        }
+        const file = evidence.file;
+        const quote = evidence.quote;
+        if (typeof file !== 'string' || typeof quote !== 'string') {
+            throw new RewardAgentOutputInvalid(`errors[${i}].evidence must have string "file" and string "quote"`);
+        }
+        return { arm, description, evidence: { file, quote } };
+    });
+}
+function parseGaps(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new RewardAgentOutputInvalid('"gaps" must be an array');
+    }
+    return raw.map((g, i) => {
+        if (!g || typeof g !== 'object') {
+            throw new RewardAgentOutputInvalid(`gaps[${i}] must be an object`);
+        }
+        const file = g.file;
+        const section = g.section;
+        const description = g.description;
+        if (typeof file !== 'string' || file.length === 0) {
+            throw new RewardAgentOutputInvalid(`gaps[${i}].file must be a non-empty string`);
+        }
+        if (typeof section !== 'string' || section.length === 0) {
+            throw new RewardAgentOutputInvalid(`gaps[${i}].section must be a non-empty string (a heading, or '*')`);
+        }
+        if (typeof description !== 'string' || description.length === 0) {
+            throw new RewardAgentOutputInvalid(`gaps[${i}].description must be a non-empty string`);
+        }
+        const weaknessClass = parseWeaknessClass(g.weaknessClass, i);
+        const severity = parseSeverity(g.severity, i);
+        return {
+            file,
+            section,
+            description,
+            ...(weaknessClass !== undefined ? { weaknessClass } : {}),
+            ...(severity !== undefined ? { severity } : {}),
+        };
+    });
+}
+const WEAKNESS_VALUES = [
+    'forgetting',
+    'boundary',
+    'rare',
+    'logic',
+    'verbosity',
+    'other',
+];
+const SEVERITY_VALUES = ['high', 'medium', 'low'];
+function parseWeaknessClass(raw, i) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'string' || !WEAKNESS_VALUES.includes(raw)) {
+        throw new RewardAgentOutputInvalid(`gaps[${i}].weaknessClass must be one of ${WEAKNESS_VALUES.map((v) => `'${v}'`).join(', ')} when present`);
+    }
+    return raw;
+}
+function parseSeverity(raw, i) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'string' || !SEVERITY_VALUES.includes(raw)) {
+        throw new RewardAgentOutputInvalid(`gaps[${i}].severity must be one of 'high', 'medium', 'low' when present`);
+    }
+    return raw;
+}
+function parseTextualGradient(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw !== 'string') {
+        throw new RewardAgentOutputInvalid('"textualGradient" must be a string or null');
+    }
+    const trimmed = raw.trim();
+    return trimmed.length === 0 ? null : trimmed;
+}
+// ── anchor mapping (defensive against both objective shapes) ─────────────────
+function numberOrNull(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+/** Map an arm's objective to its (loss, passRate, healthPenalty, verbosity) anchors. */
+export function mapArmAnchors(objective) {
+    if (!objective || typeof objective !== 'object') {
+        return { loss: null, passRate: null, healthPenalty: null, verbosity: null };
+    }
+    // loss: flat number (CRITIC AGENT) OR nested PerChangeLoss.loss (MAIN ARM).
+    let loss = null;
+    if (typeof objective.loss === 'number') {
+        loss = numberOrNull(objective.loss);
+    }
+    else if (objective.loss && typeof objective.loss === 'object') {
+        loss = numberOrNull(objective.loss.loss);
+    }
+    // passRate: flat (CRITIC AGENT) OR testMetrics.passRate (MAIN ARM FitnessSample).
+    let passRate = numberOrNull(objective.passRate);
+    if (passRate === null && objective.testMetrics && typeof objective.testMetrics === 'object') {
+        passRate = numberOrNull(objective.testMetrics.passRate);
+    }
+    // healthPenalty: flat (CRITIC AGENT) OR healthSignal / loss.healthPenalty (MAIN ARM).
+    let healthPenalty = numberOrNull(objective.healthPenalty);
+    if (healthPenalty === null) {
+        healthPenalty = numberOrNull(objective.healthSignal);
+    }
+    if (healthPenalty === null &&
+        objective.loss &&
+        typeof objective.loss === 'object') {
+        healthPenalty = numberOrNull(objective.loss.healthPenalty);
+    }
+    // verbosity: the separable verbosity sub-signal, when the capture provides it
+    // (flat `verbosity`, or nested under a `health`/`healthDetail` block). Null
+    // when absent — the rubric then judges verbosity from the artifacts alone.
+    let verbosity = numberOrNull(objective.verbosity);
+    if (verbosity === null && objective.health && typeof objective.health === 'object') {
+        verbosity = numberOrNull(objective.health.verbosity);
+    }
+    return { loss, passRate, healthPenalty, verbosity };
+}
+/** Build the {@link DiagnosisAnchors} block from both arms' objectives. */
+export function buildAnchors(mainObjective, baselineObjective) {
+    const main = mapArmAnchors(mainObjective);
+    const baseline = baselineObjective === null
+        ? { loss: null, passRate: null, healthPenalty: null, verbosity: null }
+        : mapArmAnchors(baselineObjective);
+    return {
+        mainLoss: main.loss,
+        baselineLoss: baseline.loss,
+        mainPassRate: main.passRate,
+        baselinePassRate: baseline.passRate,
+        mainHealthPenalty: main.healthPenalty,
+        baselineHealthPenalty: baseline.healthPenalty,
+        ...(main.verbosity !== null ? { mainVerbosity: main.verbosity } : {}),
+        ...(baseline.verbosity !== null ? { baselineVerbosity: baseline.verbosity } : {}),
+    };
+}
+// ── episode / arm reading ────────────────────────────────────────────────
+const SKELETON_JSON_FILE = 'skeleton.json';
+const OBJECTIVE_JSON_FILE = 'objective.json';
+/** The transcript filename convention, in priority order (main arm jsonl, baseline stdout). */
+const TRANSCRIPT_FILE_CANDIDATES = ['transcript.jsonl', 'stdout.txt'];
+/** The 5 artifacts + test-report.md, in the order they appear in the prompt. */
+const CHANGE_DIR_ARTIFACTS = [
+    'proposal.md',
+    'usecases.md',
+    'design.md',
+    'tasks.md',
+    'spec-tests.md',
+    'test-report.md',
+];
+async function readFileIfExists(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+async function readJsonIfExists(filePath) {
+    const raw = await readFileIfExists(filePath);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new RewardAgentOutputInvalid(`unreadable ${path.basename(filePath)}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Read one arm's skeleton + transcript + objective from `<episodeDir>/<arm>/`. */
+async function readArmCapture(repoRoot, episodeId, arm) {
+    const armDir = path.join(episodeDir(repoRoot, episodeId), arm);
+    const skeletonRaw = await readJsonIfExists(path.join(armDir, SKELETON_JSON_FILE));
+    const skeleton = skeletonRaw && typeof skeletonRaw === 'object' ? skeletonRaw : null;
+    let transcript = null;
+    for (const fileName of TRANSCRIPT_FILE_CANDIDATES) {
+        transcript = await readFileIfExists(path.join(armDir, fileName));
+        if (transcript !== null)
+            break;
+    }
+    const objectiveRaw = await readJsonIfExists(path.join(armDir, OBJECTIVE_JSON_FILE));
+    if (objectiveRaw === null) {
+        throw new RewardAgentOutputInvalid(`missing ${OBJECTIVE_JSON_FILE} for ${arm} of episode ${episodeId} — cannot score`);
+    }
+    if (typeof objectiveRaw !== 'object') {
+        throw new RewardAgentOutputInvalid(`${arm} ${OBJECTIVE_JSON_FILE} for episode ${episodeId} must be a JSON object`);
+    }
+    return { skeleton, transcript, objective: objectiveRaw };
+}
+/** Read the 5 artifacts + test-report.md (those that exist) from the change dir. */
+async function readChangeArtifacts(changeDirPath) {
+    const out = [];
+    for (const file of CHANGE_DIR_ARTIFACTS) {
+        const content = await readFileIfExists(path.join(changeDirPath, file));
+        if (content !== null)
+            out.push({ file, content });
+    }
+    return out;
+}
+async function invokeRewardAgent(opts) {
+    // Single attempt, delegated to the host-aware headless runner (sibling of the
+    // 演进智能体 EVOLVING AGENT — never parent-child; each fresh-context spawn). One
+    // retry on invocation failure, then throw — mirrors the proposer agent's
+    // invoke contract.
+    const attempt = async () => await runHeadlessAgent(opts.prompt, {
+        cwd: opts.repoRoot,
+        spawn: opts.spawn,
+        binaryOverride: opts.binary,
+    });
+    const first = await attempt();
+    if (first.exitCode === 0 && first.stdout.length > 0)
+        return first.stdout;
+    const second = await attempt();
+    if (second.exitCode === 0 && second.stdout.length > 0)
+        return second.stdout;
+    throw new RewardAgentInvocationError(second.stderr || first.stderr);
+}
+/**
+ * Score ONE judged duel: spawn the judge (fresh context), parse with the bounded
+ * repair loop (re-prompting with the concrete error appended), recompute and
+ * validate the advantage (incl. ① gate-not-blend), and compute ④ integrity
+ * signals. Does NOT write `diagnosis.json` — the caller (single-sample
+ * {@link runRewardAgent}, or the statistical aggregator) owns the write. This is
+ * the unit the aggregator calls k times for the A/A noise floor + SPRT.
+ */
+export async function scoreOnce(opts) {
+    const maxRepairAttempts = Math.max(0, opts.maxRepairAttempts ?? 2);
+    const anchors = opts.promptInput.anchors;
+    const basePrompt = assembleRewardAgentPrompt(opts.promptInput);
+    let feedback = null;
+    for (let attempt = 0;; attempt++) {
+        const prompt = feedback === null
+            ? basePrompt
+            : `${basePrompt}\n\n# PREVIOUS ATTEMPT FAILED VALIDATION\n${feedback}\n` +
+                'Re-emit EXACTLY ONE ```json:diagnosis fenced block matching the contract above. ' +
+                'When the baseline arm was skipped, "rewardBaseline" and "advantage" must both be null.';
+        const stdout = await invokeRewardAgent({
+            prompt,
+            repoRoot: opts.repoRoot,
+            spawn: opts.spawn,
+            binary: opts.binary,
+        });
+        try {
+            const parsed = parseRewardAgentResponse(stdout);
+            validateAgainstEpisode(parsed, opts.baselineSkipped, anchors);
+            const integrity = computeIntegrity(parsed, anchors, opts.promptInput.integrityHint ?? null);
+            return { parsed, integrity };
+        }
+        catch (err) {
+            if (err instanceof RewardAgentOutputInvalid && attempt < maxRepairAttempts) {
+                feedback = err.message;
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+/**
+ * Load everything the judge needs to score one episode WITHOUT spawning: read
+ * the episode + both arms (baseline omitted when skipped), map anchors, and read
+ * the change artifacts. Shared by {@link runRewardAgent} (single sample) and the
+ * statistical aggregator (which calls {@link scoreOnce} k times over the same
+ * context with swapped `armOrder`).
+ */
+export async function loadRewardScoringContext(repoRoot, episodeId) {
+    const episode = await readEpisode(repoRoot, episodeId);
+    // The baseline arm is SKIPPED exactly when the episode recorded it as such.
+    const baselineSkipped = episode.stage === 'baseline-skipped' ||
+        episode.stageHistory.some((h) => h.stage === 'baseline-skipped');
+    const mainArm = await readArmCapture(repoRoot, episodeId, 'main-arm');
+    const baselineArm = baselineSkipped
+        ? null
+        : await readArmCapture(repoRoot, episodeId, 'baseline-arm');
+    const anchors = buildAnchors(mainArm.objective, baselineArm?.objective ?? null);
+    const artifacts = await readChangeArtifacts(episode.changeDirPath);
+    const promptInput = {
+        changeName: episode.changeName,
+        targetId: episode.targetId,
+        policyVersions: {
+            main: episode.policyVersionMain,
+            baseline: episode.policyVersionBaseline,
+        },
+        mainArm,
+        baselineArm,
+        artifacts,
+        anchors,
+    };
+    return { episode, baselineSkipped, promptInput };
+}
+/**
+ * Run the 奖励智能体 REWARD AGENT end-to-end for one episode (single sample):
+ *   1. read the episode + both arms (baseline omitted when skipped),
+ *   2. map anchors and assemble the prompt,
+ *   3. {@link scoreOnce} — spawn the judge, parse with the bounded repair loop,
+ *      recompute/validate the advantage (incl. ① gate-not-blend), compute ④
+ *      integrity,
+ *   4. derive the ⑤ single-sample verdict and write `diagnosis.json` (schema 2)
+ *      via {@link writeDiagnosis}, then advance the episode stage to `scored`.
+ *
+ * Behaviour is byte-compatible with the historical single-call path: no extra
+ * spawns, `armOrder` defaults to `main-first`, and the new schema-2 fields are
+ * OPTIONAL (a reader that ignores them sees the same diagnosis). The statistical
+ * layer (Batch 3) wraps {@link scoreOnce} instead of calling this directly.
+ *
+ * The ONLY write path is the episode dir. Invocation errors (agent crash) are
+ * NOT repaired — they propagate as {@link RewardAgentInvocationError}.
+ */
+export async function runRewardAgent(opts) {
+    const { repoRoot, episodeId } = opts;
+    const { episode, baselineSkipped, promptInput } = await loadRewardScoringContext(repoRoot, episodeId);
+    const { parsed, integrity } = await scoreOnce({
+        promptInput,
+        baselineSkipped,
+        repoRoot,
+        spawn: opts.spawn,
+        binary: opts.binary,
+        maxRepairAttempts: opts.maxRepairAttempts,
+    });
+    const verdict = deriveSingleSampleVerdict(parsed);
+    const diagnosis = {
+        schemaVersion: 2,
+        episodeId: episode.episodeId,
+        changeName: episode.changeName,
+        targetId: episode.targetId,
+        policyVersions: {
+            main: episode.policyVersionMain,
+            baseline: episode.policyVersionBaseline,
+        },
+        rewardMain: parsed.rewardMain,
+        rewardBaseline: parsed.rewardBaseline,
+        advantage: parsed.advantage,
+        anchors: promptInput.anchors,
+        errors: parsed.errors,
+        gaps: parsed.gaps,
+        textualGradient: parsed.textualGradient,
+        abstained: parsed.abstained,
+        ...(parsed.abstainReason !== undefined ? { abstainReason: parsed.abstainReason } : {}),
+        ...(verdict !== undefined ? { verdict } : {}),
+        ...(parsed.confidence !== undefined ? { confidence: parsed.confidence } : {}),
+        integrity,
+    };
+    const diagnosisPath = await writeDiagnosis({ repoRoot, episodeId, diagnosis });
+    const advanced = await advanceEpisodeStage({
+        repoRoot,
+        episodeId,
+        stage: 'scored',
+        patch: { advantage: diagnosis.advantage },
+    });
+    return { diagnosis, diagnosisPath, episode: advanced };
+}
+/**
+ * Derive the ⑤ single-sample verdict. A judge-emitted `verdict` wins; otherwise
+ * it is read off the advantage sign (no-gap when abstained; undefined when the
+ * baseline was skipped and only the main arm was scored). The statistical layer
+ * overrides this with `insufficient-signal` when the advantage is within the
+ * A/A noise floor.
+ */
+export function deriveSingleSampleVerdict(parsed) {
+    if (parsed.verdict !== undefined)
+        return parsed.verdict;
+    if (parsed.abstained)
+        return 'no-gap';
+    if (parsed.advantage === null)
+        return undefined;
+    if (parsed.advantage > 1e-9)
+        return 'main-better';
+    if (parsed.advantage < -1e-9)
+        return 'baseline-better';
+    return 'tie';
+}
+/**
+ * Beyond this much sign-flipped disagreement between the judge's advantage and
+ * the loss-implied advantage, ④ raises a divergence flag (the judge loved an arm
+ * the verifier dislikes). The number itself is always recorded when computable.
+ */
+const DIVERGENCE_FLAG_TOLERANCE = 0.2;
+/** ④ Compute integrity signals from a parsed duel, its anchors, and the tamper hint. */
+export function computeIntegrity(parsed, anchors, integrityHint) {
+    const flags = [];
+    let judgeVerifierDivergence = null;
+    if (parsed.advantage !== null && anchors.mainLoss !== null && anchors.baselineLoss !== null) {
+        // lower loss is better, so the verifier prefers the main arm by (baseline − main).
+        const lossImpliedAdvantage = anchors.baselineLoss - anchors.mainLoss;
+        judgeVerifierDivergence = parsed.advantage - lossImpliedAdvantage;
+        const judgeSign = Math.sign(parsed.advantage);
+        const verifierSign = Math.sign(lossImpliedAdvantage);
+        if (judgeSign !== 0 &&
+            verifierSign !== 0 &&
+            judgeSign !== verifierSign &&
+            Math.abs(judgeVerifierDivergence) > DIVERGENCE_FLAG_TOLERANCE) {
+            flags.push(`judge⇄verifier divergence: judge advantage ${parsed.advantage.toFixed(3)} disagrees in ` +
+                `sign with loss-implied ${lossImpliedAdvantage.toFixed(3)}`);
+        }
+    }
+    const testTamperSuspected = integrityHint?.suspected ?? false;
+    if (testTamperSuspected && integrityHint) {
+        for (const f of integrityHint.flags)
+            flags.push(`tamper: ${f}`);
+    }
+    return { testTamperSuspected, judgeVerifierDivergence, flags };
+}
+/**
+ * Cross-check the parsed diagnosis against the episode's baseline state and
+ * RECOMPUTE the advantage. advantage ＝ reward(主臂) − reward(基线臂); a claimed
+ * advantage that disagrees with the recomputation by more than 1e-9 is a
+ * repairable {@link RewardAgentOutputInvalid}. When the baseline was skipped,
+ * rewardBaseline and advantage must both be null (no comparison possible).
+ *
+ * ① gate-not-blend: when both pass rates are known and the MAIN arm's is
+ * strictly lower, the advantage must be ≤ 0 — a correctness regression cannot be
+ * outscored by cleaner/shorter code. Repairable.
+ */
+function validateAgainstEpisode(parsed, baselineSkipped, anchors) {
+    if (baselineSkipped) {
+        if (parsed.rewardBaseline !== null) {
+            throw new RewardAgentOutputInvalid('baseline arm was skipped — "rewardBaseline" must be null (no comparison possible)');
+        }
+        if (parsed.advantage !== null) {
+            throw new RewardAgentOutputInvalid('baseline arm was skipped — "advantage" must be null (no comparison possible)');
+        }
+        return;
+    }
+    // Baseline ran: a numeric rewardBaseline is required to compute the advantage.
+    if (parsed.rewardBaseline === null) {
+        throw new RewardAgentOutputInvalid('baseline arm RAN — "rewardBaseline" must be a number in [0,1], not null');
+    }
+    if (parsed.advantage === null) {
+        throw new RewardAgentOutputInvalid('baseline arm RAN — "advantage" must be a number (rewardMain − rewardBaseline), not null');
+    }
+    const recomputed = parsed.rewardMain - parsed.rewardBaseline;
+    if (Math.abs(recomputed - parsed.advantage) > 1e-9) {
+        throw new RewardAgentOutputInvalid(`advantage mismatch: claimed ${parsed.advantage}, but rewardMain − rewardBaseline = ` +
+            `${parsed.rewardMain} − ${parsed.rewardBaseline} = ${recomputed} ` +
+            '(advantage ＝ reward(主臂) − reward(基线臂))');
+    }
+    // ① gate-not-blend: a strictly lower MAIN pass rate cannot net a positive advantage.
+    const { mainPassRate, baselinePassRate } = anchors;
+    if (mainPassRate !== null &&
+        baselinePassRate !== null &&
+        mainPassRate < baselinePassRate &&
+        parsed.advantage > 1e-9) {
+        throw new RewardAgentOutputInvalid(`gate-not-blend: main pass rate ${mainPassRate} < baseline ${baselinePassRate}, so ` +
+            `advantage must be <= 0 (a correctness regression cannot be outscored by cleaner code), ` +
+            `got ${parsed.advantage}`);
+    }
+}
+//# sourceMappingURL=reward-agent.js.map