agentic-engineering-harness 0.8.8 → 0.8.10

package/dist/releases/release-1790997662626-16390-6a2e246f/agents/waveExecutor.js

@@ -0,0 +1,529 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { minimatch } from "minimatch";
+import { planParallelism } from "./parallelism.js";
+import { knowledgePackOutputSchema, plannerOutputSchema } from "./outputContracts.js";
+import { extractMarkedJson } from "./structuredOutput.js";
+import { validateExecutionCapabilities } from "./permissions.js";
+import { materializeControlPlaneSnapshot } from "../core/controlPlane.js";
+import { executeAgentPrompt, prepareAgentExecutionIdentity } from "../workers/agentPrompt.js";
+import { dispatchDistributedDelegation } from "../distributed/worker.js";
+import { enforceSandboxPolicy } from "../security/sandbox.js";
+import { runExecutable } from "../utils/process.js";
+import { recordEvent } from "../telemetry/events.js";
+import { existingRepositoryPath, repositoryPath } from "../utils/repositoryPath.js";
+import { compileExecutionBlueprint } from "../architecture/participantPlan.js";
+import { bindOperationExecutionSemantics, bindResolvedOperationPolicy, currentOperationContext, loadOperation } from "../operations/state.js";
+import { compileResolvedOperationPolicy } from "../architecture/executionIdentity.js";
+import { configuredDeliveryPolicy, requiredHumanActionAuthorizations } from "../security/actionPolicy.js";
+import { materializeCandidateState } from "../candidates/direct.js";
+import { createWaveBase, integrateWaveChangeSets } from "../candidates/wave.js";
+import { sha256Canonical, sha256Utf8 } from "../core/digest.js";
+import { AehError } from "../core/errors.js";
+import { FileKnowledgeCacheV1, resolveKnowledgeGate, validateKnowledgePack } from "../knowledge/index.js";
+import { defaultSkillSeed } from "../participants/index.js";
+import { dropUnresolvablePlanValidationRequirementsV1, resolveValidationRequirements } from "../architecture/validationRequirements.js";
+import { compilePlannerWorkGraphWithOneCorrection, PlannerWorkGraphCorrectionError } from "./plannerWorkGraphCorrection.js";
+export async function executePlannerWaves(input) {
+    const planning = input.config.workflow?.planning;
+    if (planning?.enabled === false || input.contract.routing?.route === "DIRECT" || input.contract.routing?.route === "NO_AGENT")
+        return { used: false, waves: [], sessions: [] };
+    if (!input.precomputedPlan && !input.plannerSelection)
+        return { used: false, waves: [], sessions: [] };
+    const sessions = [];
+    let plan;
+    if (input.precomputedPlan) {
+        try {
+            plan = plannerOutputSchema.parse(input.precomputedPlan);
+        }
+        catch (error) {
+            return { used: true, waves: [], sessions, preExecutionFailure: true, aggregateSession: aggregate(sessions, 1, `Invalid Planner output schema: ${String(error)}`) };
+        }
+    }
+    else {
+        const plannerSession = await executeAgentPrompt(input.root, input.config, input.contract, input.plannerSelection, buildPlannerPrompt(input.contract), { outputContract: "planner", phase: "planning", requireExecutionAuthority: true });
+        sessions.push(plannerSession);
+        if (plannerSession.exitCode !== 0)
+            return { used: true, waves: [], sessions, preExecutionFailure: true, aggregateSession: aggregate(sessions, 1, "Planner runtime failed.") };
+        try {
+            plan = plannerOutputSchema.parse(extractMarkedJson(plannerSession.stdout, plannerSession.stderr));
+        }
+        catch (error) {
+            return { used: true, waves: [], sessions, preExecutionFailure: true, aggregateSession: aggregate(sessions, 1, `Invalid planner output: ${String(error)}`) };
+        }
+    }
+    const planIssues = validatePlannerWavePlan(input.contract, plan);
+    if (planIssues.length)
+        return { used: true, plan, waves: [], sessions, preExecutionFailure: true, aggregateSession: aggregate(sessions, 1, `Planner contract rejected: ${planIssues.join("; ")}`) };
+    if (!plan.workUnits.length)
+        return { used: false, plan, waves: [], sessions };
+    let blueprint;
+    let graph;
+    let validationResolution;
+    let knowledgeResolutions = [];
+    let operation;
+    let correctionAttempts = 0;
+    try {
+        const validatedPlan = await compilePlannerWorkGraphWithOneCorrection({
+            contract: input.contract,
+            plan,
+            requestCorrection: input.plannerSelection ? async (correctionPrompt) => {
+                const correctionSession = await executeAgentPrompt(input.root, input.config, input.contract, input.plannerSelection, correctionPrompt, { outputContract: "planner", phase: "planning", requireExecutionAuthority: true });
+                sessions.push(correctionSession);
+                if (correctionSession.exitCode !== 0)
+                    throw new Error(`corrective Planner runtime failed with exit code ${correctionSession.exitCode}`);
+                return extractMarkedJson(correctionSession.stdout, correctionSession.stderr);
+            } : undefined
+        });
+        plan = validatedPlan.plan;
+        graph = validatedPlan.graph;
+        correctionAttempts = validatedPlan.correctionAttempts;
+        knowledgeResolutions = await resolvePlannerKnowledge(plan, input);
+        const operationContext = currentOperationContext();
+        operation = operationContext.id ? await loadOperation(input.stateRoot, operationContext.id) : undefined;
+        const candidateRevision = operation?.candidateRevision;
+        const controllerEpoch = operation?.controller?.epoch;
+        if (!candidateRevision || typeof controllerEpoch !== "number" || !Number.isSafeInteger(controllerEpoch) || controllerEpoch < 0 || operation?.operationExecutionRevision === undefined) {
+            throw new AehError("EXECUTION_BLUEPRINT_INVALID", "A managed CandidateRevision and controller epoch are required before compiling an execution blueprint.");
+        }
+        validationResolution = await resolveValidationRequirements({ root: input.root, requirements: plan.validationRequirements, config: input.config, contract: input.contract, projectStack: input.projectStack });
+        // A planner-declared validation requirement that no approved project script, configured
+        // command, validator, or provider can resolve is advisory plan intent, not a frozen gate. The
+        // frozen contract's own validators are compiled and enforced independently, so an unresolvable
+        // advisory requirement must not reject the whole participant plan before implementation (it is
+        // not repairable by any implementation change). Drop it with a durable deterministic record and
+        // keep the resolvable subset; a genuine inconsistency between the remaining set still fails
+        // closed below.
+        if (validationResolution.blocked.length) {
+            const partition = dropUnresolvablePlanValidationRequirementsV1(plan.validationRequirements, validationResolution);
+            await recordEvent(input.stateRoot, input.config, "harness.plan.validation-requirements-dropped", { taskId: input.contract.task.id, dropped: partition.dropped.map((requirement) => ({ id: requirement.id, kind: requirement.kind })), reasons: validationResolution.blocked });
+            plan = { ...plan, validationRequirements: partition.kept };
+            validationResolution = await resolveValidationRequirements({ root: input.root, requirements: plan.validationRequirements, config: input.config, contract: input.contract, projectStack: input.projectStack });
+            if (validationResolution.blocked.length)
+                throw new AehError("VALIDATION_REQUIREMENT_BLOCKED", validationResolution.blocked.map((item) => `${item.requirementId}: ${item.reason}`).join("; "), { details: { validationResolution } });
+        }
+        const executionSemanticsDigest = sha256Canonical({ workGraph: graph, plannerPlan: plan, executionCatalogDigest: input.executionCatalog.digest, validationResolution, knowledge: knowledgeResolutions.map((resolution) => ({ packDigest: resolution.pack?.packDigest, trustDecisionDigest: resolution.acceptedSkill?.trustDecision.decisionDigest })).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))), contextPolicy: input.config.context ?? null });
+        operation = await bindOperationExecutionSemantics(input.stateRoot, operation.id, executionSemanticsDigest);
+        blueprint = await compileWaveExecutionBlueprint({ input, operation, graph, knowledgeResolutions, validationResolution, capabilityRegistry: input.capabilityRegistry, plan });
+    }
+    catch (error) {
+        const failedCorrectionAttempts = error instanceof PlannerWorkGraphCorrectionError ? error.correctionAttempts : correctionAttempts;
+        return { used: true, plan, waves: [], sessions, preExecutionFailure: true, correctionAttempts: failedCorrectionAttempts, aggregateSession: aggregate(sessions, 1, `Participant plan rejected: ${String(error)}`) };
+    }
+    const schedule = await planParallelism(input.root, input.config, input.contract.task.id, plan.workUnits);
+    const worktreeIsolation = planning?.worktreeIsolation !== false;
+    await recordEvent(input.stateRoot, input.config, "harness.plan.ready", { taskId: input.contract.task.id, workUnits: plan.workUnits.length, waves: schedule.waves.length, conflicts: schedule.conflicts.length, graphUsed: schedule.graphUsed, compilerDigest: blueprint.plan.compilerDigest, worktreeIsolation, distributed: planning?.distributed === true && input.config.distributed?.enabled === true });
+    const waveSummaries = [];
+    let finalReport;
+    let currentCandidate = operation?.candidateRevision;
+    for (let index = 0; index < schedule.waves.length; index += 1) {
+        if (index > 0 && graph && operation) {
+            try {
+                operation = await loadOperation(input.stateRoot, operation.id);
+                currentCandidate = operation.candidateRevision;
+                if (!currentCandidate)
+                    throw new AehError("EXECUTION_BLUEPRINT_INVALID", "Current candidate is required to recompile the next wave identity.");
+                blueprint = await compileWaveExecutionBlueprint({ input, operation, graph, knowledgeResolutions, validationResolution, capabilityRegistry: input.capabilityRegistry, plan });
+            }
+            catch (error) {
+                const summary = { wave: index + 1, taskIds: schedule.waves[index], status: "FAIL", results: [] };
+                waveSummaries.push(summary);
+                return { used: true, plan, blueprint, schedule, waves: waveSummaries, sessions, aggregateSession: aggregate(sessions, 1, `Next wave execution identity could not be recompiled: ${String(error)}`) };
+            }
+        }
+        const ids = schedule.waves[index];
+        const tasks = ids.map((id) => plan.workUnits.find((task) => task.id === id)).filter(Boolean);
+        const participantByWorkUnit = new Map();
+        for (const assignment of blueprint.plan.assignments)
+            for (const workUnitId of assignment.workUnitIds)
+                participantByWorkUnit.set(workUnitId, assignment);
+        if (!currentCandidate || !operation?.id) {
+            const summary = { wave: index + 1, taskIds: ids, status: "FAIL", results: [] };
+            waveSummaries.push(summary);
+            return { used: true, plan, blueprint, schedule, waves: waveSummaries, sessions, aggregateSession: aggregate(sessions, 1, "Candidate assembly requires a managed operation candidate.") };
+        }
+        const waveOperationId = operation.id;
+        const waveBlueprint = blueprint;
+        const waveBase = createWaveBase({ operationId: waveOperationId, taskId: input.contract.task.id, waveIndex: index, candidate: currentCandidate });
+        const results = await mapLimit(tasks, waveConcurrencyV1(planning, tasks.length), (task) => executeDelegation({ ...input, operationId: waveOperationId, task, participantAssignment: participantByWorkUnit.get(task.id), executionBlueprint: waveBlueprint, waveBase: waveBase.candidate }));
+        sessions.push(...results.map((result) => result.session));
+        if (results.some((result) => result.status === "FAIL")) {
+            const summary = { wave: index + 1, taskIds: ids, status: "FAIL", results };
+            waveSummaries.push(summary);
+            await recordEvent(input.stateRoot, input.config, "harness.wave.finish", { taskId: input.contract.task.id, wave: index + 1, status: "FAIL", tasks: ids });
+            return { used: true, plan, blueprint, schedule, waves: waveSummaries, sessions, aggregateSession: aggregate(sessions, 1, `Wave ${index + 1} failed.`) };
+        }
+        const resultByWorkUnit = new Map(results.map((result) => [result.task.id, result]));
+        const submissions = [];
+        for (const result of results) {
+            if (!result.changeSet)
+                continue;
+            submissions.push({
+                workUnitId: result.task.id,
+                changeSet: result.changeSet,
+                allowedScope: result.task.scope,
+                resourceClaims: result.task.resourceClaims ?? []
+            });
+        }
+        if (submissions.length) {
+            const integration = await integrateWaveChangeSets({ root: input.root, stateRoot: input.stateRoot, operationId: operation.id, taskId: input.contract.task.id, wave: waveBase, submissions, semanticAssessment: input.semanticAssessment });
+            for (const step of integration.integrated) {
+                const result = resultByWorkUnit.get(step.workUnitId);
+                if (result) {
+                    result.candidate = step.candidate;
+                    result.impact = step.impact;
+                }
+                await recordEvent(input.stateRoot, input.config, "harness.candidate.assembled", { taskId: input.contract.task.id, workUnitId: step.workUnitId, participantId: step.changeSet.participantId, candidateRevision: step.candidate.revision, candidateDigest: step.candidate.sourceDigest, impactDigest: step.impact.digest, changeKinds: step.impact.changeKinds, reviewDimensions: step.impact.reviewDimensions, requiresIndependentReview: step.impact.requiresIndependentReview, waveBaseRevision: waveBase.candidate.revision, derivedRebase: step.derived });
+            }
+            for (const requirement of integration.reconciliationRequired) {
+                const result = resultByWorkUnit.get(requirement.workUnitId);
+                if (result) {
+                    result.status = "FAIL";
+                    result.message = `WAVE_RECONCILIATION_REQUIRED: ${requirement.reason}`;
+                }
+            }
+            const last = integration.integrated.at(-1);
+            if (last)
+                currentCandidate = last.candidate;
+        }
+        if (results.some((result) => result.status === "FAIL")) {
+            const summary = { wave: index + 1, taskIds: ids, status: "FAIL", results };
+            waveSummaries.push(summary);
+            await recordEvent(input.stateRoot, input.config, "harness.wave.finish", { taskId: input.contract.task.id, wave: index + 1, status: "FAIL", tasks: ids, reconciliationRequired: results.filter((result) => result.message?.startsWith("WAVE_RECONCILIATION_REQUIRED")).map((result) => result.task.id) });
+            return { used: true, plan, blueprint, schedule, waves: waveSummaries, sessions, aggregateSession: aggregate(sessions, 1, `Wave ${index + 1} candidate assembly failed.`) };
+        }
+        finalReport = planning?.barrierValidation === false ? undefined : await input.revalidate();
+        const status = finalReport?.status === "FAIL" ? "FAIL" : "PASS";
+        const summary = { wave: index + 1, taskIds: ids, status, results, barrier: finalReport };
+        waveSummaries.push(summary);
+        await recordEvent(input.stateRoot, input.config, "harness.wave.finish", { taskId: input.contract.task.id, wave: index + 1, status, tasks: ids, checks: finalReport?.checks.length });
+        if (status === "FAIL")
+            return { used: true, plan, schedule, waves: waveSummaries, sessions, aggregateSession: aggregate(sessions, 1, `Wave ${index + 1} deterministic barrier failed.`), report: finalReport };
+    }
+    finalReport ??= await input.revalidate();
+    return { used: true, plan, blueprint, schedule, waves: waveSummaries, sessions, aggregateSession: aggregate(sessions, finalReport.status === "PASS" ? 0 : 1, `Executed ${plan.workUnits.length} work unit(s) across ${schedule.waves.length} wave(s).`), report: finalReport, correctionAttempts };
+}
+export async function resolvePlannerKnowledge(plan, input) {
+    const knownCompetencies = [...new Set(defaultSkillSeed().skills.flatMap((skill) => skill.competencies.map((competency) => competency.id)))];
+    const provided = [...(input.knowledgeResolutions ?? [])];
+    const providedByCompetency = new Map(provided.flatMap((resolution) => resolution.acceptedSkill ? [[resolution.acceptedSkill.competency, resolution]] : []));
+    const cache = input.knowledgeCache ?? (input.stateRoot ? new FileKnowledgeCacheV1(path.join(input.stateRoot, ".harness", "cache", "knowledge-v1")) : undefined);
+    const resolutions = [...provided];
+    const required = [...new Set(plan.workUnits.flatMap((unit) => unit.competencies))].sort();
+    for (const competency of required) {
+        if (knownCompetencies.includes(competency) || providedByCompetency.has(competency))
+            continue;
+        const resolution = await resolveKnowledgeGate({
+            requiredCompetencies: [competency],
+            knownCompetencies,
+            mode: input.knowledgeMode ?? "TRUSTED_DISCOVERY",
+            cache,
+            lookup: input.knowledgeLookup ?? (input.librarianSelection ? (gap) => lookupWithLibrarian(input, gap) : undefined)
+        });
+        if (resolution.gate !== "SUFFICIENT")
+            throw new AehError("KNOWLEDGE_GAP_BLOCKED", `knowledge gate could not establish trusted knowledge for '${competency}'.`, { details: { competency, gap: resolution.gap } });
+        resolutions.push(resolution);
+        if (resolution.acceptedSkill)
+            providedByCompetency.set(resolution.acceptedSkill.competency, resolution);
+    }
+    return [...new Map(resolutions.map((resolution) => [resolution.acceptedSkill?.competency ?? resolution.pack?.packDigest ?? JSON.stringify(resolution), resolution])).values()];
+}
+async function compileWaveExecutionBlueprint(args) {
+    const { input, operation, graph, knowledgeResolutions, validationResolution, capabilityRegistry, plan } = args;
+    const candidate = operation.candidateRevision;
+    const controllerEpoch = operation.controller?.epoch;
+    if (!candidate || !Number.isSafeInteger(operation.operationExecutionRevision) || operation.operationExecutionRevision < 1 || !Number.isSafeInteger(controllerEpoch) || controllerEpoch < 0)
+        throw new AehError("EXECUTION_BLUEPRINT_INVALID", "Current candidate, operation execution revision, and controller epoch are required to compile an execution blueprint.");
+    const knowledgePolicy = knowledgeResolutions.map((resolution) => ({ packDigest: resolution.pack?.packDigest, trustDecisionDigest: resolution.acceptedSkill?.trustDecision.decisionDigest })).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    const deliveryPolicy = configuredDeliveryPolicy(input.config, operation.kind);
+    const allowedExternalEffects = deliveryPolicy.allowedExternalEffects;
+    const humanDecisionRequirements = requiredHumanActionAuthorizations(allowedExternalEffects);
+    const resolvedOperationPolicy = compileResolvedOperationPolicy({
+        projectId: candidate.projectId ?? input.config.project.name,
+        operationId: operation.id,
+        operationExecutionRevision: operation.operationExecutionRevision,
+        candidateRevision: candidate.revision,
+        candidateDigest: candidate.identityDigest,
+        controllerEpoch: controllerEpoch,
+        intent: operation.intent?.request ?? input.contract.routing?.intent ?? input.contract.task.title,
+        route: graph.route,
+        minimumAssurance: graph.assurance,
+        policyVersions: { resolvedOperationPolicy: "2", roleInvocationPolicy: "1", executionBlueprint: "3", executionBinding: "3", skillManifest: "1", capabilityRegistry: "1", operationalSkillProjection: "1" },
+        policyDigests: {
+            validation: validationResolution.digest,
+            delivery: sha256Canonical({ ...deliveryPolicy, humanDecisionRequirements }),
+            knowledge: sha256Canonical(knowledgePolicy),
+            context: sha256Canonical(input.config.context ?? null),
+            capabilityRegistry: capabilityRegistry.digest,
+            executionLiveness: sha256Canonical(operation.resolvedOperationPolicy?.executionLiveness ?? input.config.orchestration?.operations?.liveness ?? {}),
+            economicEnvelope: sha256Canonical(operation.resolvedOperationPolicy?.economicEnvelope ?? input.config.orchestration?.operations?.economicEnvelope ?? {})
+        },
+        capabilityRegistryDigest: capabilityRegistry.digest,
+        validationPolicy: validationResolution,
+        reviewPolicy: {
+            minimumAssurance: graph.assurance,
+            reviewDimensions: plan.workUnits.flatMap((unit) => unit.changeKinds.map((kind) => `change:${kind}`)).sort(),
+            independentReviewRequired: graph.assurance === "ELEVATED" || graph.assurance === "CRITICAL",
+            leadAcceptance: input.config.workflow?.reviews?.leadAcceptance !== false,
+            leadAcceptanceDirect: input.config.workflow?.reviews?.leadAcceptanceDirect === true
+        },
+        deliveryPolicy,
+        knowledgePolicy: { resolutions: knowledgePolicy },
+        contextPolicy: input.config.context ?? { mode: "disabled" },
+        allowedExternalEffects,
+        humanDecisionRequirements,
+        executionLiveness: operation.resolvedOperationPolicy?.executionLiveness ?? input.config.orchestration?.operations?.liveness,
+        economicEnvelope: operation.resolvedOperationPolicy?.economicEnvelope ?? input.config.orchestration?.operations?.economicEnvelope
+    });
+    const persisted = operation.resolvedOperationPolicy?.digest === resolvedOperationPolicy.digest
+        ? operation
+        : await bindResolvedOperationPolicy(input.stateRoot, operation.id, resolvedOperationPolicy);
+    return compileExecutionBlueprint({ graph, maxTokens: input.config.context?.budgets?.default?.maxTokens, candidate, controllerEpoch: controllerEpoch, operationExecutionRevision: persisted.operationExecutionRevision, resolvedOperationPolicy, executionCatalog: input.executionCatalog, capabilityRegistry, knowledgeResolutions, projectStack: input.projectStack, validationRequirements: plan.validationRequirements, validationResolution });
+}
+async function lookupWithLibrarian(input, gap) {
+    if (!input.librarianSelection)
+        throw new AehError("KNOWLEDGE_GAP_BLOCKED", `no Librarian selection is available for '${gap.missingCompetencies.join(", ")}'.`);
+    const session = await executeAgentPrompt(input.root, input.config, input.contract, input.librarianSelection, buildLibrarianPrompt(gap), { outputContract: "knowledge-pack", phase: "knowledge", operationKind: "change", requireExecutionAuthority: true });
+    if (session.exitCode !== 0)
+        throw new AehError("KNOWLEDGE_GAP_BLOCKED", `Librarian failed while resolving '${gap.missingCompetencies.join(", ")}'.`);
+    try {
+        const output = knowledgePackOutputSchema.parse(extractMarkedJson(session.stdout, session.stderr));
+        return { pack: validateKnowledgePack(output.pack, gap), ...(output.skillCandidate ? { skillCandidate: output.skillCandidate } : {}) };
+    }
+    catch (error) {
+        if (error instanceof AehError)
+            throw error;
+        throw new AehError("KNOWLEDGE_PACK_REJECTED", `Librarian returned an invalid pack for '${gap.missingCompetencies.join(", ")}'.`, { cause: error });
+    }
+}
+function buildLibrarianPrompt(gap) {
+    // HYBRID: the Librarian semantically proposes claim/source links for each procedure step; SkillTrustGate deterministically verifies every reference against the accepted pack and source policy.
+    return `Resolve this deterministic knowledge gap as a read-only Librarian. Do not edit source, install anything, grant tools or change policy. ${gap.mode === "DOCS_ONLY" ? "Use official, version-matched documentation only; repository examples, public code, community pages and unknown sources are not acceptable." : gap.mode === "OFFLINE" ? "Do not perform external lookup; report the gap as unresolved." : "Use approved version-matched documentation or clearly identified repository/public-code evidence."} Preserve source provenance. Return exactly one AEH_RESULT_JSON object with {"pack":{"version":1,"cacheKey":${JSON.stringify(gap.cacheKey)},"topic":...,"claims":[{"id":...,"statement":...,"competency":...,"confidence":"high|medium|low"}],"sources":[{"uri":...,"kind":"official|repository|public-code|unknown","version":...}],"retrievedAt":"ISO-8601","packDigest":"sha256"},"skillCandidate":{"version":1,"id":"ephemeral:<competency>","competency":"<competency>","procedure":["<exact step text>"],"sourcePackDigest":"<pack digest>","procedureEvidence":[{"stepIndex":0,"claimIds":["<claim id supporting this exact step>"],"sourceUris":["<supporting source URI from pack.sources>"]}]}}. If returning a procedure, provide one procedureEvidence entry for every step, with at least one pack claim ID and allowed source URI that support that exact step; do not add trust or acceptance fields because SkillTrustGate makes that decision. The pack and any candidate must address only: ${gap.missingCompetencies.join(", ")}. Gap reason: ${gap.reason}.`;
+}
+async function executeDelegation(input) {
+    if (!input.participantAssignment)
+        return failed(input.task, input.implementationSelection, "EXECUTION_BLUEPRINT_INVALID: work unit has no frozen participant assignment.");
+    const participantId = input.participantAssignment.participantId;
+    let selection;
+    try {
+        selection = selectionForParticipant(input.implementationSelection, input.participantAssignment, input.executionCatalog);
+    }
+    catch (error) {
+        return failed(input.task, input.implementationSelection, String(error));
+    }
+    try {
+        selection = enforceSandboxPolicy(selection, input.config, input.task.risk === "critical" ? "high" : input.task.risk).selection;
+    }
+    catch (error) {
+        return failed(input.task, selection, String(error));
+    }
+    const transport = selection.transport === "inherit" ? (input.config.orchestration?.provider ?? "none") : selection.transport;
+    const capabilityIssues = validateExecutionCapabilities(selection, transport);
+    if (capabilityIssues.length)
+        return failed(input.task, selection, `Agent ${selection.logicalAgent} cannot execute: ${capabilityIssues.join("; ")}`);
+    const prompt = buildDelegationPrompt(input.contract, input.task, input.participantAssignment?.operationalSkills);
+    if (input.config.workflow?.planning?.distributed === true && input.config.distributed?.enabled === true) {
+        try {
+            const roleInvocationPolicy = input.participantAssignment.roleInvocationPolicy;
+            if (!roleInvocationPolicy)
+                throw new Error("EXECUTION_BINDING_REQUIRED: blueprint has no RoleInvocationPolicy for the distributed participant.");
+            const identity = await prepareAgentExecutionIdentity(input.root, input.config, input.contract, selection, prompt, { participantId, phase: "distributed", operationKind: currentOperationContext().kind, executionBlueprint: input.executionBlueprint, executionBlueprintDigest: input.executionBlueprint.digest, roleInvocationPolicy, skillManifest: input.participantAssignment.skillManifest });
+            const remote = await dispatchDistributedDelegation({ root: input.root, config: input.config, contract: input.contract, task: input.task, participantId, selection, controller: input.controller, waveBase: input.waveBase, identity });
+            const violations = remote.changedFiles.filter((file) => !matchesAny(file, input.task.scope));
+            if (violations.length)
+                return { task: input.task, session: remote.session, changedFiles: remote.changedFiles, patch: "", status: "FAIL", distributed: true, message: `Remote delegation escaped scope: ${violations.join(", ")}` };
+            if (remote.status === "PASS" && remote.patch.trim()) {
+                if (remote.observedCandidateSourceDigest !== input.waveBase.sourceDigest)
+                    return { task: input.task, session: remote.session, changedFiles: remote.changedFiles, patch: "", status: "FAIL", distributed: true, message: "WAVE_RECONCILIATION_REQUIRED: distributed worker did not materialize the frozen wave Candidate source." };
+                return { task: input.task, session: remote.session, changedFiles: remote.changedFiles, patch: remote.patch, status: remote.status, distributed: true, message: remote.message, changeSet: buildWaveChangeSet(input, participantId, remote.changedFiles, remote.patch) };
+            }
+            return { task: input.task, session: remote.session, changedFiles: remote.changedFiles, patch: remote.patch, status: remote.status, distributed: true, message: remote.message };
+        }
+        catch (error) {
+            return failed(input.task, selection, `Distributed delegation failed: ${String(error)}`, true);
+        }
+    }
+    const worktree = await fs.mkdtemp(path.join(os.tmpdir(), `aeh-${safe(input.contract.task.id)}-${safe(input.task.id)}-`));
+    const add = await runExecutable("git", ["worktree", "add", "--detach", worktree, "HEAD"], { cwd: input.root, timeoutMs: 120_000 });
+    if (add.exitCode !== 0)
+        return failed(input.task, selection, `Unable to create task worktree: ${add.stderr || add.stdout}`);
+    try {
+        await materializeCandidateState(input.root, worktree, input.waveBase);
+        await copyTaskContext(input.root, worktree, input.config, input.contract);
+        if (input.controller)
+            await materializeControlPlaneSnapshot(input.controller, worktree, input.config);
+        const baselineAdd = await runExecutable("git", ["add", "-A"], { cwd: worktree, timeoutMs: 30_000 });
+        if (baselineAdd.exitCode !== 0)
+            return failed(input.task, selection, `Unable to create task baseline: ${baselineAdd.stderr || baselineAdd.stdout}`);
+        const baselineCommit = await runExecutable("git", ["-c", "user.name=aeh", "-c", "user.email=aeh@localhost", "commit", "--no-gpg-sign", "-m", "aeh wave baseline", "--allow-empty"], { cwd: worktree, timeoutMs: 60_000 });
+        if (baselineCommit.exitCode !== 0)
+            return failed(input.task, selection, `Unable to create task baseline: ${baselineCommit.stderr || baselineCommit.stdout}`);
+        // The frozen role invocation policy's output contract is the durable structured result for this
+        // work unit. It must be propagated on dispatch (provider turn activation) and finalization
+        // (acceptance), or the Implementer's result channel is never activated and the participant can
+        // only fall back to unstructured text (AEH-V2-0118).
+        const session = await executeAgentPrompt(worktree, input.config, input.contract, selection, prompt, { outputContract: input.participantAssignment.roleInvocationPolicy?.outputContract ?? selection.outputContract ?? "implementer", participantId, phase: "implementation", operationKind: currentOperationContext().kind, requireExecutionAuthority: true, executionBlueprint: input.executionBlueprint, executionBlueprintDigest: input.executionBlueprint.digest, roleInvocationPolicy: input.participantAssignment.roleInvocationPolicy, skillManifest: input.participantAssignment.skillManifest });
+        if (session.exitCode !== 0)
+            return { task: input.task, session, changedFiles: [], patch: "", status: "FAIL", message: `Agent exited with ${session.exitCode}.` };
+        const status = await runExecutable("git", ["status", "--porcelain"], { cwd: worktree, timeoutMs: 30_000 });
+        const untracked = status.stdout.split(/\r?\n/).filter((line) => line.startsWith("?? ")).map((line) => line.slice(3).trim()).filter(Boolean);
+        if (untracked.length)
+            await runExecutable("git", ["add", "-N", "--", ...untracked], { cwd: worktree, timeoutMs: 30_000 });
+        const names = await runExecutable("git", ["diff", "--name-only", "HEAD"], { cwd: worktree, timeoutMs: 30_000 });
+        const changedFiles = names.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const violations = changedFiles.filter((file) => !matchesAny(file, input.task.scope));
+        if (violations.length)
+            return { task: input.task, session, changedFiles, patch: "", status: "FAIL", message: `Delegation escaped scope: ${violations.join(", ")}` };
+        const diff = await runExecutable("git", ["diff", "--binary", "--no-ext-diff", "HEAD"], { cwd: worktree, timeoutMs: 60_000 });
+        if (diff.exitCode !== 0)
+            return { task: input.task, session, changedFiles, patch: "", status: "FAIL", message: diff.stderr || "Unable to capture delegation patch." };
+        return { task: input.task, session, changedFiles, patch: diff.stdout, status: "PASS", changeSet: diff.stdout.trim() ? buildWaveChangeSet(input, participantId, changedFiles, diff.stdout) : undefined };
+    }
+    finally {
+        await runExecutable("git", ["worktree", "remove", "--force", worktree], { cwd: input.root, timeoutMs: 120_000 });
+        await fs.rm(worktree, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+function buildWaveChangeSet(input, participantId, changedFiles, patch) {
+    return {
+        version: 1,
+        operationId: input.operationId,
+        taskId: input.contract.task.id,
+        workUnitId: input.task.id,
+        participantId,
+        baseCandidateRevision: input.waveBase.revision,
+        baseCandidateDigest: input.waveBase.identityDigest,
+        changedFiles,
+        patch,
+        patchDigest: sha256Utf8(patch)
+    };
+}
+export function validatePlannerWavePlan(contract, plan) {
+    const issues = [];
+    const ids = new Set();
+    const requirements = new Set((contract.requirements ?? []).map((item) => item.id));
+    const covered = new Set();
+    for (const task of plan.workUnits) {
+        if (ids.has(task.id))
+            issues.push(`duplicate work unit id ${task.id}`);
+        ids.add(task.id);
+        if (!task.scope.length)
+            issues.push(`${task.id} has empty scope`);
+        for (const scope of task.scope)
+            if (!withinContractScope(scope, contract.scope?.allowed ?? ["**"]))
+                issues.push(`${task.id} scope ${scope} is outside TaskContract scope`);
+        for (const req of [...task.requirementRefs, ...task.acceptanceRefs]) {
+            if (requirements.size && !requirements.has(req))
+                issues.push(`${task.id} references unknown requirement ${req}`);
+            if (requirements.has(req))
+                covered.add(req);
+        }
+    }
+    for (const task of plan.workUnits)
+        for (const dependency of task.dependencies)
+            if (!ids.has(dependency))
+                issues.push(`${task.id} depends on unknown work unit ${dependency}`);
+    for (const requirement of requirements)
+        if (!covered.has(requirement))
+            issues.push(`requirement ${requirement} is not assigned to any implementation work unit`);
+    return [...new Set(issues)];
+}
+function buildPlannerPrompt(contract) { const requirements = (contract.requirements ?? []).map((item) => `- ${item.id}: ${item.description ?? ""}`).join("\n") || "- none"; return `Create the implementation WorkGraph for ${contract.task.id}: ${contract.task.title}.\nThe TaskContract and sealed sources are immutable. Produce the smallest dependency-aware workUnits, concrete path scopes, competencies, risk tags and changeKinds. Each workUnits[].objective must be concise, non-empty, and no longer than 500 characters, matching the Planner output schema and WorkGraph compiler. Map every requirement ID to at least one work unit. If validation meaning is needed, emit typed validationRequirements[{version,id,property,kind,scope,evidenceNeeded,requirementRefs,acceptanceRefs}]; state what must be demonstrated, never a command or provider. If a work unit requires exclusive or ordered access to a shared mutable resource (database schema, migration sequence, package lock, deployment environment, public API contract, generated client, shared config, external mutable resource), emit resourceClaims[{version,resource,mode,order}] with mode SHARED_READ, EXCLUSIVE_WRITE or ORDERED_SEQUENCE and a non-negative order for ORDERED_SEQUENCE. The deterministic scheduler validates and enforces claims; you cannot widen scheduling by claiming a resource. The deterministic resolver will choose approved project scripts, validators or providers. Do not select agents, reviewers, validators, commands, tools or credentials by name, and do not create product requirements. If formalization is required, set formalizationNeed=REQUIRED with one typed formalizationReason and formalizationEvidenceRefs.\nRequirements:\n${requirements}\nAllowed scope: ${(contract.scope?.allowed ?? ["**"]).join(", ")}\nReturn output matching the planner contract; when native structured output is unavailable, use one final AEH_RESULT_JSON=<json> line.`; }
+function buildDelegationPrompt(contract, task, operationalSkills) {
+    const guidance = operationalSkills?.skills.length ? `\nOperational guidance selected for this role and WorkUnit (guidance only; it grants no tools or authority):\n${operationalSkills.skills.map((skill) => `- ${skill.name} v${skill.version} [${skill.certificationStatus}${skill.accessMode === "CONTROLLER_GUIDANCE" ? ", controller-guidance-only" : ""}]: ${skill.procedure.join("; ")}${skill.recovery.length ? ` Recovery: ${skill.recovery.map((item) => `${item.failureClass} → ${item.steps.join("; ")}`).join(" | ")}` : ""}`).join("\n")}` : "";
+    return `Implement only work unit ${task.id} for parent ${contract.task.id}.\nObjective: ${task.objective}\nAllowed task scope: ${task.scope.join(", ")}\nDependencies already integrated: ${task.dependencies.join(", ") || "none"}\nAcceptance references: ${task.acceptanceRefs.join(", ") || "none"}\nRequired competencies: ${task.competencies.join(", ") || "general engineering"}\nRisk: ${task.risk}.${guidance}\nThe parent TaskContract, SDD and control-plane snapshot are frozen. Do not edit outside the declared scope, do not commit, push, rebase or change requirements. Run focused tests when practical and leave the worktree with only the implementation diff.`;
+}
+export function selectionForParticipant(base, assignment, catalog) {
+    const binding = catalog.roleBindings[assignment.role];
+    if (!binding)
+        throw new Error(`EXECUTION_BLUEPRINT_INVALID: no execution binding exists for role '${assignment.role}'.`);
+    const runtime = catalog.runtimeProfiles.find((profile) => profile.id === binding.runtimeId);
+    const model = catalog.modelProfiles.find((profile) => profile.alias === binding.modelAlias);
+    if (!runtime || !model)
+        throw new Error(`EXECUTION_BLUEPRINT_INVALID: execution binding for role '${assignment.role}' references an unavailable runtime or model.`);
+    if (model.runtime !== binding.runtimeId)
+        throw new Error(`EXECUTION_BLUEPRINT_INVALID: execution binding for role '${assignment.role}' pairs model '${binding.modelAlias}' with runtime '${binding.runtimeId}', but the model requires '${model.runtime}'.`);
+    const permissions = { ...base.permissions };
+    const exposedTools = [...new Set([...assignment.toolPack.required, ...assignment.toolPack.optional])].filter((tool) => !assignment.toolPack.forbidden.includes(tool));
+    // The compiled assignment toolPack is the role ceiling-checked capability set, so the launch
+    // permission projection must express it explicitly instead of leaving provider defaults ("ask")
+    // in place: an undefined provider permission made a real Implementer session stop for write
+    // approval and return an empty result (AEH-V2-0110). An explicit base deny is never widened.
+    const allowIfExposed = (current, tool) => {
+        if (!exposedTools.includes(tool))
+            return "deny";
+        return current === "deny" || current === "ask" ? current : "allow";
+    };
+    permissions.read = allowIfExposed(permissions.read, "repository-read");
+    permissions.write = allowIfExposed(permissions.write, "repository-write");
+    permissions.gitWrite = allowIfExposed(permissions.gitWrite, "repository-write");
+    permissions.shell = allowIfExposed(permissions.shell, "command-execute");
+    permissions.network = exposedTools.includes("approved-research") ? (permissions.network === "deny" ? "deny" : "allow") : "deny";
+    if (assignment.role === "Reviewer") {
+        permissions.write = "deny";
+        permissions.gitWrite = "deny";
+    }
+    return {
+        ...base,
+        profile: binding.profile ?? base.profile,
+        logicalAgent: assignment.participantId,
+        role: assignment.role,
+        specializations: [assignment.specialization],
+        runtimeName: runtime.id,
+        runtimeAdapter: runtime.adapter,
+        paseoProvider: runtime.provider ?? runtime.adapter,
+        modelAlias: model.alias,
+        modelId: model.id,
+        modelName: model.model,
+        modelProvider: model.provider,
+        variant: binding.variant ?? model.variant,
+        temperature: binding.temperature ?? base.temperature,
+        nativeAgent: binding.nativeAgent,
+        transport: binding.transport,
+        outputContract: binding.outputContract ?? base.outputContract,
+        args: binding.args ? [...binding.args] : [...base.args],
+        mcps: [...exposedTools].sort(),
+        skills: [...assignment.skills],
+        permissions,
+        runtimeCapabilities: { ...runtime.capabilities }
+    };
+}
+async function copyTaskContext(root, target, config, contract) { const relative = [`${config.sdd?.contractsDir ?? ".harness/contracts"}/${contract.task.id}.yaml`, `.harness/seals/${contract.task.id}.json`, ...Object.values(contract.source ?? {}).filter((value) => Boolean(value)), contract.issue?.snapshotPath].filter((value) => Boolean(value)); for (const item of [...new Set(relative)]) {
+    try {
+        const source = await existingRepositoryPath(root, item);
+        const destination = repositoryPath(target, item);
+        await fs.mkdir(path.dirname(destination), { recursive: true });
+        await fs.copyFile(source, destination);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+} }
+function withinContractScope(candidate, allowed) { return allowed.some((pattern) => pattern === "**" || minimatch(candidate, pattern, { dot: true }) || pathWithin(staticPrefix(candidate), staticPrefix(pattern))); }
+function pathWithin(candidate, parent) { return Boolean(candidate && parent) && (candidate === parent || candidate.startsWith(`${parent}/`)); }
+function matchesAny(file, patterns) { return patterns.some((pattern) => pattern === "**" || minimatch(file, pattern, { dot: true }) || pathWithin(file, staticPrefix(pattern))); }
+function staticPrefix(pattern) { return pattern.split(/[?*\[]/, 1)[0].replace(/\/+$/, ""); }
+function failed(task, selection, message, distributed = false) { return { task, session: { provider: selection.runtimeAdapter, model: selection.modelName, logicalAgent: selection.logicalAgent, runtime: selection.runtimeName, profile: selection.profile, exitCode: 1, stdout: "", stderr: message }, changedFiles: [], patch: "", status: "FAIL", message, distributed }; }
+function aggregate(sessions, exitCode, message) { return { provider: "multi-worker", logicalAgent: "planner-waves", exitCode, stdout: message, stderr: exitCode ? sessions.filter((session) => session.exitCode !== 0).map((session) => session.stderr).filter(Boolean).join("\n") : "" }; }
+/**
+ * AEH-V2-0129: `workflow.planning.worktreeIsolation` defaults to true and is honored by per-unit
+ * candidate worktrees. When it is explicitly disabled, same-workspace writers are serialized
+ * deterministically (one work unit at a time) instead of running parallel writers, because
+ * DELEGATED candidate assembly always captures one ChangeSet per unit.
+ */
+export function waveConcurrencyV1(planning, taskCount) {
+    if (planning?.worktreeIsolation === false)
+        return 1;
+    return Math.max(1, Math.min(planning?.maxWaveConcurrency ?? taskCount, taskCount));
+}
+async function mapLimit(values, limit, fn) { if (!values.length)
+    return []; const result = new Array(values.length); let cursor = 0; const workers = Array.from({ length: Math.max(1, Math.min(limit, values.length)) }, async () => { while (true) {
+    const index = cursor++;
+    if (index >= values.length)
+        return;
+    result[index] = await fn(values[index]);
+} }); await Promise.all(workers); return result; }
+function safe(value) { return value.replace(/[^A-Za-z0-9._-]/g, "-"); }
+//# sourceMappingURL=waveExecutor.js.map