@claudexor/orchestrator 5.0.1 → 5.1.0

package/dist/orchestrator.js

@@ -7,7 +7,7 @@ import { openRunScopeCustody, scopedRouteContext, scopedSpecEnv, } from "./runSc
 import { delegationBeltFor } from "./delegationBelt.js";
 import { routePromptCacheTtl, withReviewerPromptCacheTtl } from "./prompt-cache-routing.js";
 import { bindProcessingAdmission, processingAttemptCostEvidence, processingAdmissionForLease, updateProcessingStreamHold, } from "./processing-dispatch.js";
-import { cancelledCandidatesResult, emptyCandidateResult, failedCandidatesResult, failAfterCandidates, } from "./candidateTerminals.js";
+import { cancelledCandidatesResult, emptyCandidateResult, erroredWinnerFailure, failedCandidatesResult, failAfterCandidates, } from "./candidateTerminals.js";
 import { deepScanFailureResult, readOnlyChainFailureResult, } from "./readonlyTerminals.js";
 import { effectiveAuthPreference, observeNativeSessionEvent, resumeSessionForProfile, } from "./credential-profiles.js";
 import { AdmissionProfileProbes, OrchestratorCredentials, reviewerProfileResolver, } from "./orchestrator-credentials.js";
@@ -15,14 +15,14 @@ import { continuityWorkspace, carryingAttempts, resumableOf, resumableTerminal,
 import { openContinuity } from "./continue-from.js";
 import { accountPoolRows } from "./account-pool.js";
 import { PoolAttemptEvidence, terminalPoolAttempts, withPoolAttempts, } from "./pool-attempt-evidence.js";
-import { writeRunTelemetryArtifact } from "./runTelemetryWriter.js";
+import { pickTelemetry, writeRunTelemetryArtifact, } from "./runTelemetryWriter.js";
 import { buildFileBackedSynthesisInput, materializeWinnerOutputs, stageFileBackedContext, writeCandidateAttemptArtifacts, } from "./candidateOutputs.js";
 import { processAttemptUsage } from "./attemptUsage.js";
-import { captureDirectoryCandidate, directoryHasOutput, directoryCandidateStable, observeDirectoryPaths, publishDirectoryCandidate, } from "./directoryCandidate.js";
+import { captureDirectoryCandidate, directoryPreparationNotice, directoryHasOutput, directoryCandidateStable, observeDirectoryPaths, publishDirectoryCandidate, } from "./directoryCandidate.js";
 import { appliedAttemptFacts, assertDelegatedEvidence, isMutatingAccess, outerBoundaryNotice, scopedHarnessHome, selectLaneHome, followSpecHome, } from "./delegatedHome.js";
 import * as AC from "./attemptUsageCost.js";
 import * as custody from "./continuation-custody.js";
-import { candidateRoster, candidateStatuses, convergenceOutcomeFacts, isWorkingCandidate, partitionCandidates, toCandidateEvidence, } from "./candidateEvidence.js";
+import { capturedNoGitChangeValue, candidateCaptureRefusals, candidateCompletion, candidateRoster, candidateStatuses, convergenceOutcomeFacts, declaredFailureSpeaks, interruptionOf, isWorkingCandidate, needsPostTurnFence, partitionCandidates, toCandidateEvidence, } from "./candidateEvidence.js";
 import { capabilityIntents } from "@claudexor/gateway";
 import { reviewCandidateRuns, unreviewedCandidateEvidence, evaluateUnreviewedConvergence, } from "./candidateReview.js";
 import { join } from "node:path";
@@ -33,7 +33,7 @@ import { globalConfigDir } from "@claudexor/config";
 import { executionRunConfig } from "./run-defaults.js";
 import { preflightOneShot } from "./one-shot-preflight.js";
 import { prepareRoutedProcessing, processingCostEvidence, prepareReviewerProcessing, } from "./processing-routing.js";
-import { acceptedTryOutput, AccessProfileIncompatibleError, AnswerAssembly, appendHarnessEvent, AuxiliaryWritableRootsUnsupportedError, CLAUDEXOR_BROWSER_ARTIFACT_SUBDIR, countsAsAgentProgress, HarnessUnavailableError, withInactivityWatchdog, } from "@claudexor/core";
+import { acceptedTryOutput, AccessProfileIncompatibleError, AnswerAssembly, appendHarnessEvent, AuxiliaryWritableRootsUnsupportedError, CLAUDEXOR_BROWSER_ARTIFACT_SUBDIR, countsAsAgentProgress, HarnessUnavailableError, ModelSelectionRequiredError, missingRouteModel, withInactivityWatchdog, } from "@claudexor/core";
 import { assertRouteModelsAllowed, isDispatchRefusal, runModelGovernedRoute, } from "./modelGovernance.js";
 import { authModeForCredentialRoute, authModeForPreference, authRouteEvidenceFor, } from "./auth-route-classification.js";
 import { isFullAccess, RequestRequirementsResolver } from "./requestRequirements.js";
@@ -50,21 +50,21 @@ import { cancelledResult, declaredFailure, failTerminally, guardAnnouncedRun, wr
 import { budgetFailureRecord, classifyBudgetFailure } from "./budgetFailure.js";
 import { finalizeStructuredOutput } from "./structuredOutput.js";
 import { prepareRunAdmission } from "./runAdmission.js";
-import { dropDeltaPastBudget, emitPlanProgress, emitTransientExhausted, observeReadonlySpend, recordAdapterThrow, } from "./laneStreamEvents.js";
+import { dropDeltaPastBudget, emitPlanProgress, emitTransientExhausted, observeUsageSpend, recordAdapterThrow, } from "./laneStreamEvents.js";
 import { promptWithEngineConstraints, sleep, harnessEventPayload, safeErrorMessage, renderSummary, observeBudgetSignals, rotateOnStall, recordCleanAttemptMetrics, envInheritance, transientRetryPolicy, reviewerTimeoutMs, harnessInactivityTimeoutMs, observeAuthSwitch, emitPoolDegraded, deliveryRefusalFailure, winnerNeedsHuman, writeRaceDeliveryDecision, } from "./runSupport.js";
 import { candidateStatusInRouteContext, resolveReadOnlyRouteContext, } from "./routeContext.js";
 import { resolveAutoReviewerPanel, resolveExplicitReviewerPanel } from "./reviewerPanel.js";
 import { ensureClaudeBridgeForRun, ensureWriteModeGitBoundary } from "./git-precondition.js";
-import { buildContinuation, } from "./continuity.js";
-import { activePlanPointer, resolveContinuitySummary, workspaceAnchor, } from "./continuity-facts.js";
+import { buildContinuation } from "./continuity.js";
+import { resolveContinuitySummary, threadContinuityRequest } from "./continuity-facts.js";
 import { runDiffReview } from "./diffReview.js";
 import { rawScoutBundle, resolveDeepScanSynthesis, } from "./deepScanReducer.js";
 import { createAttemptTelemetry, observeAttemptTelemetry, setAttemptOutcome, telemetrySummary, toolWarnings, unrecoveredToolErrors, webUnsatisfied, } from "./attemptTelemetry.js";
 import { beginNativeRetry } from "./native-retry-telemetry.js";
 import * as delegateFailure from "./delegationFailure.js";
 import * as secretDiff from "./secretDiff.js";
-import { finalizeAttempt, unrecoveredToolErrorFailure, webEvidenceFailure, } from "./attemptFinalize.js";
-import { resolveWorkReportEnvelope, unwrapWorkReportEnvelope, } from "./workReportEnvelope.js";
+import { attemptInterruption, finalizeAttempt, interruptionDetail, unrecoveredToolErrorFailure, webEvidenceFailure, } from "./attemptFinalize.js";
+import { resolveWorkReportEnvelope, unwrapAttemptAnswer, } from "./workReportEnvelope.js";
 import { buildContinuationPacket, decideContinuation, synthesizeContinuationRequest, } from "./continuation.js";
 import { interactionChannelFor } from "./interaction.js";
 import { liveAttempt } from "./live-input.js";
@@ -74,15 +74,17 @@ import { recordProcessingIntent } from "./retry-processing-intent.js";
 import { prepareReviewEvidenceDir, recordReviewEvidenceCleanup } from "./reviewEvidence.js";
 import { savedForSynthesis } from "./savedCandidate.js";
 import { ArtifactStore } from "@claudexor/artifact-store";
-import { buildContextPack, rawContextSizer, writeEvidencePacket } from "@claudexor/context";
-import { WorkspaceManager, captureRawPatchEnvelope, consumeRawPatchEnvelope, snapshotTree, } from "@claudexor/workspace";
+import { buildContextPack, writeEvidencePacket } from "@claudexor/context";
+import { RawPatchLane, correctableRefusal, endsConvergence } from "./rawPatchLane.js";
+import { runRuntimeRoot } from "./run-runtime-root.js";
+import { WorkspaceManager, snapshotTree, } from "@claudexor/workspace";
 import { blockedDecisionOverride, finalVerifyBlocks, verifyAndDeliverFiles, verifyAndDeliver, } from "@claudexor/delivery";
 import { HarnessGateway } from "@claudexor/gateway";
-import { ReadinessLedger, evaluateConvergence, failureSignature, gatesPassed, reviewCandidate, runGates, } from "@claudexor/review";
+import { ReadinessLedger, evaluateConvergence, failureSignature, gatesPassed, requireReadingReviewers, reviewCandidate, runGates, } from "@claudexor/review";
 import { arbitrate } from "@claudexor/arbitration";
 import { buildSynthesisPlan, decideSynthesis } from "@claudexor/synthesis";
 import { billingKnowledgeForAuthRoute, attemptUsageCostSettlement, BudgetLedger, isBudgetTerminal, explainRanking, loadHarnessMetrics, promptFingerprint, rankHarnesses, } from "@claudexor/budget";
-import { readTextSafe, hashJson, newId, noProjectRepoRoot, redactSecrets, safeInvoke, userConfigDir, } from "@claudexor/util";
+import { hashJson, newId, noProjectRepoRoot, redactSecrets, safeInvoke, userConfigDir, } from "@claudexor/util";
 const LABELS = "ABCDEFGHIJ".split("");
 const NO_PROJECT_ROOT = noProjectRepoRoot();
 export class Orchestrator {
@@ -191,7 +193,7 @@ export class Orchestrator {
     }
     async resolveReviewers(run, onIgnoredSetting) {
         if (this.deps.reviewers)
-            return this.deps.reviewers;
+            return requireReadingReviewers(this.deps.reviewers);
         const { repoRoot: cwd, authPreference, signal } = run;
         const panelDeps = {
             cwd,
@@ -269,7 +271,7 @@ export class Orchestrator {
         if (input.mode === "ask" && input.contextMode === "off" && input.repoRoot === NO_PROJECT_ROOT) {
             return new ArtifactStore(input.repoRoot, { claudexorDir: userConfigDir() });
         }
-        return new ArtifactStore(input.repoRoot);
+        return new ArtifactStore(input.repoRoot, { claudexorDir: runRuntimeRoot(input) });
     }
     /** The producing intent a candidate plays (create flag switches it; not hardcoded to implement). */
     candidateIntent(input) {
@@ -425,6 +427,8 @@ export class Orchestrator {
                     throw new AuxiliaryWritableRootsUnsupportedError(detail);
                 if (stage === "access")
                     throw new AccessProfileIncompatibleError(detail);
+                if (stage === "model")
+                    throw new ModelSelectionRequiredError(detail);
                 throw new HarnessUnavailableError(detail);
             }
             dropped.push(detail);
@@ -587,6 +591,13 @@ export class Orchestrator {
                 dropLane(id, "capability", readRefusal);
                 continue;
             }
+            const modelRefusal = status.enabledIntents.includes(intent)
+                ? missingRouteModel(adapter, input.models?.[id] ?? cfgEntry?.default_model)
+                : null;
+            if (modelRefusal) {
+                dropLane(id, "model", modelRefusal);
+                continue;
+            }
             const reason = status.reasons.length > 0 ? `: ${status.reasons.join("; ")}` : "";
             if (status.enabledIntents.includes(intent) && accessSupported) {
                 pool.push({
@@ -594,6 +605,7 @@ export class Orchestrator {
                     adapterAccess: requiredAccess,
                     auxiliaryWritableRoots,
                     webSupport,
+                    accessControl: manifest.capability_profile.access_control,
                     providerFamily: manifest.provider_family,
                     supportsMaxTurns: manifest.capabilities.max_turns,
                     supportsToolLists: manifest.capabilities.tool_lists,
@@ -1136,33 +1148,7 @@ export class Orchestrator {
             return null;
         try {
             const profileId = resolvedProfileId ?? ctx.profileId ?? null;
-            const lane = { harness: harnessId, profileId };
-            const checkpoint = ctx.laneCheckpoints.find((c) => c.harness === harnessId && (c.profileId ?? null) === profileId);
-            const headTurnId = ctx.priorTurns.length
-                ? ctx.priorTurns[ctx.priorTurns.length - 1].id
-                : null;
-            const priorHeadOwner = headTurnId
-                ? ctx.laneCheckpoints.find((c) => c.turnId === headTurnId)
-                : undefined;
-            const priorHeadLane = priorHeadOwner
-                ? { harness: priorHeadOwner.harness, profileId: priorHeadOwner.profileId ?? null }
-                : null;
-            const priorTurns = ctx.priorTurns.map((t) => ({
-                id: t.id,
-                prompt: t.prompt,
-                outputText: t.runId
-                    ? (readTextSafe(join(store.runPaths(t.runId).finalDir, "answer.md")) ?? "")
-                    : "",
-            }));
-            const req = {
-                lane,
-                priorTurns,
-                laneCheckpointTurnId: checkpoint?.turnId ?? null,
-                nativeResumeAvailable,
-                priorHeadLane,
-                activePlan: activePlanPointer(ctx.priorTurns, store),
-                anchor: await workspaceAnchor(repoRoot),
-            };
+            const req = await threadContinuityRequest(ctx, { harness: harnessId, profileId }, nativeResumeAvailable, store, repoRoot);
             // V9c: when the packet would collapse an older prefix, replace the
             // mechanical one-liners with a cached (or freshly summarized) prose
             // summary. Same credential route + scoped lane home a real read-only
@@ -1174,6 +1160,7 @@ export class Orchestrator {
                 projectRoot: runInput.repoRoot,
                 cwd: repoRoot,
                 adapter: this.deps.registry.get(harnessId),
+                model: this.deps.registry.get(harnessId)?.modelRequirement && runInput.models?.[harnessId],
                 credentialProfile: sessionFields.credential_profile,
                 authPreference: sessionFields.auth_preference ?? "auto",
                 laneEnv: scopedSpecEnv(runInput.runScopeMarker, this.laneHomeEnvFor(runInput, harnessId, profileId) ?? {}) ?? {},
@@ -1262,11 +1249,12 @@ export class Orchestrator {
         const inPlaceEnvelope = envelope.worktree_path === envelope.repo_root;
         const directory = envelope.workspace_kind === "directory";
         let directoryCapture = {};
-        const captureDirectory = async () => (directoryCapture = await captureDirectoryCandidate({
+        const captureDirectory = async (final = false) => (directoryCapture = await captureDirectoryCandidate({
             manager: wsm,
             envelope,
             artifactRoot: join(paths.attemptsDir, attemptId),
             observedPaths: [...observedPaths],
+            ...(final ? { holder: { runId: paths.runId, runDir: paths.root } } : {}),
         }));
         const sessionFields = runInput
             ? await this.sessionSpecFields(runInput, adapter.id, knobs.model, log, routed.authRouteEstimate, routed.quotaAdmission)
@@ -1304,6 +1292,7 @@ export class Orchestrator {
             [
                 prompt,
                 outerBoundaryNotice(harnessHome, routed.auxiliaryWritableRoots),
+                await directoryPreparationNotice(envelope, attemptId, log),
                 laneContinuity?.pointerLine,
                 continuationPointer,
             ]
@@ -1340,13 +1329,8 @@ export class Orchestrator {
         // #147: bound to the project's context config; each try's dispatch sizes its own
         // packet for THIS request from the catalog read the gate makes for that try.
         const { context } = this.projectConfig(contract.repo.root);
-        const sizeRawContext = rawContextSizer(routed.implementationTransport, envelope, context);
-        let rawContextPacket = null;
-        const dispatch = sizeRawContext
-            ? {
-                rawContext: async (capacity) => (rawContextPacket = await sizeRawContext(capacity)),
-            }
-            : {};
+        const rawLane = new RawPatchLane(routed.implementationTransport, envelope, context);
+        const { dispatch } = rawLane;
         bindProcessingAdmission(spec, ledger, processingLease.lease, adapter.id, attemptId, processingLease.onDenied, processingAdmission);
         // Profile-less processing keeps its existing route estimate. Named rows
         // receive their own verification at the shared physical-dispatch gate.
@@ -1431,8 +1415,7 @@ export class Orchestrator {
                 const refusal = continuity.beginTry(runSpec, nativeTry, attemptAbort);
                 const transientStart = telemetry.transientFailures.length;
                 const rateLimitStart = telemetry.rateLimits.length;
-                let rawPatch = null;
-                rawContextPacket = null; // a patch binds only the packet its own try sent
+                rawLane.beginTry();
                 try {
                     const watched = withInactivityWatchdog(runModelGovernedRoute(routed, runSpec, dispatch), {
                         timeoutMs: inactivityMs,
@@ -1452,7 +1435,7 @@ export class Orchestrator {
                         // After Stop: stored evidence only, but file paths are still collected for the capture.
                         const stopped = signal?.aborted === true;
                         if (!stopped)
-                            rawPatch = captureRawPatchEnvelope(sizeRawContext !== null, rawPatch, ev);
+                            rawLane.observe(ev);
                         if (ev.type === "patch_produced")
                             continue;
                         if (directory)
@@ -1523,14 +1506,7 @@ export class Orchestrator {
                         observeBudgetSignals(ledger, log, adapter.id, attemptId, ev, budgetSignalState);
                         this.deps.quotaEventSink?.(adapter.id, ev);
                     }
-                    if (sizeRawContext && !harnessErrored)
-                        await consumeRawPatchEnvelope({
-                            repoRoot: envelope.repo_root,
-                            worktreePath: envelope.worktree_path,
-                            baseCommitSha: envelope.base_sha ?? "HEAD",
-                            context: rawContextPacket,
-                            envelope: rawPatch,
-                        });
+                    await rawLane.settle(harnessErrored);
                 }
                 catch (err) {
                     // A throwing adapter must not lose the cost already streamed: record the
@@ -1543,14 +1519,12 @@ export class Orchestrator {
                         processingRefusal = err;
                         break;
                     }
-                    if (!recordAdapterThrow(telemetry, err))
+                    if (!rawLane.refused(err) && !recordAdapterThrow(telemetry, err))
                         break;
                 }
                 finally {
                     clearFileBackedContext();
                 }
-                if (telemetry.requestRefusal)
-                    break;
                 const newTransients = telemetry.transientFailures.slice(transientStart);
                 // #31: the centralized retry gate reads the classified `retryable` verdict.
                 const sawRetryable = newTransients.some((f) => f.retryable);
@@ -1580,6 +1554,8 @@ export class Orchestrator {
                 this.credentials.noteTryServed(refusal, telemetry.outputMarkers, delivered);
                 const verdict = await continuity.afterTry({
                     ...tryFacts,
+                    // A refused patch is its account row above, but no retry or rotation repairs it.
+                    requestRefused: tryFacts.requestRefused || rawLane.refusal !== null,
                     // A cancel or deadline that landed during capture still stops the
                     // attempt; the try's own facts above stay its evidence.
                     stopped: signal?.aborted === true,
@@ -1619,6 +1595,7 @@ export class Orchestrator {
         if (harnessErrored &&
             !poolExhausted &&
             !processingRefusal &&
+            !rawLane.refusal &&
             !telemetry.requestRefusal &&
             !signal?.aborted) {
             emitTransientExhausted((t, p) => log?.emit(t, p), adapter.id, attemptId, telemetry, retryPolicy.maxRetries);
@@ -1629,10 +1606,10 @@ export class Orchestrator {
         }
         // D-16: answer.md persists only the deliverable. A3: an errored attempt
         // with no typed final contributes no answer material (acceptedTryOutput).
-        const unwrapped = unwrapWorkReportEnvelope(acceptedTryOutput(answer, harnessErrored), workReportMode, { sideToolReport: telemetry.sideToolWorkReport ?? undefined });
+        const unwrapped = unwrapAttemptAnswer(acceptedTryOutput(answer, harnessErrored), harnessErrored && !answer.hasFinal(), workReportMode, { sideToolReport: telemetry.sideToolWorkReport ?? undefined });
         const answerText = unwrapped.deliverable.trim().length > 0 ? unwrapped.deliverable : undefined;
         if (directory)
-            await captureDirectory();
+            await captureDirectory(true);
         const captured = directory
             ? { diff: "", captureRefusal: directoryCapture.refusal }
             : await secretDiff.captureCandidateWorkspace({
@@ -1695,7 +1672,7 @@ export class Orchestrator {
             workReportSource: unwrapped.source,
             workReportViolation: unwrapped.contractViolation,
             workReportUnverified: unwrapped.unverified ?? null,
-            contextTerminalExhausted: telemetry.contextExhausted,
+            interruption: attemptInterruption(telemetry),
         });
         harnessErrored = finalized.harnessErrored;
         if (finalized.outcomeClass === "contract_failure" && unwrapped.contractViolation)
@@ -1723,6 +1700,7 @@ export class Orchestrator {
         const attemptDir = join(paths.attemptsDir, attemptId);
         recordCleanAttemptMetrics(globalConfigDir(), adapter.id, {
             costUsd: cost,
+            usageCost: telemetry.usageCost,
             streamMs: attemptStreamEndedMs - attemptStartedMs,
             errored,
             aborted: signal?.aborted === true,
@@ -1795,8 +1773,10 @@ export class Orchestrator {
             // A5: the typed refusal survives NORMAL attempt finalization (no throw).
             ...(telemetry.requestRefusal
                 ? { declaredFailure: requestRefusalFailure(telemetry.requestRefusal) }
-                : poolExhausted || processingRefusal
-                    ? { declaredFailure: declaredFailure(processingRefusal ?? poolExhausted) }
+                : poolExhausted || processingRefusal || rawLane.refusal
+                    ? {
+                        declaredFailure: declaredFailure(processingRefusal ?? rawLane.refusal ?? poolExhausted),
+                    }
                     : {}),
             outcomeClass: finalized.outcomeClass,
             applied,
@@ -1876,7 +1856,7 @@ export class Orchestrator {
         // this SINGLE root.
         const execRoot = this.execRootOf(input);
         const projectRoot = input.repoRoot;
-        const wsm = new WorkspaceManager(execRoot, { projectRoot });
+        const wsm = new WorkspaceManager(execRoot, { projectRoot, runtimeRoot: runRuntimeRoot(input) });
         const anchors = secretDiff.revertAnchors(execRoot, projectRoot);
         store.writeYaml(join(paths.contextDir, "task.yaml"), contract);
         log.emit("task.contract.created", { task_contract_hash: hashJson(contract) });
@@ -2108,17 +2088,7 @@ export class Orchestrator {
                 }, input, requestedSingleCandidate, // W-C4 deltas: single-candidate chat lane only (racing = noise x N)
                 undefined, undefined, harnessHome, undefined, tried);
                 ledger.settle(slot.lease.lease_id, attemptUsageCostSettlement(run.cost, run.costEstimated, run.attemptId, run.harnessId, run.telemetry.authMode, run.telemetry.usageCost));
-                log.emit("harness.completed", {
-                    harness_id: adapter.id,
-                    attempt_id: slot.attemptId,
-                    // QA-027: never claim `success` over an attempt the operator/deadline
-                    // cut short. An abort makes the run non-successful; the top-level
-                    // status axis must say `cancelled` (the nested outcome axis already
-                    // rides in telemetrySummary), not launder a torn-off stream as clean.
-                    status: input.signal?.aborted ? "cancelled" : run.errored ? "failed" : "success",
-                    cost_usd: run.cost,
-                    ...telemetrySummary(run.telemetry),
-                });
+                log.emit("harness.completed", candidateCompletion(run, input.signal));
                 // D-16d one-shot continuation for an ENVELOPED candidate (parity with the
                 // read-only loop, which had the ONLY continuation wiring). An eligible
                 // terminal context exhaustion (repeated_refill, no completed report) gets
@@ -2187,21 +2157,18 @@ export class Orchestrator {
                                     return true;
                                 }, input, requestedSingleCandidate, undefined, packet.pointerLine ?? undefined, harnessHome, undefined, contTried);
                                 ledger.settle(contLeaseId, attemptUsageCostSettlement(contRun.cost, contRun.costEstimated, contRun.attemptId, contRun.harnessId, contRun.telemetry.authMode, contRun.telemetry.usageCost));
-                                log.emit("harness.completed", {
-                                    harness_id: adapter.id,
-                                    attempt_id: contAttemptId,
-                                    status: input.signal?.aborted
-                                        ? "cancelled"
-                                        : contRun.errored
-                                            ? "failed"
-                                            : "success",
-                                    cost_usd: contRun.cost,
-                                    ...telemetrySummary(contRun.telemetry),
-                                });
+                                log.emit("harness.completed", candidateCompletion(contRun, input.signal));
                                 // Supersede the exhausted candidate ONLY after the continuation
                                 // actually completes cleanly (never over a torn-off/aborted stream).
                                 if (!contRun.errored && !input.signal?.aborted)
                                     effectiveRun = contRun;
+                                // A refused capture is errored: the original keeps leading, and
+                                // the copy they share stays kept under the continuation's receipt.
+                                if (contRun.captureRefusal)
+                                    effectiveRun.continuationRefusal = {
+                                        attemptId: contRun.attemptId,
+                                        refusal: contRun.captureRefusal,
+                                    };
                             }
                             catch (err) {
                                 ledger.settle(contLeaseId, AC.attemptFailureCost(err, "continuation-error", 0).settlement);
@@ -2263,7 +2230,7 @@ export class Orchestrator {
                     // Keep a TYPED pre-spawn refusal (spent quota window + its reset)
                     // alive past this catch; `message` alone would force the terminal to
                     // read prose back out.
-                    ...(declared.code ? { declaredFailure: declared } : {}),
+                    ...(declared.code || declared.quotaRefusal ? { declaredFailure: declared } : {}),
                     applied: appliedAttemptFacts(harnessHome, slot.routed.adapterAccess, this.credentials.effectiveProfileId(input, adapter.id)),
                 };
             }
@@ -2311,18 +2278,17 @@ export class Orchestrator {
                 : undefined,
             signal: input.signal,
         });
-        // Revert divergence fence for the single-candidate in-place path: the
-        // candidate mutated the LIVE tree during execution above, so the post-turn
-        // snapshot must be taken NOW — before review/synthesis/arbitration, which can
-        // run for a long time during which the user may edit files. Snapshotting after
-        // arbitration (as the race-adoption path does) would fold those user edits
-        // into the revert target and let a later revert clobber them.
+        // Revert divergence fence for the single-candidate in-place path.
+        // The candidate mutated the LIVE tree above. Snapshot NOW, before slow
+        // review/synthesis/arbitration, or later user edits enter the revert target
+        // and a revert can clobber them. The race-adoption path snapshots later.
+        // No change, no fence.
         let earlyPostTurnSha = null;
         if (mutatingRun &&
             input.workspaceKind !== "directory" &&
             input.inPlace &&
             requestedSingleCandidate &&
-            runs.every((run) => !run.captureRefusal)) {
+            needsPostTurnFence(runs)) {
             try {
                 earlyPostTurnSha = await snapshotTree(execRoot);
             }
@@ -2334,7 +2300,7 @@ export class Orchestrator {
             await disposeReviewEnvelopes();
             return cancelledRaceResult();
         }
-        const failedDelegation = delegateFailure.dominantRaceCandidateFailure(runs);
+        const failedDelegation = delegateFailure.dominantRaceCandidateFailure(runs, input);
         if (failedDelegation) {
             await disposeReviewEnvelopes();
             const failedOutput = {
@@ -2360,7 +2326,7 @@ export class Orchestrator {
                     budgetDenial,
                     ...(mutatingRun ? { liveCapture: failedOutput } : {}),
                 });
-            const failure = delegateFailure.candidateFailureTerminal(failedDelegation, "race");
+            const failure = delegateFailure.candidateFailureTerminal(failedDelegation, "race", runs);
             if (mutatingRun)
                 await delegateFailure.persistFailedCandidateOutput(failedOutput);
             raceTerminal.writeTelemetry();
@@ -2768,6 +2734,7 @@ export class Orchestrator {
                 if (inPlaceWinner && requestedSingleCandidate && adopted === true) {
                     revertAnchorId = await anchors.turn(preTurnSha, postTurnSha);
                 }
+                const capturedNoGitChange = capturedNoGitChangeValue(winnerRun);
                 store.writeYaml(join(paths.finalDir, "work_product.yaml"), {
                     id: newId("wp"),
                     kind: input.create === true ? "new_repo" : "patch",
@@ -2787,6 +2754,7 @@ export class Orchestrator {
                         budget_stopped: budgetStopped,
                         ...{ patch_sha256: patchSha256, ...savedPatch.meta },
                         result_kind: resultKind,
+                        ...(capturedNoGitChange !== null ? { capturedNoGitChange } : {}),
                         diffstat: {
                             files: wstats.paths.length,
                             additions: wstats.additions,
@@ -2802,7 +2770,7 @@ export class Orchestrator {
                     },
                 });
             }
-            store.writeText(join(paths.finalDir, "summary.md"), withPoolAttempts(renderSummary(runId, mode, { ...result.decision, facts }, evidences, synth.reason, actualReviewVerified, secretDiff.resultSummaryLines(winnerRun)), racePool()));
+            store.writeText(join(paths.finalDir, "summary.md"), withPoolAttempts(renderSummary(runId, mode, { ...result.decision, facts }, evidences, synth.reason, actualReviewVerified, delegateFailure.raceSummaryDisclosure(winnerRun, runs)), racePool()));
             // summary.md is a DIAGNOSTIC artifact only (V8/PLAN addendum 2): it no
             // longer carries primary-output authority. A clean applyable success or a
             // winner answer still marks it ready for legacy INV-116 ordering; any
@@ -2829,12 +2797,15 @@ export class Orchestrator {
         const needsDecisionTerminal = facts.review === "blocked" || facts.checks === "failed";
         const isFailureTerminal = facts.lifecycle !== "succeeded" || needsDecisionTerminal;
         const pool = racePool();
+        // Beside whichever failure record leads, a source another attempt kept stays named.
+        const keptSources = candidateCaptureRefusals(runs).flatMap(secretDiff.captureInspectionActions);
         if (deliveryFailureReason && !finalVerifyFailed) {
             const refused = deliveryRefusalFailure(deliveryFailureReason, paths.root);
             writeFailure(store, paths, {
                 ...refused,
                 safeMessage: withPoolAttempts(refused.safeMessage, pool),
                 poolAttempts: pool,
+                nextActions: [...refused.nextActions, ...keptSources],
             });
         }
         else if (finalVerifyFailed) {
@@ -2848,15 +2819,18 @@ export class Orchestrator {
                     : `final verify failed: ${finalVerify?.reason ?? (finalVerify?.gates_passed === false ? "deterministic gates failed on the fresh verify tree" : "unknown")}`, pool),
                 poolAttempts: pool,
                 runDir: paths.root,
-                nextActions: finalVerify?.applied_cleanly === null
-                    ? [
-                        "Inspect arbitration/decision.yaml (final_verify) for the verifier error",
-                        "Fix the verify infrastructure (git worktree/tmp) and re-run, or accept_risk to override",
-                    ]
-                    : [
-                        "Inspect arbitration/decision.yaml (final_verify)",
-                        "Re-run after fixing the base conflict or the failing gates",
-                    ],
+                nextActions: [
+                    ...(finalVerify?.applied_cleanly === null
+                        ? [
+                            "Inspect arbitration/decision.yaml (final_verify) for the verifier error",
+                            "Fix the verify infrastructure (git worktree/tmp) and re-run, or accept_risk to override",
+                        ]
+                        : [
+                            "Inspect arbitration/decision.yaml (final_verify)",
+                            "Re-run after fixing the base conflict or the failing gates",
+                        ]),
+                    ...keptSources,
+                ],
             });
         }
         else if (isFailureTerminal) {
@@ -2888,19 +2862,23 @@ export class Orchestrator {
                     ? `attempts/${winnerRun.attemptId}/attempt.yaml`
                     : undefined,
                 runDir: paths.root,
-                nextActions: decisionBlock
-                    ? [
-                        "Review the blocking findings on the run's turn",
-                        "Accept the risk to apply this exact patch, or discard the change",
-                        ...(facts.checks === "failed"
-                            ? ["Configure/approve the deterministic test command, then re-run"]
-                            : []),
-                    ]
-                    : [
-                        "Open diagnostics",
-                        "Inspect candidate artifacts",
-                        "Retry with a narrower prompt or different harness pool",
-                    ],
+                nextActions: [
+                    ...(decisionBlock
+                        ? [
+                            "Review the blocking findings on the run's turn",
+                            "Accept the risk to apply this exact patch, or discard the change",
+                            ...(facts.checks === "failed"
+                                ? ["Configure/approve the deterministic test command, then re-run"]
+                                : []),
+                        ]
+                        : [
+                            "Open diagnostics",
+                            "Inspect candidate artifacts",
+                            "Retry with a narrower prompt or different harness pool",
+                        ]),
+                    ...keptSources,
+                ],
+                ...(decisionBlock ? {} : erroredWinnerFailure(winnerRun, keptSources)),
             });
             if (!winnerRun) {
                 store.writeText(join(paths.finalDir, "summary.md"), `# Run ${runId} (${mode})\n\n- Lifecycle: ${facts.lifecycle}${facts.reason ? ` (${facts.reason})` : ""}\n- Phase: arbitration\n\n${withPoolAttempts(result.decision.why_winner, pool)}\n`);
@@ -3056,7 +3034,10 @@ export class Orchestrator {
         // local `execRoot`; this path previously ensured the boundary on repoRoot,
         // which for an isolated thread is the project, not the mutated worktree.
         const execRoot = this.execRootOf(input);
-        const wsm = new WorkspaceManager(execRoot, { projectRoot: input.repoRoot });
+        const wsm = new WorkspaceManager(execRoot, {
+            projectRoot: input.repoRoot,
+            runtimeRoot: runRuntimeRoot(input),
+        });
         const anchors = secretDiff.revertAnchors(execRoot, input.repoRoot);
         const readiness = new ReadinessLedger();
         store.writeYaml(join(paths.contextDir, "task.yaml"), contract);
@@ -3172,7 +3153,7 @@ export class Orchestrator {
         let converged = false;
         let exhausted = false;
         let processingBudgetDenial = null;
-        let interrupted = false; // D-16 r8: terminalizes the run interrupted
+        let interrupted = null; // D-16 r8, #299
         let lastFindings = [];
         let lastRun = null;
         const convergenceRuns = [];
@@ -3323,18 +3304,17 @@ export class Orchestrator {
                         costEstimated: failureCost.estimated,
                         errors: [message],
                         poolAttempts: tried.snapshot(),
-                        ...(declared.code ? { declaredFailure: declared } : {}),
+                        ...(declared.code || declared.quotaRefusal ? { declaredFailure: declared } : {}),
                         telemetry: createAttemptTelemetry(knobs.webPolicy, contract.external_context.web_required, effectiveWeb, [routed.browserRequirement, routed.denyRequirement, routed.delegationRequirement], knobs.model),
                     };
                     if (envelope.workspace_kind === "directory") {
-                        const captured = await captureDirectoryCandidate({
+                        ({ files: run.files, refusal: run.captureRefusal } = await captureDirectoryCandidate({
                             manager: wsm,
                             envelope,
                             artifactRoot: join(paths.attemptsDir, attemptId),
                             observedPaths: [...observedPaths],
-                        });
-                        run.files = captured.files;
-                        run.captureRefusal = captured.refusal;
+                            holder: { runId: paths.runId, runDir: paths.root },
+                        }));
                     }
                 }
                 lastRun = run;
@@ -3342,12 +3322,12 @@ export class Orchestrator {
                 // Fail-closed twin of the candidate lane's gate: this loop terminalizes
                 // per attempt, so the proof is spent per attempt.
                 assertDelegatedEvidence(input.delegated === true, convergenceAccess, [run]);
-                attemptTelemetries.push({ attemptId, harnessId: adapter.id, telemetry: run.telemetry });
+                attemptTelemetries.push({ attemptId, harnessId: adapter.id, ...pickTelemetry(run) });
                 lastPostTurnSha = null;
                 // Post-mutation fence for in-place: snapshot the live tree NOW (after the
                 // harness mutated it, before this attempt's review). The last attempt's
-                // value is the revert target persisted into work_product.yaml.
-                if (input.inPlace === true && input.workspaceKind !== "directory" && !run.captureRefusal) {
+                // value is the revert target persisted into work_product.yaml (an unchanged one has none).
+                if (input.inPlace && input.workspaceKind !== "directory" && needsPostTurnFence([run])) {
                     try {
                         lastPostTurnSha = await snapshotTree(execRoot);
                     }
@@ -3367,8 +3347,7 @@ export class Orchestrator {
                     exhausted = true;
                     break;
                 }
-                if (run.telemetry.requestRefusal ||
-                    run.telemetry.effortResolution?.resolution === "rejected")
+                if (endsConvergence(run))
                     break;
                 if (delegateFailure.candidateFailureKind(run)) {
                     const failure = delegateFailure.candidateFailureTerminal(run, "convergence");
@@ -3399,7 +3378,7 @@ export class Orchestrator {
                 // D-16 r8: interrupted (errored===false) would CONVERGE a partial diff
                 // as clean — break BEFORE review; a harness error still gate-retries.
                 if (run.outcomeClass === "interrupted") {
-                    interrupted = true;
+                    interrupted = interruptionOf(run);
                     break;
                 }
                 // The review round is wrapped so a preflight/revalidation throw ends the
@@ -3469,7 +3448,8 @@ export class Orchestrator {
                     converged = true;
                     break;
                 }
-                const requiredGateFailing = run.gates.length > 0 && !gatesPassed(run.gates);
+                const refusal = correctableRefusal(run); // INV-047: a refused patch has no result
+                const requiredGateFailing = !refusal && run.gates.length > 0 && !gatesPassed(run.gates);
                 const diffHash = run.files
                     ? run.files.manifestSha256
                     : input.workspaceKind === "directory"
@@ -3478,7 +3458,7 @@ export class Orchestrator {
                 if (requiredGateFailing && diffHash !== null && diffHash === lastFailingGateDiffHash) {
                     sameFailingGateDiffs += 1;
                 }
-                else {
+                else if (!refusal) {
                     sameFailingGateDiffs = requiredGateFailing ? 1 : 0;
                     lastFailingGateDiffHash = requiredGateFailing ? (diffHash ?? "") : "";
                 }
@@ -3496,11 +3476,9 @@ export class Orchestrator {
                     });
                     break;
                 }
-                const sig = failureSignature([
-                    ...conv.reasons,
-                    ...(run.files ? [`files_manifest:${run.files.manifestSha256}`] : []),
-                ]);
-                readiness.recordRound(sig, conv.reasons.join("; "));
+                const manifest = run.files ? [`files_manifest:${run.files.manifestSha256}`] : [];
+                const sig = refusal ?? failureSignature([...conv.reasons, ...manifest]);
+                readiness.recordRound(sig, refusal ?? conv.reasons.join("; "));
                 if (sig !== lastSig) {
                     triedSinceProgress = new Set();
                     lastSig = sig;
@@ -3681,6 +3659,7 @@ export class Orchestrator {
                         : "applied_review_blocked"
                     : "not_applied";
                 const revertAnchorId = convAdopted === true ? await anchors.turn(preTurnSha, lastPostTurnSha) : null;
+                const capturedNoGitChange = capturedNoGitChangeValue(lastRun);
                 store.writeYaml(join(paths.finalDir, "work_product.yaml"), {
                     id: newId("wp"),
                     kind: "patch",
@@ -3689,6 +3668,7 @@ export class Orchestrator {
                     meta: {
                         harness_id: lastRun.harnessId,
                         result_kind: "patch",
+                        ...(capturedNoGitChange !== null ? { capturedNoGitChange } : {}),
                         mode,
                         attempts: attempt,
                         lifecycle: facts.lifecycle,
@@ -4087,6 +4067,8 @@ export class Orchestrator {
                 if (outcome.status !== "success") {
                     if (outcome.telemetry?.effortResolution?.resolution === "rejected")
                         break;
+                    if (outcome.telemetry?.turnLimitReached)
+                        break; // #299: the cap ends the run
                     const next = adapters[idx + 1];
                     if (next && !input.signal?.aborted) {
                         fallbackFrom = outcome.harnessId;
@@ -4556,7 +4538,8 @@ export class Orchestrator {
                     report: "",
                     error: message,
                     telemetry,
-                    ...(preDeclared.code ? { declaredFailure: preDeclared } : {}), // typed pre-spawn refusal
+                    // A typed pre-spawn refusal, a provider refusal with no code of its own included (#558).
+                    ...(declaredFailureSpeaks(preDeclared) ? { declaredFailure: preDeclared } : {}),
                 });
                 attemptTelemetries.push({ attemptId, harnessId: adapter.id, telemetry });
                 if (opts.deepScan) {
@@ -4664,7 +4647,7 @@ export class Orchestrator {
                             // the loudest) — same single owner as the agent loop.
                             observeBudgetSignals(ledger, log, adapter.id, attemptId, ev, budgetSignalState);
                             this.deps.quotaEventSink?.(adapter.id, ev);
-                            const spend = observeReadonlySpend(ev, (t, p) => log.emit(t, p), adapter.id, attemptId);
+                            const spend = observeUsageSpend(ev, (t, p) => log.emit(t, p), adapter.id, attemptId, telemetry.usageCost);
                             cost += spend.costUsd;
                             costEstimated ||= spend.estimated;
                             const streamDenial = updateProcessingStreamHold(runSpec, telemetry.usageCost, ledger, lease.lease.lease_id, adapter.id, attemptId);
@@ -4692,8 +4675,6 @@ export class Orchestrator {
                         if (!recordAdapterThrow(telemetry, err))
                             break;
                     }
-                    if (telemetry.requestRefusal)
-                        break;
                     const newTransients = telemetry.transientFailures.slice(transientStart);
                     const sawRetryable = newTransients.some((f) => f.retryable);
                     const sawTypedLimit = telemetry.rateLimits.length > rateLimitStart;
@@ -4755,7 +4736,7 @@ export class Orchestrator {
             attemptTelemetries.push({ attemptId, harnessId: adapter.id, telemetry });
             // D-16: the deliverable is the report. A3: an errored attempt with no
             // typed final contributes no report material (acceptedTryOutput).
-            const roUnwrapped = unwrapWorkReportEnvelope(acceptedTryOutput(answer, harnessError !== null), readonlyWorkMode, { sideToolReport: telemetry.sideToolWorkReport ?? undefined });
+            const roUnwrapped = unwrapAttemptAnswer(acceptedTryOutput(answer, harnessError !== null), harnessError !== null && !answer.hasFinal(), readonlyWorkMode, { sideToolReport: telemetry.sideToolWorkReport ?? undefined });
             // Trim symmetrically with the plan path: a whitespace-only answer is not
             // a delivered report (the final-artifact wrapper heading would otherwise
             // make it read as present content by construction).
@@ -4774,7 +4755,7 @@ export class Orchestrator {
                 workReportSource: roUnwrapped.source,
                 workReportViolation: roUnwrapped.contractViolation,
                 workReportUnverified: roUnwrapped.unverified ?? null,
-                contextTerminalExhausted: telemetry.contextExhausted,
+                interruption: attemptInterruption(telemetry),
             });
             // A broken WorkReport contract is a hard failure ONLY when the finalizer
             // ranked it so — a concurrent terminal context exhaustion outranks it
@@ -4845,9 +4826,8 @@ export class Orchestrator {
                 harnessId: adapter.id,
                 status: scoutInterrupted ? "failed" : "success",
                 report: report || "(no output)",
-                error: scoutInterrupted ? "context capacity exhausted before the scout completed" : null,
+                error: scoutInterrupted ? interruptionDetail(roFinalized.reason) : null,
                 telemetry,
-                ...(scoutInterrupted ? { interrupted: true } : {}),
                 ...continuity.terminalFacts(roResumable),
             });
             launched.delete(tried);
@@ -4858,7 +4838,7 @@ export class Orchestrator {
                         .join("; ")}\n`
                     : "";
                 const scoutTag = scoutInterrupted
-                    ? " interrupted (context capacity exhausted)"
+                    ? ` interrupted (${interruptionDetail(roFinalized.reason)})`
                     : ` (${adapter.id})`;
                 store.writeText(join(paths.findingsDir, `${attemptId}${scoutInterrupted ? "-interrupted" : ""}.md`), `# Explorer ${attemptId}${scoutTag}\n\n${report || "(no output)"}${warningNote}\n`);
             }
@@ -4936,12 +4916,13 @@ export class Orchestrator {
                     if (last?.telemetry.effortResolution?.resolution === "rejected")
                         break;
                     // Per-harness fallback_model: one same-harness retry on FAILURE (not
-                    // policy blocks) before falling through to the next harness.
+                    // policy blocks or the caller's max-turns cap, #299) before the next harness.
                     const fallbackModel = routed.settings?.fallbackModel;
                     const firstModel = contract.routing_models[routed.adapter.id] ?? routed.settings?.defaultModel ?? null;
                     if (last &&
                         last.status === "failed" &&
                         !last.telemetry.requestRefusal &&
+                        !last.telemetry.turnLimitReached &&
                         fallbackModel &&
                         fallbackModel !== firstModel &&
                         !budgetStopped &&