@claudexor/orchestrator 3.17.0 → 3.17.2

package/dist/orchestrator.js

@@ -1,8 +1,10 @@
+import { applyWorkEnvelope, promptWithPointers as renderPromptWithPointers, threadContextPointer, } from "./prompt-framing.js";
+import { requestRefusalFailure } from "./runTerminalResults.js";
 import { delegationBeltFor } from "./delegationBelt.js";
 import { bindProcessingAdmission, processingAdmissionForLease, updateProcessingStreamHold, ProcessingBudgetAdmissionError, } from "./processing-dispatch.js";
 import { cancelledCandidatesResult, emptyCandidateResult, failedCandidatesResult, } from "./candidateTerminals.js";
 import { existsSync } from "node:fs";
-import { effectiveAuthPreference, observeNativeSessionEvent, resumeSessionForProfile, rotateSpecOnTypedLimit, selectedProfileAvailability, } from "./credential-profiles.js";
+import { effectiveAuthPreference, observeNativeSessionEvent, resumeSessionForProfile, rotateSpecOnTypedLimit, } from "./credential-profiles.js";
 import { OrchestratorCredentials, reviewerProfileResolver, rotatedSpecInLaneHome, } from "./orchestrator-credentials.js";
 import { accountPoolRows } from "./account-pool.js";
 import { writeRunTelemetryArtifact } from "./runTelemetryWriter.js";
@@ -11,7 +13,7 @@ import { processAttemptUsage } from "./attemptUsage.js";
 import { captureDirectoryCandidate, directoryHasOutput, directoryCandidateStable, observeDirectoryPaths, publishDirectoryCandidate, } from "./directoryCandidate.js";
 import { appliedAttemptFacts, assertDelegatedEvidence, isMutatingAccess, outerBoundaryNotice, scopedHarnessHome, } from "./delegatedHome.js";
 import * as AC from "./attemptUsageCost.js";
-import { candidateRoster, candidateStatuses, convergenceOutcomeFacts, isWorkingCandidate, partitionCandidates, toCandidateEvidence, } from "./candidateEvidence.js";
+import { candidateRoster, candidateStatuses, convergenceOutcomeFacts, isWorkingCandidate, partitionCandidates, toCandidateEvidence, unanimousDeclaredFailure, } from "./candidateEvidence.js";
 import { capabilityIntents } from "@claudexor/gateway";
 import { reviewCandidateRuns, resolveEngineReview, unreviewedCandidateEvidence, evaluateUnreviewedConvergence, } from "./candidateReview.js";
 import { join } from "node:path";
@@ -39,7 +41,7 @@ import { cancelledResult, declaredFailure, failTerminally, guardAnnouncedRun, wr
 import { budgetFailureRecord, classifyBudgetFailure } from "./budgetFailure.js";
 import { finalizeStructuredOutput } from "./structuredOutput.js";
 import { admitRun } from "./runAdmission.js";
-import { dropDeltaPastBudget, emitPlanProgress, emitTransientExhausted, emitTransientRetryPlan, observeReadonlySpend, } from "./laneStreamEvents.js";
+import { dropDeltaPastBudget, emitPlanProgress, emitTransientExhausted, emitTransientRetryPlan, observeReadonlySpend, recordAdapterThrow, } from "./laneStreamEvents.js";
 import { promptWithEngineConstraints, sleep, redactHarnessEvent, harnessEventPayload, safeErrorMessage, renderSummary, observeBudgetSignals, rotateOnStall, recordCleanAttemptMetrics, envInheritance, transientRetryPolicy, reviewerTimeoutMs, harnessInactivityTimeoutMs, observeAuthSwitch, emitPrimaryDivergence, emitPoolDegraded, deliveryRefusalFailure, winnerNeedsHuman, writeRaceDeliveryDecision, } from "./runSupport.js";
 import { candidateStatusInRouteContext, resolveReadOnlyRouteContext, } from "./routeContext.js";
 import { resolveAutoReviewerPanel, resolveExplicitReviewerPanel } from "./reviewerPanel.js";
@@ -48,7 +50,7 @@ import { buildContinuation, } from "./continuity.js";
 import { activePlanPointer, resolveContinuitySummary, workspaceAnchor, } from "./continuity-facts.js";
 import { runDiffReview } from "./diffReview.js";
 import { rawScoutBundle, resolveDeepScanSynthesis, } from "./deepScanReducer.js";
-import { classifyAdapterThrow, createAttemptTelemetry, observeAttemptTelemetry, setAttemptOutcome, telemetrySummary, toolWarnings, unrecoveredToolErrors, webUnsatisfied, } from "./attemptTelemetry.js";
+import { createAttemptTelemetry, observeAttemptTelemetry, setAttemptOutcome, telemetrySummary, toolWarnings, unrecoveredToolErrors, webUnsatisfied, } from "./attemptTelemetry.js";
 import { newAttemptOutputMarkers } from "./attemptOutputMarkers.js";
 import * as delegateFailure from "./delegationFailure.js";
 import * as secretDiff from "./secretDiff.js";
@@ -366,6 +368,7 @@ export class Orchestrator {
         quotaAbsences: () => this.deps.quotaAbsences?.() ?? [],
         credentialUnusable: () => this.deps.credentialUnusable?.() ?? [],
         recordCredentialUnusable: (obs) => this.deps.recordCredentialUnusable?.(obs),
+        preProgressRefusals: () => this.deps.preProgressRefusals,
         authPreferenceForHarness: (repoRoot, harnessId, runPreference) => this.authPreferenceForHarness(repoRoot, harnessId, runPreference),
     });
     /**
@@ -554,43 +557,19 @@ export class Orchestrator {
             // profile-admitted route joins even an AUTO pool (the run spawns with
             // the profile's transport, so the default store's state is not the
             // routing truth). Capability/manifest gating above still applies.
-            let profileAdmitted = false;
             const profileAdapter = this.deps.registry.get(id);
-            const profileProbe = profileAdapter?.probeCredentialProfile?.bind(profileAdapter);
             const explicitPin = this.credentials.effectiveProfileId(input, id);
-            const model = input.models?.[id] ?? cfgEntry?.default_model ?? null;
             // Pins and bound/pool rows are checked against their own readiness.
-            const rowCandidateIds = [];
-            if (explicitPin) {
-                rowCandidateIds.push(explicitPin);
-            }
-            else if (status.status !== "ok") {
-                const pool = accountPoolRows(this.config(input.repoRoot)?.global.credential_profiles ?? [], id);
-                const bound = input.threadAccountBindings?.[id] ?? null;
-                rowCandidateIds.push(...(bound && pool.some((row) => row.profile_id === bound) ? [bound] : []), ...pool.map((row) => row.profile_id).filter((rowId) => rowId !== bound));
-            }
-            let lastRowVerdict = null;
-            for (const candidateId of rowCandidateIds) {
-                const verdict = await selectedProfileAvailability({
-                    registry: this.config(input.repoRoot)?.global.credential_profiles ?? [],
-                    profileId: candidateId,
-                    harnessId: id,
-                    probe: profileProbe,
-                    // `verification: passed` from the local store only means a login file
-                    // is present. The poller's authenticated vendor call is the only
-                    // liveness evidence; admission must act on it or dispatch may use a revoked token.
-                    quota: vendorQuota,
-                    unusable: liveUnusable,
-                    model,
-                    // Only an explicit/bound route may consume bounded stale LKG evidence.
-                    allowStale: explicitPin !== null || input.threadAccountBindings?.[id] === candidateId,
-                });
-                if (verdict === "available") {
-                    profileAdmitted = true;
-                    break;
-                }
-                lastRowVerdict = verdict;
-            }
+            const rows = await this.credentials.admitRouteRows({
+                input,
+                harnessId: id,
+                defaultReady: status.status === "ok",
+                model: input.models?.[id] ?? cfgEntry?.default_model ?? null,
+                quota: vendorQuota,
+                unusable: liveUnusable,
+                probe: profileAdapter?.probeCredentialProfile?.bind(profileAdapter),
+            });
+            const profileAdmitted = rows.admitted;
             if (profileAdmitted) {
                 // A valid account row restores manifest intent truth when the default store failed.
                 if (status.status !== "ok") {
@@ -603,14 +582,19 @@ export class Orchestrator {
                 }
             }
             else if (explicitPin) {
-                // An explicit pin that is not ready refuses/drops the lane; a
-                // not-ready UNPINNED row merely leaves the default doctor verdict in
-                // charge (the gates below keep the refusal honest when neither a row
-                // nor a default login exists).
-                const why = `${id} credential profile is not ready: ${lastRowVerdict}`;
+                // An explicit pin that is not ready refuses/drops the lane; not-ready
+                // UNPINNED rows are named below, and the default doctor verdict speaks
+                // only when neither a row nor a default login exists.
+                const why = `${id} credential profile is not ready: ${rows.pinVerdict}`;
                 dropLane(id, "credential", why);
                 continue;
             }
+            // #363: registered rows own this lane, so their observed states — not
+            // the default login's doctor advice — explain why none was admitted.
+            if (rows.unreadyRows && (status.status === "unavailable" || !explicitPool)) {
+                dropLane(id, "credential", rows.unreadyRows);
+                continue;
+            }
             if (status.status === "unavailable" && !profileAdmitted) {
                 const why = `${id} is unavailable${status.reasons.length ? `: ${status.reasons.join("; ")}` : ""}`;
                 dropLane(id, "doctor", why);
@@ -1135,25 +1119,6 @@ export class Orchestrator {
             callerSchema: contract.output_schema ?? null,
         });
     }
-    /**
-     * D-16: apply the resolved WorkReport transport to a built spec — set the
-     * envelope output_schema (constrained/side_tool routes) and APPEND the fenced
-     * metadata instruction (validated routes, e.g. cursor). Mutates the spec in
-     * place and returns the mode the answer unwrap consumes. Called at every
-     * task-producing spec-build site so the transport is never wired one-off.
-     */
-    applyWorkEnvelope(spec, workEnvelope) {
-        if (workEnvelope.outputSchema !== undefined)
-            spec.output_schema = workEnvelope.outputSchema;
-        const instruction = workEnvelope.mode.instruction;
-        if (instruction) {
-            spec.instructions =
-                spec.instructions && spec.instructions.trim()
-                    ? `${spec.instructions}\n\n${instruction}`
-                    : instruction;
-        }
-        return workEnvelope.mode;
-    }
     routeSpecKnobs(routed, contract, overrideModel, effortHint) {
         const s = routed.settings;
         const contractPolicy = contract.external_context.policy;
@@ -1286,7 +1251,7 @@ export class Orchestrator {
             const briefPath = join(paths.contextDir, "THREAD.md");
             store.writeText(briefPath, result.packetMarkdown);
             return {
-                pointerLine: `Earlier conversation context for this thread is at: ${briefPath} — read it before answering.`,
+                pointerLine: threadContextPointer(briefPath),
             };
         }
         catch (err) {
@@ -1405,6 +1370,8 @@ export class Orchestrator {
             raw_context_packet: rawContextPacket,
             stream_deltas: streamDeltas,
         });
+        if (runInput)
+            this.credentials.stampProfileSelection(spec, runInput, adapter.id);
         bindProcessingAdmission(spec, ledger, processingLease.id, adapter.id, attemptId, processingLease.onDenied, processingAdmission);
         const billingInput = runInput ?? { repoRoot: contract.repo.root };
         // Keep billing route-bound until admission observes the actual prepared
@@ -1418,7 +1385,7 @@ export class Orchestrator {
         if (interaction)
             spec.extra["interactionChannel"] = interaction;
         const workEnvelope = this.workReportEnvelopeFor(routed, contract, Boolean(interaction));
-        const workReportMode = this.applyWorkEnvelope(spec, workEnvelope);
+        const workReportMode = applyWorkEnvelope(spec, workEnvelope);
         const inactivityMs = harnessInactivityTimeoutMs(this.config(contract.repo.root));
         // Named once: the attempt record, the CandidateRun and the terminal gate all
         // read the SAME applied facts rather than three re-derivations. Derived
@@ -1482,6 +1449,8 @@ export class Orchestrator {
                     ? AbortSignal.any([signal, attemptAbort.signal])
                     : attemptAbort.signal;
                 activeSessionId = runSpec.session_id;
+                // #363: bound before the spawn — a credential change mid-try voids it.
+                const refusal = this.credentials.bindPreProgressRefusal(adapter.id, runSpec);
                 const transientStart = telemetry.transientFailures.length;
                 const rateLimitStart = telemetry.rateLimits.length;
                 let rawPatch = null;
@@ -1589,11 +1558,14 @@ export class Orchestrator {
                         processingRefusal = err;
                         break;
                     }
-                    telemetry.transientFailures.push(classifyAdapterThrow({ errorName: err instanceof Error ? err.name : null }));
+                    if (!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);
@@ -1605,6 +1577,8 @@ export class Orchestrator {
                     ? directoryCapture.files?.noChanges === true
                     : currentDiff.trim().length === 0;
                 const deliverableEmpty = workspaceUnchanged && answer.text().length === 0;
+                const delivered = !harnessErrored && !deliverableEmpty && !signal?.aborted;
+                this.credentials.noteTryServed(refusal, telemetry.outputMarkers, delivered);
                 // W5.4 + A2 failover: a typed-limit hit OR a structural pre-progress
                 // death rebuilds the spec on a NEW session under the next profile.
                 if (harnessErrored && runInput && !signal?.aborted) {
@@ -1616,9 +1590,10 @@ export class Orchestrator {
                         registry: this.config(contract.repo.root)?.global.credential_profiles ?? [],
                         snapshots: this.deps.quotaSnapshots?.() ?? [],
                         probeReadyProfiles: () => this.credentials.readyProfileIdsForRotation(runInput, adapter.id, spec.credential_profile ?? null, triedProfiles, spec.model_hint ?? null),
-                        ...this.credentials.rotationObservations(adapter, spec, newTransients),
+                        ...this.credentials.rotationObservations(adapter, spec, newTransients, refusal),
                         triedProfiles,
                         markers: telemetry.outputMarkers,
+                        requestRefused: Boolean(telemetry.requestRefusal),
                         sawTypedLimit,
                         sawRetryable,
                         attemptErrored: harnessErrored,
@@ -1670,7 +1645,7 @@ export class Orchestrator {
         }
         // A pool-exhausted terminal is rotation's verdict, not the transient
         // machinery's — no `route.transient.exhausted` rides along with it.
-        if (harnessErrored && !poolExhausted && !processingRefusal) {
+        if (harnessErrored && !poolExhausted && !processingRefusal && !telemetry.requestRefusal) {
             emitTransientExhausted((t, p) => log?.emit(t, p), adapter.id, attemptId, telemetry, retryPolicy.maxRetries);
         }
         const attemptStreamEndedMs = Date.now();
@@ -1821,9 +1796,11 @@ export class Orchestrator {
             telemetry,
             ...(secretDiffRefusal ? { secretDiffRefusal } : {}),
             // A5: the typed refusal survives NORMAL attempt finalization (no throw).
-            ...(poolExhausted || processingRefusal
-                ? { declaredFailure: declaredFailure(processingRefusal ?? poolExhausted) }
-                : {}),
+            ...(telemetry.requestRefusal
+                ? { declaredFailure: requestRefusalFailure(telemetry.requestRefusal) }
+                : poolExhausted || processingRefusal
+                    ? { declaredFailure: declaredFailure(processingRefusal ?? poolExhausted) }
+                    : {}),
             outcomeClass: finalized.outcomeClass,
             applied,
         };
@@ -3326,6 +3303,9 @@ export class Orchestrator {
                 // Cancellation/deadline keeps priority over a belt failure finalized concurrently.
                 if (input.signal?.aborted || processingBudgetDenial)
                     break;
+                if (run.telemetry.requestRefusal ||
+                    run.telemetry.effortResolution?.resolution === "rejected")
+                    break;
                 if (delegateFailure.candidateFailureKind(run)) {
                     const failure = delegateFailure.candidateFailureTerminal(run, "convergence");
                     if (run.files) {
@@ -3699,6 +3679,7 @@ export class Orchestrator {
                             : (convDeclared?.category ?? "internal"),
                 code: processingBudgetMapping?.code ?? convDeclared?.code ?? null,
                 resetsAt: convDeclared?.resetsAt ?? null,
+                requestRefusal: convDeclared?.requestRefusal,
                 safeMessage: convNeedsDecision
                     ? `review escalated to a human decision after ${attempt} attempt(s)`
                     : facts.reason === "stuck_no_progress"
@@ -3843,6 +3824,7 @@ export class Orchestrator {
                         ? this.laneHomeEnvFor(input, adapter.id, sessionFields.credential_profile?.profile_id ?? input.credentialProfileId ?? null)
                         : null) ?? args.fallbackHome,
                 });
+                this.credentials.stampProfileSelection(spec, input, adapter.id);
                 const plannerAbort = new AbortController();
                 spec.extra["abortSignal"] = input.signal
                     ? AbortSignal.any([input.signal, plannerAbort.signal])
@@ -3850,7 +3832,7 @@ export class Orchestrator {
                 const planInteraction = this.interactionChannelFor(input, log, runId, taskId, attemptId, adapter.id, routed.supportsInteractive);
                 if (planInteraction)
                     spec.extra["interactionChannel"] = planInteraction;
-                const planWorkMode = this.applyWorkEnvelope(spec, this.workReportEnvelopeFor(routed, contract, Boolean(planInteraction)));
+                const planWorkMode = applyWorkEnvelope(spec, this.workReportEnvelopeFor(routed, contract, Boolean(planInteraction)));
                 return {
                     knobs,
                     effectiveWeb,
@@ -4036,6 +4018,8 @@ export class Orchestrator {
                     error: outcome.error,
                 });
                 if (outcome.status !== "success") {
+                    if (outcome.telemetry?.effortResolution?.resolution === "rejected")
+                        break;
                     const next = adapters[idx + 1];
                     if (next && !input.signal?.aborted) {
                         fallbackFrom = outcome.harnessId;
@@ -4211,10 +4195,11 @@ export class Orchestrator {
                     env_inheritance: envInheritance(this.config(input.repoRoot)),
                     env: homeEnv,
                 });
+                this.credentials.stampProfileSelection(spec, input, routed.adapter.id);
                 // D-16: compile the WorkReport transport onto the reducer spec (the
                 // reducer is non-interactive) so its output is unwrapped + finalized
                 // through the shared attempt contract, not a fourth deliverable predicate.
-                const workReportMode = this.applyWorkEnvelope(spec, this.workReportEnvelopeFor(routed, contract, false));
+                const workReportMode = applyWorkEnvelope(spec, this.workReportEnvelopeFor(routed, contract, false));
                 return {
                     spec,
                     webPolicy: knobs.webPolicy,
@@ -4417,13 +4402,7 @@ export class Orchestrator {
                     : null;
                 // D-16d: the continuation packet pointer rides after the lane pointer so
                 // the fresh session is re-grounded in the exhausted attempt's work.
-                const promptWithPointers = [
-                    explorerPrompt,
-                    laneContinuity?.pointerLine,
-                    continuationPointer,
-                ]
-                    .filter((p) => Boolean(p))
-                    .join("\n\n");
+                const promptWithPointers = renderPromptWithPointers(explorerPrompt, laneContinuity?.pointerLine, continuationPointer);
                 const spec = HarnessRunSpec.parse({
                     session_id: newId("ses"),
                     intent: opts.intent,
@@ -4446,6 +4425,7 @@ export class Orchestrator {
                         ? this.laneHomeEnvFor(input, adapter.id, sessionFields.credential_profile?.profile_id ?? input.credentialProfileId ?? null)
                         : null) ?? roHome.env,
                 });
+                this.credentials.stampProfileSelection(spec, input, adapter.id);
                 const reportAbort = new AbortController();
                 spec.extra["abortSignal"] = input.signal
                     ? AbortSignal.any([input.signal, reportAbort.signal])
@@ -4455,7 +4435,7 @@ export class Orchestrator {
                     spec.extra["interactionChannel"] = reportInteraction;
                 // D-16: compile the WorkReport envelope for the read-only lane.
                 const readonlyWorkEnvelope = this.workReportEnvelopeFor(routed, contract, Boolean(reportInteraction));
-                const readonlyWorkMode = this.applyWorkEnvelope(spec, readonlyWorkEnvelope);
+                const readonlyWorkMode = applyWorkEnvelope(spec, readonlyWorkEnvelope);
                 const attemptEventsPath = join(paths.attemptsDir, attemptId, "events.jsonl");
                 const answer = new AnswerAssembly();
                 const telemetry = createAttemptTelemetry(knobs.webPolicy, contract.external_context.web_required, effectiveWeb, [], 
@@ -4548,6 +4528,8 @@ export class Orchestrator {
                             extra: { ...spec.extra },
                         });
                     activeSessionId = runSpec.session_id;
+                    // #363: bound before the spawn — a credential change mid-try voids it.
+                    const refusal = this.credentials.bindPreProgressRefusal(adapter.id, runSpec);
                     const transientStart = telemetry.transientFailures.length;
                     const rateLimitStart = telemetry.rateLimits.length;
                     log.emit("harness.started", {
@@ -4618,14 +4600,19 @@ export class Orchestrator {
                             break;
                         }
                         // #31: classify the throw (watchdog timeout vs process crash) as typed.
-                        telemetry.transientFailures.push(classifyAdapterThrow({ errorName: err instanceof Error ? err.name : null }));
+                        if (!recordAdapterThrow(telemetry, err))
+                            break;
                     }
                     if (streamBudgetDenied)
                         break;
+                    if (telemetry.requestRefusal)
+                        break;
                     const newTransients = telemetry.transientFailures.slice(transientStart);
                     const sawRetryable = newTransients.some((f) => f.retryable);
                     const sawTypedLimit = telemetry.rateLimits.length > rateLimitStart;
                     const reportSoFar = answer.text();
+                    const delivered = !harnessError && reportSoFar.length > 0 && !input.signal?.aborted;
+                    this.credentials.noteTryServed(refusal, telemetry.outputMarkers, delivered);
                     // W5.4 + A2 reactive failover, READ-ONLY lane (same contract as the
                     // candidate lane: typed limit or structural pre-progress death).
                     if (harnessError && !input.signal?.aborted) {
@@ -4637,9 +4624,10 @@ export class Orchestrator {
                             registry: this.config(input.repoRoot)?.global.credential_profiles ?? [],
                             snapshots: this.deps.quotaSnapshots?.() ?? [],
                             probeReadyProfiles: () => this.credentials.readyProfileIdsForRotation(input, adapter.id, spec.credential_profile ?? null, triedProfiles, spec.model_hint ?? null),
-                            ...this.credentials.rotationObservations(adapter, spec, newTransients),
+                            ...this.credentials.rotationObservations(adapter, spec, newTransients, refusal),
                             triedProfiles,
                             markers: telemetry.outputMarkers,
+                            requestRefused: Boolean(telemetry.requestRefusal),
                             sawTypedLimit,
                             sawRetryable,
                             attemptErrored: harnessError !== null,
@@ -4698,7 +4686,7 @@ export class Orchestrator {
                     preStreamFailureSource: "readonly-pre-stream",
                 });
             }
-            if (harnessError && !poolExhausted && !processingRefusal) {
+            if (harnessError && !poolExhausted && !processingRefusal && !telemetry.requestRefusal) {
                 emitTransientExhausted((t, p) => log.emit(t, p), adapter.id, attemptId, telemetry, retryPolicy.maxRetries);
             }
             attemptTelemetries.push({ attemptId, harnessId: adapter.id, telemetry });
@@ -4759,9 +4747,11 @@ export class Orchestrator {
                     report,
                     error: harnessError,
                     telemetry,
-                    ...(poolExhausted || processingRefusal
-                        ? { declaredFailure: declaredFailure(processingRefusal ?? poolExhausted) }
-                        : {}),
+                    ...(telemetry.requestRefusal
+                        ? { declaredFailure: requestRefusalFailure(telemetry.requestRefusal) }
+                        : poolExhausted || processingRefusal
+                            ? { declaredFailure: declaredFailure(processingRefusal ?? poolExhausted) }
+                            : {}),
                 });
                 if (opts.deepScan) {
                     store.writeText(join(paths.findingsDir, `${attemptId}-error.md`), `# Explorer ${attemptId} failed\n\n${harnessError}\n`);
@@ -4868,12 +4858,15 @@ 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.
                     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 &&
                         fallbackModel &&
                         fallbackModel !== firstModel &&
                         !budgetStopped &&
@@ -5000,6 +4993,7 @@ export class Orchestrator {
                     eventRefs: roEventRefs,
                     runDir: paths.root,
                     resetsAt: roDeclared?.resetsAt ?? null,
+                    requestRefusal: roDeclared?.requestRefusal,
                     vendorFailure: attemptVendorFailure(attemptTelemetries, last?.attemptId),
                     nextActions: harnessFailureNextActions(roCategory),
                 });
@@ -5060,10 +5054,7 @@ export class Orchestrator {
         const succeeded = succeededReadonly;
         if (opts.deepScan && succeeded.length === 0) {
             const blocked = attempts.some((a) => a.status === "blocked");
-            // QA-050/QA-019: an all-denied scan (finite-zero, or every scout refused
-            // before spawn) is a BUDGET failure, not harness_error — route it through
-            // the shared classifier. Only a pure-denial scan (no scout actually errored
-            // in the harness) qualifies, so a real explorer failure is never masked.
+            // QA-050/QA-019: only a pure-denial scan may claim a budget failure.
             const scanBudgetMapping = budgetStopped && !blocked && attempts.every((a) => a.budgetDenied === true)
                 ? classifyBudgetFailure({ denial: budgetDenial, terminal: ledger.terminal() })
                 : null;
@@ -5085,12 +5076,15 @@ export class Orchestrator {
                 }));
             }
             else {
-                // #31: classify the scout failures; keep the scan-specific width hint but
-                // drop the unconditional auth line unless the cause was a real auth failure.
+                // Mixed causes stay generic; only unanimous evidence may name the scan's cause.
+                const declared = blocked ? null : unanimousDeclaredFailure(attempts);
                 const scanCategory = dominantHarnessFailureCategory(attemptTelemetries.flatMap((a) => a.telemetry.transientFailures));
                 writeFailure(store, paths, {
                     phase: "harness",
-                    category: blocked ? "policy" : "harness_error",
+                    category: blocked ? "policy" : (declared?.category ?? "harness_error"),
+                    code: declared?.code,
+                    resetsAt: declared?.resetsAt,
+                    requestRefusal: declared?.requestRefusal,
                     safeMessage: message || "all explorers failed",
                     eventRefs: attempts.map((a) => `attempts/${a.attemptId}/events.jsonl`),
                     runDir: paths.root,
@@ -5101,10 +5095,7 @@ export class Orchestrator {
                     ],
                 });
             }
-            // QA-036: with ZERO successful explorers there is no synthesizable
-            // deliverable, so a blocked scan can no longer read as a succeeded
-            // "needs review" run (exit 0). An empty scan is a failure whether the
-            // explorers were blocked or errored.
+            // QA-036: no successful explorer means no synthesizable deliverable.
             store.writeText(join(paths.finalDir, "summary.md"), `# Run ${runId} (${opts.mode})\n\n- Lifecycle: ${scanFailFacts.lifecycle}${scanFailFacts.reason ? ` (${scanFailFacts.reason})` : ""}\n\n${message}\n`);
             log.emit("output.ready", { kind: "summary", path: "final/summary.md", state: "diagnostic" });
             log.emit("run.failed", {