@claudexor/orchestrator 4.1.0 → 4.1.1

package/dist/orchestrator.js

@@ -1,9 +1,9 @@
 import { applyWorkEnvelope, promptWithPointers as renderPromptWithPointers, threadContextPointer, } from "./prompt-framing.js";
 import { requestRefusalFailure } from "./runTerminalResults.js";
+import { openRunScopeCustody, scopedRouteContext, scopedSpecEnv, } from "./runScope.js";
 import { delegationBeltFor } from "./delegationBelt.js";
 import { bindProcessingAdmission, processingAttemptCostEvidence, processingAdmissionForLease, updateProcessingStreamHold, ProcessingBudgetAdmissionError, } from "./processing-dispatch.js";
 import { cancelledCandidatesResult, emptyCandidateResult, failedCandidatesResult, failAfterCandidates, } from "./candidateTerminals.js";
-import { existsSync } from "node:fs";
 import { effectiveAuthPreference, observeNativeSessionEvent, resumeSessionForProfile, } from "./credential-profiles.js";
 import { AdmissionProfileProbes, OrchestratorCredentials, reviewerProfileResolver, } from "./orchestrator-credentials.js";
 import { continuityWorkspace, resumableOf, resumableTerminal, } from "./continuity-terminal.js";
@@ -62,12 +62,13 @@ import { resolveWorkReportEnvelope, unwrapWorkReportEnvelope, } from "./workRepo
 import { buildContinuationPacket, decideContinuation, synthesizeContinuationRequest, } from "./continuation.js";
 import { interactionChannelFor } from "./interaction.js";
 import { liveAttempt } from "./live-input.js";
-import { gateSpecsFromContract, renderTestsEvidence } from "./contract-gates.js";
+import { finalVerifyRun, gateSpecsFromContract, renderTestsEvidence } from "./contract-gates.js";
 import { buildTaskContract } from "./task-contract-builder.js";
+import { prepareReviewEvidenceDir, recordReviewEvidenceCleanup } from "./reviewEvidence.js";
 import { ArtifactStore } from "@claudexor/artifact-store";
-import { buildContextPack, rawContextForEnvelope, preflightEvidence, writeEvidencePacket, } from "@claudexor/context";
+import { buildContextPack, rawContextForEnvelope, writeEvidencePacket } from "@claudexor/context";
 import { WorkspaceManager, captureRawPatchEnvelope, createRevertAnchorFromPatchOrNull, createRevertAnchorOrNull, consumeRawPatchEnvelope, snapshotTree, } from "@claudexor/workspace";
-import { blockedDecisionOverride, finalVerifyBlocks, finalVerifyPatch, finalVerifyFiles, verifyAndDeliverFiles, verifyAndDeliver, } from "@claudexor/delivery";
+import { blockedDecisionOverride, finalVerifyBlocks, verifyAndDeliverFiles, verifyAndDeliver, } from "@claudexor/delivery";
 import { HarnessGateway } from "@claudexor/gateway";
 import { ReadinessLedger, evaluateConvergence, failureSignature, gatesPassed, reviewCandidate, runGates, } from "@claudexor/review";
 import { arbitrate } from "@claudexor/arbitration";
@@ -162,39 +163,54 @@ export class Orchestrator {
             this.routingRationaleByRun.delete(settledRunId);
             this.deps.delegationBudgetAuthority?.releaseRun(settledRunId);
         };
+        // Process custody (owner 1A, #449; `runScope.ts`): the marker is minted and
+        // recorded BEFORE the first launch, rides every spec env (`scopedSpecEnv`),
+        // and every announced run HOLDS its terminal until the barrier has ended
+        // what still carries it. The reap never changes the verdict.
+        const custody = await openRunScopeCustody(this.deps.runScopes, runId);
+        resolved = { ...resolved, runScopeMarker: custody.marker };
         try {
             return await guardAnnouncedRun(resolved.signal, (announce) => {
+                const announced = custody.announced(announce);
                 switch (mode) {
                     case "ask":
                         // `--deep-scan` widens the answer into the bounded multi-scout
                         // research sweep with synthesis (the old `audit --swarm`/`explore`).
                         return resolved.deepScan
-                            ? this.runDeepScan(resolved, announce)
-                            : this.runAsk(resolved, announce);
+                            ? this.runDeepScan(resolved, announced)
+                            : this.runAsk(resolved, announced);
                     case "agent":
                         // Engine strategies are FLAGS on agent (v0.9 collapse): `--until-clean`
                         // and `--attempts` select the convergence loop; `--n` selects the race
                         // width; `--create` switches the candidate intent to create_from_scratch.
                         if (resolved.untilClean)
-                            return this.runConvergence(resolved, mode, null, announce);
+                            return this.runConvergence(resolved, mode, null, announced);
                         if (resolved.attempts !== undefined && resolved.attempts !== null) {
-                            return this.runConvergence(resolved, mode, resolved.attempts, announce);
+                            return this.runConvergence(resolved, mode, resolved.attempts, announced);
                         }
-                        return this.runRace({ ...resolved, n: resolved.n ?? 1 }, mode, announce);
+                        return this.runRace({ ...resolved, n: resolved.n ?? 1 }, mode, announced);
                     case "plan":
-                        return this.runPlan(resolved, announce);
+                        return this.runPlan(resolved, announced);
                 }
-            }, async ({ runId }) => {
+            }, 
+            // The whole-run barrier: drain delegated children, then end the run's
+            // process scope and record its outcome before ANY terminal is flushed
+            // (a child-drain rejection keeps its error). Bounded by the reap deadline.
+            ({ runId }) => custody.barrier(async () => {
                 const authority = this.deps.delegationBudgetAuthority;
                 if (!authority?.hasParent(runId))
                     return;
                 authority.beginParentClose(runId);
                 await authority.waitForChildren(runId);
-            }, 
-            // Single per-run terminalization hook: release the routing-rationale map
-            // entry on EVERY terminal (incl. a run that died before its telemetry
-            // writer ran, which is the leak this closes).
-            releaseRunState);
+            }), 
+            // Single per-run terminalization hook: the custody fallback for a path
+            // that never reached the barrier, then release per-run engine state
+            // (the delegated-child drain authority is released only AFTER
+            // settlement) on EVERY terminal.
+            async (settledRunId) => {
+                await custody.record();
+                releaseRunState(settledRunId);
+            });
         }
         catch (error) {
             // A durable startup sink may refuse `run.created` before the strategy can
@@ -206,6 +222,9 @@ export class Orchestrator {
             }
             throw error;
         }
+        finally {
+            await custody.settleUnannounced();
+        }
     }
     async resolveReviewers(cwd, runAuthPreference, onIgnoredSetting) {
         if (this.deps.reviewers)
@@ -1217,7 +1236,7 @@ export class Orchestrator {
                 adapter: this.deps.registry.get(harnessId),
                 credentialProfile: sessionFields.credential_profile,
                 authPreference: sessionFields.auth_preference ?? "auto",
-                laneEnv: this.laneHomeEnvFor(runInput, harnessId, profileId) ?? {},
+                laneEnv: scopedSpecEnv(runInput.runScopeMarker, this.laneHomeEnvFor(runInput, harnessId, profileId) ?? {}) ?? {},
                 envInheritance: envInheritance(this.config(runInput.repoRoot)),
                 signal: runInput.signal,
                 processing,
@@ -1328,6 +1347,9 @@ export class Orchestrator {
         if (routed.browserRequirement.effective && artifactRelativeDir === null) {
             throw new Error("browser artifact ownership marker was not persisted");
         }
+        // The run's scope marker rides every spec env (plus the host facts when the
+        // HOME is scoped), added AFTER the lane/profile home so that patch is kept.
+        const scopedEnv = scopedSpecEnv(runInput?.runScopeMarker, harnessHome.env);
         let spec = HarnessRunSpec.parse({
             session_id: newId("ses"),
             intent,
@@ -1359,7 +1381,7 @@ export class Orchestrator {
             ...(inPlaceEnvelope && sessionFields?.resume_session_id
                 ? { resume_session_id: sessionFields.resume_session_id }
                 : {}),
-            ...(harnessHome.env ? { env: harnessHome.env } : {}),
+            ...(scopedEnv ? { env: scopedEnv } : {}),
             raw_context_packet: rawContextPacket,
             stream_deltas: streamDeltas,
         });
@@ -1650,7 +1672,7 @@ export class Orchestrator {
         }
         const gates = gateSignalAborted
             ? []
-            : await runGates(gateSpecsFromContract(contract), {
+            : await runGates(gateSpecsFromContract(contract, runInput?.runScopeMarker), {
                 cwd: envelope.worktree_path,
                 env: wsm.envFor(envelope),
                 signal,
@@ -2396,7 +2418,7 @@ export class Orchestrator {
             // candidates (a trivial greeting in agent mode no longer burns two reviewers on
             // "(empty diff)"). Candidates still flow through arbitration/gates so the
             // no_op/answer outcome and gate failures are unchanged.
-            evidences = await this.reviewRuns(workingRuns, reviewers, reviewVerified, reviewDir, input.repoRoot, contract, store, paths, log, ledger, taskId, input.signal, this.reservationEstimateUsd(input));
+            evidences = await this.reviewRuns(workingRuns, reviewers, reviewVerified, reviewDir, input.repoRoot, contract, store, paths, log, ledger, taskId, input.signal, this.reservationEstimateUsd(input), false, input.runScopeMarker);
         }
         catch (err) {
             // Review preflight/evidence failures end TERMINALLY with artifacts —
@@ -2468,7 +2490,7 @@ export class Orchestrator {
                     runs.push(run);
                     try {
                         if (isWorkingCandidate(run)) {
-                            const synthEvidence = await this.reviewRuns([run], reviewers, reviewVerified, reviewDir, input.repoRoot, contract, store, paths, log, ledger, taskId, input.signal, this.reservationEstimateUsd(input));
+                            const synthEvidence = await this.reviewRuns([run], reviewers, reviewVerified, reviewDir, input.repoRoot, contract, store, paths, log, ledger, taskId, input.signal, this.reservationEstimateUsd(input), false, input.runScopeMarker);
                             evidences.push(...synthEvidence);
                             workingRuns.push(run);
                         }
@@ -2570,9 +2592,7 @@ export class Orchestrator {
             facts.lifecycle === "succeeded" &&
             facts.review !== "blocked" &&
             !input.signal?.aborted) {
-            finalVerify = winnerRun.files
-                ? await finalVerifyFiles(winnerRun.files, undefined, gateSpecsFromContract(contract), log)
-                : await finalVerifyPatch(execRoot, winnerRun, gateSpecsFromContract(contract), log);
+            finalVerify = await finalVerifyRun(execRoot, winnerRun, contract, log, input);
             finalVerifyFailed = finalVerifyBlocks(finalVerify);
             if (finalVerifyFailed)
                 facts = { ...facts, checks: "failed", reason: "checks_failed" };
@@ -2617,7 +2637,7 @@ export class Orchestrator {
                     facts.checks !== "failed" &&
                     !workStateVetoes(facts);
                 if (input.inPlace === true && !inPlaceWinner && directoryAdoptable) {
-                    const delivered = await verifyAndDeliverFiles(execRoot, winnerRun.files, {}, gateSpecsFromContract(contract), (freshVerify) => finalVerifyBlocks(freshVerify)
+                    const delivered = await verifyAndDeliverFiles(execRoot, winnerRun.files, {}, gateSpecsFromContract(contract, input.runScopeMarker), (freshVerify) => finalVerifyBlocks(freshVerify)
                         ? (freshVerify.reason ?? "final verify failed before directory race adoption")
                         : null, log);
                     store.writeYaml(join(paths.finalDir, "delivery_receipt.yaml"), delivered);
@@ -2680,7 +2700,7 @@ export class Orchestrator {
                     }
                     else if (adoptable) {
                         // Protected apply preserves the live tree or reports tree_mutated.
-                        const applied = await verifyAndDeliver(execRoot, winnerRun.diff, { mode: "apply", protectedApply: true }, gateSpecsFromContract(contract), (freshVerify) => {
+                        const applied = await verifyAndDeliver(execRoot, winnerRun.diff, { mode: "apply", protectedApply: true }, gateSpecsFromContract(contract, input.runScopeMarker), (freshVerify) => {
                             finalVerify = freshVerify;
                             return finalVerifyBlocks(freshVerify)
                                 ? (freshVerify.reason ?? "final verify failed before race adoption")
@@ -2954,7 +2974,7 @@ export class Orchestrator {
             transientRetryPolicy: input.transientRetryPolicy ?? transientRetryPolicy(this.config(input.cwd)),
         });
     }
-    async reviewRuns(runs, reviewers, reviewVerified, reviewDir, cwd, contract, store, paths, log, ledger, taskId, signal, reservationEstimateUsd, reviewUnchanged = false) {
+    async reviewRuns(runs, reviewers, reviewVerified, reviewDir, cwd, contract, store, paths, log, ledger, taskId, signal, reservationEstimateUsd, reviewUnchanged = false, runScopeMarker) {
         return reviewCandidateRuns({
             runs,
             reviewers,
@@ -2970,50 +2990,17 @@ export class Orchestrator {
             signal,
             reservationEstimateUsd,
             reviewUnchanged,
+            runScopeMarker,
         }, {
             prepareReviewEvidenceDir: this.prepareReviewEvidenceDir.bind(this),
-            recordReviewEvidenceCleanup: this.recordReviewEvidenceCleanup.bind(this),
+            recordReviewEvidenceCleanup,
             reviewScoped: this.reviewScoped.bind(this),
             config: this.config.bind(this),
         });
     }
-    prepareReviewEvidenceDir(sourceDir, _candidateCwd) {
-        // Evidence is an external runtime artifact. ReviewEngine builds a separate
-        // reviewer workspace and copies the packet there; writing/copying it into
-        // the candidate tree would contaminate the Git diff and, worse, overwrite a
-        // user-owned path with the same name.
-        if (!existsSync(sourceDir)) {
-            throw new Error(`review evidence preflight failed for ${sourceDir}: source packet missing`);
-        }
-        return this.requireReviewEvidence(sourceDir);
-    }
-    requireReviewEvidence(dir) {
-        const result = preflightEvidence(dir);
-        if (result.ok)
-            return dir;
-        const missing = result.missing.length ? `missing=${result.missing.join(",")}` : "";
-        const empty = result.empty.length ? `empty=${result.empty.join(",")}` : "";
-        throw new Error(`review evidence preflight failed for ${dir}: ${[missing, empty].filter(Boolean).join(" ")}`);
-    }
-    cleanupReviewEvidenceDir(_candidateEvidenceDir, _candidateCwd) {
-        // No candidate-tree packet exists in v2; external runtime retention is
-        // governed by the artifact/journal lifecycle rather than best-effort rm.
-        return null;
-    }
-    recordReviewEvidenceCleanup(store, metadataPath, attemptId, candidateEvidenceDir, candidateCwd) {
-        const cleanupMetadata = this.cleanupReviewEvidenceDir(candidateEvidenceDir, candidateCwd);
-        if (!cleanupMetadata)
-            return;
-        try {
-            store.writeYaml(metadataPath, {
-                ...cleanupMetadata,
-                attempt_id: attemptId,
-            });
-        }
-        catch {
-            // Cleanup telemetry must not mask the review/revalidation failure that
-            // triggered best-effort cleanup.
-        }
+    /** The instance method is the seam tests stub to make evidence setup fail. */
+    prepareReviewEvidenceDir(sourceDir, candidateCwd) {
+        return prepareReviewEvidenceDir(sourceDir, candidateCwd);
     }
     async runConvergence(input, mode, maxAttempts, announce) {
         const taskId = input.taskId ?? newId("task");
@@ -3398,7 +3385,7 @@ export class Orchestrator {
                             log.emit("review.skipped", { reason: "not_requested", attempt_id: attemptId });
                             return evaluateUnreviewedConvergence(evidence, contract);
                         }
-                        const [evidence] = await this.reviewRuns([run], reviewers, reviewVerified, reviewDir, input.repoRoot, contract, store, paths, log, ledger, taskId, input.signal, this.reservationEstimateUsd(input), true);
+                        const [evidence] = await this.reviewRuns([run], reviewers, reviewVerified, reviewDir, input.repoRoot, contract, store, paths, log, ledger, taskId, input.signal, this.reservationEstimateUsd(input), true, input.runScopeMarker);
                         if (!evidence)
                             throw new Error("Convergence review produced no evidence");
                         lastFindings = evidence.findings;
@@ -3587,9 +3574,7 @@ export class Orchestrator {
             facts.lifecycle === "succeeded" &&
             facts.review !== "blocked" &&
             !input.signal?.aborted) {
-            convFinalVerify = lastRun.files
-                ? await finalVerifyFiles(lastRun.files, undefined, gateSpecsFromContract(contract), log)
-                : await finalVerifyPatch(execRoot, lastRun, gateSpecsFromContract(contract), log);
+            convFinalVerify = await finalVerifyRun(execRoot, lastRun, contract, log, input);
             if (finalVerifyBlocks(convFinalVerify))
                 facts = { ...facts, checks: "failed", reason: "checks_failed" };
         }
@@ -3848,9 +3833,9 @@ export class Orchestrator {
                     ...sessionFields,
                     ...this.harnessSpecKnobs(contract, knobs, args.intent),
                     env_inheritance: envInheritance(this.config(input.repoRoot)),
-                    env: (args.laneRun
+                    env: scopedSpecEnv(input.runScopeMarker, (args.laneRun
                         ? this.laneHomeEnvFor(input, adapter.id, sessionFields.credential_profile?.profile_id ?? input.credentialProfileId ?? null)
-                        : null) ?? args.fallbackHome,
+                        : null) ?? args.fallbackHome),
                 });
                 this.credentials.stampProfileSelection(spec, input, adapter.id);
                 const plannerAbort = new AbortController();
@@ -3903,9 +3888,9 @@ export class Orchestrator {
         // harnesses run sequentially. Doctor, model inventory, and spawn share each
         // lane's durable HOME; the disposable context remains the non-thread fallback.
         const laneRun = Boolean(input.threadId);
-        const roHome = resolveReadOnlyRouteContext(this.execRootOf(input), laneRun
+        const roHome = scopedRouteContext(resolveReadOnlyRouteContext(this.execRootOf(input), laneRun
             ? (id) => this.laneHomeEnvFor(input, id, input.credentialProfileId ?? null)
-            : undefined);
+            : undefined), input.runScopeMarker);
         let adapters;
         try {
             adapters = await this.resolveCandidateAdapters({ ...input, n: undefined }, "plan", ledger, log, roHome, runId);
@@ -4190,7 +4175,7 @@ export class Orchestrator {
      */
     deepScanReducerDeps(input, contract, log) {
         return {
-            newReadOnlyHome: () => resolveReadOnlyRouteContext(this.execRootOf(input)),
+            newReadOnlyHome: () => scopedRouteContext(resolveReadOnlyRouteContext(this.execRootOf(input)), input.runScopeMarker),
             costEvidence: (harnessId, attemptId, routed) => 
             // The reducer admits under a finite estimate floor (mirror of the n>1
             // scout reserve) so a subscription route is not refused for lacking a
@@ -4213,7 +4198,7 @@ export class Orchestrator {
                     resume_session_id: null,
                     ...this.harnessSpecKnobs(contract, knobs, "synthesize"),
                     env_inheritance: envInheritance(this.config(input.repoRoot)),
-                    env: homeEnv,
+                    env: scopedSpecEnv(input.runScopeMarker, homeEnv),
                 });
                 this.credentials.stampProfileSelection(spec, input, routed.adapter.id);
                 // D-16: compile the WorkReport transport onto the reducer spec (the
@@ -4265,9 +4250,9 @@ export class Orchestrator {
         // and the next lane turn resumes it (INV-034). Its doctor/model/spawn path
         // shares that lane HOME; deep-scan and one-shot asks keep the disposable one.
         const laneRun = Boolean(input.threadId) && opts.mode === "ask" && !opts.deepScan;
-        const roHome = resolveReadOnlyRouteContext(this.execRootOf(input), laneRun
+        const roHome = scopedRouteContext(resolveReadOnlyRouteContext(this.execRootOf(input), laneRun
             ? (id) => this.laneHomeEnvFor(input, id, input.credentialProfileId ?? null)
-            : undefined);
+            : undefined), input.runScopeMarker);
         let adapters, width;
         try {
             ({ adapters, width } = await resolveReadOnlyCandidates({
@@ -4445,9 +4430,9 @@ export class Orchestrator {
                     // A thread lane turn spawns in its DURABLE per-lane home so the native
                     // session it records is reachable for resume next turn; everything else
                     // uses the disposable route-context home.
-                    env: (laneRun
+                    env: scopedSpecEnv(input.runScopeMarker, (laneRun
                         ? this.laneHomeEnvFor(input, adapter.id, sessionFields.credential_profile?.profile_id ?? input.credentialProfileId ?? null)
-                        : null) ?? roHome.env,
+                        : null) ?? roHome.env),
                 });
                 this.credentials.stampProfileSelection(spec, input, adapter.id);
                 const reportInteraction = interactionChannelFor(input, log, runId, taskId, attemptId, adapter.id, routed.supportsInteractive);