@claudexor/orchestrator 5.1.0 → 6.1.1

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, erroredWinnerFailure, failedCandidatesResult, failAfterCandidates, } from "./candidateTerminals.js";
+import { cancelledCandidatesResult, emptyCandidateResult, erroredWinnerFailure, failedCandidatesResult, failAfterCandidates, convergenceCause, raceStatement, } 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";
@@ -54,7 +54,7 @@ import { dropDeltaPastBudget, emitPlanProgress, emitTransientExhausted, observeU
 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 { ensureWriteModeGitBoundary } from "./git-precondition.js";
 import { buildContinuation } from "./continuity.js";
 import { resolveContinuitySummary, threadContinuityRequest } from "./continuity-facts.js";
 import { runDiffReview } from "./diffReview.js";
@@ -75,9 +75,9 @@ import { prepareReviewEvidenceDir, recordReviewEvidenceCleanup } from "./reviewE
 import { savedForSynthesis } from "./savedCandidate.js";
 import { ArtifactStore } from "@claudexor/artifact-store";
 import { buildContextPack, writeEvidencePacket } from "@claudexor/context";
-import { RawPatchLane, correctableRefusal, endsConvergence } from "./rawPatchLane.js";
+import { RawAdoption, RawPatchLane, correctableRefusal, endsConvergence } from "./rawPatchLane.js";
 import { runRuntimeRoot } from "./run-runtime-root.js";
-import { WorkspaceManager, snapshotTree, } from "@claudexor/workspace";
+import { WorkspaceManager, rawAwareSnapshot, } from "@claudexor/workspace";
 import { blockedDecisionOverride, finalVerifyBlocks, verifyAndDeliverFiles, verifyAndDeliver, } from "@claudexor/delivery";
 import { HarnessGateway } from "@claudexor/gateway";
 import { ReadinessLedger, evaluateConvergence, failureSignature, gatesPassed, requireReadingReviewers, reviewCandidate, runGates, } from "@claudexor/review";
@@ -1159,6 +1159,7 @@ export class Orchestrator {
                 threadId: runInput.threadId,
                 projectRoot: runInput.repoRoot,
                 cwd: repoRoot,
+                inputFileDir: paths.contextDir,
                 adapter: this.deps.registry.get(harnessId),
                 model: this.deps.registry.get(harnessId)?.modelRequirement && runInput.models?.[harnessId],
                 credentialProfile: sessionFields.credential_profile,
@@ -1307,6 +1308,7 @@ export class Orchestrator {
                 : join(envelope.worktree_path, artifactRelativeDir, CLAUDEXOR_BROWSER_ARTIFACT_SUBDIR)),
             extra_mcp_servers: delegationBeltFor(runInput, intent, routed, contract.budget.paid_budget),
             cwd: envelope.worktree_path,
+            input_file_dir: paths.contextDir,
             access: routed.adapterAccess,
             // Writable lanes only: routing admitted this list for this exact lane.
             auxiliary_writable_roots: routed.auxiliaryWritableRoots,
@@ -1882,22 +1884,12 @@ export class Orchestrator {
                 };
             }
         }
-        // Same run-prep stage as the git boundary: if the PROJECT root uses AGENTS.md
-        // with no CLAUDE.md, bridge it so a Claude Code candidate reads it (INV-113).
-        if (mutatingRun && input.workspaceKind !== "directory") {
-            ensureClaudeBridgeForRun(input.repoRoot, input.inPlace === true, log);
-        }
         // Pre-turn snapshot of the live tree for in-place runs: the revert restore
         // target (server-owned revertInPlace). A snapshot failure must never fail the
         // run — revert is simply unavailable then.
         let preTurnSha = null;
         if (mutatingRun && input.inPlace === true && input.workspaceKind !== "directory") {
-            try {
-                preTurnSha = await snapshotTree(execRoot);
-            }
-            catch {
-                preTurnSha = null;
-            }
+            preTurnSha = await rawAwareSnapshot(execRoot).catch(() => null);
         }
         // ContextPack is LAZY: agent/race candidates explore the live tree
         // themselves inside their envelopes; only the read-only report modes
@@ -1948,6 +1940,7 @@ export class Orchestrator {
             for (const env of envelopes)
                 await kept.settle(wsm, env, runsBySlot);
         };
+        const rawAdoption = new RawAdoption(execRoot, input);
         const candidateAccess = contract.access.effective_profile;
         let budgetStopped = false;
         // QA-050: keep the ledger's typed denial so the zero-candidate terminal
@@ -2072,6 +2065,9 @@ export class Orchestrator {
                             requestedSingleCandidate &&
                             slot.routed.implementationTransport !== "git_patch_envelope"),
                 });
+                // A continueFrom envelope already owns its record: no empty source overwrites it.
+                if (!input.continuation?.adopt)
+                    await rawAdoption.seed(envelope.worktree_path);
                 harnessHome = this.harnessHomeFor(wsm, envelope, slot.routed, input);
                 const run = await this.runCandidateInEnvelope(slot.routed, envelope, slot.attemptId, slot.label, contract, input.prompt, store, paths, wsm, ledger, {
                     lease: slot.lease,
@@ -2192,6 +2188,8 @@ export class Orchestrator {
                         }
                     }
                 }
+                if (!effectiveRun.errored && secretDiff.hasCandidateChanges(effectiveRun))
+                    await rawAdoption.keep(effectiveRun.attemptId, envelope.worktree_path);
                 runsBySlot[slotIdx] = effectiveRun;
                 reviewEnvelopes.push(envelope);
                 envelope = undefined;
@@ -2202,6 +2200,7 @@ export class Orchestrator {
                 const message = safeErrorMessage(err);
                 const declared = declaredFailure(err);
                 const infraPhase = envelope === undefined ? "workspace" : "harness";
+                const applied = appliedAttemptFacts(harnessHome, slot.routed.adapterAccess, this.credentials.effectiveProfileId(input, adapter.id));
                 log.emit("harness.completed", {
                     harness_id: adapter.id,
                     attempt_id: slot.attemptId,
@@ -2209,7 +2208,7 @@ export class Orchestrator {
                     error: message,
                     phase: infraPhase,
                 });
-                store.writeYaml(join(paths.attemptsDir, slot.attemptId, "attempt.yaml"), AC.attemptFailureRecord(slot.attemptId, adapter.id, failureCost, infraPhase, message, appliedAttemptFacts(harnessHome, slot.routed.adapterAccess, this.credentials.effectiveProfileId(input, adapter.id))));
+                store.writeYaml(join(paths.attemptsDir, slot.attemptId, "attempt.yaml"), AC.attemptFailureRecord(slot.attemptId, adapter.id, failureCost, infraPhase, message, applied));
                 runsBySlot[slotIdx] = {
                     attemptId: slot.attemptId,
                     harnessId: adapter.id,
@@ -2231,7 +2230,9 @@ export class Orchestrator {
                     // alive past this catch; `message` alone would force the terminal to
                     // read prose back out.
                     ...(declared.code || declared.quotaRefusal ? { declaredFailure: declared } : {}),
-                    applied: appliedAttemptFacts(harnessHome, slot.routed.adapterAccess, this.credentials.effectiveProfileId(input, adapter.id)),
+                    applied,
+                    // No HOME was decided, so no child started (#648); never read from a record.
+                    ...(harnessHome === undefined ? { homeUndecided: true } : {}),
                 };
             }
             finally {
@@ -2289,12 +2290,7 @@ export class Orchestrator {
             input.inPlace &&
             requestedSingleCandidate &&
             needsPostTurnFence(runs)) {
-            try {
-                earlyPostTurnSha = await snapshotTree(execRoot);
-            }
-            catch {
-                earlyPostTurnSha = null;
-            }
+            earlyPostTurnSha = await rawAwareSnapshot(execRoot).catch(() => null);
         }
         if (input.signal?.aborted) {
             await disposeReviewEnvelopes();
@@ -2447,6 +2443,7 @@ export class Orchestrator {
                             workspaceKind: input.workspaceKind,
                             scopePaths: input.scopePaths,
                         });
+                        await rawAdoption.seed(envelope.worktree_path);
                         const synthHome = this.harnessHomeFor(wsm, envelope, synthRouted, input);
                         const run = await this.runCandidateInEnvelope(synthRouted, envelope, "synth", "Synthesis", contract, synthesisInput.prompt, store, paths, wsm, ledger, {
                             lease: lease.lease,
@@ -2456,6 +2453,8 @@ export class Orchestrator {
                             },
                         }, candidateAccess, input.onHarnessEvent, input.signal, undefined, input.effort, "synthesize", log, effectiveWeb, interactionChannelFor(input, log, runId, taskId, "synth", synthAdapter.id, synthRouted.supportsInteractive), undefined, input, false, synthesisInput.content, undefined, synthHome, undefined, synthTried);
                         ledger.settle(lease.lease?.lease_id ?? "", attemptUsageCostSettlement(run.cost, run.costEstimated, run.attemptId, run.harnessId, run.telemetry.authMode, run.telemetry.usageCost));
+                        if (!run.errored && secretDiff.hasCandidateChanges(run))
+                            await rawAdoption.keep(run.attemptId, envelope.worktree_path);
                         reviewEnvelopes.push(envelope);
                         envelope = undefined;
                         // D-16 r8: only a WORKING synth is reviewed/adopted (same veto owner
@@ -2700,8 +2699,9 @@ export class Orchestrator {
                                 applied: true,
                                 patch_sha256: patchSha256,
                                 winner: winnerRun.attemptId,
+                                ...(await rawAdoption.publish(winnerRun.attemptId)),
                             });
-                            postTurnSha = await snapshotTree(execRoot).catch(() => null);
+                            postTurnSha = await rawAwareSnapshot(execRoot).catch(() => null);
                             revertAnchorId = await anchors.after(winnerRun, applied);
                         }
                         else {
@@ -2719,6 +2719,7 @@ export class Orchestrator {
                                 patch_sha256: patchSha256,
                                 detail: redactSecrets(applied.detail ?? "apply failed"),
                                 tree_mutated: applied.treeMutated,
+                                ...(adopted ? await rawAdoption.publish(winnerRun.attemptId) : {}),
                             });
                         }
                     }
@@ -2796,6 +2797,8 @@ export class Orchestrator {
         // (applyable, no_changes, or not-verified) is an honest completion.
         const needsDecisionTerminal = facts.review === "blocked" || facts.checks === "failed";
         const isFailureTerminal = facts.lifecycle !== "succeeded" || needsDecisionTerminal;
+        const decisionBlock = needsHuman || needsDecisionTerminal;
+        const statement = raceStatement(winnerRun, decisionBlock, result.decision.why_winner);
         const pool = racePool();
         // Beside whichever failure record leads, a source another attempt kept stays named.
         const keptSources = candidateCaptureRefusals(runs).flatMap(secretDiff.captureInspectionActions);
@@ -2840,7 +2843,6 @@ export class Orchestrator {
             // stays `internal`. A review/checks block is `policy` (the acceptance
             // path), phase `review`, and its remedy names the decision, not "retry
             // with a different harness".
-            const decisionBlock = needsHuman || needsDecisionTerminal;
             writeFailure(store, paths, {
                 phase: decisionBlock ? "review" : "arbitration",
                 category: decisionBlock
@@ -2856,7 +2858,7 @@ export class Orchestrator {
                     ? `review escalated to a human decision: ${result.decision.why_winner}`
                     : needsDecisionTerminal
                         ? `review blocked before apply: ${result.decision.why_winner}`
-                        : result.decision.why_winner, pool),
+                        : statement, pool),
                 poolAttempts: pool,
                 rawDetailRef: winnerRun?.errored
                     ? `attempts/${winnerRun.attemptId}/attempt.yaml`
@@ -2937,7 +2939,7 @@ export class Orchestrator {
             facts,
             winner: result.decision.winner,
             runDir: paths.root,
-            summary: withPoolAttempts(result.decision.why_winner, pool),
+            summary: withPoolAttempts(statement, pool),
             candidates: candidateStatuses(runs),
             decisionPath,
             reviewVerified: actualReviewVerified,
@@ -3059,11 +3061,6 @@ export class Orchestrator {
                     candidates: [],
                 };
             }
-            // Same run-prep stage as the git boundary (and the same `!inPlace`
-            // exclusion — we are inside that branch, so inPlace is false here): bridge
-            // an AGENTS.md-only PROJECT root so a Claude Code convergence attempt reads
-            // it (INV-113).
-            ensureClaudeBridgeForRun(input.repoRoot, false, log);
         }
         const reviewDir = join(paths.root, "review-evidence");
         if (contract.review_requested !== false)
@@ -3187,12 +3184,7 @@ export class Orchestrator {
             // access level the envelope did not actually run with.
             const convergenceAccess = contract.access.effective_profile;
             if (input.inPlace === true && input.workspaceKind !== "directory") {
-                try {
-                    preTurnSha = await snapshotTree(execRoot);
-                }
-                catch {
-                    preTurnSha = null;
-                }
+                preTurnSha = await rawAwareSnapshot(execRoot).catch(() => null);
             }
             envelope = await wsm.create({
                 taskId,
@@ -3285,15 +3277,16 @@ export class Orchestrator {
                     // A5: keep a TYPED refusal alive past this catch (race-lane parity).
                     const declared = declaredFailure(err);
                     ledger.settle(lease.lease?.lease_id ?? "", failureCost.settlement);
+                    const applied = appliedAttemptFacts(harnessHome, routed.adapterAccess, this.credentials.effectiveProfileId(input, adapter.id));
                     log.emit("harness.completed", {
                         harness_id: adapter.id,
                         attempt_id: attemptId,
                         status: "failed",
                         error: message,
                     });
-                    store.writeYaml(join(paths.attemptsDir, attemptId, "attempt.yaml"), AC.attemptFailureRecord(attemptId, adapter.id, failureCost, "harness", message, appliedAttemptFacts(harnessHome, routed.adapterAccess, this.credentials.effectiveProfileId(input, adapter.id))));
+                    store.writeYaml(join(paths.attemptsDir, attemptId, "attempt.yaml"), AC.attemptFailureRecord(attemptId, adapter.id, failureCost, "harness", message, applied));
                     run = {
-                        applied: appliedAttemptFacts(harnessHome, routed.adapterAccess, this.credentials.effectiveProfileId(input, adapter.id)),
+                        applied,
                         attemptId,
                         harnessId: adapter.id,
                         label: `Attempt ${attempt}`,
@@ -3316,6 +3309,9 @@ export class Orchestrator {
                             holder: { runId: paths.runId, runDir: paths.root },
                         }));
                     }
+                    // Refused before its HOME was decided, no child ran: that refusal ends the run (#648).
+                    if (input.delegated === true && harnessHome === undefined)
+                        throw err;
                 }
                 lastRun = run;
                 convergenceRuns.push(run);
@@ -3328,12 +3324,7 @@ export class Orchestrator {
                 // harness mutated it, before this attempt's review). The last attempt's
                 // 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);
-                    }
-                    catch {
-                        lastPostTurnSha = null;
-                    }
+                    lastPostTurnSha = await rawAwareSnapshot(execRoot).catch(() => null);
                 }
                 // Cancellation/deadline keeps priority over a belt failure finalized concurrently.
                 if (input.signal?.aborted || processingBudgetDenial)
@@ -3614,6 +3605,7 @@ export class Orchestrator {
         const convNeedsDecision = facts.review === "blocked" || facts.checks === "failed";
         // Every attempt's failed tries by the actual outcome; a block is not an account failure.
         const convPool = terminalPoolAttempts(facts, convergenceRuns);
+        const convCause = convergenceCause(lastRun, facts, Boolean(convBudgetMapping));
         if (decision) {
             // Shared honesty owner (same as the race path): a needs-decision terminal
             // overrides the persisted decision; final_verify is recorded either way.
@@ -3689,7 +3681,7 @@ export class Orchestrator {
                 store.writeText(join(paths.finalDir, "answer.md"), lastRun.answerText);
                 log.emit("output.ready", { kind: "answer", path: "final/answer.md" });
             }
-            store.writeText(join(paths.finalDir, "summary.md"), `${withPoolAttempts(`# Run ${runId} (${mode})\n\n- Lifecycle: ${facts.lifecycle}${facts.reason ? ` (${facts.reason})` : ""}\n- Attempts: ${attempt}\n- Winner: ${lastRun.attemptId}\n- Review verified (cross-family): ${actualReviewVerified}\n- Apply recommendation: ${decision?.apply_recommendation ?? "inspect"}${stuckNoProgressReason ? `\n- No-progress reason: ${stuckNoProgressReason}` : ""}${secretDiff.resultSummaryDisclosure(lastRun)}`, convPool)}\n`);
+            store.writeText(join(paths.finalDir, "summary.md"), `${withPoolAttempts(`# Run ${runId} (${mode})\n\n- Lifecycle: ${facts.lifecycle}${facts.reason ? ` (${facts.reason})` : ""}\n- Attempts: ${attempt}\n- Winner: ${lastRun.attemptId}\n- Review verified (cross-family): ${actualReviewVerified}\n- Apply recommendation: ${decision?.apply_recommendation ?? "inspect"}${stuckNoProgressReason ? `\n- No-progress reason: ${stuckNoProgressReason}` : ""}${convCause ? `\n- Failure: ${convCause}` : ""}${secretDiff.resultSummaryDisclosure(lastRun)}`, convPool)}\n`);
             // Lifecycle invariant (all modes): output.ready precedes the terminal
             // event so a client that applied the terminal event has the output.
             log.emit("output.ready", {
@@ -3725,6 +3717,7 @@ export class Orchestrator {
                 rawContextShortfall: convDeclared?.rawContextShortfall,
                 harnessId: lastRun?.harnessId,
                 attemptId: lastRun?.attemptId,
+                vendorFailure: convCause ? lastRun?.telemetry.vendorFailure : null,
                 runDir: paths.root,
                 captureFailure: lastRun?.captureRefusal?.failure,
                 nextActions: [
@@ -3763,7 +3756,7 @@ export class Orchestrator {
                         ? `review escalated to a human decision after ${attempt} attempt(s)`
                         : facts.reason === "stuck_no_progress"
                             ? (stuckNoProgressReason ?? `stuck_no_progress after ${attempt} attempt(s)`)
-                            : `${facts.lifecycle}${facts.reason ? ` (${facts.reason})` : ""} after ${attempt} attempt(s)${lastDiffStable ? "" : " (diff changed after review; review is stale)"}`), convPool),
+                            : `${convCause ? `${convCause}\n` : ""}${facts.lifecycle}${facts.reason ? ` (${facts.reason})` : ""} after ${attempt} attempt(s)${lastDiffStable ? "" : " (diff changed after review; review is stale)"}`), convPool),
                 poolAttempts: convPool,
             });
             // D-16 r8/r9: an INTERRUPTED envelope run still gets its diagnostic
@@ -3839,7 +3832,7 @@ export class Orchestrator {
                 : {}),
             summary: withPoolAttempts(converged
                 ? `converged in ${attempt} attempt(s)`
-                : `${facts.lifecycle} after ${attempt} attempt(s)`, convPool),
+                : `${convCause ? `${convCause}\n` : ""}${facts.lifecycle} after ${attempt} attempt(s)`, convPool),
             candidates: lastRun
                 ? [
                     {
@@ -3874,6 +3867,7 @@ export class Orchestrator {
                         ? `${args.promptBody}\n\n${laneContinuity.pointerLine}`
                         : args.promptBody,
                     cwd: this.execRootOf(input),
+                    input_file_dir: paths.contextDir,
                     access: "readonly",
                     attachments: input.attachments ?? [],
                     ...sessionFields,
@@ -4222,7 +4216,7 @@ export class Orchestrator {
      * route/session/knob machinery HERE and hands the module only finished public
      * types (a `HarnessRunSpec`, cost evidence, a disposable home).
      */
-    deepScanReducerDeps(input, contract, log) {
+    deepScanReducerDeps(input, contract, log, paths) {
         return {
             newReadOnlyHome: () => scopedRouteContext(resolveReadOnlyRouteContext(this.execRootOf(input)), input.runScopeMarker),
             costEvidence: (harnessId, attemptId, routed) => 
@@ -4239,6 +4233,7 @@ export class Orchestrator {
                     intent: "synthesize",
                     prompt,
                     cwd: this.execRootOf(input),
+                    input_file_dir: paths.contextDir,
                     access: "readonly",
                     attachments: [],
                     auth_preference: sessionFields.auth_preference,
@@ -4472,6 +4467,7 @@ export class Orchestrator {
                     intent: opts.intent,
                     prompt: promptWithPointers,
                     cwd: this.execRootOf(input),
+                    input_file_dir: paths.contextDir,
                     access: "readonly",
                     // ASK/EXPLORE/AUDIT read-only runs must forward the user's attachments —
                     // a live "describe this image" turn sent an image that was being dropped here, so
@@ -5016,7 +5012,7 @@ export class Orchestrator {
         let deepScanSynthesis = null;
         let reducedReport = null;
         if (opts.deepScan) {
-            ({ deepScanSynthesis, reducedReport } = await resolveDeepScanSynthesis(this.deepScanReducerDeps(input, contract, log), {
+            ({ deepScanSynthesis, reducedReport } = await resolveDeepScanSynthesis(this.deepScanReducerDeps(input, contract, log, paths), {
                 succeeded,
                 adapters,
                 budgetStopped,