@navels/neal 0.1.0

package/dist/neal/agents/schemas.js

@@ -0,0 +1,832 @@
+import { repairReviewerSquashMessageDraft, validateReviewerSquashMessageDraft } from '../squash-message.js';
+const REVIEWER_PAYLOAD_KEYS = [
+    'summary',
+    'findings',
+    'meaningfulProgressAction',
+    'meaningfulProgressRationale',
+];
+const REVIEWER_FINDING_KEYS = ['severity', 'files', 'claim', 'evidence', 'requiredAction'];
+const REVIEWER_FINDING_SEVERITIES = ['blocking', 'non_blocking'];
+const REVIEWER_MEANINGFUL_PROGRESS_ACTIONS = [
+    'accept',
+    'block_for_operator',
+    'replace_plan',
+    'advance_parent',
+];
+export const EXECUTE_SCOPE_PROGRESS_PAYLOAD_START = 'NEAL_PROGRESS_JUSTIFICATION_JSON_START';
+export const EXECUTE_SCOPE_PROGRESS_PAYLOAD_END = 'NEAL_PROGRESS_JUSTIFICATION_JSON_END';
+export function buildReviewerSchema() {
+    return {
+        type: 'object',
+        properties: {
+            summary: { type: 'string' },
+            findings: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        severity: { type: 'string', enum: ['blocking', 'non_blocking'] },
+                        files: { type: 'array', items: { type: 'string' } },
+                        claim: { type: 'string' },
+                        evidence: { type: 'string' },
+                        requiredAction: { type: 'string' },
+                    },
+                    required: ['severity', 'files', 'claim', 'evidence', 'requiredAction'],
+                    additionalProperties: false,
+                },
+            },
+            meaningfulProgressAction: { type: 'string', enum: ['accept', 'block_for_operator', 'replace_plan', 'advance_parent'] },
+            meaningfulProgressRationale: { type: 'string' },
+        },
+        required: ['summary', 'findings', 'meaningfulProgressAction', 'meaningfulProgressRationale'],
+        additionalProperties: false,
+    };
+}
+export function validateReviewerPayload(payload) {
+    const value = requireReviewerObject(payload, 'Reviewer payload');
+    requireReviewerProperties(value, REVIEWER_PAYLOAD_KEYS, 'Reviewer payload');
+    if (!Array.isArray(value.findings)) {
+        throw new Error('Reviewer payload.findings must be an array.');
+    }
+    return {
+        summary: requireReviewerString(value.summary, 'Reviewer payload.summary'),
+        findings: value.findings.map(validateReviewerFindingPayload),
+        meaningfulProgressAction: requireReviewerEnum(value.meaningfulProgressAction, 'Reviewer payload.meaningfulProgressAction', REVIEWER_MEANINGFUL_PROGRESS_ACTIONS),
+        meaningfulProgressRationale: requireReviewerString(value.meaningfulProgressRationale, 'Reviewer payload.meaningfulProgressRationale'),
+    };
+}
+function validateReviewerFindingPayload(finding, index) {
+    const label = `Reviewer payload.findings[${index}]`;
+    const value = requireReviewerObject(finding, label);
+    requireReviewerProperties(value, REVIEWER_FINDING_KEYS, label);
+    if (!Array.isArray(value.files)) {
+        throw new Error(`${label}.files must be an array.`);
+    }
+    return {
+        severity: requireReviewerEnum(value.severity, `${label}.severity`, REVIEWER_FINDING_SEVERITIES),
+        files: value.files.map((file, fileIndex) => requireReviewerString(file, `${label}.files[${fileIndex}]`)),
+        claim: requireReviewerString(value.claim, `${label}.claim`),
+        evidence: requireReviewerString(value.evidence, `${label}.evidence`),
+        requiredAction: requireReviewerString(value.requiredAction, `${label}.requiredAction`),
+    };
+}
+function requireReviewerObject(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${label} must be a non-null object.`);
+    }
+    return value;
+}
+function requireReviewerProperties(value, requiredKeys, label) {
+    for (const key of requiredKeys) {
+        if (!Object.prototype.hasOwnProperty.call(value, key)) {
+            throw new Error(`${label} is missing required property "${key}".`);
+        }
+    }
+    for (const key of Object.keys(value)) {
+        if (!requiredKeys.includes(key)) {
+            throw new Error(`${label} included unknown property "${key}".`);
+        }
+    }
+}
+function requireReviewerString(value, fieldPath) {
+    if (typeof value !== 'string') {
+        throw new Error(`${fieldPath} must be a string.`);
+    }
+    return value;
+}
+function requireReviewerEnum(value, fieldPath, allowedValues) {
+    if (typeof value !== 'string' || !allowedValues.includes(value)) {
+        throw new Error(`${fieldPath} must be exactly one of: ${allowedValues.join(', ')}.`);
+    }
+    return value;
+}
+export function buildPlanReviewerSchema() {
+    return {
+        type: 'object',
+        properties: {
+            summary: { type: 'string' },
+            executionShape: { type: 'string', enum: ['one_shot', 'multi_scope', 'multi_scope_unknown'] },
+            findings: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        severity: { type: 'string', enum: ['blocking', 'non_blocking'] },
+                        files: { type: 'array', items: { type: 'string' } },
+                        claim: { type: 'string' },
+                        requiredAction: { type: 'string' },
+                    },
+                    required: ['severity', 'files', 'claim', 'requiredAction'],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ['summary', 'executionShape', 'findings'],
+        additionalProperties: false,
+    };
+}
+export function buildBlockedAdjudicatorSchema() {
+    return {
+        type: 'object',
+        properties: {
+            recoverable: { type: 'boolean' },
+            triageCategory: {
+                type: 'string',
+                enum: ['misunderstanding', 'authorization', 'external_precondition', 'impossible_task'],
+            },
+            resolutionDirective: { type: 'string' },
+            targetCanonicalIds: { type: 'array', items: { type: 'string' } },
+            rationale: { type: 'string' },
+        },
+        required: ['recoverable', 'triageCategory', 'resolutionDirective', 'rationale'],
+        additionalProperties: false,
+    };
+}
+// Validates a read-only review_stuck arbiter verdict. Exactly one triage
+// category is autonomously recoverable: `misunderstanding` requires
+// recoverable=true plus a non-empty resolutionDirective; the three genuine-wall
+// categories (`authorization`, `external_precondition`, `impossible_task`)
+// require recoverable=false. Anything else (recoverable=true with another
+// triage, or recoverable=false paired with `misunderstanding`) is rejected so a
+// malformed verdict can never drive an autonomous recovery.
+export function validateBlockedAdjudicatorVerdictPayload(rawPayload) {
+    const value = requirePayloadObject(rawPayload, 'Review-stuck arbiter payload');
+    const payload = {
+        recoverable: requirePayloadBoolean(value.recoverable, 'Review-stuck arbiter payload.recoverable'),
+        triageCategory: requirePayloadEnum(value.triageCategory, 'Review-stuck arbiter payload.triageCategory', [
+            'misunderstanding',
+            'authorization',
+            'external_precondition',
+            'impossible_task',
+        ]),
+        resolutionDirective: requirePayloadString(value.resolutionDirective, 'Review-stuck arbiter payload.resolutionDirective'),
+        // The verdict's targetCanonicalIds is optional: a coder/split-plan block has
+        // no reviewer findings to point at, so an absent value defaults to [].
+        targetCanonicalIds: value.targetCanonicalIds === undefined
+            ? []
+            : requirePayloadStringArray(value.targetCanonicalIds, 'Review-stuck arbiter payload.targetCanonicalIds'),
+        rationale: requirePayloadString(value.rationale, 'Review-stuck arbiter payload.rationale'),
+    };
+    if (!payload.rationale.trim()) {
+        throw new Error('Review-stuck arbiter returned an empty rationale.');
+    }
+    if (payload.recoverable) {
+        if (payload.triageCategory !== 'misunderstanding') {
+            throw new Error('Review-stuck arbiter returned recoverable=true with a triageCategory other than misunderstanding.');
+        }
+        if (!payload.resolutionDirective.trim()) {
+            throw new Error('Review-stuck arbiter returned recoverable=true without a non-empty resolutionDirective.');
+        }
+    }
+    else if (payload.triageCategory === 'misunderstanding') {
+        throw new Error('Review-stuck arbiter returned recoverable=false paired with triageCategory=misunderstanding.');
+    }
+    return payload;
+}
+export function validatePlanReviewerPayload(payload) {
+    const value = requirePayloadObject(payload, 'Plan reviewer payload');
+    return {
+        summary: requirePayloadString(value.summary, 'Plan reviewer payload.summary'),
+        executionShape: requirePayloadEnum(value.executionShape, 'Plan reviewer payload.executionShape', [
+            'one_shot',
+            'multi_scope',
+            'multi_scope_unknown',
+        ]),
+        findings: requirePayloadObjectArray(value.findings, 'Plan reviewer payload.findings').map((finding, index) => ({
+            severity: requirePayloadEnum(finding.severity, `Plan reviewer payload.findings[${index}].severity`, [
+                'blocking',
+                'non_blocking',
+            ]),
+            files: requirePayloadStringArray(finding.files, `Plan reviewer payload.findings[${index}].files`),
+            claim: requirePayloadString(finding.claim, `Plan reviewer payload.findings[${index}].claim`),
+            evidence: '',
+            requiredAction: requirePayloadString(finding.requiredAction, `Plan reviewer payload.findings[${index}].requiredAction`),
+        })),
+    };
+}
+export function buildCoderResponseSchema() {
+    return {
+        type: 'object',
+        properties: {
+            outcome: { type: 'string', enum: ['responded', 'blocked', 'split_plan'] },
+            summary: { type: 'string' },
+            blocker: { type: 'string' },
+            derivedPlan: { type: 'string' },
+            responses: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        decision: { type: 'string', enum: ['fixed', 'rejected', 'deferred'] },
+                        summary: { type: 'string' },
+                    },
+                    required: ['id', 'decision', 'summary'],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ['outcome', 'summary', 'blocker', 'derivedPlan', 'responses'],
+        additionalProperties: false,
+    };
+}
+export function buildCoderBlockedRecoveryDispositionSchema() {
+    return {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['resume_current_scope', 'replace_current_scope', 'stay_blocked', 'terminal_block'],
+            },
+            summary: { type: 'string' },
+            rationale: { type: 'string' },
+            blocker: { type: 'string' },
+            replacementPlan: { type: 'string' },
+        },
+        required: ['action', 'summary', 'rationale', 'blocker', 'replacementPlan'],
+        additionalProperties: false,
+    };
+}
+export function buildCoderPlanResponseSchema() {
+    return {
+        type: 'object',
+        properties: {
+            outcome: { type: 'string', enum: ['responded', 'blocked'] },
+            summary: { type: 'string' },
+            blocker: { type: 'string' },
+            responses: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        decision: { type: 'string', enum: ['fixed', 'rejected', 'deferred'] },
+                        summary: { type: 'string' },
+                    },
+                    required: ['id', 'decision', 'summary'],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ['outcome', 'summary', 'blocker', 'responses'],
+        additionalProperties: false,
+    };
+}
+export function buildCoderPlanSchema() {
+    return {
+        type: 'object',
+        properties: {
+            action: { type: 'string', enum: ['ready_for_review', 'blocked'] },
+            message: { type: 'string' },
+            executionShape: { type: 'string', enum: ['one_shot', 'multi_scope', 'multi_scope_unknown'] },
+            planBody: { type: 'string' },
+            blockedReason: { type: 'string' },
+        },
+        required: ['action', 'message', 'executionShape', 'planBody', 'blockedReason'],
+        additionalProperties: false,
+    };
+}
+export function buildCoderScopeSchema() {
+    const manualGateResumeCheckSchema = {
+        type: 'object',
+        properties: {
+            type: { type: 'string', enum: ['command'] },
+            name: { type: 'string' },
+            command: {
+                type: 'array',
+                items: { type: 'string' },
+            },
+            cwd: { type: ['string', 'null'], enum: ['repo', 'run_dir', null] },
+            timeoutMs: { type: ['number', 'null'] },
+        },
+        required: ['type', 'name', 'command', 'cwd', 'timeoutMs'],
+        additionalProperties: false,
+    };
+    return {
+        type: 'object',
+        properties: {
+            action: { type: 'string', enum: ['continue', 'scope_done', 'done', 'blocked', 'split_plan', 'manual_gate'] },
+            message: { type: 'string' },
+            progress: buildExecuteScopeProgressSchema(),
+            manualGate: {
+                type: ['object', 'null'],
+                properties: {
+                    id: { type: 'string' },
+                    title: { type: 'string' },
+                    reason: { type: 'string' },
+                    instructionsMarkdown: { type: 'string' },
+                    resumeChecks: {
+                        type: 'array',
+                        items: manualGateResumeCheckSchema,
+                    },
+                },
+                required: ['id', 'title', 'reason', 'instructionsMarkdown', 'resumeChecks'],
+                additionalProperties: false,
+            },
+            derivedPlan: { type: 'string' },
+            blockedReason: { type: 'string' },
+        },
+        required: ['action', 'message', 'progress', 'manualGate', 'derivedPlan', 'blockedReason'],
+        additionalProperties: false,
+    };
+}
+export function buildExecuteScopeProgressSchema() {
+    return {
+        type: 'object',
+        properties: {
+            milestoneTargeted: { type: 'string' },
+            newEvidence: { type: 'string' },
+            whyNotRedundant: { type: 'string' },
+            nextStepUnlocked: { type: 'string' },
+        },
+        required: ['milestoneTargeted', 'newEvidence', 'whyNotRedundant', 'nextStepUnlocked'],
+        additionalProperties: false,
+    };
+}
+export function buildFinalCompletionSummarySchema() {
+    return {
+        type: 'object',
+        properties: {
+            planGoalSatisfied: { type: 'boolean' },
+            whatChangedOverall: { type: 'string' },
+            verificationSummary: { type: 'string' },
+            remainingKnownGaps: {
+                type: 'array',
+                items: { type: 'string' },
+            },
+        },
+        required: ['planGoalSatisfied', 'whatChangedOverall', 'verificationSummary', 'remainingKnownGaps'],
+        additionalProperties: false,
+    };
+}
+export function buildFinalCompletionReviewerSchema() {
+    return {
+        type: 'object',
+        properties: {
+            action: { type: 'string', enum: ['accept_complete', 'continue_execution', 'block_for_operator'] },
+            summary: { type: 'string' },
+            rationale: { type: 'string' },
+            missingWork: {
+                type: ['object', 'null'],
+                properties: {
+                    summary: { type: 'string' },
+                    requiredOutcome: { type: 'string' },
+                    verification: { type: 'string' },
+                },
+                required: ['summary', 'requiredOutcome', 'verification'],
+                additionalProperties: false,
+            },
+            squashCommitMessage: {
+                description: 'Project-facing Git history metadata used only when action is accept_complete; set null for continue_execution or block_for_operator.',
+                type: ['object', 'null'],
+                properties: {
+                    subject: {
+                        description: 'Concise project-facing commit subject summarizing code or product behavior, not plan documents, paths, scopes, Neal mechanics, provider process, reviewer process, or final cleanup.',
+                        type: 'string',
+                    },
+                    bullets: {
+                        description: 'Two to five project-facing Git history bullets summarizing behavior changes; avoid plan paths, markdown plan filenames, temporary run paths, scope wording, Neal mechanics, provider process, or reviewer process.',
+                        type: 'array',
+                        minItems: 2,
+                        maxItems: 5,
+                        items: { type: 'string' },
+                    },
+                },
+                required: ['subject', 'bullets'],
+                additionalProperties: false,
+            },
+        },
+        required: ['action', 'summary', 'rationale', 'missingWork', 'squashCommitMessage'],
+        additionalProperties: false,
+    };
+}
+function parseJsonPayload(raw, label) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${label} returned invalid JSON: ${message}\nRaw response:\n${raw}`);
+    }
+}
+function extractDelimitedPayload(raw, label) {
+    const startIndex = raw.indexOf(EXECUTE_SCOPE_PROGRESS_PAYLOAD_START);
+    if (startIndex === -1) {
+        throw new Error(`${label} did not include the required progress-justification payload start marker.`);
+    }
+    if (raw.indexOf(EXECUTE_SCOPE_PROGRESS_PAYLOAD_START, startIndex + EXECUTE_SCOPE_PROGRESS_PAYLOAD_START.length) !== -1) {
+        throw new Error(`${label} included multiple progress-justification payload start markers.`);
+    }
+    const endIndex = raw.indexOf(EXECUTE_SCOPE_PROGRESS_PAYLOAD_END, startIndex + EXECUTE_SCOPE_PROGRESS_PAYLOAD_START.length);
+    if (endIndex === -1) {
+        throw new Error(`${label} did not include the required progress-justification payload end marker.`);
+    }
+    if (raw.indexOf(EXECUTE_SCOPE_PROGRESS_PAYLOAD_END, endIndex + EXECUTE_SCOPE_PROGRESS_PAYLOAD_END.length) !== -1) {
+        throw new Error(`${label} included multiple progress-justification payload end markers.`);
+    }
+    const payloadText = raw.slice(startIndex + EXECUTE_SCOPE_PROGRESS_PAYLOAD_START.length, endIndex).trim();
+    if (!payloadText) {
+        throw new Error(`${label} returned an empty progress-justification payload.`);
+    }
+    return {
+        payloadText,
+        startIndex,
+        endIndex,
+    };
+}
+function requireNonEmptyString(value, field, label) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`${label} returned an empty or missing ${field} field in the progress-justification payload.`);
+    }
+    return value.trim();
+}
+function requirePayloadObject(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${label} must be a non-null object.`);
+    }
+    return value;
+}
+function requirePayloadString(value, fieldPath) {
+    if (typeof value !== 'string') {
+        throw new Error(`${fieldPath} must be a string.`);
+    }
+    return value;
+}
+function requirePayloadBoolean(value, fieldPath) {
+    if (typeof value !== 'boolean') {
+        throw new Error(`${fieldPath} must be a boolean.`);
+    }
+    return value;
+}
+function requirePayloadStringArray(value, fieldPath) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${fieldPath} must be an array.`);
+    }
+    return value.map((item, index) => requirePayloadString(item, `${fieldPath}[${index}]`));
+}
+function requirePayloadObjectArray(value, fieldPath) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${fieldPath} must be an array.`);
+    }
+    return value.map((item, index) => requirePayloadObject(item, `${fieldPath}[${index}]`));
+}
+function requirePayloadEnum(value, fieldPath, allowedValues) {
+    if (typeof value !== 'string' || !allowedValues.includes(value)) {
+        throw new Error(`${fieldPath} must be exactly one of: ${allowedValues.join(', ')}.`);
+    }
+    return value;
+}
+function validateCoderFindingResponse(value, fieldPath) {
+    const response = requirePayloadObject(value, fieldPath);
+    return {
+        id: requirePayloadString(response.id, `${fieldPath}.id`),
+        decision: requirePayloadEnum(response.decision, `${fieldPath}.decision`, ['fixed', 'rejected', 'deferred']),
+        summary: requirePayloadString(response.summary, `${fieldPath}.summary`),
+    };
+}
+// Legacy marker-protocol compatibility for active legacy_marker_v1 execution
+// sessions. New primary execution sessions use CoderScopePayload instead.
+export function parseExecuteScopeProgressPayload(raw) {
+    const label = 'Coder scope round';
+    const { payloadText } = extractDelimitedPayload(raw, label);
+    const payload = parseJsonPayload(payloadText, `${label} progress-justification payload`);
+    return {
+        milestoneTargeted: requireNonEmptyString(payload.milestoneTargeted, 'milestoneTargeted', label),
+        newEvidence: requireNonEmptyString(payload.newEvidence, 'newEvidence', label),
+        whyNotRedundant: requireNonEmptyString(payload.whyNotRedundant, 'whyNotRedundant', label),
+        nextStepUnlocked: requireNonEmptyString(payload.nextStepUnlocked, 'nextStepUnlocked', label),
+    };
+}
+export function stripExecuteScopeProgressPayload(raw) {
+    const { startIndex, endIndex } = extractDelimitedPayload(raw, 'Coder scope round');
+    const before = raw.slice(0, startIndex).trimEnd();
+    const after = raw.slice(endIndex + EXECUTE_SCOPE_PROGRESS_PAYLOAD_END.length).trimStart();
+    if (before && after) {
+        return `${before}\n\n${after}`;
+    }
+    return before || after;
+}
+export function validateCoderResponsePayload(rawPayload) {
+    const value = requirePayloadObject(rawPayload, 'Coder response round payload');
+    const payload = {
+        outcome: requirePayloadEnum(value.outcome, 'Coder response round payload.outcome', [
+            'responded',
+            'blocked',
+            'split_plan',
+        ]),
+        summary: requirePayloadString(value.summary, 'Coder response round payload.summary'),
+        blocker: requirePayloadString(value.blocker, 'Coder response round payload.blocker'),
+        derivedPlan: requirePayloadString(value.derivedPlan, 'Coder response round payload.derivedPlan'),
+        responses: requirePayloadObjectArray(value.responses, 'Coder response round payload.responses').map((response, index) => validateCoderFindingResponse(response, `Coder response round payload.responses[${index}]`)),
+    };
+    const derivedPlan = payload.derivedPlan?.trim() ?? '';
+    if (payload.outcome === 'split_plan' && !derivedPlan) {
+        throw new Error('Coder response round returned outcome=split_plan without a derivedPlan payload.');
+    }
+    if (payload.outcome !== 'split_plan' && derivedPlan) {
+        throw new Error('Coder response round returned a derivedPlan payload without outcome=split_plan.');
+    }
+    return payload;
+}
+export function validateCoderPlanResponsePayload(payload) {
+    const value = requirePayloadObject(payload, 'Planner plan-response round payload');
+    return {
+        outcome: requirePayloadEnum(value.outcome, 'Planner plan-response round payload.outcome', [
+            'responded',
+            'blocked',
+        ]),
+        summary: requirePayloadString(value.summary, 'Planner plan-response round payload.summary'),
+        blocker: requirePayloadString(value.blocker, 'Planner plan-response round payload.blocker'),
+        responses: requirePayloadObjectArray(value.responses, 'Planner plan-response round payload.responses').map((response, index) => validateCoderFindingResponse(response, `Planner plan-response round payload.responses[${index}]`)),
+    };
+}
+export function validateCoderPlanPayload(rawPayload) {
+    const value = requirePayloadObject(rawPayload, 'Planner plan round payload');
+    const payload = {
+        action: requirePayloadEnum(value.action, 'Planner plan round payload.action', [
+            'ready_for_review',
+            'blocked',
+        ]),
+        message: requirePayloadString(value.message, 'Planner plan round payload.message'),
+        executionShape: requirePayloadEnum(value.executionShape, 'Planner plan round payload.executionShape', [
+            'one_shot',
+            'multi_scope',
+            'multi_scope_unknown',
+        ]),
+        planBody: requirePayloadString(value.planBody, 'Planner plan round payload.planBody'),
+        blockedReason: requirePayloadString(value.blockedReason, 'Planner plan round payload.blockedReason'),
+    };
+    const planBody = payload.planBody.trim();
+    const blockedReason = payload.blockedReason.trim();
+    if (payload.action === 'ready_for_review' && !planBody) {
+        throw new Error('Planner plan round returned action=ready_for_review without a planBody payload.');
+    }
+    if (payload.action === 'ready_for_review' && blockedReason) {
+        throw new Error('Planner plan round returned a blockedReason payload with action=ready_for_review.');
+    }
+    if (payload.action === 'blocked' && !blockedReason) {
+        throw new Error('Planner plan round returned action=blocked without a blockedReason payload.');
+    }
+    return {
+        ...payload,
+        message: payload.message.trim(),
+    };
+}
+export function validateCoderScopePayload(rawPayload) {
+    const value = requirePayloadObject(rawPayload, 'Coder scope round payload');
+    const payload = {
+        action: requirePayloadEnum(value.action, 'Coder scope round payload.action', [
+            'continue',
+            'scope_done',
+            'done',
+            'blocked',
+            'split_plan',
+            'manual_gate',
+        ]),
+        message: requirePayloadString(value.message, 'Coder scope round payload.message'),
+        progress: requirePayloadObject(value.progress, 'Coder scope round payload.progress'),
+        manualGate: value.manualGate === null
+            ? null
+            : requirePayloadObject(value.manualGate, 'Coder scope round payload.manualGate'),
+        derivedPlan: requirePayloadString(value.derivedPlan, 'Coder scope round payload.derivedPlan'),
+        blockedReason: requirePayloadString(value.blockedReason, 'Coder scope round payload.blockedReason'),
+    };
+    const progress = {
+        milestoneTargeted: requireNonEmptyString(payload.progress?.milestoneTargeted, 'milestoneTargeted', 'Coder scope round'),
+        newEvidence: requireNonEmptyString(payload.progress?.newEvidence, 'newEvidence', 'Coder scope round'),
+        whyNotRedundant: requireNonEmptyString(payload.progress?.whyNotRedundant, 'whyNotRedundant', 'Coder scope round'),
+        nextStepUnlocked: requireNonEmptyString(payload.progress?.nextStepUnlocked, 'nextStepUnlocked', 'Coder scope round'),
+    };
+    const derivedPlan = payload.derivedPlan.trim();
+    const blockedReason = payload.blockedReason.trim();
+    const manualGate = payload.manualGate;
+    if (payload.action === 'split_plan' && !derivedPlan) {
+        throw new Error('Coder scope round returned action=split_plan without a derivedPlan payload.');
+    }
+    if (payload.action !== 'split_plan' && derivedPlan) {
+        throw new Error('Coder scope round returned a derivedPlan payload without action=split_plan.');
+    }
+    if (payload.action === 'blocked' && !blockedReason) {
+        throw new Error('Coder scope round returned action=blocked without a blockedReason payload.');
+    }
+    if (payload.action !== 'blocked' && blockedReason) {
+        throw new Error('Coder scope round returned a blockedReason payload without action=blocked.');
+    }
+    if (payload.action === 'manual_gate') {
+        if (manualGate === null || typeof manualGate !== 'object') {
+            throw new Error('Coder scope round returned action=manual_gate without a manualGate payload.');
+        }
+        if (derivedPlan) {
+            throw new Error('Coder scope round returned a derivedPlan payload with action=manual_gate.');
+        }
+        if (blockedReason) {
+            throw new Error('Coder scope round returned a blockedReason payload with action=manual_gate.');
+        }
+        const id = requireNonEmptyManualGateString(manualGate.id, 'manualGate.id');
+        const title = requireNonEmptyManualGateString(manualGate.title, 'manualGate.title');
+        const reason = requireNonEmptyManualGateString(manualGate.reason, 'manualGate.reason');
+        const instructionsMarkdown = requireNonEmptyManualGateString(manualGate.instructionsMarkdown, 'manualGate.instructionsMarkdown');
+        const resumeChecks = validateManualGateResumeChecks(manualGate.resumeChecks);
+        return {
+            ...payload,
+            message: payload.message.trim(),
+            progress,
+            manualGate: {
+                id,
+                title,
+                reason,
+                instructionsMarkdown,
+                resumeChecks,
+            },
+        };
+    }
+    if (manualGate !== null) {
+        throw new Error('Coder scope round returned a manualGate payload without action=manual_gate.');
+    }
+    return {
+        ...payload,
+        message: payload.message.trim(),
+        progress,
+    };
+}
+function requireNonEmptyManualGateString(value, fieldPath) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`Coder scope round returned an empty or missing ${fieldPath} field.`);
+    }
+    return value.trim();
+}
+function validateManualGateResumeChecks(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error('Coder scope round returned manualGate.resumeChecks without at least one command check.');
+    }
+    return value.map((check, index) => {
+        const fieldPath = `manualGate.resumeChecks[${index}]`;
+        if (check === null || typeof check !== 'object') {
+            throw new Error(`Coder scope round returned invalid ${fieldPath}.`);
+        }
+        const candidate = check;
+        if (candidate.type !== 'command') {
+            throw new Error(`Coder scope round returned ${fieldPath}.type that is not "command".`);
+        }
+        const name = requireNonEmptyManualGateString(candidate.name, `${fieldPath}.name`);
+        if (!Array.isArray(candidate.command) || candidate.command.length === 0) {
+            throw new Error(`Coder scope round returned ${fieldPath}.command without a non-empty string array.`);
+        }
+        const command = candidate.command.map((part, commandIndex) => requireNonEmptyManualGateString(part, `${fieldPath}.command[${commandIndex}]`));
+        if (candidate.cwd !== undefined &&
+            candidate.cwd !== null &&
+            candidate.cwd !== 'repo' &&
+            candidate.cwd !== 'run_dir') {
+            throw new Error(`Coder scope round returned ${fieldPath}.cwd that is not "repo" or "run_dir".`);
+        }
+        if (candidate.timeoutMs !== undefined &&
+            candidate.timeoutMs !== null &&
+            (typeof candidate.timeoutMs !== 'number' || !Number.isSafeInteger(candidate.timeoutMs) || candidate.timeoutMs < 1)) {
+            throw new Error(`Coder scope round returned ${fieldPath}.timeoutMs that is not a positive safe integer.`);
+        }
+        return {
+            type: 'command',
+            name,
+            command,
+            ...(candidate.cwd === undefined || candidate.cwd === null ? {} : { cwd: candidate.cwd }),
+            ...(candidate.timeoutMs === undefined || candidate.timeoutMs === null ? {} : { timeoutMs: candidate.timeoutMs }),
+        };
+    });
+}
+function nonEmptyTrimmedItems(items) {
+    return items.map((item) => item.trim()).filter((item) => item.length > 0);
+}
+export function validateCoderBlockedRecoveryDispositionPayload(rawPayload) {
+    const value = requirePayloadObject(rawPayload, 'Coder blocked-recovery payload');
+    const payload = {
+        action: requirePayloadEnum(value.action, 'Coder blocked-recovery payload.action', [
+            'resume_current_scope',
+            'replace_current_scope',
+            'stay_blocked',
+            'terminal_block',
+        ]),
+        summary: requirePayloadString(value.summary, 'Coder blocked-recovery payload.summary'),
+        rationale: requirePayloadString(value.rationale, 'Coder blocked-recovery payload.rationale'),
+        blocker: requirePayloadString(value.blocker, 'Coder blocked-recovery payload.blocker'),
+        replacementPlan: requirePayloadString(value.replacementPlan, 'Coder blocked-recovery payload.replacementPlan'),
+    };
+    const blocker = payload.blocker.trim();
+    const replacementPlan = payload.replacementPlan.trim();
+    if (payload.action === 'replace_current_scope' && !replacementPlan) {
+        throw new Error('Coder blocked-recovery round returned action=replace_current_scope without a replacementPlan payload.');
+    }
+    if (payload.action !== 'replace_current_scope' && replacementPlan) {
+        throw new Error('Coder blocked-recovery round returned a replacementPlan payload without action=replace_current_scope.');
+    }
+    if ((payload.action === 'stay_blocked' || payload.action === 'terminal_block') && !blocker) {
+        throw new Error(`Coder blocked-recovery round returned action=${payload.action} without a blocker payload.`);
+    }
+    return payload;
+}
+export function parseFinalCompletionSummaryPayload(rawPayload) {
+    const value = requirePayloadObject(rawPayload, 'Final completion summary payload');
+    const payload = {
+        planGoalSatisfied: requirePayloadBoolean(value.planGoalSatisfied, 'Final completion summary payload.planGoalSatisfied'),
+        whatChangedOverall: requirePayloadString(value.whatChangedOverall, 'Final completion summary payload.whatChangedOverall'),
+        verificationSummary: requirePayloadString(value.verificationSummary, 'Final completion summary payload.verificationSummary'),
+        remainingKnownGaps: requirePayloadStringArray(value.remainingKnownGaps, 'Final completion summary payload.remainingKnownGaps'),
+    };
+    const whatChangedOverall = payload.whatChangedOverall.trim();
+    const verificationSummary = payload.verificationSummary.trim();
+    const remainingKnownGaps = payload.remainingKnownGaps
+        .map((gap) => gap.trim())
+        .filter((gap) => gap.length > 0);
+    if (!whatChangedOverall) {
+        throw new Error('Final completion summary returned an empty whatChangedOverall field.');
+    }
+    if (!verificationSummary) {
+        throw new Error('Final completion summary returned an empty verificationSummary field.');
+    }
+    if (payload.planGoalSatisfied && remainingKnownGaps.length > 0) {
+        throw new Error('Final completion summary cannot set planGoalSatisfied=true while remainingKnownGaps is non-empty.');
+    }
+    if (!payload.planGoalSatisfied && remainingKnownGaps.length === 0) {
+        throw new Error('Final completion summary cannot set planGoalSatisfied=false with an empty remainingKnownGaps array.');
+    }
+    return {
+        planGoalSatisfied: payload.planGoalSatisfied,
+        whatChangedOverall,
+        verificationSummary,
+        remainingKnownGaps,
+    };
+}
+export function parseFinalCompletionReviewerPayload(rawPayload) {
+    const value = requirePayloadObject(rawPayload, 'Final completion reviewer verdict payload');
+    const action = requirePayloadEnum(value.action, 'Final completion reviewer verdict payload.action', [
+        'accept_complete',
+        'continue_execution',
+        'block_for_operator',
+    ]);
+    const missingWorkValue = value.missingWork;
+    const missingWorkShape = missingWorkValue === null
+        ? null
+        : requirePayloadObject(missingWorkValue, 'Final completion reviewer verdict payload.missingWork');
+    const payload = {
+        action,
+        summary: requirePayloadString(value.summary, 'Final completion reviewer verdict payload.summary'),
+        rationale: requirePayloadString(value.rationale, 'Final completion reviewer verdict payload.rationale'),
+        missingWork: missingWorkShape === null
+            ? null
+            : {
+                summary: requirePayloadString(missingWorkShape.summary, 'Final completion reviewer verdict payload.missingWork.summary'),
+                requiredOutcome: requirePayloadString(missingWorkShape.requiredOutcome, 'Final completion reviewer verdict payload.missingWork.requiredOutcome'),
+                verification: requirePayloadString(missingWorkShape.verification, 'Final completion reviewer verdict payload.missingWork.verification'),
+            },
+        squashCommitMessage: value.squashCommitMessage === null || value.squashCommitMessage === undefined
+            ? null
+            : requirePayloadObject(value.squashCommitMessage, 'Final completion reviewer verdict payload.squashCommitMessage'),
+    };
+    const summary = payload.summary.trim();
+    const rationale = payload.rationale.trim();
+    const squashCommitMessageValue = payload.squashCommitMessage ?? null;
+    if (!['accept_complete', 'continue_execution', 'block_for_operator'].includes(payload.action)) {
+        throw new Error(`Final completion reviewer verdict returned unsupported action ${JSON.stringify(payload.action)}.`);
+    }
+    if (!summary) {
+        throw new Error('Final completion reviewer verdict returned an empty summary field.');
+    }
+    if (!rationale) {
+        throw new Error('Final completion reviewer verdict returned an empty rationale field.');
+    }
+    const missingWork = payload.missingWork === null
+        ? null
+        : {
+            summary: payload.missingWork.summary.trim(),
+            requiredOutcome: payload.missingWork.requiredOutcome.trim(),
+            verification: payload.missingWork.verification.trim(),
+        };
+    if (payload.action === 'continue_execution') {
+        if (!missingWork ||
+            !missingWork.summary ||
+            !missingWork.requiredOutcome ||
+            !missingWork.verification) {
+            throw new Error('Final completion reviewer verdict must include a non-empty missingWork payload when action=continue_execution.');
+        }
+    }
+    if (payload.action !== 'continue_execution' && missingWork) {
+        throw new Error(`Final completion reviewer verdict cannot include missingWork when action=${payload.action}.`);
+    }
+    let squashCommitMessage = null;
+    if (payload.action === 'accept_complete' && squashCommitMessageValue !== null) {
+        try {
+            squashCommitMessage = validateReviewerSquashMessageDraft(squashCommitMessageValue, {
+                label: 'Final completion reviewer squashCommitMessage',
+            });
+        }
+        catch (error) {
+            squashCommitMessage = repairReviewerSquashMessageDraft(squashCommitMessageValue);
+        }
+    }
+    return {
+        action: payload.action,
+        summary,
+        rationale,
+        missingWork,
+        squashCommitMessage,
+    };
+}