harnery 0.18.0 → 0.19.1

package/dist/core/supervisor/planning.js

@@ -1,15 +1,16 @@
-import { randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { appendFileSync, chmodSync, existsSync, linkSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { createWorkItem, readWorkItem } from "../work/index.js";
-import { readWorkflowProof, runWorkflow, WorkflowParkedError, workflowScriptDigest, } from "../workflow/index.js";
-import { readSupervisorPlan, readSupervisorPlans } from "./plan-read.js";
+import { digestResult, readWorkflowProof, runWorkflow, WorkflowParkedError, workflowScriptDigest, } from "../workflow/index.js";
+import { readSupervisorPlan, readSupervisorPlanReviewReceipt, readSupervisorPlans, } from "./plan-read.js";
 import { SUPERVISOR_PLAN_SCHEMA_VERSION, supervisorGraphFingerprint, } from "./plan-types.js";
 const PLAN_KEY = /^[a-z][a-z0-9-]{0,31}$/;
 const TEMPLATE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const MAX_RECORD_BYTES = 256 * 1024;
 const MAX_EVENTS_BYTES = 512 * 1024;
 const MAX_REASON = 2_000;
+const PROPOSAL_ROOT_RULE = "proposal.root names one newly proposed work key using a root-capable template; it does not preserve or repeat active_root, which is context only";
 export async function runSupervisorPlanner(input) {
     const coordRoot = resolve(input.coordRoot);
     const policy = input.record.intent.replanning;
@@ -27,32 +28,106 @@ export async function runSupervisorPlanner(input) {
         history.latest.request.prior_root_work_id === input.record.projection.root_work_id
         ? history.latest
         : undefined;
-    const request = resumable
-        ? resumable.request
+    const interrupted = !resumable &&
+        history.latest?.status === "interrupted" &&
+        history.latest.request.trigger_fingerprint === triggerFingerprint &&
+        history.latest.request.prior_root_work_id === input.record.projection.root_work_id &&
+        policy.review &&
+        hasReviewRecoveryEvidence(coordRoot, input.record.intent.id, history.latest.request.id)
+        ? history.latest
+        : undefined;
+    const request = resumable || interrupted
+        ? (resumable ?? interrupted).request
         : createPlanRequest(coordRoot, input.record, history.plans.length + 1, triggerFingerprint, trigger);
     const scriptPath = planScriptPath(coordRoot, input.record.intent.id, request.id);
     if (resumable) {
         appendPlanEvent(coordRoot, input.record.intent.id, request.id, {
             event: "plan.resumed",
             actor: input.actor,
-            reason: `resuming planner workflow after approval ${resumable.approval_id}`,
+            reason: `resuming planning workflow after approval ${resumable.approval_id}`,
             approval_id: resumable.approval_id,
         });
     }
-    let proposalWritten = false;
-    try {
-        const report = await runWorkflow(scriptPath, {
-            ...input.engine,
+    if (interrupted) {
+        const recovered = await recoverReviewedPlan({
             coordRoot,
-            ...(resumable
-                ? { resumeRunId: request.workflow_run_id }
-                : { runId: request.workflow_run_id }),
-            specialists: input.record.intent.specialists,
-            maxAgents: 1,
-            concurrency: 1,
-            onLog: input.onLog,
+            record: input.record,
+            request,
+            history,
+            trigger: request.trigger ?? "recovery",
+            policy,
+            actor: input.actor,
         });
-        const proposal = normalizeProposal(request.id, report.result, input.record, history.materialized_work_ids.length, request.trigger ?? "recovery");
+        if (recovered)
+            return recovered;
+    }
+    let proposalWritten = false;
+    try {
+        const reviewRunId = reviewWorkflowRunId(request.id);
+        const resumingReview = Boolean(resumable &&
+            policy.review &&
+            existsSync(reviewInputPath(coordRoot, input.record.intent.id, request.id)) &&
+            existsSync(join(coordRoot, ".harnery", "workflows", reviewRunId, "run.json")));
+        const reviewInput = resumingReview
+            ? readBoundedJson(reviewInputPath(coordRoot, input.record.intent.id, request.id), "supervisor plan review input")
+            : undefined;
+        const rawProposal = reviewInput
+            ? reviewInput.candidate
+            : (await runWorkflow(scriptPath, {
+                ...input.engine,
+                coordRoot,
+                ...(resumable
+                    ? { resumeRunId: request.workflow_run_id }
+                    : { runId: request.workflow_run_id }),
+                specialists: input.record.intent.specialists,
+                maxAgents: 1,
+                concurrency: 1,
+                onLog: input.onLog,
+            })).result;
+        const proposal = normalizeProposal(request.id, rawProposal, input.record, history.materialized_work_ids.length, request.trigger ?? "recovery", reviewInput ? persistedProposalTimestamp(reviewInput.candidate) : undefined);
+        if (policy.review) {
+            if (proposal.decision === "attention") {
+                appendPlanEvent(coordRoot, input.record.intent.id, request.id, {
+                    event: "plan.attention",
+                    actor: input.actor,
+                    reason: proposal.rationale,
+                });
+                return outcome(readSupervisorPlan(coordRoot, input.record.intent.id, request.id));
+            }
+            let receipt;
+            try {
+                receipt = await ensurePlanReview({
+                    coordRoot,
+                    record: input.record,
+                    request,
+                    proposal,
+                    history,
+                    trigger: request.trigger ?? "recovery",
+                    policy,
+                    engine: input.engine,
+                    actor: input.actor,
+                    onLog: input.onLog,
+                });
+            }
+            catch (error) {
+                if (error instanceof WorkflowParkedError)
+                    throw error;
+                appendPlanEvent(coordRoot, input.record.intent.id, request.id, {
+                    event: "plan.attention",
+                    actor: input.actor,
+                    reason: bounded(`plan review requires attention: ${error.message}`, "plan review attention", MAX_REASON),
+                });
+                return outcome(readSupervisorPlan(coordRoot, input.record.intent.id, request.id));
+            }
+            return finalizeReviewedProposal({
+                coordRoot,
+                record: input.record,
+                request,
+                receipt,
+                policy,
+                actor: input.actor,
+            });
+        }
         writeExclusiveJson(planProposalPath(coordRoot, input.record.intent.id, request.id), proposal, "supervisor plan proposal");
         appendPlanEvent(coordRoot, input.record.intent.id, request.id, {
             event: "plan.proposed",
@@ -86,7 +161,7 @@ export async function runSupervisorPlanner(input) {
             appendPlanEvent(coordRoot, input.record.intent.id, request.id, {
                 event: "plan.awaiting_approval",
                 actor: input.actor,
-                reason: `planner workflow parked for approval ${error.approvalId}`,
+                reason: `planning workflow parked for approval ${error.approvalId}`,
                 approval_id: error.approvalId,
             });
             return outcome(readSupervisorPlan(coordRoot, input.record.intent.id, request.id));
@@ -99,6 +174,115 @@ export async function runSupervisorPlanner(input) {
         throw error;
     }
 }
+async function recoverReviewedPlan(input) {
+    const review = input.policy.review;
+    if (!review)
+        return undefined;
+    const existing = readSupervisorPlanReviewReceipt(input.coordRoot, input.record.intent.id, input.request.id);
+    const receipt = existing ??
+        reconstructReviewReceiptFromProof({
+            coordRoot: input.coordRoot,
+            record: input.record,
+            request: input.request,
+            history: input.history,
+            trigger: input.trigger,
+            policy: input.policy,
+        });
+    if (!receipt)
+        return undefined;
+    if (!existing) {
+        writeExclusiveJson(reviewReceiptPath(input.coordRoot, input.record.intent.id, input.request.id), receipt, "supervisor plan review receipt");
+    }
+    return finalizeReviewedProposal({
+        coordRoot: input.coordRoot,
+        record: input.record,
+        request: input.request,
+        receipt,
+        policy: input.policy,
+        actor: input.actor,
+    });
+}
+async function ensurePlanReview(input) {
+    const existing = readSupervisorPlanReviewReceipt(input.coordRoot, input.record.intent.id, input.request.id);
+    if (existing)
+        return existing;
+    const reconstructed = reconstructReviewReceiptFromProof(input);
+    if (reconstructed) {
+        writeExclusiveJson(reviewReceiptPath(input.coordRoot, input.record.intent.id, input.request.id), reconstructed, "supervisor plan review receipt");
+        return reconstructed;
+    }
+    const reviewScript = reviewScriptPath(input.coordRoot, input.record.intent.id, input.request.id);
+    writeExclusiveJson(reviewInputPath(input.coordRoot, input.record.intent.id, input.request.id), { candidate: input.proposal }, "supervisor plan review input");
+    writeExclusive(reviewScript, plannerReviewScript(input.record, input.request.id, input.proposal, input.trigger), "supervisor plan review script");
+    const review = input.policy.review;
+    const runId = reviewWorkflowRunId(input.request.id);
+    const runExists = existsSync(join(input.coordRoot, ".harnery", "workflows", runId, "run.json"));
+    const report = await runWorkflow(reviewScript, {
+        ...input.engine,
+        coordRoot: input.coordRoot,
+        ...(runExists ? { resumeRunId: runId } : { runId }),
+        specialists: input.record.intent.specialists,
+        maxAgents: review.reviewer_specialists.length * (review.max_revision_rounds + 1) +
+            review.max_revision_rounds,
+        concurrency: input.record.intent.limits.agent_concurrency,
+        onLog: input.onLog,
+    });
+    const receipt = normalizeReviewReceipt({
+        raw: report.result,
+        initialCandidate: input.proposal,
+        record: input.record,
+        request: input.request,
+        history: input.history,
+        trigger: input.trigger,
+        policy: input.policy,
+    });
+    writeExclusiveJson(reviewReceiptPath(input.coordRoot, input.record.intent.id, input.request.id), receipt, "supervisor plan review receipt");
+    return receipt;
+}
+function finalizeReviewedProposal(input) {
+    if (input.receipt.status !== "passed") {
+        const event = input.receipt.status === "failed" ? "plan.failed" : "plan.attention";
+        appendPlanEventIfMissing(input.coordRoot, input.record.intent.id, input.request.id, event, {
+            event,
+            actor: input.actor,
+            reason: reviewStatusReason(input.receipt),
+        });
+        return outcome(readSupervisorPlan(input.coordRoot, input.record.intent.id, input.request.id));
+    }
+    // The review authority must become durable before the proposal can become
+    // visible. If the process stops after this event, the plan remains
+    // interrupted and proof-backed recovery can reconstruct the proposal. The
+    // opposite order can expose an unapprovable proposal with no recovery path.
+    appendPlanEventIfMissing(input.coordRoot, input.record.intent.id, input.request.id, "plan.reviewed", {
+        event: "plan.reviewed",
+        actor: input.actor,
+        reason: `plan review passed after ${input.receipt.rounds.length} round(s)`,
+    });
+    writeExclusiveJson(planProposalPath(input.coordRoot, input.record.intent.id, input.request.id), input.receipt.final_candidate, "supervisor plan proposal");
+    appendPlanEventIfMissing(input.coordRoot, input.record.intent.id, input.request.id, "plan.proposed", {
+        event: "plan.proposed",
+        actor: input.actor,
+        reason: input.receipt.final_candidate.rationale,
+    });
+    if (input.policy.auto_apply) {
+        return applySupervisorPlanProposal({
+            coordRoot: input.coordRoot,
+            record: input.record,
+            planId: input.request.id,
+            actor: input.actor,
+            reason: "proposal applied by frozen supervisor replanning policy",
+        });
+    }
+    return outcome(readSupervisorPlan(input.coordRoot, input.record.intent.id, input.request.id));
+}
+function reviewStatusReason(receipt) {
+    if (receipt.status === "revision_exhausted") {
+        return "plan review exhausted its bounded revision rounds";
+    }
+    if (receipt.status === "failed")
+        return "plan review failed";
+    return "plan review requires attention";
+}
 export function applySupervisorPlanProposal(input) {
     const coordRoot = resolve(input.coordRoot);
     const policy = input.record.intent.replanning;
@@ -112,6 +296,18 @@ export function applySupervisorPlanProposal(input) {
         !["apply", "complete"].includes(plan.proposal.decision)) {
         throw new Error(`supervisor plan ${input.planId} cannot be applied from ${plan.status}`);
     }
+    if (policy.review) {
+        const receipt = readSupervisorPlanReviewReceipt(coordRoot, input.record.intent.id, input.planId);
+        if (receipt?.status !== "passed") {
+            throw new Error(`supervisor plan ${input.planId} has no passed review receipt`);
+        }
+        if (candidateDigest(plan.proposal) !== receipt.candidate_sha256) {
+            throw new Error(`supervisor plan ${input.planId} proposal does not match its passed review`);
+        }
+        if (!plan.events.some((event) => event.event === "plan.reviewed")) {
+            throw new Error(`supervisor plan ${input.planId} has no reviewed authority event`);
+        }
+    }
     if (plan.request.prior_root_work_id !== input.record.projection.root_work_id) {
         throw new Error(`supervisor plan ${input.planId} targets stale root ${plan.request.prior_root_work_id}`);
     }
@@ -244,7 +440,8 @@ function plannerScript(coordRoot, record, planId, trigger) {
             : "Return decision=apply with a replacement immutable root graph, or decision=attention when human judgment is required.",
         "Never claim mission completion unless the frozen mission acceptance is met. Never request a workflow outside the frozen template catalog.",
         "Dependencies may name an active work ID or an earlier key in your proposed work array.",
-        "Every proposed item must be reachable from root. The root must be a proposed key using a root-capable template.",
+        `Every proposed item must be reachable from root. ${PROPOSAL_ROOT_RULE}.`,
+        "Work keys are lowercase identifiers no longer than 32 characters. Keep titles within 200 characters, objectives within 4000 characters, and each acceptance criterion within 500 characters.",
         `Plan id: ${planId}`,
         `Planning trigger: ${trigger}`,
         `Goal: ${record.intent.title}`,
@@ -288,43 +485,7 @@ function plannerScript(coordRoot, record, planId, trigger) {
                 : null,
         })))}`,
     ].join("\n\n");
-    const schema = {
-        type: "object",
-        properties: {
-            decision: {
-                type: "string",
-                enum: record.intent.mission ? ["apply", "complete", "attention"] : ["apply", "attention"],
-            },
-            rationale: { type: "string" },
-            root: { type: "string" },
-            work: {
-                type: "array",
-                items: {
-                    type: "object",
-                    properties: {
-                        key: { type: "string" },
-                        title: { type: "string" },
-                        objective: { type: "string" },
-                        acceptance: { type: "array", items: { type: "string" } },
-                        dependencies: { type: "array", items: { type: "string" } },
-                        template: { type: "string" },
-                    },
-                    required: ["key", "title", "objective", "acceptance", "dependencies", "template"],
-                },
-            },
-            milestone: {
-                type: "object",
-                properties: {
-                    sequence: { type: "number" },
-                    title: { type: "string" },
-                    objective: { type: "string" },
-                    acceptance: { type: "array", items: { type: "string" } },
-                },
-                required: ["sequence", "title", "objective", "acceptance"],
-            },
-        },
-        required: ["decision", "rationale", "root", "work"],
-    };
+    const schema = planProposalSchema(record, trigger);
     return [
         `export const meta = ${JSON.stringify({ name: `replan-${planId}` })};`,
         "export default async ({ agent, stage }) => {",
@@ -342,7 +503,500 @@ function plannerScript(coordRoot, record, planId, trigger) {
         "",
     ].join("\n");
 }
-function normalizeProposal(planId, raw, record, previouslyApplied, trigger) {
+function plannerReviewScript(record, planId, initialCandidate, trigger) {
+    const policy = record.intent.replanning;
+    const review = policy?.review;
+    if (!policy || !review)
+        throw new Error(`supervisor ${record.intent.id} does not review plans`);
+    const proposalSchema = planProposalSchema(record, trigger);
+    const reviewerSchema = {
+        type: "object",
+        properties: {
+            verdict: { type: "string", enum: ["approve", "revise", "attention"] },
+            rationale: { type: "string", minLength: 1, maxLength: MAX_REASON },
+            findings: {
+                type: "array",
+                maxItems: 50,
+                items: {
+                    type: "object",
+                    properties: {
+                        code: {
+                            type: "string",
+                            minLength: 1,
+                            maxLength: 100,
+                            pattern: "^[a-z][a-z0-9._-]*$",
+                        },
+                        severity: { type: "string", enum: ["blocking", "advisory"] },
+                        summary: { type: "string", minLength: 1, maxLength: 1_000 },
+                        recommendation: { type: "string", minLength: 1, maxLength: 1_000 },
+                    },
+                    required: ["code", "severity", "summary", "recommendation"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ["verdict", "rationale", "findings"],
+        additionalProperties: false,
+    };
+    return [
+        `export const meta = ${JSON.stringify({ name: `review-${planId}` })};`,
+        "export default async ({ agent, stage }) => {",
+        `  const reviewers = ${JSON.stringify(review.reviewer_specialists)};`,
+        `  const planner = ${JSON.stringify(policy.planner_specialist)};`,
+        `  const maxRevisionRounds = ${JSON.stringify(review.max_revision_rounds)};`,
+        `  const proposalSchema = ${JSON.stringify(proposalSchema)};`,
+        `  const reviewerSchema = ${JSON.stringify(reviewerSchema)};`,
+        `  const goalContext = ${JSON.stringify({
+            plan_id: planId,
+            trigger,
+            goal: record.intent.title,
+            mission: record.intent.mission ?? null,
+            original_root: record.intent.root_work_id,
+            active_root: record.projection.root_work_id,
+            proposal_root_rule: PROPOSAL_ROOT_RULE,
+            templates: policy.templates,
+        })};`,
+        `  let candidate = ${JSON.stringify(initialCandidate)};`,
+        "  const rounds = [];",
+        "  const aggregate = (items) => {",
+        "    if (items.some((item) => item.verdict === 'attention')) return 'attention';",
+        "    if (items.some((item) => item.verdict === 'revise')) return 'revise';",
+        "    if (items.some((item) => item.findings.some((finding) => finding.severity === 'blocking'))) return 'revise';",
+        "    return 'approved';",
+        "  };",
+        "  for (let round = 1; round <= maxRevisionRounds + 1; round++) {",
+        "    stage('Review round ' + round);",
+        "    const reviewersOut = await Promise.all(reviewers.map(async (specialist) => {",
+        "      const prompt = [",
+        "        'Review this bounded supervisor plan candidate independently.',",
+        "        'Return approve only when the candidate is complete, scoped, and satisfies the goal context.',",
+        "        'Return revise for blocking defects. Return attention when human judgment is required.',",
+        "        'Apply proposal_root_rule exactly; never require proposal.root to equal active_root.',",
+        "        'Goal context: ' + JSON.stringify(goalContext),",
+        "        'Candidate: ' + JSON.stringify(candidate)",
+        "      ].join('\\n\\n');",
+        "      const result = await agent(prompt, {",
+        "        specialist,",
+        "        schema: reviewerSchema,",
+        "        label: 'Review plan candidate as ' + specialist",
+        "      });",
+        "      return { specialist, ...result };",
+        "    }));",
+        "    const roundRecord = { round, candidate, reviewers: reviewersOut, outcome: aggregate(reviewersOut) };",
+        "    rounds.push(roundRecord);",
+        "    if (roundRecord.outcome === 'approved' || roundRecord.outcome === 'attention') break;",
+        "    if (round > maxRevisionRounds) break;",
+        "    stage('Revise round ' + round);",
+        "    const revisionPrompt = [",
+        "      'Revise this supervisor plan candidate. Return a complete replacement candidate, not a patch.',",
+        "      'Do not merge reviewer text mechanically; satisfy the blocking findings within the frozen goal and template constraints.',",
+        "      'Apply proposal_root_rule exactly; never require proposal.root to equal active_root.',",
+        "      'Goal context: ' + JSON.stringify(goalContext),",
+        "      'Current candidate: ' + JSON.stringify(candidate),",
+        "      'Reviewer findings: ' + JSON.stringify(reviewersOut)",
+        "    ].join('\\n\\n');",
+        "    roundRecord.revision_candidate = await agent(revisionPrompt, {",
+        "      specialist: planner,",
+        "      schema: proposalSchema,",
+        "      label: 'Revise bounded replacement plan'",
+        "    });",
+        "    candidate = roundRecord.revision_candidate;",
+        "  }",
+        "  return { rounds };",
+        "};",
+        "",
+    ].join("\n");
+}
+function normalizeReviewReceipt(input) {
+    const review = input.policy.review;
+    if (!review)
+        throw new Error("missing review policy");
+    if (!input.raw || typeof input.raw !== "object" || Array.isArray(input.raw)) {
+        throw new Error("review result must be an object");
+    }
+    const raw = input.raw;
+    if (!Array.isArray(raw.rounds))
+        throw new Error("review result rounds must be an array");
+    if (raw.rounds.length < 1 || raw.rounds.length > review.max_revision_rounds + 1) {
+        throw new Error("review result has an invalid number of rounds");
+    }
+    const rounds = [];
+    let candidate = input.initialCandidate;
+    let status;
+    for (const [index, rawRound] of raw.rounds.entries()) {
+        if (!rawRound || typeof rawRound !== "object" || Array.isArray(rawRound)) {
+            throw new Error(`review round ${index + 1} must be an object`);
+        }
+        if (status)
+            throw new Error("review result contains rounds after a terminal outcome");
+        const value = rawRound;
+        const roundNumber = positive(value.round, "review round", review.max_revision_rounds + 1);
+        if (roundNumber !== index + 1)
+            throw new Error(`review round must be ${index + 1}`);
+        const reviewers = normalizeReviewers(value.reviewers, review.reviewer_specialists);
+        const outcome = aggregateReviewers(reviewers);
+        const round = {
+            round: roundNumber,
+            candidate_sha256: candidateDigest(candidate),
+            reviewers,
+            outcome,
+        };
+        if (outcome === "approved") {
+            status = "passed";
+        }
+        else if (outcome === "attention") {
+            status = "attention";
+        }
+        else if (roundNumber > review.max_revision_rounds) {
+            status = "revision_exhausted";
+        }
+        else {
+            const revision = normalizeProposal(input.request.id, value.revision_candidate, input.record, input.history.materialized_work_ids.length, input.trigger);
+            round.revision_workflow_run_id = reviewWorkflowRunId(input.request.id);
+            if (candidateDigest(revision) === candidateDigest(candidate)) {
+                status = "attention";
+            }
+            else {
+                candidate = revision;
+            }
+        }
+        rounds.push(round);
+    }
+    status ??= "attention";
+    return {
+        schema_version: SUPERVISOR_PLAN_SCHEMA_VERSION,
+        plan_id: input.request.id,
+        status,
+        candidate_sha256: candidateDigest(candidate),
+        final_candidate: candidate,
+        rounds,
+    };
+}
+function normalizeReviewers(raw, expectedSpecialists) {
+    if (!Array.isArray(raw) || raw.length !== expectedSpecialists.length) {
+        throw new Error("reviewer result count does not match the frozen review policy");
+    }
+    return raw.map((value, index) => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            throw new Error(`reviewer result ${index + 1} must be an object`);
+        }
+        const item = value;
+        const specialist = bounded(item.specialist, `reviewer ${index + 1} specialist`, 100);
+        if (specialist !== expectedSpecialists[index]) {
+            throw new Error(`reviewer ${index + 1} does not match the frozen review order`);
+        }
+        const findings = normalizeFindings(item.findings, specialist);
+        return {
+            specialist,
+            verdict: enumValue(item.verdict, ["approve", "revise", "attention"], "review verdict"),
+            rationale: bounded(item.rationale, "review rationale", MAX_REASON),
+            findings,
+        };
+    });
+}
+function normalizeFindings(raw, specialist) {
+    if (!Array.isArray(raw) || raw.length > 50) {
+        throw new Error(`review findings from ${specialist} must contain at most 50 items`);
+    }
+    return raw.map((value, index) => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            throw new Error(`review finding ${index + 1} from ${specialist} must be an object`);
+        }
+        const item = value;
+        return {
+            code: findingCode(item.code, specialist, index),
+            severity: enumValue(item.severity, ["blocking", "advisory"], "review finding severity"),
+            summary: bounded(item.summary, "review finding summary", 1_000),
+            recommendation: bounded(item.recommendation, "review finding recommendation", 1_000),
+        };
+    });
+}
+function findingCode(value, specialist, index) {
+    const code = bounded(value, `review finding ${index + 1} code from ${specialist}`, 100);
+    if (!/^[a-z][a-z0-9._-]*$/.test(code)) {
+        throw new Error(`review finding ${index + 1} code from ${specialist} must be a stable lowercase identifier`);
+    }
+    return code;
+}
+function aggregateReviewers(reviewers) {
+    if (reviewers.length < 1)
+        return "failed";
+    if (reviewers.some((reviewer) => reviewer.verdict === "attention"))
+        return "attention";
+    if (reviewers.some((reviewer) => reviewer.verdict === "revise" ||
+        reviewer.findings.some((finding) => finding.severity === "blocking"))) {
+        return "revise";
+    }
+    return "approved";
+}
+function reconstructReviewReceiptFromProof(input) {
+    const runId = reviewWorkflowRunId(input.request.id);
+    const proofPath = join(input.coordRoot, ".harnery", "workflows", runId, "proof.json");
+    if (!existsSync(proofPath))
+        return undefined;
+    const proof = readWorkflowProof(input.coordRoot, runId);
+    if (proof.run.status !== "succeeded")
+        return undefined;
+    const raw = recoverReviewWorkflowResult(input.coordRoot, input.record.intent.id, input.request.id, proof, input.policy.review.reviewer_specialists);
+    assertResultDigest(raw.result, proof.run.result, runId);
+    return normalizeReviewReceipt({
+        raw: raw.result,
+        initialCandidate: raw.initialCandidate,
+        record: input.record,
+        request: input.request,
+        history: input.history,
+        trigger: input.trigger,
+        policy: input.policy,
+    });
+}
+function recoverReviewWorkflowResult(coordRoot, goalId, planId, proof, expectedSpecialists) {
+    const inputPath = reviewInputPath(coordRoot, goalId, planId);
+    const reviewInput = readBoundedJson(inputPath, "supervisor plan review input");
+    const journal = readVerifiedWorkflowJournal(coordRoot, reviewWorkflowRunId(planId), proof);
+    const starts = new Map();
+    const byRound = new Map();
+    let currentCandidate = reviewInput.candidate;
+    for (const line of journal.split("\n")) {
+        if (!line.trim())
+            continue;
+        const event = JSON.parse(line);
+        if (event.event === "agent.start" && typeof event.id === "string") {
+            starts.set(event.id, {
+                specialist: typeof event.specialist === "string" ? event.specialist : undefined,
+            });
+        }
+        if (event.event !== "agent.end" || event.result_kind !== "json")
+            continue;
+        const round = workflowJournalRound(event.stage);
+        if (!round)
+            continue;
+        let record = byRound.get(round.round);
+        if (!record) {
+            record = { round: round.round, candidate: currentCandidate, reviewers: [] };
+            byRound.set(round.round, record);
+        }
+        if (round.kind === "review") {
+            const specialist = typeof event.id === "string" ? starts.get(event.id)?.specialist : undefined;
+            if (!event.result || typeof event.result !== "object" || Array.isArray(event.result)) {
+                throw new Error("supervisor plan review journal contains an invalid reviewer result");
+            }
+            record.reviewers.push({
+                specialist,
+                ...event.result,
+            });
+        }
+        else {
+            record.revision_candidate = event.result;
+            currentCandidate = event.result;
+        }
+    }
+    const rounds = [...byRound.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([, value]) => {
+        const reviewers = orderRecoveredReviewers(value.reviewers, expectedSpecialists);
+        const round = {
+            round: value.round,
+            candidate: value.candidate,
+            reviewers,
+            outcome: aggregateRecoveredReviewers(reviewers),
+        };
+        if (value.revision_candidate !== undefined) {
+            round.revision_candidate = value.revision_candidate;
+        }
+        return round;
+    });
+    return {
+        initialCandidate: reviewInput.candidate,
+        result: { rounds },
+    };
+}
+function readVerifiedWorkflowJournal(coordRoot, runId, proof) {
+    const journalPath = join(coordRoot, ".harnery", "workflows", runId, proof.integrity.journal.path);
+    const journal = readFileSync(journalPath, "utf8");
+    const bytes = Buffer.byteLength(journal);
+    if (bytes <= 0 || bytes > MAX_RECORD_BYTES || bytes !== proof.integrity.journal.bytes) {
+        throw new Error(`supervisor plan review journal does not match proof integrity`);
+    }
+    const sha256 = createHash("sha256").update(journal).digest("hex");
+    if (sha256 !== proof.integrity.journal.sha256) {
+        throw new Error(`supervisor plan review journal does not match proof integrity`);
+    }
+    return journal;
+}
+function orderRecoveredReviewers(raw, expectedSpecialists) {
+    if (!Array.isArray(raw) || raw.length !== expectedSpecialists.length)
+        return raw;
+    const expected = new Set(expectedSpecialists);
+    const bySpecialist = new Map();
+    for (const value of raw) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return raw;
+        const specialist = value.specialist;
+        if (typeof specialist !== "string" ||
+            !expected.has(specialist) ||
+            bySpecialist.has(specialist)) {
+            return raw;
+        }
+        bySpecialist.set(specialist, value);
+    }
+    return expectedSpecialists.map((specialist) => bySpecialist.get(specialist));
+}
+function aggregateRecoveredReviewers(reviewers) {
+    if (reviewers.some((value) => value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value.verdict === "attention")) {
+        return "attention";
+    }
+    if (reviewers.some((value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return true;
+        const reviewer = value;
+        return (reviewer.verdict === "revise" ||
+            (Array.isArray(reviewer.findings) &&
+                reviewer.findings.some((finding) => finding &&
+                    typeof finding === "object" &&
+                    !Array.isArray(finding) &&
+                    finding.severity === "blocking")));
+    })) {
+        return "revise";
+    }
+    return "approved";
+}
+function assertResultDigest(raw, expected, runId) {
+    if (!expected) {
+        throw new Error(`supervisor plan review proof ${runId} is missing its result digest`);
+    }
+    const actual = digestResult(raw, "json");
+    if (actual.kind !== expected.kind ||
+        actual.sha256 !== expected.sha256 ||
+        actual.bytes !== expected.bytes) {
+        throw new Error(`supervisor plan review result does not match proof digest`);
+    }
+}
+function workflowJournalRound(stage) {
+    if (typeof stage !== "string")
+        return undefined;
+    const review = /^Review round ([1-9][0-9]*)$/.exec(stage);
+    if (review)
+        return { kind: "review", round: Number(review[1]) };
+    const revision = /^Revise round ([1-9][0-9]*)$/.exec(stage);
+    if (revision)
+        return { kind: "revision", round: Number(revision[1]) };
+    return undefined;
+}
+function candidateDigest(candidate) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalCandidate(candidate)))
+        .digest("hex");
+}
+function canonicalCandidate(candidate) {
+    return {
+        schema_version: candidate.schema_version,
+        plan_id: candidate.plan_id,
+        decision: candidate.decision,
+        rationale: candidate.rationale,
+        root: candidate.root,
+        work: candidate.work,
+        milestone: candidate.milestone,
+    };
+}
+function hasReviewRecoveryEvidence(coordRoot, goalId, planId) {
+    return (existsSync(reviewReceiptPath(coordRoot, goalId, planId)) ||
+        existsSync(join(coordRoot, ".harnery", "workflows", reviewWorkflowRunId(planId), "proof.json")));
+}
+function planProposalSchema(record, trigger) {
+    const policy = record.intent.replanning;
+    if (!policy)
+        throw new Error(`supervisor ${record.intent.id} does not allow replanning`);
+    const rationale = { type: "string", minLength: 1, maxLength: MAX_REASON };
+    const workItem = {
+        type: "object",
+        properties: {
+            key: { type: "string", pattern: "^[a-z][a-z0-9-]{0,31}$", maxLength: 32 },
+            title: { type: "string", minLength: 1, maxLength: 200 },
+            objective: { type: "string", minLength: 1, maxLength: 4_000 },
+            acceptance: {
+                type: "array",
+                maxItems: 50,
+                items: { type: "string", minLength: 1, maxLength: 500 },
+            },
+            dependencies: {
+                type: "array",
+                maxItems: 50,
+                items: { type: "string", minLength: 1, maxLength: 100 },
+            },
+            template: { type: "string", enum: Object.keys(policy.templates), maxLength: 64 },
+        },
+        required: ["key", "title", "objective", "acceptance", "dependencies", "template"],
+        additionalProperties: false,
+    };
+    const milestone = {
+        type: "object",
+        properties: {
+            sequence: {
+                type: "number",
+                enum: [record.projection.milestones_completed + 1],
+            },
+            title: { type: "string", minLength: 1, maxLength: 200 },
+            objective: { type: "string", minLength: 1, maxLength: 4_000 },
+            acceptance: {
+                type: "array",
+                minItems: 1,
+                maxItems: 50,
+                items: { type: "string", minLength: 1, maxLength: 500 },
+            },
+        },
+        required: ["sequence", "title", "objective", "acceptance"],
+        additionalProperties: false,
+    };
+    const applyProperties = {
+        decision: { type: "string", enum: ["apply"] },
+        rationale,
+        root: {
+            type: "string",
+            minLength: 1,
+            maxLength: 32,
+            pattern: "^[a-z][a-z0-9-]{0,31}$",
+        },
+        work: {
+            type: "array",
+            minItems: 1,
+            maxItems: policy.max_work_items_per_plan,
+            items: workItem,
+        },
+    };
+    const applyRequired = ["decision", "rationale", "root", "work"];
+    if (record.intent.mission) {
+        applyProperties.milestone = milestone;
+        applyRequired.push("milestone");
+    }
+    const apply = {
+        type: "object",
+        properties: applyProperties,
+        required: applyRequired,
+        additionalProperties: false,
+    };
+    const terminal = (decision) => ({
+        type: "object",
+        properties: {
+            decision: { type: "string", enum: [decision] },
+            rationale,
+            root: { type: "string", enum: [""] },
+            work: { type: "array", maxItems: 0 },
+        },
+        required: ["decision", "rationale", "root", "work"],
+        additionalProperties: false,
+    });
+    const branches = [];
+    if (!record.intent.mission || record.projection.milestones_remaining > 0)
+        branches.push(apply);
+    if (record.intent.mission && trigger === "milestone")
+        branches.push(terminal("complete"));
+    branches.push(terminal("attention"));
+    return { type: "object", oneOf: branches };
+}
+function normalizeProposal(planId, raw, record, previouslyApplied, trigger, preservedProposedAt) {
     const policy = record.intent.replanning;
     if (!policy)
         throw new Error(`supervisor ${record.intent.id} does not allow replanning`);
@@ -350,6 +1004,7 @@ function normalizeProposal(planId, raw, record, previouslyApplied, trigger) {
         throw new Error("planner result must be an object");
     }
     const value = raw;
+    const proposedAt = preservedProposedAt ?? new Date().toISOString();
     const decision = enumValue(value.decision, ["apply", "complete", "attention"], "plan decision");
     const rationale = bounded(value.rationale, "plan rationale", MAX_REASON);
     const root = typeof value.root === "string" ? value.root.trim() : "";
@@ -369,7 +1024,7 @@ function normalizeProposal(planId, raw, record, previouslyApplied, trigger) {
             rationale,
             root: "",
             work: [],
-            proposed_at: new Date().toISOString(),
+            proposed_at: proposedAt,
         };
     }
     const milestone = record.intent.mission
@@ -457,9 +1112,19 @@ function normalizeProposal(planId, raw, record, previouslyApplied, trigger) {
         root,
         work,
         ...(milestone ? { milestone } : {}),
-        proposed_at: new Date().toISOString(),
+        proposed_at: proposedAt,
     };
 }
+function persistedProposalTimestamp(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("persisted review candidate must be an object");
+    }
+    const value = raw.proposed_at;
+    if (typeof value !== "string" || value.length > 40 || !Number.isFinite(Date.parse(value))) {
+        throw new Error("persisted review candidate has an invalid proposed_at timestamp");
+    }
+    return value;
+}
 function normalizeMilestone(raw, expectedSequence) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error("mission plan must contain a milestone object");
@@ -510,6 +1175,12 @@ function appendPlanEvent(coordRootRaw, goalId, planId, input) {
     appendFileSync(path, line, { encoding: "utf8", mode: 0o600 });
     chmodSync(path, 0o600);
 }
+function appendPlanEventIfMissing(coordRoot, goalId, planId, eventType, input) {
+    const plan = readSupervisorPlan(coordRoot, goalId, planId);
+    if (plan.events.some((event) => event.event === eventType))
+        return;
+    appendPlanEvent(coordRoot, goalId, planId, input);
+}
 function outcome(plan) {
     return {
         plan_id: plan.request.id,
@@ -561,6 +1232,31 @@ function planScriptPath(coordRoot, goalId, planId) {
 function planProposalPath(coordRoot, goalId, planId) {
     return join(planDir(coordRoot, goalId, planId), "proposal.json");
 }
+function reviewScriptPath(coordRoot, goalId, planId) {
+    return join(planDir(coordRoot, goalId, planId), "review.mjs");
+}
+function reviewInputPath(coordRoot, goalId, planId) {
+    return join(planDir(coordRoot, goalId, planId), "review-input.json");
+}
+function reviewReceiptPath(coordRoot, goalId, planId) {
+    return join(planDir(coordRoot, goalId, planId), "review.json");
+}
+function reviewWorkflowRunId(planId) {
+    return `${planId}-review`;
+}
+function readBoundedJson(path, label) {
+    if (!existsSync(path))
+        throw new Error(`${label} does not exist at ${path}`);
+    const size = statSync(path).size;
+    if (size <= 0 || size > MAX_RECORD_BYTES)
+        throw new Error(`${label} has invalid size ${size}`);
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`cannot parse ${label} at ${path}: ${error.message}`);
+    }
+}
 function bounded(value, field, max) {
     if (typeof value !== "string")
         throw new Error(`${field} must be a string`);
@@ -571,6 +1267,12 @@ function bounded(value, field, max) {
         throw new Error(`${field} exceeds ${max} characters`);
     return normalized;
 }
+function positive(value, field, max) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > max) {
+        throw new Error(`${field} must be an integer from 1 to ${max}`);
+    }
+    return value;
+}
 function enumValue(value, values, field) {
     if (typeof value !== "string" || !values.includes(value)) {
         throw new Error(`${field} must be one of ${values.join(", ")}`);