@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/dist/runs/foreground/wait-run.js

@@ -0,0 +1,139 @@
+import * as path from "node:path";
+import { writeAsyncControlRequest } from "../background/async-control.js";
+import { ownedRunExecutionResult, ownedRunProgressResult, ownedRunStatusResult, ownedRunView, resolveOwnedRun } from "../shared/run-records.js";
+import { getRunMetadataDir, listOwnedRunQuestions, questionProcessAlive, readRunJson } from "../shared/supervisor-questions.js";
+import { getSingleResultOutput, readStatus } from "../../shared/utils.js";
+import { INTERCOM_DETACH_REQUEST_EVENT, INTERCOM_DETACH_RESPONSE_EVENT, POLL_INTERVAL_MS } from "../../shared/types.js";
+import { resolveSubagentRunId } from "../background/run-id-resolver.js";
+import { resolveNestedAsyncDir } from "../shared/nested-events.js";
+import { nestedResolutionScopeForExecutor } from "./foreground-control.js";
+/** Wait on the saved outcome, not the transient notification file or an early terminal status. */
+export async function waitForOwnedRun(input) {
+    const { deps, id, index, ctx } = input;
+    const owner = ctx.sessionManager.getSessionId(), session = deps.state.currentSessionId;
+    let run, nested = false;
+    try {
+        run = resolveOwnedRun(deps.state, id);
+        if (!run) {
+            const resolved = resolveSubagentRunId(id, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps) });
+            if (resolved?.kind === "nested") {
+                const asyncDir = resolveNestedAsyncDir(resolved.match.rootRunId, resolved.match.run);
+                const status = asyncDir ? readStatus(asyncDir) : null;
+                if (status?.runId === resolved.id) {
+                    const savedOwner = readRunJson(path.join(getRunMetadataDir(resolved.id), "question-owner.json"));
+                    // Read through the authorized route without adopting the descendant or attributing its usage to this caller.
+                    run = { runId: resolved.id, rootRunId: resolved.match.rootRunId, ownerSessionId: savedOwner?.sessionId ?? status.sessionId ?? "",
+                        source: "async", mode: status.mode, cwd: status.cwd ?? "", task: "Nested delegated run", startedAt: status.startedAt, asyncDir, pid: status.pid,
+                        children: (status.steps ?? []).map((step, index) => ({ agent: step.agent, index, sessionFile: step.sessionFile })) };
+                    nested = true;
+                }
+            }
+        }
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: String(error) }], isError: true, details: { mode: "management", results: [] } };
+    }
+    if (!run || (!nested && run.ownerSessionId !== owner))
+        return { content: [{ type: "text", text: "Run is not available to wait on in this session. This wait did not start or stop work." }], isError: true, details: { mode: "management", results: [] } };
+    const target = run;
+    const waiting = deps.state.waitingRuns ??= new Map();
+    waiting.set(target.runId, (waiting.get(target.runId) ?? 0) + 1);
+    return new Promise((resolve) => {
+        let finished = false, timer, unsubscribe;
+        let previous = "";
+        const finish = (status, text, result) => {
+            if (finished)
+                return;
+            finished = true;
+            const remaining = (waiting.get(target.runId) ?? 1) - 1;
+            if (remaining)
+                waiting.set(target.runId, remaining);
+            else
+                waiting.delete(target.runId);
+            if (timer)
+                clearInterval(timer);
+            unsubscribe?.();
+            input.signal?.removeEventListener("abort", abort);
+            const execution = input.executionResult && status === "completed" ? ownedRunExecutionResult(target, deps.state, index, input.includeProgress) : undefined;
+            const saved = status === "completed" ? readRunJson(path.join(getRunMetadataDir(target.runId), "result.json")) : undefined;
+            resolve({ ...result, ...execution, content: status === "completed" && execution ? execution.content : [{ type: "text", text }],
+                ...(status === "unavailable" || status === "cancelled" ? { isError: true } : {}),
+                details: { mode: "management", results: [], ...result?.details, ...execution?.details, wait: { runId: target.runId, completionId: saved?.completionId, index, status } } });
+        };
+        const abort = () => {
+            if (input.cancelNewRun && target.asyncDir) {
+                writeAsyncControlRequest(target.asyncDir, target.runId, "cancel");
+            }
+            finish("cancelled", input.cancelNewRun ? `Wait cancelled; cancellation requested for newly launched run ${target.runId}. Process exit is not yet confirmed.` : `Stopped waiting for ${target.runId}. The child was not stopped; completion will arrive automatically.`);
+        };
+        const check = () => {
+            if (deps.state.currentSessionId !== session || ctx.sessionManager.getSessionId() !== owner) {
+                finish("unavailable", "The owning session changed. This wait ended without stopping the child.");
+                return;
+            }
+            try {
+                const runQuestions = listOwnedRunQuestions(target.ownerSessionId, target.runId);
+                // Poll execution facts once. Native conversation configuration is only
+                // needed when returning an inspection, never for live progress.
+                const view = ownedRunView(target, deps.state, {
+                    pendingInput: runQuestions.some((question) => question.state === "awaiting_input" || question.state === "answer_pending"),
+                    readConfiguration: false, includeContinuations: false,
+                });
+                const children = view.children.filter((child) => index === undefined || child.index === index);
+                if (index !== undefined && !children.length) {
+                    finish("unavailable", `Run ${target.runId} has no child at index ${index}.`);
+                    return;
+                }
+                const questions = runQuestions.filter((question) => question.ownerSessionId === owner && (index === undefined || question.index === index) && question.state === "awaiting_input");
+                if (questions.length) {
+                    const result = ownedRunStatusResult(target, deps.state);
+                    result.details.questions = questions;
+                    finish("awaiting_input", `Run ${target.runId} needs input; waiting ended without stopping it.\n\n${questions.map((question) => `Question ${question.questionId}: ${question.message}`).join("\n\n")}`, result);
+                    return;
+                }
+                if ((index !== undefined || view.resultPath) && children.every((child) => child.result && child.state !== "live" && child.state !== "unknown") && (index !== undefined || view.state !== "live")) {
+                    const result = ownedRunStatusResult(target, deps.state);
+                    result.isError = children.some((child) => child.state === "failed") || (index === undefined && view.state === "failed") || undefined;
+                    finish("completed", [`Saved result for ${target.runId}${index !== undefined ? ` child ${index}` : ""}: ${index !== undefined ? children[0].state : view.state}`, ...children.map((child) => `\n${child.agent}: ${child.state}\n${getSingleResultOutput(child.result) || child.result?.error || "(no output)"}`), result.content.map((part) => part.type === "text" ? part.text : "").join("\n")].join("\n"), result);
+                    return;
+                }
+                const pid = target.pid ?? (target.asyncDir ? readStatus(target.asyncDir)?.pid : undefined);
+                const producerAlive = pid ? questionProcessAlive({ pid }) : children.some((child) => child.state === "live");
+                if (!producerAlive) {
+                    finish("unavailable", `No saved final result is available for ${target.runId}; completion is unconfirmed. Inspect the saved session. No work was started.`, ownedRunStatusResult(target, deps.state));
+                    return;
+                }
+                const update = `Waiting for ${target.runId}${index !== undefined ? ` child ${index}` : ""}: ${children.map((child) => child.state).join(", ")}. ${input.cancelNewRun ? "Cancelling requests cancellation of this newly launched run; process exit still needs confirmation." : "Cancelling this wait leaves existing work alive."}`;
+                if (input.onUpdate) {
+                    const progress = ownedRunProgressResult(target, deps.state, index, view);
+                    const signature = JSON.stringify(progress.details.progress?.map(({ durationMs: _duration, ...activity }) => activity));
+                    if (signature !== previous) {
+                        previous = signature;
+                        input.onUpdate({ ...progress, content: [{ type: "text", text: update }, ...progress.content] });
+                    }
+                }
+            }
+            catch (error) {
+                finish("unavailable", `Wait could not read ${target.runId}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        };
+        unsubscribe = deps.pi.events.on(INTERCOM_DETACH_REQUEST_EVENT, (payload) => {
+            if (finished || !payload || typeof payload !== "object")
+                return;
+            const requestId = payload.requestId;
+            if (typeof requestId !== "string")
+                return;
+            deps.pi.events.emit(INTERCOM_DETACH_RESPONSE_EVENT, { requestId, accepted: true });
+            finish("yielded", `Released the wait for an incoming Intercom message. Run ${target.runId} is unchanged. Continue useful work or end the turn; completion will arrive automatically.`);
+        });
+        input.signal?.addEventListener("abort", abort, { once: true });
+        if (input.signal?.aborted)
+            abort();
+        else
+            check();
+        // Unlike passive background tracking, this foreground call owes a result.
+        // The detached runner cannot keep this process alive; finish() releases the timer.
+        if (!finished)
+            timer = setInterval(check, POLL_INTERVAL_MS);
+    });
+}

package/dist/runs/shared/acceptance-contract.js

@@ -0,0 +1,253 @@
+import { Compile } from "../../shared/native-typebox.js";
+import { AcceptanceOverride } from "../../extension/schemas.js";
+import { formatAcceptanceReportExample } from "./acceptance-reports.js";
+const DEFAULT_FINALIZATION_MAX_TURNS = 3;
+const MAX_FINALIZATION_TURNS = 10;
+const VALID_EVIDENCE = new Set([
+    "changed-files",
+    "tests-added",
+    "commands-run",
+    "validation-output",
+    "residual-risks",
+    "no-staged-files",
+    "diff-summary",
+    "review-findings",
+    "manual-notes",
+]);
+const ACCEPTANCE_KEYS = new Set(Object.keys(AcceptanceOverride.properties));
+const REMOVED_ACCEPTANCE_KEYS = new Set(["level", "finalization", "reason", "review"]);
+const ACCEPTANCE_VALIDATOR = Compile(AcceptanceOverride);
+const EVIDENCE_REPORT_FIELDS = {
+    "changed-files": "changedFiles: array of changed file paths",
+    "tests-added": "testsAddedOrUpdated: array of test files, suites, or cases added/updated",
+    "commands-run": "commandsRun: array of commands with result passed/failed/not-run and a short summary",
+    "validation-output": "validationOutput: array of relevant validation output summaries",
+    "residual-risks": "residualRisks: array of remaining risks or blockers; use [] when none remain",
+    "no-staged-files": "noStagedFiles: boolean",
+    "diff-summary": "diffSummary: non-empty string summarizing changed behavior and important files",
+    "review-findings": "reviewFindings: array of reviewer findings as strings or objects; use [] when no findings remain",
+    "manual-notes": "manualNotes: string for manual notes or external evidence",
+};
+export function formatEvidenceReportFieldMapping(evidence) {
+    return evidence.map((kind) => `- ${kind} -> ${EVIDENCE_REPORT_FIELDS[kind]}`);
+}
+function hasArrayItems(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+function acceptanceErrorPath(pathLabel, instancePath) {
+    return instancePath.split("/").slice(1).reduce((result, part) => {
+        const decoded = part.replaceAll("~1", "/").replaceAll("~0", "~");
+        return /^\d+$/.test(decoded) ? `${result}[${decoded}]` : `${result}.${decoded}`;
+    }, pathLabel);
+}
+export function validateAcceptanceInput(input, pathLabel = "acceptance") {
+    if (input === undefined)
+        return [];
+    if (input === false || typeof input === "string") {
+        return [`${pathLabel} must be an object. Public acceptance levels and false disables are no longer supported.`];
+    }
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return [`${pathLabel} must be an object.`];
+    const value = input;
+    const errors = [];
+    if (Object.hasOwn(value, "level"))
+        errors.push(`${pathLabel}.level is no longer supported; configure criteria, evidence, and verify directly.`);
+    if (Object.hasOwn(value, "review"))
+        errors.push(`${pathLabel}.review is not supported; launch a separate parent-controlled reviewer after the worker completes.`);
+    if (Object.hasOwn(value, "finalization"))
+        errors.push(`${pathLabel}.finalization is not supported; acceptance contracts always run the self-review loop.`);
+    if (Object.hasOwn(value, "reason"))
+        errors.push(`${pathLabel}.reason is not supported because acceptance is disabled by omitting the field.`);
+    for (const key of Object.keys(value)) {
+        if (!ACCEPTANCE_KEYS.has(key) && !REMOVED_ACCEPTANCE_KEYS.has(key))
+            errors.push(`${pathLabel}.${key} is not supported.`);
+    }
+    const structuralValue = Object.fromEntries(Object.entries(value).filter(([key]) => ACCEPTANCE_KEYS.has(key)));
+    const schemaErrors = [...ACCEPTANCE_VALIDATOR.Errors(structuralValue)];
+    for (const error of schemaErrors) {
+        const criterionMatch = error.instancePath.match(/^\/criteria\/(\d+)$/);
+        if (criterionMatch) {
+            const criterion = Array.isArray(value.criteria) ? value.criteria[Number(criterionMatch[1])] : undefined;
+            if (criterion && typeof criterion === "object" && !Array.isArray(criterion)) {
+                if (error.keyword === "anyOf" || error.schemaPath.includes("/anyOf/0"))
+                    continue;
+            }
+            else if (typeof criterion === "string") {
+                if (error.keyword === "anyOf" || error.schemaPath.includes("/anyOf/1"))
+                    continue;
+            }
+            else if (error.keyword !== "anyOf") {
+                continue;
+            }
+        }
+        if (error.keyword === "minLength")
+            continue;
+        const errorPath = acceptanceErrorPath(pathLabel, error.instancePath);
+        if (error.keyword === "anyOf" && criterionMatch) {
+            errors.push(`${errorPath} must be a string or object.`);
+        }
+        else if (error.keyword === "required") {
+            for (const property of error.params.requiredProperties)
+                errors.push(`${errorPath}.${property} is required.`);
+        }
+        else if (error.keyword === "enum" && error.instancePath.includes("/evidence/")) {
+            errors.push(`${errorPath} is not a supported evidence kind.`);
+        }
+        else if (error.keyword === "enum" && error.instancePath.endsWith("/severity")) {
+            errors.push(`${errorPath} must be required or recommended.`);
+        }
+        else if (error.instancePath.endsWith("/timeoutMs")) {
+            errors.push(`${errorPath} must be a positive integer.`);
+        }
+        else if (error.instancePath === "/maxFinalizationTurns") {
+            errors.push(`${errorPath} must be an integer from 1 to ${MAX_FINALIZATION_TURNS}.`);
+        }
+        else if (error.keyword === "additionalProperties") {
+            for (const property of error.params.additionalProperties) {
+                errors.push(error.instancePath.endsWith("/env") ? `${errorPath}.${property} must be a string.` : `${errorPath}.${property} is not supported.`);
+            }
+        }
+        else if (error.keyword === "type") {
+            const expected = String(error.params.type);
+            const suffix = error.instancePath.match(/^\/stopRules\/\d+$/) ? "a non-empty string" : expected === "array" || expected === "object" ? `an ${expected}` : `a ${expected}`;
+            errors.push(`${errorPath} must be ${suffix}.`);
+        }
+        else {
+            errors.push(`${errorPath} ${error.message}.`);
+        }
+    }
+    for (const [index, criterion] of Array.isArray(value.criteria) ? value.criteria.entries() : []) {
+        if (typeof criterion === "string" && !criterion.trim())
+            errors.push(`${pathLabel}.criteria[${index}] must not be empty.`);
+        if (criterion && typeof criterion === "object" && !Array.isArray(criterion)) {
+            const item = criterion;
+            if (typeof item.id === "string" && !item.id.trim())
+                errors.push(`${pathLabel}.criteria[${index}].id is required.`);
+            if (typeof item.must === "string" && !item.must.trim())
+                errors.push(`${pathLabel}.criteria[${index}].must is required.`);
+        }
+    }
+    for (const [index, command] of Array.isArray(value.verify) ? value.verify.entries() : []) {
+        if (!command || typeof command !== "object" || Array.isArray(command))
+            continue;
+        const item = command;
+        if (typeof item.id === "string" && !item.id.trim())
+            errors.push(`${pathLabel}.verify[${index}].id is required.`);
+        if (typeof item.command === "string" && !item.command.trim())
+            errors.push(`${pathLabel}.verify[${index}].command is required.`);
+    }
+    for (const [index, rule] of Array.isArray(value.stopRules) ? value.stopRules.entries() : []) {
+        if (typeof rule === "string" && !rule.trim())
+            errors.push(`${pathLabel}.stopRules[${index}] must be a non-empty string.`);
+    }
+    if (!hasArrayItems(value.criteria) && !hasArrayItems(value.evidence) && !hasArrayItems(value.verify) && !hasArrayItems(value.stopRules)) {
+        errors.push(`${pathLabel} must include at least one of criteria, evidence, verify, or stopRules.`);
+    }
+    return [...new Set(errors)];
+}
+function normalizeCriteria(criteria, evidence) {
+    return (criteria ?? []).map((criterion, index) => {
+        if (typeof criterion === "string") {
+            return { id: `criterion-${index + 1}`, must: criterion, evidence, severity: "required" };
+        }
+        return {
+            id: criterion.id.trim(),
+            must: criterion.must,
+            evidence: criterion.evidence?.filter((item) => VALID_EVIDENCE.has(item)) ?? evidence,
+            severity: criterion.severity ?? "required",
+        };
+    }).filter((criterion) => criterion.must.trim());
+}
+function deriveAcceptanceLevel(config) {
+    if ((config.verify?.length ?? 0) > 0)
+        return "verified";
+    return "checked";
+}
+export function resolveEffectiveAcceptance(input) {
+    if (input.explicit === undefined) {
+        return {
+            level: "none",
+            explicit: false,
+            inferredReason: ["acceptance not configured"],
+            criteria: [],
+            evidence: [],
+            verify: [],
+            stopRules: [],
+            finalization: { mode: "none", maxTurns: 0 },
+        };
+    }
+    const validationErrors = validateAcceptanceInput(input.explicit);
+    if (validationErrors.length > 0)
+        throw new Error(validationErrors.join(" "));
+    const explicit = input.explicit;
+    const evidence = [...new Set(explicit.evidence ?? [])];
+    const criteria = normalizeCriteria(explicit.criteria, evidence);
+    const verify = explicit.verify ?? [];
+    const stopRules = explicit.stopRules ?? [];
+    return {
+        level: deriveAcceptanceLevel(explicit),
+        explicit: true,
+        inferredReason: ["explicit acceptance contract"],
+        criteria,
+        evidence,
+        verify,
+        stopRules,
+        finalization: { mode: "self-review-loop", maxTurns: explicit.maxFinalizationTurns ?? DEFAULT_FINALIZATION_MAX_TURNS },
+    };
+}
+export function acceptanceInputFromResolved(acceptance) {
+    if (!acceptance?.explicit)
+        return undefined;
+    const maxTurns = acceptance.finalization?.maxTurns;
+    return {
+        criteria: acceptance.criteria,
+        evidence: acceptance.evidence,
+        verify: acceptance.verify,
+        stopRules: acceptance.stopRules,
+        ...(maxTurns !== undefined ? { maxFinalizationTurns: maxTurns } : {}),
+    };
+}
+export function shouldRunAcceptanceFinalization(acceptance) {
+    return acceptance.explicit && acceptance.finalization.mode === "self-review-loop" && acceptance.finalization.maxTurns > 0;
+}
+export function acceptanceSelfReviewConfig(acceptance) {
+    if (acceptance.verify.length === 0)
+        return acceptance;
+    return {
+        ...acceptance,
+        level: "checked",
+        verify: [],
+    };
+}
+export function formatAcceptancePrompt(acceptance, nativeReport = false) {
+    if (acceptance.level === "none")
+        return "";
+    const evidence = [...new Set([...acceptance.evidence, ...acceptance.criteria.flatMap((criterion) => criterion.evidence)])];
+    const lines = [
+        "",
+        "## Acceptance Contract",
+        nativeReport
+            ? "Completion is not accepted from prose alone. Finish the initial response with a sole structured_output tool call containing {value:{answer,report}}. answer is the complete standalone visible answer; report is a typed object, never JSON embedded in a string."
+            : "Completion is not accepted from prose alone. End the initial response with a structured acceptance report.",
+        "After the initial response, the runtime will continue this same session for a bounded self-review/repair loop before accepting the run.",
+        "For an observed human-only boundary (such as Touch ID or an unavailable MFA code), report the affected criterion as blocked with concrete evidence and a nonempty humanAction stating the exact user action. Retain completed evidence. This leaves acceptance incomplete and stops finalization/verification until explicit Continue. Do not use blocked for ordinary errors, missing unrelated evidence, or work you can fix.",
+        "",
+        "Criteria:",
+        ...(acceptance.criteria.length ? acceptance.criteria.map((criterion) => `- ${criterion.id}: ${criterion.must}${criterion.evidence.length ? ` (evidence: ${criterion.evidence.join(", ")})` : ""}`) : ["- No explicit criteria were configured; satisfy the requested task and the required evidence/checks below."]),
+        "",
+        `Required evidence: ${evidence.join(", ") || "none explicitly requested"}`,
+    ];
+    if (evidence.length > 0) {
+        lines.push("", `Structured evidence must be present in the ${nativeReport ? "typed report object" : "`acceptance-report` JSON fields"}. Markdown sections in your visible answer do not satisfy required evidence by themselves. If you already described evidence in prose, copy or summarize it into the matching JSON field.`, "Evidence field mapping:", ...formatEvidenceReportFieldMapping(evidence));
+    }
+    if (acceptance.verify.length > 0) {
+        lines.push("", "Runtime verification commands configured by parent:");
+        for (const command of acceptance.verify)
+            lines.push(`- ${command.id}: ${command.command}`);
+    }
+    if (acceptance.stopRules.length > 0) {
+        lines.push("", "Stop rules:", ...acceptance.stopRules.map((rule) => `- ${rule}`));
+    }
+    lines.push("", nativeReport ? "Submit this shape through structured_output; do not emit a fenced acceptance-report:" : "Finish with a fenced JSON block tagged `acceptance-report` in this shape:", formatAcceptanceReportExample(nativeReport));
+    return lines.join("\n");
+}

package/dist/runs/shared/acceptance-evaluation.js

@@ -0,0 +1,256 @@
+import { spawn, spawnSync } from "node:child_process";
+import { addAbortListener } from "node:events";
+import * as path from "node:path";
+import { attachChildProcessLifecycle } from "../../shared/post-exit-stdio-guard.js";
+import { parseAcceptanceReport, validateAcceptanceReportShape } from "./acceptance-reports.js";
+const LEVEL_RANK = {
+    none: 0,
+    attested: 1,
+    checked: 2,
+    verified: 3,
+};
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function checkCriteriaSatisfied(criteria, report) {
+    const reports = new Map((report.criteriaSatisfied ?? []).filter((item) => item.id).map((item) => [item.id, item]));
+    const checks = [];
+    for (const criterion of criteria.filter((item) => item.severity !== "recommended")) {
+        const item = reports.get(criterion.id);
+        if (!item)
+            checks.push({ id: `criterion:${criterion.id}`, status: "failed", message: `Required criterion '${criterion.id}' was not reported.` });
+        else if (item.status === "blocked")
+            checks.push({ id: `criterion:${criterion.id}`, status: "blocked", message: `Needs human action: ${item.humanAction}. Evidence: ${item.evidence}` });
+        else if (item.status !== "satisfied")
+            checks.push({ id: `criterion:${criterion.id}`, status: "failed", message: `Required criterion '${criterion.id}' was reported as ${item.status}.` });
+        else
+            checks.push({ id: `criterion:${criterion.id}`, status: "passed", message: `Required criterion '${criterion.id}' satisfied.` });
+        for (const kind of criterion.evidence ?? []) {
+            const present = reportEvidencePresent(report, kind);
+            checks.push({
+                id: `criterion:${criterion.id}:evidence:${kind}`,
+                status: present ? "passed" : item?.status === "blocked" ? "blocked" : "failed",
+                message: present ? `${kind} evidence present for '${criterion.id}'.` : `${kind} evidence missing for required criterion '${criterion.id}'.`,
+            });
+        }
+    }
+    return checks;
+}
+function reportEvidencePresent(report, kind) {
+    switch (kind) {
+        case "changed-files": return isStringArray(report.changedFiles) && report.changedFiles.length > 0;
+        case "tests-added": return isStringArray(report.testsAddedOrUpdated) && report.testsAddedOrUpdated.length > 0;
+        case "commands-run": return Array.isArray(report.commandsRun) && report.commandsRun.some((command) => command.result !== "not-run");
+        case "validation-output": return isStringArray(report.validationOutput) && report.validationOutput.length > 0;
+        case "residual-risks": return isStringArray(report.residualRisks);
+        case "no-staged-files": return report.noStagedFiles === true;
+        case "diff-summary": return typeof report.diffSummary === "string" && report.diffSummary.trim().length > 0;
+        case "review-findings": return Array.isArray(report.reviewFindings);
+        case "manual-notes": return Boolean((report.manualNotes ?? report.notes)?.trim());
+    }
+}
+function checkNoStagedFiles(cwd) {
+    const result = spawnSync("git", ["status", "--short"], { cwd, encoding: "utf-8" });
+    if (result.status !== 0) {
+        return { id: "no-staged-files", status: "not-applicable", message: "git status unavailable; no staged-files check skipped" };
+    }
+    const staged = result.stdout.split(/\r?\n/).filter((line) => line.length >= 2 && line[0] !== " " && line[0] !== "?");
+    return staged.length === 0
+        ? { id: "no-staged-files", status: "passed", message: "No staged files detected." }
+        : { id: "no-staged-files", status: "failed", message: `Staged files present: ${staged.join(", ")}` };
+}
+function runStructuralChecks(acceptance, report) {
+    const checks = [];
+    checks.push(...checkCriteriaSatisfied(acceptance.criteria, report));
+    if (!acceptance.criteria.length)
+        for (const item of report.criteriaSatisfied ?? []) {
+            if (item.status === "blocked")
+                checks.push({ id: `criterion:${item.id ?? "human-action"}`, status: "blocked", message: `Needs human action: ${item.humanAction}. Evidence: ${item.evidence}` });
+        }
+    const blockedCriteria = new Set((report.criteriaSatisfied ?? []).filter((criterion) => criterion.status === "blocked").map((criterion) => criterion.id));
+    const blockedEvidence = new Set(acceptance.criteria.filter((criterion) => blockedCriteria.has(criterion.id)).flatMap((criterion) => criterion.evidence));
+    for (const kind of acceptance.evidence) {
+        const present = reportEvidencePresent(report, kind);
+        const deferred = blockedEvidence.has(kind) || (!acceptance.criteria.length && blockedCriteria.size > 0);
+        checks.push({
+            id: `evidence:${kind}`,
+            status: present ? "passed" : deferred ? "blocked" : "failed",
+            message: present ? `${kind} evidence present.` : `${kind} evidence missing from child report.`,
+        });
+    }
+    return checks;
+}
+const MAX_VERIFY_OUTPUT_CHARS = 12_000;
+function appendVerifyOutput(current, chunk) {
+    const text = chunk.toString();
+    const remaining = Math.max(0, MAX_VERIFY_OUTPUT_CHARS - current.length);
+    return { value: current + text.slice(0, remaining), truncated: text.length > remaining };
+}
+function trimOutput(value, truncated = false) {
+    const trimmed = value.trim();
+    if (!trimmed && !truncated)
+        return undefined;
+    return truncated || trimmed.length > MAX_VERIFY_OUTPUT_CHARS
+        ? `${trimmed.slice(0, MAX_VERIFY_OUTPUT_CHARS)}${trimmed ? "\n" : ""}...[truncated]`
+        : trimmed;
+}
+function runVerifyCommand(command, defaultCwd, signal) {
+    return new Promise((resolve) => {
+        const startedAt = Date.now();
+        const cwd = command.cwd ? path.resolve(defaultCwd, command.cwd) : defaultCwd;
+        let stdout = "";
+        let stderr = "";
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        let timedOut = false;
+        let cancelled = false;
+        const child = spawn(command.command, {
+            cwd,
+            env: { ...process.env, ...(command.env ?? {}) },
+            shell: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: true,
+        });
+        const lifecycle = attachChildProcessLifecycle(child);
+        const abortListener = signal && addAbortListener(signal, () => {
+            cancelled = true;
+            lifecycle.terminate();
+        });
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            lifecycle.terminate();
+        }, command.timeoutMs ?? 120_000);
+        timeout.unref?.();
+        child.stdout.on("data", (chunk) => {
+            const next = appendVerifyOutput(stdout, chunk);
+            stdout = next.value;
+            stdoutTruncated ||= next.truncated;
+        });
+        child.stderr.on("data", (chunk) => {
+            const next = appendVerifyOutput(stderr, chunk);
+            stderr = next.value;
+            stderrTruncated ||= next.truncated;
+        });
+        const cleanup = () => {
+            clearTimeout(timeout);
+            abortListener?.[Symbol.dispose]();
+        };
+        child.on("close", (exitCode) => {
+            cleanup();
+            const durationMs = Date.now() - startedAt;
+            const passed = exitCode === 0 && !timedOut && !cancelled;
+            resolve({
+                id: command.id,
+                command: command.command,
+                cwd,
+                exitCode,
+                status: cancelled ? "failed" : timedOut ? "timed-out" : passed ? "passed" : command.allowFailure ? "allowed-failure" : "failed",
+                stdout: trimOutput(stdout, stdoutTruncated),
+                stderr: cancelled ? "Verification cancelled." : trimOutput(stderr, stderrTruncated),
+                durationMs,
+            });
+        });
+        child.on("error", (error) => {
+            cleanup();
+            resolve({
+                id: command.id,
+                command: command.command,
+                cwd,
+                exitCode: 1,
+                status: command.allowFailure ? "allowed-failure" : "failed",
+                stderr: error instanceof Error ? error.message : String(error),
+                durationMs: Date.now() - startedAt,
+            });
+        });
+    });
+}
+/** Structural evidence only. The run owner must still perform runtime checks before acceptance. */
+export function evaluateAcceptanceReport(input) {
+    const acceptance = input.acceptance;
+    const ledger = {
+        status: acceptance.level === "none" ? "not-required" : "claimed",
+        explicit: acceptance.explicit,
+        effectiveAcceptance: input.governing ?? acceptance,
+        inferredReason: acceptance.inferredReason,
+        criteria: acceptance.criteria,
+        runtimeChecks: [],
+        verifyRuns: [],
+    };
+    if (acceptance.level === "none")
+        return ledger;
+    const shapeError = input.report !== undefined ? validateAcceptanceReportShape(input.report) : undefined;
+    const parsed = input.report === undefined ? parseAcceptanceReport(input.output)
+        : shapeError ? { error: `Acceptance report is invalid: ${shapeError}` } : { report: input.report };
+    if (parsed.report) {
+        ledger.childReport = parsed.report;
+        ledger.status = "attested";
+    }
+    else {
+        ledger.childReportParseError = parsed.error;
+        ledger.runtimeChecks.push({ id: "attestation", status: "failed", message: parsed.error ?? "Structured acceptance report missing." });
+        ledger.status = "rejected";
+        return ledger;
+    }
+    if (LEVEL_RANK[acceptance.level] >= LEVEL_RANK.checked || parsed.report.criteriaSatisfied?.some((item) => item.status === "blocked")) {
+        ledger.runtimeChecks = runStructuralChecks(acceptance, parsed.report);
+        if (ledger.runtimeChecks.some((check) => check.status === "failed")) {
+            ledger.status = "rejected";
+            return ledger;
+        }
+        if (ledger.runtimeChecks.some((check) => check.status === "blocked")) {
+            ledger.status = "blocked";
+            return ledger;
+        }
+        ledger.status = "checked";
+    }
+    return ledger;
+}
+export async function evaluateAcceptance(input) {
+    const { acceptance } = input;
+    const ledger = evaluateAcceptanceReport(input);
+    if (!ledger.childReport)
+        return ledger;
+    if ((LEVEL_RANK[acceptance.level] >= LEVEL_RANK.checked || ledger.childReport.criteriaSatisfied?.some((item) => item.status === "blocked"))
+        && (acceptance.evidence.includes("no-staged-files") || acceptance.criteria.some((criterion) => criterion.evidence?.includes("no-staged-files")))) {
+        const check = checkNoStagedFiles(input.cwd);
+        ledger.runtimeChecks.push(check);
+        if (check.status === "failed")
+            ledger.status = "rejected";
+    }
+    if (ledger.status === "rejected" || ledger.status === "blocked")
+        return ledger;
+    if (acceptance.verify.length > 0) {
+        ledger.verifyRuns = [];
+        for (const command of acceptance.verify) {
+            if (input.signal?.aborted) {
+                ledger.runtimeChecks.push({ id: "cancelled", status: "failed", message: "Acceptance verification cancelled." });
+                ledger.status = "rejected";
+                return ledger;
+            }
+            ledger.verifyRuns.push(await runVerifyCommand(command, input.cwd, input.signal));
+        }
+        if (ledger.verifyRuns.some((run) => run.status === "failed" || run.status === "timed-out")) {
+            ledger.status = "rejected";
+            return ledger;
+        }
+        ledger.status = "verified";
+    }
+    return ledger;
+}
+export function acceptanceHumanAction(ledger) {
+    if (ledger?.status !== "blocked")
+        return undefined;
+    return ledger.childReport?.criteriaSatisfied?.filter((criterion) => criterion.status === "blocked")
+        .map((criterion) => `${criterion.id ?? "Criterion"}: ${criterion.humanAction}\nEvidence: ${criterion.evidence}`).join("\n");
+}
+export function acceptanceFailureMessage(ledger) {
+    if (ledger.status !== "rejected")
+        return undefined;
+    const failedCheck = ledger.runtimeChecks.find((check) => check.status === "failed");
+    if (failedCheck)
+        return `Acceptance rejected: ${failedCheck.message}`;
+    const failedVerify = ledger.verifyRuns.find((run) => run.status === "failed" || run.status === "timed-out");
+    if (failedVerify)
+        return `Acceptance verification '${failedVerify.id}' ${failedVerify.status}.`;
+    return "Acceptance rejected.";
+}