agentic-engineering-harness 0.14.2 → 0.15.0

package/dist/releases/release-1791267146418-18806-f0438c13/agents/waveExecutor.d.ts

@@ -0,0 +1,240 @@
+import type { AgentExecutionSelection } from "./types.js";
+import { type ParallelismPlan } from "./parallelism.js";
+import { type PlannerOutput, type WorkUnitOutput } from "./outputContracts.js";
+import type { ControlPlaneSnapshot } from "../core/controlPlane.js";
+import type { HarnessProjectConfig, TaskContract, ValidationReport, WorkerSession } from "../core/types.js";
+import { type ExecutionBlueprint, type ParticipantAssignmentV1 } from "../architecture/participantPlan.js";
+import type { ExecutionCatalogV1 } from "../architecture/executionCatalog.js";
+import type { CapabilityRegistryV1 } from "../capabilities/registry.js";
+import type { CandidateImpactAssessmentRuntimeV1, CandidateImpactV1, CandidateScopeEscapeV1, ChangeSetV1 } from "../candidates/assembler.js";
+import type { CandidateRevisionV1 } from "../operations/v2Contracts.js";
+import { resolveKnowledgeGate, type KnowledgeCacheV1, type KnowledgeLookupResultV1, type KnowledgeModeV1, type KnowledgePackV1, type KnowledgeResolutionV1 } from "../knowledge/index.js";
+import type { ProjectStackProfileV1 } from "../participants/stack.js";
+import { RuntimeSupervisorV1 } from "../runtime/supervisorV2.js";
+export interface DelegationExecutionResult {
+    task: WorkUnitOutput;
+    session: WorkerSession;
+    changedFiles: string[];
+    patch: string;
+    status: "PASS" | "FAIL";
+    message?: string;
+    distributed?: boolean;
+    candidate?: CandidateRevisionV1;
+    impact?: CandidateImpactV1;
+    changeSet?: ChangeSetV1;
+}
+export interface WaveExecutionSummary {
+    wave: number;
+    taskIds: string[];
+    status: "PASS" | "FAIL";
+    results: DelegationExecutionResult[];
+    barrier?: ValidationReport;
+}
+export interface PlannerWaveResult {
+    used: boolean;
+    plan?: PlannerOutput;
+    blueprint?: ExecutionBlueprint;
+    schedule?: ParallelismPlan;
+    waves: WaveExecutionSummary[];
+    sessions: WorkerSession[];
+    aggregateSession?: WorkerSession;
+    report?: ValidationReport;
+    preExecutionFailure?: boolean;
+    correctionAttempts?: 0 | 1;
+}
+export declare function executePlannerWaves(input: {
+    root: string;
+    stateRoot: string;
+    config: HarnessProjectConfig;
+    contract: TaskContract;
+    plannerSelection?: AgentExecutionSelection;
+    librarianSelection?: AgentExecutionSelection;
+    implementationSelection: AgentExecutionSelection;
+    executionCatalog: ExecutionCatalogV1;
+    capabilityRegistry: CapabilityRegistryV1;
+    controller?: ControlPlaneSnapshot;
+    precomputedPlan?: PlannerOutput;
+    semanticAssessment?: CandidateImpactAssessmentRuntimeV1;
+    projectStack?: ProjectStackProfileV1;
+    knowledgeMode?: KnowledgeModeV1;
+    knowledgeCache?: KnowledgeCacheV1;
+    knowledgeResolutions?: readonly KnowledgeResolutionV1[];
+    knowledgeLookup?: (gap: Parameters<NonNullable<Parameters<typeof resolveKnowledgeGate>[0]["lookup"]>>[0]) => Promise<KnowledgePackV1 | KnowledgeLookupResultV1>;
+    revalidate: () => Promise<ValidationReport>;
+    onScopeEscape?: (record: CandidateScopeEscapeV1) => Promise<void> | void;
+}): Promise<PlannerWaveResult>;
+export declare function resolvePlannerKnowledge(plan: PlannerOutput, input: Pick<Parameters<typeof executePlannerWaves>[0], "contract" | "root" | "config" | "librarianSelection" | "knowledgeMode" | "knowledgeCache" | "knowledgeResolutions" | "knowledgeLookup"> & Partial<Pick<Parameters<typeof executePlannerWaves>[0], "stateRoot">>): Promise<KnowledgeResolutionV1[]>;
+export declare function validatePlannerWavePlan(contract: TaskContract, plan: PlannerOutput): string[];
+export declare function selectionForParticipant(base: AgentExecutionSelection, assignment: ParticipantAssignmentV1, catalog: ExecutionCatalogV1): AgentExecutionSelection;
+/**
+ * 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.
+ *
+ * Unit 3 provider backpressure (DETERMINISTIC): wave fan-out never widens the
+ * provider-session lease ceiling (single source:
+ * `DEFAULT_OPERATION_RESOURCE_POLICY.maxConcurrentProviderSessionsPerOperation`;
+ * caps unchanged). The default concurrency is `min(taskCount, lease cap)` and
+ * any configured `maxWaveConcurrency` above the cap is clamped down
+ * (fail-closed). Excess work waits in the bounded `mapLimit` worker queue
+ * (QUEUE, never throw); operation-wide saturation QUEUES via durable
+ * `waitForProviderSessionCapacity` (production caller, bounded WAIT against the
+ * caller's existing deadline, terminal on exhaustion); per-workspace
+ * write-write conflicts QUEUE via non-throwing `tryAcquireProviderLease`
+ * (production caller below, bounded `providerLeaseQueueWaitMs` WAIT, RETRY
+ * within budget, never throw-on-conflict on the wired path); residual
+ * lease/rate-limit conflicts classify via `isWaveBackpressureError`
+ * (narrow 429/rate-limit marker, never bare `retry-after`) and wait via
+ * bounded `waveRateLimitWaitMs`/`waveQueueWaitMs` against the caller's
+ * existing deadline (WAIT is not an attempt; exhausted budgets are terminal).
+ * Telemetry is observation-only `harness.wave.backpressure` counter/gauge
+ * attributes via existing `recordEvent` conventions.
+ */
+export declare const WAVE_CONCURRENCY_LEASE_CAP_V1: number;
+export declare const WAVE_BACKPRESSURE_MAX_WAIT_MS_V1 = 30000;
+export declare const WAVE_BACKPRESSURE_EVENT_V1 = "harness.wave.backpressure";
+export interface WaveBackpressureTelemetryV1 {
+    wave: number;
+    taskId: string;
+    active: number;
+    ceiling: number;
+    queued: number;
+    retryAfterMs: number;
+    disposition: "QUEUE" | "PROCEED" | "CLAMPED";
+    rateLimited?: boolean;
+}
+export declare function waveConcurrencyV1(planning: {
+    worktreeIsolation?: boolean;
+    maxWaveConcurrency?: number;
+} | undefined, taskCount: number): number;
+/**
+ * Luna F1: remaining wave/operation budget threading (DETERMINISTIC, no I/O).
+ *
+ * The operation capacity WAIT must never start a fresh 30s budget unbounded
+ * by the existing wave/operation deadline. `resolveWaveCapacityDeadlineAtMs`
+ * returns `min(now + maxWaitMs, operationDeadlineAtMs)` when a finite
+ * operation deadline exists, and `undefined` when none can be established
+ * (never mints fresh `now+30s`). Callers treat `undefined` as no-wait budget:
+ * single immediate capacity check only (headroom proceeds, saturation is
+ * terminal FAIL with zero sleeps). `remainingWaveBudgetMs` returns
+ * `max(0, deadline - now)`; 0 or undefined deadline means exhausted → terminal
+ * FAIL with no wait (fail-closed). Deterministic clocks: callers pass `nowMs`;
+ * tests pin it.
+ */
+export declare function resolveWaveCapacityDeadlineAtMs(nowMs: number, operationDeadlineAtMs?: number, maxWaitMs?: number): number | undefined;
+export declare function remainingWaveBudgetMs(deadlineAtMs: number | undefined, nowMs: number): number;
+/**
+ * Bounded backpressure telemetry attributes for existing `recordEvent`
+ * conventions (counter: queued/active; gauge: ceiling/concurrency). Refs-only,
+ * never provider content; observation only, never a gate.
+ */
+export declare function waveBackpressureAttributes(signal: WaveBackpressureTelemetryV1): Record<string, unknown>;
+/** DETERMINISTIC classifier: true when the failure is backpressure (QUEUE/WAIT, not FAIL). Narrow marker: bare `retry-after` without a 429/rate-limit signal is never backpressure. */
+export declare function isWaveBackpressureError(error: unknown): boolean;
+/** Alias for wave callers: backpressure failures queue; all other failures are terminal. */
+export declare function shouldQueueWaveWork(error: unknown): boolean;
+/**
+ * Honor a Retry-After/queue WAIT against an existing deadline budget. Never
+ * extends caps: returns `min(boundedWait, remainingBudget)`, or 0 when
+ * exhausted (terminal, fail-closed). A WAIT is not an attempt.
+ */
+export declare function waveRateLimitWaitMs(retryAfterMs: number | {
+    retryAfterMs: number;
+} | undefined, remainingBudgetMs?: number): number;
+/** Bounded QUEUE wait alias (lease-conflict path shares the same budget rule as rate-limit WAIT). */
+export declare function waveQueueWaitMs(retryAfterMs: number | undefined, remainingBudgetMs?: number): number;
+/**
+ * Wave-dispatch QUEUE RETRY within an existing deadline (production wired path).
+ *
+ * MECHANISM: DETERMINISTIC classification + bounded WAIT. Backpressure
+ * (`isWaveBackpressureError`, including 429 via `parseProviderRateLimitDetail`
+ * narrow marker and lease conflicts via `isProviderLeaseConflictError`) QUEUES:
+ * Retry-After is honored via `waveRateLimitWaitMs` (429) or
+ * `providerLeaseQueueWaitMs`/`waveQueueWaitMs` (lease QUEUED hint) against the
+ * caller's existing deadline budget (never extends caps; 0 when exhausted →
+ * terminal rethrow, fail-closed). A WAIT is not an attempt. Non-backpressure
+ * failures rethrow immediately (FAIL). Injectable `now`/`sleep` keep fixtures
+ * scripted with no network (same pattern as `waitForProviderSessionCapacity`).
+ */
+export interface WaveBackpressureRetryOptionsV1 {
+    timeoutMs?: number;
+    nowMs?: () => number;
+    sleepMs?: (ms: number) => Promise<void>;
+    onWait?: (waitMs: number, error: unknown) => void;
+}
+export declare function withWaveBackpressureRetry<T>(action: (remainingBudgetMs: number | undefined) => Promise<T>, options?: WaveBackpressureRetryOptionsV1): Promise<T>;
+/**
+ * Intra-wave per-workspace write-lease admission (NOT shared enforcement).
+ *
+ * SCOPE HONESTY (Luna F2): this serializes concurrent writers *within one
+ * wave in one process* via the provided in-memory supervisor. A fresh
+ * `RuntimeSupervisorV1` per wave cannot see leases from other waves,
+ * operations, or processes — it is blind to cross-wave/operation contention
+ * by construction. Cross-wave/operation contention is enforced by the SHARED
+ * durable authority: the operation-wide capacity gate
+ * (`waitForProviderSessionCapacity` over `readManagedRuntimeSnapshot`, the
+ * same lease store `acquireProviderLease` persists to) plus
+ * `acquireWaveProviderSlotSharedOrQueue` below plus the real provider
+ * lifecycle (`runWithOperationProviderLease`). Never use this alone to claim
+ * shared enforcement.
+ *
+ * Isolated worktrees use distinct workspace keys (no contention, ACQUIRED);
+ * shared-workspace waves share one key (second writer QUEUES). On QUEUED, the
+ * bounded `providerLeaseQueueWaitMs` WAIT is honored against the caller's
+ * existing deadline (never extends caps; exhaustion → terminal false, FAIL).
+ */
+export declare function acquireWaveProviderSlotOrQueue(supervisor: RuntimeSupervisorV1, input: {
+    provider: string;
+    projectId: string;
+    canonicalRoot: string;
+    workspaceId: string;
+    ownerId: string;
+    mode?: "read" | "write";
+}, options?: {
+    remainingBudgetMs?: number;
+    sleepMs?: (ms: number) => Promise<void>;
+}): Promise<{
+    acquired: boolean;
+    retryAfterMs: number;
+    queueDepth: number;
+}>;
+/**
+ * Shared durable per-workspace gate for wave dispatch (Luna F2+F3, fail-closed).
+ *
+ * MECHANISM: DETERMINISTIC atomic acquire-or-wait-or-fail via the REAL
+ * `acquireProviderLease` store path (`acquireDurableWaveSlotOrQueue` over the
+ * file-locked managed-runtime snapshot, same `findConflictingProviderLeases`
+ * predicate as `tryAcquireProviderLease`). Check-then-proceed is deleted: the
+ * previous read-only `checkDurableWaveSlotConflict` + proceed-without-acquire
+ * (TOCTOU, two racers both proceeding) cannot be made atomic and is removed
+ * (no dead code). ATOMICITY: in-memory `tryAcquireProviderLease` is atomic
+ * within one process only; cross-wave/operation/process atomicity comes from
+ * the snapshot `.lock` transact in `operationResources.ts` (reload→check→write
+ * under one lock, never both proceed).
+ *
+ * Bounded WAIT (`min(retryAfter, remainingBudget)`) against the caller's
+ * existing deadline (never mints fresh; undefined/0 budget means single
+ * immediate attempt only, exhaustion → terminal false, FAIL). Unreadable
+ * durability BLOCKS (acquired false, retryAfter 0, no wait). Deterministic
+ * clocks via `nowMs`/`sleepMs`. Returns durable `leaseId` on ACQUIRED for
+ * explicit `releaseDurableWaveSlot` (callers release in finally, best-effort).
+ */
+export declare function acquireWaveProviderSlotSharedOrQueue(root: string, input: {
+    provider: string;
+    projectId: string;
+    canonicalRoot: string;
+    workspaceId: string;
+    ownerId: string;
+    mode?: "read" | "write";
+}, options?: {
+    remainingBudgetMs?: number;
+    sleepMs?: (ms: number) => Promise<void>;
+    nowMs?: () => number;
+}): Promise<{
+    acquired: boolean;
+    retryAfterMs: number;
+    queueDepth: number;
+    scope: "shared-durable";
+    leaseId?: string;
+}>;

package/dist/releases/{release-1791263434955-18515-5948278e → release-1791267146418-18806-f0438c13}/agents/waveExecutor.js

@@ -25,6 +25,10 @@ import { FileKnowledgeCacheV1, resolveKnowledgeGate, validateKnowledgePack } fro
 import { defaultSkillSeed } from "../participants/index.js";
 import { dropUnresolvablePlanValidationRequirementsV1, resolveValidationRequirements } from "../architecture/validationRequirements.js";
 import { compilePlannerWorkGraphWithOneCorrection, PlannerWorkGraphCorrectionError } from "./plannerWorkGraphCorrection.js";
+import { DEFAULT_OPERATION_RESOURCE_POLICY, PROVIDER_BACKPRESSURE_EVENT_V1, acquireDurableWaveSlotOrQueue, isProviderCapacityError, providerBackpressureAttributes, releaseDurableWaveSlot, waitForProviderSessionCapacity } from "../runtime/operationResources.js";
+import { isProviderLeaseConflictError, providerLeaseBackpressureSignal, providerLeaseQueueWaitMs } from "../runtime/supervisorV2.js";
+import { frozenOperationHardDeadlineAt } from "../operations/state.js";
+import { isProviderRateLimited, parseProviderRateLimitDetail } from "../paseo/sdk.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")
@@ -146,7 +150,131 @@ export async function executePlannerWaves(input) {
         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 }));
+        const concurrency = waveConcurrencyV1(planning, tasks.length);
+        if (tasks.length > concurrency || (planning?.maxWaveConcurrency ?? 0) > WAVE_CONCURRENCY_LEASE_CAP_V1) {
+            await recordEvent(input.stateRoot, input.config, WAVE_BACKPRESSURE_EVENT_V1, waveBackpressureAttributes({ wave: index + 1, taskId: input.contract.task.id, active: tasks.length, ceiling: WAVE_CONCURRENCY_LEASE_CAP_V1, queued: Math.max(0, tasks.length - concurrency), retryAfterMs: 0, disposition: "CLAMPED" }));
+        }
+        // Operation-wide provider-session QUEUE gate (durable equivalent of
+        // tryAcquireProviderLease; production caller of waitForProviderSessionCapacity).
+        // Luna F1: bounded WAIT against the wave's EXISTING budget — WAIT =
+        // min(requested 30s, remaining wave/operation budget) when a finite frozen
+        // Owner hard deadline exists; when none can be established (undefined),
+        // mint NO fresh 30s (single immediate check only: headroom proceeds,
+        // saturation is terminal FAIL with zero sleeps, fail-closed).
+        // MECHANISM: DETERMINISTIC. Wave budget deadline = min(now + 30s, frozen
+        // Owner hard deadline) when present, else undefined (no fresh); threaded
+        // as deadlineAtMs so the wait never extends caps. Deterministic clocks via
+        // pure helpers (tests pin it).
+        const waveStartedAtMs = Date.now();
+        const operationDeadlineAtMs = operation ? frozenOperationHardDeadlineAt(operation) : undefined;
+        const waveCapacityDeadlineAtMs = resolveWaveCapacityDeadlineAtMs(waveStartedAtMs, operationDeadlineAtMs, WAVE_BACKPRESSURE_MAX_WAIT_MS_V1);
+        const capacity = await waitForProviderSessionCapacity(input.stateRoot, waveOperationId, {
+            ceiling: WAVE_CONCURRENCY_LEASE_CAP_V1,
+            maxWaitMs: WAVE_BACKPRESSURE_MAX_WAIT_MS_V1,
+            deadlineAtMs: waveCapacityDeadlineAtMs,
+            pollMs: 50
+        });
+        if (!capacity.acquired) {
+            await recordEvent(input.stateRoot, input.config, WAVE_BACKPRESSURE_EVENT_V1, waveBackpressureAttributes({ wave: index + 1, taskId: input.contract.task.id, active: capacity.active, ceiling: capacity.ceiling, queued: tasks.length, retryAfterMs: WAVE_BACKPRESSURE_MAX_WAIT_MS_V1, disposition: "QUEUE" }));
+            // Observation-only provider backpressure telemetry via existing conventions
+            // (production caller of providerBackpressureAttributes + providerLeaseBackpressureSignal;
+            // never a gate).
+            const providerSignal = providerLeaseBackpressureSignal(capacity.active, tasks.length, capacity.ceiling);
+            await recordEvent(input.stateRoot, input.config, PROVIDER_BACKPRESSURE_EVENT_V1, providerBackpressureAttributes({
+                operationId: waveOperationId,
+                active: providerSignal.active,
+                ceiling: providerSignal.ceiling ?? capacity.ceiling,
+                queued: providerSignal.queued,
+                retryAfterMs: WAVE_BACKPRESSURE_MAX_WAIT_MS_V1,
+                disposition: "QUEUE"
+            })).catch(() => undefined);
+            const summary = {
+                wave: index + 1,
+                taskIds: ids,
+                status: "FAIL",
+                results: tasks.map((task) => ({
+                    task,
+                    session: { provider: "wave-queue", logicalAgent: task.id, exitCode: 1, stdout: "", stderr: `WAVE_QUEUE_EXHAUSTED: operation ${waveOperationId} holds ${capacity.active}/${capacity.ceiling} provider sessions; QUEUE budget exhausted.` },
+                    changedFiles: [],
+                    patch: "",
+                    status: "FAIL",
+                    message: `WAVE_QUEUE_EXHAUSTED: operation ${waveOperationId} holds ${capacity.active}/${capacity.ceiling} provider sessions; QUEUE budget exhausted.`
+                }))
+            };
+            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} provider capacity QUEUE exhausted.`) };
+        }
+        // Per-workspace write-lease admission (Luna F2+F3: SHARED durable atomic
+        // acquire, not wave-local check-then-proceed; non-throwing QUEUE, never
+        // throw-on-conflict on the wired path). Isolated tasks use distinct
+        // workspace keys (ACQUIRED); shared-workspace waves share one key (second
+        // writer QUEUES, serializing to 1). The durable atomic acquire
+        // (`acquireWaveProviderSlotSharedOrQueue` → `acquireDurableWaveSlotOrQueue`
+        // file-locked transact, same store/predicate as `acquireProviderLease`)
+        // sees cross-wave/operation/process contention end-to-end (acquire-or-wait-
+        // or-fail, never both proceed). Residual 429/lease conflicts RETRY via
+        // bounded `withWaveBackpressureRetry` within the REMAINING wave budget
+        // (Luna F1: WAIT is not an attempt; exhaustion terminal; never a fresh 30s
+        // unbounded by the wave/operation deadline).
+        const waveProjectId = input.config.project.name;
+        // Luna F1 (continued): per-slot retries share the wave's remaining budget,
+        // not a fresh 30s. Remaining = waveCapacityDeadline - now (0/undefined →
+        // terminal, no fresh). Undefined deadline means no wait budget (immediate).
+        const waveSlotTimeoutMs = Math.max(0, remainingWaveBudgetMs(waveCapacityDeadlineAtMs, Date.now()));
+        const executeWithQueue = (task) => withWaveBackpressureRetry(async (remaining) => {
+            const isolated = planning?.worktreeIsolation !== false;
+            const workspaceId = isolated ? `wave:${waveOperationId}:${index}:${task.id}` : `wave:${waveOperationId}:${index}`;
+            const slot = await acquireWaveProviderSlotSharedOrQueue(input.stateRoot, { provider: "wave", projectId: waveProjectId, canonicalRoot: input.root, workspaceId, ownerId: task.id, mode: "write" }, {
+                ...(remaining !== undefined ? { remainingBudgetMs: remaining } : { remainingBudgetMs: 0 }),
+            });
+            if (!slot.acquired) {
+                // QUEUE budget exhausted for this slot → terminal FAIL (fail-closed, never throw).
+                return {
+                    task,
+                    session: { provider: "wave-queue", logicalAgent: task.id, exitCode: 1, stdout: "", stderr: `WAVE_QUEUE_EXHAUSTED: provider wave already leased (depth ${slot.queueDepth}); QUEUE budget exhausted.` },
+                    changedFiles: [],
+                    patch: "",
+                    status: "FAIL",
+                    message: `WAVE_QUEUE_EXHAUSTED: provider wave is already leased in ${workspaceId} (depth ${slot.queueDepth}); QUEUE budget exhausted.`
+                };
+            }
+            try {
+                const result = await executeDelegation({ ...input, operationId: waveOperationId, task, participantAssignment: participantByWorkUnit.get(task.id), executionBlueprint: waveBlueprint, waveBase: waveBase.candidate });
+                // Residual backpressure surfaced as FAIL message QUEUES (not terminal FAIL):
+                // throw to trigger WAIT+RETRY within budget; exhaustion rethrows as FAIL below.
+                // shouldQueueWaveWork is the wave QUEUE gate (alias of isWaveBackpressureError).
+                if (result.status === "FAIL" && result.message && shouldQueueWaveWork(result.message)) {
+                    throw new Error(result.message);
+                }
+                return result;
+            }
+            finally {
+                // Release durable wave slot for the next QUEUED waiter (best-effort
+                // atomic release under the same snapshot lock; never fails delegation).
+                // LeaseId is present on ACQUIRED (atomic path); missing means nothing to release.
+                try {
+                    if (slot.leaseId)
+                        await releaseDurableWaveSlot(input.stateRoot, slot.leaseId, task.id);
+                }
+                catch { /* best-effort slot release never fails the delegation */ }
+            }
+        }, { timeoutMs: waveSlotTimeoutMs }).catch((error) => {
+            // Exhausted QUEUE budget or terminal non-backpressure failure → FAIL (never throw).
+            if (shouldQueueWaveWork(error)) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    task,
+                    session: { provider: "wave-queue", logicalAgent: task.id, exitCode: 1, stdout: "", stderr: message.slice(0, 500) },
+                    changedFiles: [],
+                    patch: "",
+                    status: "FAIL",
+                    message: message.slice(0, 500)
+                };
+            }
+            throw error;
+        });
+        const results = await mapLimit(tasks, concurrency, executeWithQueue);
         sessions.push(...results.map((result) => result.session));
         if (results.some((result) => result.status === "FAIL")) {
             const summary = { wave: index + 1, taskIds: ids, status: "FAIL", results };
@@ -512,11 +640,248 @@ function aggregate(sessions, exitCode, message) { return { provider: "multi-work
  * 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.
+ *
+ * Unit 3 provider backpressure (DETERMINISTIC): wave fan-out never widens the
+ * provider-session lease ceiling (single source:
+ * `DEFAULT_OPERATION_RESOURCE_POLICY.maxConcurrentProviderSessionsPerOperation`;
+ * caps unchanged). The default concurrency is `min(taskCount, lease cap)` and
+ * any configured `maxWaveConcurrency` above the cap is clamped down
+ * (fail-closed). Excess work waits in the bounded `mapLimit` worker queue
+ * (QUEUE, never throw); operation-wide saturation QUEUES via durable
+ * `waitForProviderSessionCapacity` (production caller, bounded WAIT against the
+ * caller's existing deadline, terminal on exhaustion); per-workspace
+ * write-write conflicts QUEUE via non-throwing `tryAcquireProviderLease`
+ * (production caller below, bounded `providerLeaseQueueWaitMs` WAIT, RETRY
+ * within budget, never throw-on-conflict on the wired path); residual
+ * lease/rate-limit conflicts classify via `isWaveBackpressureError`
+ * (narrow 429/rate-limit marker, never bare `retry-after`) and wait via
+ * bounded `waveRateLimitWaitMs`/`waveQueueWaitMs` against the caller's
+ * existing deadline (WAIT is not an attempt; exhausted budgets are terminal).
+ * Telemetry is observation-only `harness.wave.backpressure` counter/gauge
+ * attributes via existing `recordEvent` conventions.
  */
+export const WAVE_CONCURRENCY_LEASE_CAP_V1 = DEFAULT_OPERATION_RESOURCE_POLICY.maxConcurrentProviderSessionsPerOperation;
+export const WAVE_BACKPRESSURE_MAX_WAIT_MS_V1 = 30_000;
+export const WAVE_BACKPRESSURE_EVENT_V1 = "harness.wave.backpressure";
 export function waveConcurrencyV1(planning, taskCount) {
     if (planning?.worktreeIsolation === false)
         return 1;
-    return Math.max(1, Math.min(planning?.maxWaveConcurrency ?? taskCount, taskCount));
+    const requested = planning?.maxWaveConcurrency ?? taskCount;
+    const boundedRequested = Number.isFinite(requested) ? Math.floor(requested) : taskCount;
+    return Math.max(1, Math.min(boundedRequested, taskCount, WAVE_CONCURRENCY_LEASE_CAP_V1));
+}
+/**
+ * Luna F1: remaining wave/operation budget threading (DETERMINISTIC, no I/O).
+ *
+ * The operation capacity WAIT must never start a fresh 30s budget unbounded
+ * by the existing wave/operation deadline. `resolveWaveCapacityDeadlineAtMs`
+ * returns `min(now + maxWaitMs, operationDeadlineAtMs)` when a finite
+ * operation deadline exists, and `undefined` when none can be established
+ * (never mints fresh `now+30s`). Callers treat `undefined` as no-wait budget:
+ * single immediate capacity check only (headroom proceeds, saturation is
+ * terminal FAIL with zero sleeps). `remainingWaveBudgetMs` returns
+ * `max(0, deadline - now)`; 0 or undefined deadline means exhausted → terminal
+ * FAIL with no wait (fail-closed). Deterministic clocks: callers pass `nowMs`;
+ * tests pin it.
+ */
+export function resolveWaveCapacityDeadlineAtMs(nowMs, operationDeadlineAtMs, maxWaitMs = WAVE_BACKPRESSURE_MAX_WAIT_MS_V1) {
+    const safeNow = Number.isFinite(nowMs) ? Math.floor(nowMs) : 0;
+    const safeMax = Number.isFinite(maxWaitMs) && maxWaitMs >= 0
+        ? Math.min(WAVE_BACKPRESSURE_MAX_WAIT_MS_V1, Math.floor(maxWaitMs))
+        : WAVE_BACKPRESSURE_MAX_WAIT_MS_V1;
+    if (operationDeadlineAtMs === undefined || !Number.isFinite(operationDeadlineAtMs)) {
+        // Fail-closed: no existing wave/operation deadline can be established, so
+        // mint no fresh time. Callers do immediate-check-only (no wait).
+        return undefined;
+    }
+    const freshDeadline = safeNow + safeMax;
+    return Math.min(freshDeadline, Math.floor(operationDeadlineAtMs));
+}
+export function remainingWaveBudgetMs(deadlineAtMs, nowMs) {
+    if (deadlineAtMs === undefined || !Number.isFinite(deadlineAtMs) || !Number.isFinite(nowMs))
+        return 0;
+    return Math.max(0, Math.floor(deadlineAtMs) - Math.floor(nowMs));
+}
+/**
+ * Bounded backpressure telemetry attributes for existing `recordEvent`
+ * conventions (counter: queued/active; gauge: ceiling/concurrency). Refs-only,
+ * never provider content; observation only, never a gate.
+ */
+export function waveBackpressureAttributes(signal) {
+    return {
+        wave: Math.max(0, Math.floor(signal.wave)),
+        taskId: signal.taskId.slice(0, 200),
+        active: Math.max(0, Math.floor(signal.active)),
+        ceiling: Math.max(1, Math.floor(signal.ceiling)),
+        queued: Math.max(0, Math.floor(signal.queued)),
+        retryAfterMs: Math.max(0, Math.min(WAVE_BACKPRESSURE_MAX_WAIT_MS_V1, Math.floor(signal.retryAfterMs))),
+        disposition: signal.disposition,
+        ...(signal.rateLimited !== undefined ? { rateLimited: signal.rateLimited } : {})
+    };
+}
+/** DETERMINISTIC classifier: true when the failure is backpressure (QUEUE/WAIT, not FAIL). Narrow marker: bare `retry-after` without a 429/rate-limit signal is never backpressure. */
+export function isWaveBackpressureError(error) {
+    const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    if (!message)
+        return false;
+    if (message.includes("RESOURCE_CEILING_EXHAUSTED") && message.includes("active provider sessions"))
+        return true;
+    if (message.includes("already leased in"))
+        return true;
+    if (message.includes("PASEO_PROVIDER_LEASE_TAKEOVER_BLOCKED"))
+        return true;
+    return /(?:\b429\b|rate[\s_\-]*limit|too many requests)/i.test(message);
+}
+/** Alias for wave callers: backpressure failures queue; all other failures are terminal. */
+export function shouldQueueWaveWork(error) {
+    return isWaveBackpressureError(error);
+}
+/**
+ * Honor a Retry-After/queue WAIT against an existing deadline budget. Never
+ * extends caps: returns `min(boundedWait, remainingBudget)`, or 0 when
+ * exhausted (terminal, fail-closed). A WAIT is not an attempt.
+ */
+export function waveRateLimitWaitMs(retryAfterMs, remainingBudgetMs) {
+    const raw = typeof retryAfterMs === "number" ? retryAfterMs : retryAfterMs?.retryAfterMs;
+    if (raw === undefined || !Number.isFinite(raw) || raw <= 0)
+        return 0;
+    const bounded = Math.min(WAVE_BACKPRESSURE_MAX_WAIT_MS_V1, Math.floor(raw));
+    if (remainingBudgetMs === undefined)
+        return bounded;
+    if (!Number.isFinite(remainingBudgetMs) || remainingBudgetMs <= 0)
+        return 0;
+    return Math.min(bounded, Math.floor(remainingBudgetMs));
+}
+/** Bounded QUEUE wait alias (lease-conflict path shares the same budget rule as rate-limit WAIT). */
+export function waveQueueWaitMs(retryAfterMs, remainingBudgetMs) {
+    return waveRateLimitWaitMs(retryAfterMs, remainingBudgetMs);
+}
+export async function withWaveBackpressureRetry(action, options = {}) {
+    const nowMs = options.nowMs ?? Date.now;
+    const sleepMs = options.sleepMs ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const startedAt = nowMs();
+    // Luna F1: never mint fresh `now+30s` when the caller has no deadline.
+    // Undefined timeout means no wait budget: single attempt, backpressure is
+    // terminal immediately (no implicit wait). Defined timeout bounds WAIT via
+    // min(bounded, remaining); exhaustion is terminal rethrow (fail-closed).
+    const deadlineAt = options.timeoutMs !== undefined ? startedAt + options.timeoutMs : undefined;
+    for (;;) {
+        const remaining = deadlineAt !== undefined ? deadlineAt - nowMs() : undefined;
+        try {
+            return await action(remaining);
+        }
+        catch (error) {
+            // QUEUE classifiers (narrow 429/rate-limit, never bare retry-after):
+            // - isWaveBackpressureError: wave gate (429/lease/takeover/ceiling)
+            // - isProviderCapacityError: durable capacity/lease shape (operationResources)
+            // - isProviderRateLimited: SDK-boundary 429 (narrow marker)
+            const waveQueueable = isWaveBackpressureError(error) || isProviderCapacityError(error) || isProviderRateLimited(error, nowMs);
+            if (!waveQueueable)
+                throw error;
+            // 429 path honors typed Retry-After (narrow marker guarantees real 429/rate-limit,
+            // never bare retry-after); lease-conflict path uses bounded queue WAIT.
+            // SDK 60s hints clamp into the wave 30s ceiling via waveRateLimitWaitMs.
+            const rateDetail = parseProviderRateLimitDetail(error, nowMs);
+            // No existing deadline: immediate terminal, never mint fresh wait.
+            const effectiveRemaining = deadlineAt !== undefined ? deadlineAt - nowMs() : 0;
+            let waitMs;
+            if (rateDetail) {
+                waitMs = waveRateLimitWaitMs(rateDetail.retryAfterMs, effectiveRemaining);
+            }
+            else if (isProviderLeaseConflictError(error)) {
+                waitMs = waveQueueWaitMs(250, effectiveRemaining);
+            }
+            else {
+                waitMs = waveQueueWaitMs(250, effectiveRemaining);
+            }
+            if (waitMs <= 0)
+                throw error;
+            options.onWait?.(waitMs, error);
+            await sleepMs(waitMs);
+        }
+    }
+}
+/**
+ * Intra-wave per-workspace write-lease admission (NOT shared enforcement).
+ *
+ * SCOPE HONESTY (Luna F2): this serializes concurrent writers *within one
+ * wave in one process* via the provided in-memory supervisor. A fresh
+ * `RuntimeSupervisorV1` per wave cannot see leases from other waves,
+ * operations, or processes — it is blind to cross-wave/operation contention
+ * by construction. Cross-wave/operation contention is enforced by the SHARED
+ * durable authority: the operation-wide capacity gate
+ * (`waitForProviderSessionCapacity` over `readManagedRuntimeSnapshot`, the
+ * same lease store `acquireProviderLease` persists to) plus
+ * `acquireWaveProviderSlotSharedOrQueue` below plus the real provider
+ * lifecycle (`runWithOperationProviderLease`). Never use this alone to claim
+ * shared enforcement.
+ *
+ * Isolated worktrees use distinct workspace keys (no contention, ACQUIRED);
+ * shared-workspace waves share one key (second writer QUEUES). On QUEUED, the
+ * bounded `providerLeaseQueueWaitMs` WAIT is honored against the caller's
+ * existing deadline (never extends caps; exhaustion → terminal false, FAIL).
+ */
+export async function acquireWaveProviderSlotOrQueue(supervisor, input, options = {}) {
+    const result = supervisor.tryAcquireProviderLease({
+        provider: input.provider,
+        projectId: input.projectId,
+        canonicalRoot: input.canonicalRoot,
+        workspaceId: input.workspaceId,
+        mode: input.mode ?? "write",
+        ownerId: input.ownerId
+    });
+    if (result.status === "ACQUIRED")
+        return { acquired: true, retryAfterMs: 0, queueDepth: 0 };
+    const queued = result;
+    const waitMs = providerLeaseQueueWaitMs(queued, options.remainingBudgetMs);
+    if (waitMs <= 0)
+        return { acquired: false, retryAfterMs: queued.retryAfterMs, queueDepth: queued.queueDepth };
+    const sleepMs = options.sleepMs ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    await sleepMs(waitMs);
+    // Single bounded WAIT then re-attempt once; exhaustion on second QUEUED is terminal.
+    const second = supervisor.tryAcquireProviderLease({
+        provider: input.provider,
+        projectId: input.projectId,
+        canonicalRoot: input.canonicalRoot,
+        workspaceId: input.workspaceId,
+        mode: input.mode ?? "write",
+        ownerId: input.ownerId
+    });
+    if (second.status === "ACQUIRED")
+        return { acquired: true, retryAfterMs: waitMs, queueDepth: queued.queueDepth };
+    return { acquired: false, retryAfterMs: second.retryAfterMs, queueDepth: second.queueDepth };
+}
+/**
+ * Shared durable per-workspace gate for wave dispatch (Luna F2+F3, fail-closed).
+ *
+ * MECHANISM: DETERMINISTIC atomic acquire-or-wait-or-fail via the REAL
+ * `acquireProviderLease` store path (`acquireDurableWaveSlotOrQueue` over the
+ * file-locked managed-runtime snapshot, same `findConflictingProviderLeases`
+ * predicate as `tryAcquireProviderLease`). Check-then-proceed is deleted: the
+ * previous read-only `checkDurableWaveSlotConflict` + proceed-without-acquire
+ * (TOCTOU, two racers both proceeding) cannot be made atomic and is removed
+ * (no dead code). ATOMICITY: in-memory `tryAcquireProviderLease` is atomic
+ * within one process only; cross-wave/operation/process atomicity comes from
+ * the snapshot `.lock` transact in `operationResources.ts` (reload→check→write
+ * under one lock, never both proceed).
+ *
+ * Bounded WAIT (`min(retryAfter, remainingBudget)`) against the caller's
+ * existing deadline (never mints fresh; undefined/0 budget means single
+ * immediate attempt only, exhaustion → terminal false, FAIL). Unreadable
+ * durability BLOCKS (acquired false, retryAfter 0, no wait). Deterministic
+ * clocks via `nowMs`/`sleepMs`. Returns durable `leaseId` on ACQUIRED for
+ * explicit `releaseDurableWaveSlot` (callers release in finally, best-effort).
+ */
+export async function acquireWaveProviderSlotSharedOrQueue(root, input, options = {}) {
+    const result = await acquireDurableWaveSlotOrQueue(root, input, {
+        ...(options.remainingBudgetMs !== undefined ? { remainingBudgetMs: options.remainingBudgetMs } : {}),
+        ...(options.sleepMs ? { sleepMs: options.sleepMs } : {}),
+        ...(options.nowMs ? { nowMs: options.nowMs } : {}),
+    });
+    if (result.acquired) {
+        return { acquired: true, retryAfterMs: 0, queueDepth: 0, scope: "shared-durable", leaseId: result.leaseId };
+    }
+    return { acquired: false, retryAfterMs: result.retryAfterMs, queueDepth: result.queueDepth, scope: "shared-durable" };
 }
 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) {