dsh-continual-evolve 0.1.0 → 0.2.0

package/lib/auto.js

@@ -17,12 +17,16 @@
  */
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { slug } from "./types.js";
 import { planWithLlm } from "./planner.js";
 import { reviewAutoRefine, serializeSurface } from "./review.js";
 import { goalServiceOf } from "./goal.js";
 import { notifyAutoReview } from "./notify.js";
+import { runLocalFatePhase } from "./fate.js";
 import { entrySourceOf } from "./source.js";
 import { mergeHarnessStates } from "./state.js";
+/** Turns a rejected skill candidate stays silent before being offered again. */
+export const SKILL_CONSULT_COOLDOWN_TURNS = 10;
 /**
  * Count completed turns from agent/status transitions alone. The runtime
  * emits `agent/status` with a `{status}` payload and (per host consumers like
@@ -133,7 +137,14 @@ export function registerAutoReview(ctx, engine, config) {
 function stateFor(map, sessionId) {
     let state = map.get(sessionId);
     if (!state) {
-        state = { turns: 0, lastReviewAt: 0, running: false };
+        state = {
+            turns: 0,
+            lastReviewAt: 0,
+            running: false,
+            skillRejects: new Map(),
+            lastFateAt: 0,
+            fateRejects: new Map(),
+        };
         map.set(sessionId, state);
     }
     return state;
@@ -150,7 +161,19 @@ function stateFor(map, sessionId) {
 export function loadGateHarnessView(engine, sessionId) {
     return mergeHarnessStates(engine.load("global", undefined), engine.load("local", sessionId));
 }
+/**
+ * One gate run = review phase + local-fate phase (#11 P2). The review phase
+ * judges and applies local refinements; the local-fate phase then gives the
+ * session's existing local entries a running exit (promote/archive proposals,
+ * consulted before they land). Running fate AFTER the review keeps the
+ * review's baseline fresh — fate re-loads the store and never races the
+ * review's optimistic-concurrency checks.
+ */
 async function runGate(ctx, engine, agent, config, state, reason, record) {
+    await runReviewPhase(ctx, engine, agent, config, state, reason, record);
+    await runLocalFatePhase(ctx, engine, agent, config, state, reason, record);
+}
+async function runReviewPhase(ctx, engine, agent, config, state, reason, record) {
     const sessionId = agent.id;
     const turnsSinceLastReview = state.turns - state.lastReviewAt;
     const logger = ctx.logger("continual-evolve");
@@ -189,9 +212,31 @@ async function runGate(ctx, engine, agent, config, state, reason, record) {
         history,
         ...(review.instructions ? { instructions: review.instructions } : {}),
         global: false,
+        // Read the skill-creator template facts (fallback: builtin distilled
+        // guide) so skill proposals follow the standard.
+        skillsRoot: join(engine.baseDir, "skills"),
     });
+    // Skills are governed resources: an auto-created skill is OFFERED to the
+    // user for a decision (固化/不固化) before it lands — the gate never
+    // writes a skill silently. Without consent the skill edits are withheld
+    // and the rest of the proposal proceeds as usual.
+    const { skillEdits, otherEdits } = splitSkillEdits(proposal);
+    const skillConsented = await consultSkillEdits(ctx, agent, skillEdits, state);
+    const finalProposal = skillConsented
+        ? proposal
+        : {
+            ...proposal,
+            edits: otherEdits,
+            summary: skillEdits.length > 0 ? `${proposal.summary} (skill edits withheld — pending user decision)` : proposal.summary,
+        };
+    if (finalProposal.edits.length === 0) {
+        const withheld = skillEdits.length > 0 ? " (skill proposal withheld — user not consulted or declined)" : "";
+        logger.info(`auto-review declined (${reason}) [${sessionId}] after ${turnsSinceLastReview} turns: no consented edits${withheld} — ${review.rationale}`);
+        record({ sessionId, reason, turnsSinceLastReview, outcome: "declined", rationale: `${review.rationale}${withheld}` });
+        return;
+    }
     const source = entrySourceOf(agent, sessionId);
-    const result = engine.apply("local", sessionId, proposal, {
+    const result = engine.apply("local", sessionId, finalProposal, {
         scope: "local",
         baselineState: localState,
         ...(source ? { source } : {}),
@@ -214,4 +259,65 @@ async function readTrajectory(ctx, agent, maxChars) {
     const snapshot = await sessionQuery.readSurface(agent.id);
     return serializeSurface(snapshot.events, maxChars);
 }
+/**
+ * Split a proposal into skill edits and everything else. Skill edits are the
+ * governed part: they need explicit user consent before the gate applies
+ * them, while the remaining edits flow through the normal auto path.
+ */
+export function splitSkillEdits(proposal) {
+    return {
+        skillEdits: proposal.edits.filter((edit) => edit.kind === "skill"),
+        otherEdits: proposal.edits.filter((edit) => edit.kind !== "skill"),
+    };
+}
+/**
+ * Ask the user whether to solidify proposed skill edits (guidance or
+ * executable) into the harness. Returns true when every skill edit is
+ * consented. Never writes a skill silently:
+ * - no question service available → false (conservative);
+ * - the same candidate was rejected within the cooldown window → false
+ *   without asking again (no nagging);
+ * - the user declines → false and the rejection is recorded for cooldown;
+ * - the question call fails/aborts → false (conservative).
+ */
+export async function consultSkillEdits(ctx, agent, skillEdits, gate) {
+    if (skillEdits.length === 0)
+        return true;
+    const key = skillEdits.map((edit) => edit.id ?? slug(edit.title ?? edit.kind, edit.kind)).join("|");
+    const lastReject = gate.skillRejects.get(key);
+    if (lastReject !== undefined && gate.turns - lastReject < SKILL_CONSULT_COOLDOWN_TURNS) {
+        return false;
+    }
+    const userQuestions = ctx.userQuestions;
+    if (!userQuestions) {
+        return false;
+    }
+    const description = skillEdits
+        .map((edit) => {
+        const form = edit.skill_kind === "guidance" ? "guidance 技能（SKILL.md 文档）" : "可执行技能";
+        return `- ${edit.action}「${edit.title ?? edit.id}」(${form})`;
+    })
+        .join("\n");
+    try {
+        const answer = await userQuestions.ask({
+            questions: [
+                {
+                    id: "evolve-skill-consult",
+                    question: `自进化检测到反复出现的流程/技能候选，建议沉淀：\n\n${description}\n\n是否固化？`,
+                    options: [{ label: "固化" }, { label: "不固化" }],
+                },
+            ],
+            agent,
+        });
+        const item = answer.answers?.find((entry) => entry.id === "evolve-skill-consult");
+        const consented = item?.selected?.includes("固化") ?? false;
+        if (!consented) {
+            gate.skillRejects.set(key, gate.turns);
+        }
+        return consented;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=auto.js.map

package/lib/benchmark.d.ts

@@ -16,9 +16,23 @@ export interface BenchmarkDefinition {
 export interface CellScore {
     caseId: string;
     run: number;
+    /**
+     * Failure-cell protocol (gap A2): "ok" = a real score; "failed" = the
+     * unit could not produce one (rubric decrypt error, child crash, protocol
+     * error). A failed cell is NOT a zero — aggregation excludes it and
+     * counts it, and the acceptance rule rejects a round with more failures
+     * than the threshold instead of silently averaging a 0 into the mean.
+     */
+    status: "ok" | "failed";
     score: number;
     passed: boolean;
     notes: string;
+    /**
+     * Trace evidence pointer (gap A4): the executor child's session id whose
+     * transcript produced this cell's evidence — the score can be drilled
+     * back to the exact session steps that earned it.
+     */
+    sessionId?: string;
 }
 export interface EvaluationEntry {
     label: string;

package/lib/command.js

@@ -2,7 +2,9 @@ import { ARCHIVED_AT_KEY } from "./types.js";
 import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
 import { planWithLlm } from "./planner.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { requireGlobalApproval } from "./approval.js";
+import { assessLocalEntries, candidateKey, filterPromotable, listLocalCandidates, splitArchiveGuards, splitPromoteBlocked, splitPromoteProposals, wholePromoteProposals } from "./wrapup.js";
 import { saveHarnessState } from "./state.js";
 import { loadLedger, mountSkill, unmountSkill } from "./mount.js";
 import { blockEvolutionGoal, completeEvolutionGoal, goalServiceOf, goalStatusText, upsertEvolutionGoal } from "./goal.js";
@@ -18,6 +20,8 @@ const USAGE = `Usage:
   /evolve history [global] show applied refinements (rollback ids)
   /evolve rollback <id> [global]  deterministically revert a refinement
   /evolve plan [msg]       run the LLM planner against the current store
+  /evolve wrapup           assess this session's local entries: promote reusable ones
+                           to the global store (approval required), archive one-offs
   /evolve archive <id> [global]   hide an entry from injection (data kept, restorable)
   /evolve unarchive <id> [global] restore an archived entry
   /evolve log [tail N]            show the recent plugin log (default 50 lines)
@@ -255,6 +259,8 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     ...(instructions ? { instructions } : {}),
                     global: scope === "global",
                     signal: invocation.signal,
+                    // skill-creator template facts (fallback: builtin guide).
+                    skillsRoot: join(engine.baseDir, "skills"),
                 });
                 if (scope === "global" && opts.requireGlobalApproval && proposal.edits.length > 0) {
                     await requireGlobalApproval(ctx, invocation.agent, invocation.signal, `/evolve plan global 将应用 ${proposal.edits.length} 条编辑到跨会话 store：${proposal.summary}`);
@@ -266,6 +272,9 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                 });
                 return success(renderResult(result));
             }
+            case "wrapup": {
+                return await executeWrapupCommand(ctx, engine, invocation);
+            }
             case "goal": {
                 return executeGoalCommand(ctx, invocation, rest);
             }
@@ -320,6 +329,211 @@ function executeGoalCommand(ctx, invocation, rest) {
         return error(cause instanceof Error ? cause.message : String(cause));
     }
 }
+async function executeWrapupCommand(ctx, engine, invocation) {
+    const sessionId = invocation.agent.id;
+    const localState = engine.load("local", sessionId);
+    const globalState = engine.load("global", undefined);
+    const candidates = listLocalCandidates(localState, globalState);
+    if (candidates.length === 0) {
+        return success(`(nothing to wrap up: ${sessionId}'s local store has no active, un-promoted entries — use /evolve list to inspect it)`);
+    }
+    // 1. Classify: the model judges each audited candidate's fate.
+    const assessment = await assessLocalEntries(ctx, invocation.agent, candidates, { signal: invocation.signal });
+    const byKey = new Map(candidates.map((candidate) => [candidateKey(candidate.kind, candidate.id), candidate]));
+    // 2. Partition by action. Deterministic guards re-check the LIVE global
+    //    store right before anything lands (state may have changed mid-call).
+    const { promotable, skipped } = filterPromotable(assessment.items, globalState, candidates);
+    const promoteItems = promotable.filter((item) => item.verdict === "promote");
+    const archiveItems = assessment.items.filter((item) => item.verdict === "archive");
+    // Split promotion (A-form): archive a mixed entry but promote ONLY the
+    // cleaned durable part the model extracted. Guarded the same way as whole
+    // promotes — a split that would duplicate a globally covered topic is
+    // dropped and the entry archives plain.
+    const splitItems = [];
+    const splitSkipped = [];
+    for (const item of archiveItems) {
+        if (!item.promote)
+            continue;
+        const candidate = byKey.get(item.key);
+        if (!candidate) {
+            splitSkipped.push({ key: item.key, reason: "not in the audited candidate list" });
+            continue;
+        }
+        const blocked = splitPromoteBlocked(item, globalState, candidate.kind);
+        if (blocked) {
+            splitSkipped.push({ key: item.key, reason: blocked });
+            continue;
+        }
+        splitItems.push({ item, candidate });
+    }
+    // Plain archives (no split payload): the symmetric guard — an archive that
+    // is NOT globally covered AND was distilled from real user messages must
+    // not proceed silently.
+    const plainArchives = archiveItems.filter((item) => !item.promote);
+    const { silent: silentArchives, review: reviewArchives } = splitArchiveGuards(plainArchives, candidates);
+    const keepItems = assessment.items.filter((item) => item.verdict === "keep");
+    // 3. Report the assessment before touching anything.
+    const lines = [
+        `wrapup assessment (${sessionId}): ${candidates.length} candidates${candidates.some((c) => c.coveredGlobally) ? `, ${candidates.filter((c) => c.coveredGlobally).length} covered globally` : ""}`,
+        `${assessment.rationale}`,
+    ];
+    for (const [heading, items] of [
+        ["PROMOTE (to global)", promoteItems],
+        ["SPLIT (archive + promote durable part)", splitItems.map((split) => split.item)],
+        ["ARCHIVE", silentArchives],
+        ["ARCHIVE (needs review)", reviewArchives],
+        ["KEEP", keepItems],
+    ]) {
+        lines.push(`${heading}: ${items.length}`);
+        for (const item of items) {
+            const candidate = byKey.get(item.key);
+            const title = candidate ? candidate.title : item.key;
+            const splitNote = item.promote ? ` → 拆出提升「${item.promote.title}」` : "";
+            lines.push(`- ${item.key} "${title}"${splitNote} — ${item.reason}`);
+        }
+    }
+    for (const skip of skipped) {
+        lines.push(`- promote skipped: ${skip.key} — ${skip.reason}`);
+    }
+    for (const skip of splitSkipped) {
+        lines.push(`- split skipped: ${skip.key} — ${skip.reason}`);
+    }
+    lines.push("");
+    const applied = [];
+    // 4. Global writes: governed resource — ONE human approval gate covers
+    //    every create (whole promotes AND split promotions). On approval:
+    //    - whole promote → create global copy + stamp local promotedTo+archivedAt;
+    //    - split → create the cleaned durable part + archive the original with
+    //      promotedTo. On rejection: whole promotes are not written, and each
+    //      split's original STILL archives plain (its snapshot half deserves
+    //      the archive; the durable half is reported for manual handling).
+    const wholeCreates = promoteItems.map((item) => ({ item, candidate: byKey.get(item.key) }));
+    const splitCreates = splitItems;
+    const allCreates = new Set([...wholeCreates.map((c) => c.item.key), ...splitCreates.map((c) => c.item.key)]);
+    if (allCreates.size > 0) {
+        const what = `wrapup 将写入跨会话 global store（共 ${allCreates.size} 条：${promoteItems.length} 条整条提升 + ${splitItems.length} 条拆解提升）：\n${[
+            ...promoteItems.map((item) => `- 整条提升 ${item.key} "${byKey.get(item.key)?.title ?? item.key}"`),
+            ...splitItems.map((split) => `- 拆解提升 ${split.item.key} → 清洗「${split.item.promote?.title}」（原条目随之归档）`),
+        ].join("\n")}`;
+        let promoteAllowed = true;
+        try {
+            await requireGlobalApproval(ctx, invocation.agent, invocation.signal, what);
+        }
+        catch (cause) {
+            promoteAllowed = false;
+            const message = `global 写入未批准 — 整条提升与拆解提升均未写入 (${cause instanceof Error ? cause.message : String(cause)})`;
+            applied.push(message);
+            lines.push(message);
+        }
+        if (promoteAllowed) {
+            // Whole promotes: create global entry, retire the local copy.
+            // Shared proposal builders keep the wrap-up command and the gate's
+            // local-fate dimension writing IDENTICAL edits.
+            for (const { item, candidate } of wholeCreates) {
+                if (!candidate)
+                    continue;
+                const proposals = wholePromoteProposals(item, candidate, sessionId);
+                const globalResult = engine.apply("global", undefined, proposals.global, { scope: "global" });
+                const createdId = globalResult.appliedEdits.find((edit) => edit.applied)?.id ?? candidate.id;
+                const localResult = engine.apply("local", sessionId, proposals.localStamp(createdId), {
+                    scope: "local",
+                    baselineState: localState,
+                });
+                applied.push(`promoted ${item.key} → global:${createdId} (${globalResult.id}; local stamped ${localResult.id})`);
+            }
+            // Split promotions: create the cleaned durable part, retire the
+            // original local entry (its snapshot half is archived along).
+            for (const { item, candidate } of splitCreates) {
+                if (!item.promote)
+                    continue;
+                const proposals = splitPromoteProposals(item, candidate, sessionId);
+                const globalResult = engine.apply("global", undefined, proposals.global, { scope: "global" });
+                const createdId = globalResult.appliedEdits.find((edit) => edit.applied)?.id ?? candidate.id;
+                const localResult = engine.apply("local", sessionId, proposals.localStamp(createdId), {
+                    scope: "local",
+                    baselineState: localState,
+                });
+                applied.push(`split ${item.key}: promoted cleaned part → global:${createdId} (${globalResult.id}); original archived (${localResult.id})`);
+            }
+        }
+        else {
+            // Rejected: whole promotes stay un-written; each split's original
+            // still archives plain (reported, data restorable).
+            for (const { item, candidate } of splitCreates) {
+                if (!candidate)
+                    continue;
+                const result = engine.apply("local", sessionId, {
+                    summary: `wrapup: split promotion not approved — archive original ${item.key} plain`,
+                    rationale: item.reason,
+                    expectedOutcome: `The original leaves injection; the cleaned part was NOT written (reported for manual handling).`,
+                    edits: [{ action: "archive", kind: candidate.kind, id: candidate.id }],
+                }, { scope: "local", baselineState: localState });
+                applied.push(`split ${item.key}: promotion not approved — original archived plain (${result.id})`);
+            }
+        }
+    }
+    // 5. Silent archives: deterministic local action (hidden from injection,
+    //    data kept restorable) — covered topics and operational entries need no
+    //    confirmation, matching the original behavior.
+    for (const item of silentArchives) {
+        const candidate = byKey.get(item.key);
+        if (!candidate)
+            continue;
+        const result = engine.apply("local", sessionId, {
+            summary: `wrapup: archive local ${item.key} — ${item.reason}`,
+            rationale: item.reason,
+            expectedOutcome: `The entry stops being injected but stays restorable.`,
+            edits: [{ action: "archive", kind: candidate.kind, id: candidate.id }],
+        }, { scope: "local", baselineState: localState });
+        applied.push(`archived ${item.key} (${result.id})`);
+    }
+    // 6. Review archives (symmetric guard): not covered globally + distilled
+    //    from real user messages — the user decides before this content is
+    //    hidden from future sessions. No question service → conservative keep.
+    const userQuestions = ctx.userQuestions;
+    for (const item of reviewArchives) {
+        const candidate = byKey.get(item.key);
+        if (!candidate)
+            continue;
+        if (!userQuestions) {
+            applied.push(`kept ${item.key} — archive pending user confirmation (no question service)`);
+            continue;
+        }
+        const questionId = "evolve-wrapup-archive-review";
+        let archiveConfirmed = false;
+        try {
+            const answer = await userQuestions.ask({
+                questions: [
+                    {
+                        id: questionId,
+                        question: `wrapup：条目「${candidate.title}」未被全局覆盖且源自真实对话，直接归档会隐藏它（数据保留、可恢复）。确认归档？`,
+                        options: [{ label: "归档" }, { label: "保留" }],
+                    },
+                ],
+                agent: invocation.agent,
+                signal: invocation.signal,
+            });
+            archiveConfirmed = answer.answers?.find((entry) => entry.id === questionId)?.selected?.includes("归档") ?? false;
+        }
+        catch {
+            archiveConfirmed = false;
+        }
+        if (archiveConfirmed) {
+            const result = engine.apply("local", sessionId, {
+                summary: `wrapup: archive local ${item.key} (user-confirmed) — ${item.reason}`,
+                rationale: item.reason,
+                expectedOutcome: `The entry stops being injected but stays restorable.`,
+                edits: [{ action: "archive", kind: candidate.kind, id: candidate.id }],
+            }, { scope: "local", baselineState: localState });
+            applied.push(`archived ${item.key} (user-confirmed, ${result.id})`);
+        }
+        else {
+            applied.push(`kept ${item.key} — user declined the archive`);
+        }
+    }
+    lines.push(...(applied.length > 0 ? applied : ["(no changes applied — all entries kept)"]));
+    return success(lines.join("\n"));
+}
 async function executeMountCommand(ctx, engine, invocation, rest) {
     const sub = rest[0] ?? "";
     if (sub === "list") {
@@ -351,6 +565,11 @@ async function executeMountCommand(ctx, engine, invocation, rest) {
         return error(cause instanceof Error ? cause.message : String(cause));
     }
 }
+/** " (N failed)" suffix when an evaluation entry carries failed cells. */
+function failedTextOf(entry) {
+    const failed = entry.cells.filter((cell) => cell.status === "failed").length;
+    return failed > 0 ? ` (${failed} failed)` : "";
+}
 async function executeBenchmarkCommand(ctx, engine, invocation, rest, runtime) {
     const sub = rest[0] ?? "";
     const args = rest.slice(1);
@@ -409,13 +628,13 @@ async function executeBenchmarkCommand(ctx, engine, invocation, rest, runtime) {
             const board = loadScoreboard(baseDir, bid);
             const lines = [];
             if (board.reference) {
-                lines.push(`reference "${board.reference.label}": overall=${board.reference.overall ?? "?"} cells=${board.reference.cells.length}`);
+                lines.push(`reference "${board.reference.label}": overall=${board.reference.overall ?? "?"} cells=${board.reference.cells.length}${failedTextOf(board.reference)}`);
             }
             else {
                 lines.push("(no reference evaluation yet)");
             }
             for (const c of board.candidates) {
-                lines.push(`candidate "${c.label}": overall=${c.overall ?? "?"} cells=${c.cells.length}${c.refinementId ? ` (${c.refinementId})` : ""}`);
+                lines.push(`candidate "${c.label}": overall=${c.overall ?? "?"} cells=${c.cells.length}${failedTextOf(c)}${c.refinementId ? ` (${c.refinementId})` : ""}`);
             }
             for (const d of board.decisions) {
                 lines.push(`decision: ${d.accepted ? "ACCEPTED" : "rejected"} ${d.candidateLabel} — ${d.reasons.join("; ") || "ok"}`);
@@ -449,19 +668,29 @@ async function executeBenchmarkCommand(ctx, engine, invocation, rest, runtime) {
                 signal: invocation.signal,
             });
             const entry = entryFromCells(label, outcome.cells, candidateId);
+            const failedCells = outcome.cells.filter((cell) => cell.status === "failed").length;
             const lines = [
-                `evaluation "${label}": ${outcome.cells.length} cells, overall=${entry.overall ?? "?"}`,
+                `evaluation "${label}": ${outcome.cells.length} cells${failedCells > 0 ? `, ${failedCells} failed` : ""}, overall=${entry.overall ?? "?"}`,
                 ...Object.entries(entry.aggregate)
-                    .filter(([key]) => key !== "overall")
+                    .filter(([key]) => key !== "overall" && key !== "failed" && key !== "total")
                     .map(([key, value]) => `  ${key}: ${value ?? "?"}`),
             ];
+            if (failedCells > 0) {
+                for (const cell of outcome.cells.filter((cell) => cell.status === "failed")) {
+                    lines.push(`  [failed] ${cell.caseId} r${cell.run}: ${cell.notes}`);
+                }
+            }
             if (candidateId) {
                 if (!board.reference) {
                     lines.push("(no reference yet — this run only recorded the candidate)");
                     board.candidates.push(entry);
                 }
                 else {
-                    const decision = decide(board.reference, entry, { passThreshold: definition.passThreshold, regressionTolerance: 0 });
+                    const decision = decide(board.reference, entry, {
+                        passThreshold: definition.passThreshold,
+                        regressionTolerance: 0,
+                        maxFailedCells: 0,
+                    });
                     board.candidates.push(entry);
                     board.decisions.push({
                         candidateLabel: label,

package/lib/evaluate.d.ts

@@ -1,14 +1,34 @@
 /**
- * The evaluation matrix runner: executes every case × run as a fresh
- * structured-output subagent, with the provider/model frozen to the calling
- * agent's own route. Raw per-cell scores come back to the host; aggregation
- * and acceptance happen in code (`src/score.ts`).
+ * The evaluation matrix runner: executes every case × run as a TWO-STAGE
+ * structured-output subagent pair, with the provider/model frozen to the
+ * calling agent's own route.
+ *
+ * Stage 1 — executor: a fresh child performs the case task with its tools
+ * and records CONCRETE EVIDENCE of what it did and found. It NEVER sees the
+ * rubric (gap A1, evaluator/scorer separation): the agent under test cannot
+ * optimize its behavior toward the grading criteria, and cannot grade its
+ * own execution.
+ *
+ * Stage 2 — reviewer: an INDEPENDENT child grades the executor's evidence
+ * strictly against the rubric. The rubric plaintext is decrypted in the host
+ * and flows ONLY into this reviewer branch; the executor branch never
+ * touches it. A separate model instance grading someone else's evidence
+ * removes the self-serving bias of self-scoring.
+ *
+ * Failure-cell protocol (gap A2): a unit that cannot produce a score
+ * (decrypt error, executor crash, reviewer crash, protocol error) returns a
+ * cell with `status: "failed"` — NEVER a zero — so aggregation can exclude
+ * it and the acceptance rule can reject rounds with too many failures instead
+ * of silently averaging a 0 into the mean.
+ *
+ * Each cell carries the executor child's session id (gap A4): the score can
+ * be drilled back to the exact session transcript that produced the evidence.
  *
  * Uses the host-plane `subagents` service (available in every profile) with
  * the native `outputSchema` structured-output seam: the provider validates
- * the child's reply against the cell schema, so the host never parses
- * model text for evaluations. (The workflow engine was rejected because the
- * web profile keeps it in a per-agent isolated realm a host plugin cannot
+ * each child's reply against its cell schema, so the host never parses model
+ * text for evaluations. (The workflow engine was rejected because the web
+ * profile keeps it in a per-agent isolated realm a host plugin cannot
  * resolve.)
  */
 import type { Context } from "@deepseek-ai/cordis";
@@ -32,7 +52,16 @@ export interface EvaluationOutcome {
 }
 /** How many evaluation units may run concurrently (bounded subagent fan-out). */
 export declare const DEFAULT_EVALUATION_CONCURRENCY = 4;
+/** Evidence handed to the reviewer is capped so the grading call stays bounded. */
+export declare const MAX_EVIDENCE_CHARS = 8000;
 export declare function evaluateState(ctx: Context, agent: Agent, options: EvaluateOptions): Promise<EvaluationOutcome>;
+export interface ExecutorResult {
+    caseId: string;
+    run: number;
+    evidence: string;
+}
+/** Validate a provider-validated executor result; returns undefined when malformed. */
+export declare function normalizeExecutor(value: unknown, caseId: string, run: number): ExecutorResult | undefined;
 /** Validate a provider-validated structured cell; returns undefined when malformed. */
 export declare function normalizeCell(value: unknown, caseId: string, run: number, passThreshold: number): CellScore | undefined;
 //# sourceMappingURL=evaluate.d.ts.map