@tangle-network/agent-eval 0.126.2 → 0.126.3

package/CHANGELOG.md

@@ -4,7 +4,17 @@ All notable changes to `@tangle-network/agent-eval` and its sibling `agent-eval-
 
 ---
 
-## [Unreleased]
+## [0.126.3] - 2026-07-24 - execution-bound optimizer resume
+
+### Added
+
+- `runCampaign({ abortOnCellError: true })` stops scheduling after the first dispatch or judge error, aborts and drains active sibling cells, then rejects with the original error.
+- Failed cells write `<cell>/failure-receipt.json` before cancellation, including the exact cell result, call IDs, and settled agent-plus-judge cost and token totals.
+
+### Fixed
+
+- Official GEPA, SkillOpt, and generic external optimizer resume identities include the caller's exact dispatch identity, so changed agent, retrieval, judge, model, or service behavior cannot restore incompatible optimizer state.
+- `compareOptimizationMethods()` passes its final-scoring dispatch identity into method optimization and rejects conflicting identities.
 
 ## [0.126.2] - 2026-07-24 - fail-closed candidate ranking
 

package/README.md

@@ -90,6 +90,26 @@ console.log(
 Each call runs every case, records the artifact, applies the same judge, and returns score distributions.
 The surface is the value being changed, such as a prompt, skill, or serialized configuration.
 
+### Stop after the first failed cell
+
+`runCampaign()` normally records a dispatch or judge error on that cell and continues the remaining cases.
+Set `abortOnCellError: true` when another failed cell would only waste time or money:
+
+```ts
+await runCampaign({
+  scenarios,
+  dispatch,
+  judges: [judge],
+  runDir: 'release-candidate',
+  abortOnCellError: true,
+})
+```
+
+The failed cell is written first to `<runDir>/<cell>/failure-receipt.json`.
+That receipt contains the original error, the cell result, exact call IDs, and settled agent-plus-judge cost and token totals.
+Active sibling cells are cancelled and allowed to finish recording their own receipts before the campaign rejects with the original cell error.
+Leaving `abortOnCellError` unset preserves continue-on-error behavior.
+
 ## Adapt Another Text Optimizer
 
 Use `externalTextOptimizationMethod()` when an existing package owns search and selection for a text prompt or named text components.
@@ -97,7 +117,7 @@ Its `run` callback receives the starting candidate plus serialized train and sel
 The optimizer must score candidates through `context.evaluate()` so Agent Eval can enforce the evaluation limit and use the configured execution and judges.
 Every optimizer-owned paid call must use `context.cost.runPaidCall()`.
 Set `source` to the package version and revision, and set `evaluationId` to a commit, content hash, or other stable identity for the execution and scoring behavior.
-Agent Eval derives the run identity from those values, the optimizer settings, the starting surface, the described data, and the seed.
+Agent Eval derives the run identity from those values, the exact dispatch identity, the optimizer settings, the starting surface, the described data, and the seed.
 The callback returns the selected candidate, whether compatible state was restored, and how optimizer spend was recorded.
 
 See [Adapt A Third-Party Text Optimizer](./docs/campaign-proposers.md#adapt-a-third-party-text-optimizer) for a complete minimal adapter.

package/dist/benchmarks/index.js

@@ -16,10 +16,10 @@ import {
   routing_exports,
   runBenchmarkAdapter,
   summarizeBenchmarkCampaign
-} from "../chunk-W4L6C2XT.js";
-import "../chunk-Y5CLI4PY.js";
-import "../chunk-7AN2E7BU.js";
-import "../chunk-UCLVDLCH.js";
+} from "../chunk-CGG5SLH3.js";
+import "../chunk-P6WN2KF5.js";
+import "../chunk-3I74FLK6.js";
+import "../chunk-ZVCHKKOP.js";
 import "../chunk-WGXIEX7P.js";
 import "../chunk-ARU2PZFM.js";
 import "../chunk-J5SQWP6Y.js";

package/dist/campaign/index.d.ts

@@ -2368,6 +2368,14 @@ interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
     costTags?: Readonly<Record<string, string>>;
     /** Max concurrent cells. Default 2. */
     maxConcurrency?: number;
+    /**
+     * Stop after the first dispatch or judge error. The failed cell is persisted
+     * before active sibling cells are aborted and drained, then the campaign
+     * rejects with the exact error thrown by that dispatch or judge.
+     * Default false preserves the normal behavior of returning failed cells and
+     * continuing the remaining schedule.
+     */
+    abortOnCellError?: boolean;
     /**
      * Per-cell dispatch deadline in ms. A `dispatch` that neither resolves nor
      * rejects within this window is a hang (a stalled model request, an
@@ -2432,6 +2440,26 @@ interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
         generation?: number;
     }) => string | undefined;
 }
+/** Durable `<cell>/failure-receipt.json` written before a failed cell can
+ * trigger campaign-wide cancellation. The cell keeps its dispatch-only usage
+ * fields for compatibility; `cost` covers every settled agent and judge call
+ * attributed to this exact run attempt. */
+interface CampaignCellFailureReceipt<TArtifact = unknown> {
+    schemaVersion: 1;
+    runAttemptId: string;
+    recordedAt: string;
+    failure: {
+        stage: 'dispatch' | 'judge';
+        judge?: string;
+        error: {
+            name: string;
+            message: string;
+            stack?: string;
+        };
+    };
+    cell: CampaignCellResult<TArtifact>;
+    cost: CostLedgerSummary;
+}
 /**
  * Core campaign orchestrator: fan scenarios through dispatch, score with judges, aggregate bootstrap CIs, and persist reproducible `CampaignResult` records.
  */
@@ -6076,4 +6104,4 @@ declare function verifyCodeSurface(surface: CodeSurface, worktreeDir?: string):
  *  identity against the checkout at `worktreeRef`. */
 declare function resolveWorktreePath(surface: CodeSurface, worktreeDir?: string): string;
 
-export { type AnalystArtifact, type AnalystScenario, type AnalyzeCrossSurfaceInteractionsInput, type AxisEvidence, type AxisVerdict, type BuildAnalystSurfaceDispatchOptions, type BuildEvidenceVectorOptions, type BuildLoopProvenanceArgs, type CampaignAggregates, type CampaignArtifactWriter, type CampaignBreakdown, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignRunPlan, type CampaignRunPlanCell, type CampaignScenarioIdentity, type CampaignStorage, type CampaignTokenUsage, type CampaignTraceWriter, type CodeSurface, type CodeSurfaceVerification, type CompareOptimizationMethodsOptions, type ComparisonCost, type ComponentSurface, type CostLedgerHandle, type CrossSurfaceAdditionDecision, type CrossSurfaceAdditionRejectionReason, type CrossSurfaceAttemptCompleteness, type CrossSurfaceBestSingleSelection, type CrossSurfaceBootstrapPolicy, type CrossSurfaceCandidate, type CrossSurfaceCandidateComparison, type CrossSurfaceCandidateEvidence, type CrossSurfaceCandidateOutcome, type CrossSurfaceCandidateSummary, type CrossSurfaceComponent, type CrossSurfaceComponentEvidence, type CrossSurfaceCompositionStep, type CrossSurfaceDistribution, type CrossSurfaceEligibility, type CrossSurfaceEvidenceBreakdown, type CrossSurfaceIneligibilityReason, type CrossSurfaceInteractionAwareSelection, type CrossSurfaceInteractionEffect, type CrossSurfaceInteractionPath, type CrossSurfaceInteractionReport, type CrossSurfaceInteractionTask, type CrossSurfaceNaiveStackSelection, type CrossSurfacePairCompatibility, type CrossSurfacePairEvidence, type CrossSurfacePairIncompatibilityReason, type CrossSurfacePairwiseEntry, type CrossSurfaceRankedSingle, type CrossSurfaceRelativeCost, type CrossSurfaceSelectionPolicy, type CrossSurfaceSelections, type CrossSurfaceTaskRow, type DefaultProductionGateOptions, type DimensionRegression, type DiscriminationScore, type DispatchContext, type DispatchFn, type EmitLoopProvenanceArgs, type EmitLoopProvenanceResult, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type EvidenceVector, type ExternalOptimizationExample, type ExternalTextEvaluationResponse, type ExternalTextOptimizationMethodConfig, type ExternalTextOptimizerContext, type ExternalTextOptimizerResult, type FailureModeRecallJudgeOptions, FileSearchLedger, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaAdaptiveEngineRun, type GepaEngineOptions, type GepaEngineRun, type GepaOptimizationMethodConfig, type GepaOptimizationRecipe, type GepaRunnerCommand, type GitWorktreeAdapterOptions, type HeldOutGateOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type JudgeAggregate, type JudgeConfig, type JudgeDimension, type JudgeScore, type LabelTrust, type LabeledScenarioRecord, type LabeledScenarioSampleArgs, type LabeledScenarioSource, type LabeledScenarioStore, LabeledScenarioStoreError, type LabeledScenarioWrite, type LlmJudgeDimension, type LlmJudgeOptions, type LoadEvalFixtureScenariosOptions, type LoopProvenanceArgsFromResult, type LoopProvenanceBackend, type LoopProvenanceCandidate, type LoopProvenanceEvidence, type LoopProvenanceOptimizationMethod, type LoopProvenanceRecord, type MutableSurface, type NeutralizationGateOptions, type ObjectiveSource, type OpenAICompatibleOptimizerModel, type OpenAutoPrOptions, type OpenAutoPrResult, type OpenSearchLedgerOptions, type OptimizationMethod, type OptimizationMethodComparison, type OptimizationMethodInput, type OptimizationMethodPairwise, type OptimizationMethodProvenance, type OptimizationMethodResult, type OptimizationMethodRunOptions, type OptimizationMethodScore, type OptimizationPackageSource, type OptimizationProposer, type OptimizationTokenUsage, type OptimizerConfig, type OptimizerModelBudget, type PairedHoldout, type ParetoParent, type ParetoSignificanceGateOptions, type PendingCostCallView, type PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PowerPreflight, type PowerPreflightOptions, type PremeasuredOptimizationBaseline, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, type PromotionObjective, type PromotionPolicy, type ProposalTrackContext, type ProposeContext, type ProposedCandidate, type RedactionStatus, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceScenario, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunOptimizationOptions, type RunOptimizationResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, SEARCH_LEDGER_SCHEMA, type Scenario, type ScenarioAggregate, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type ScoredSurfaceOutcome, type SearchAccountingAudit, type SearchArtifactRef, type SearchAttemptAccounting, type SearchCandidateDecidedEvent, type SearchCandidateLineage, type SearchCandidateRegisteredEvent, type SearchCandidateSlot, type SearchCandidateSlotClosedEvent, type SearchCandidateSurface, type SearchCompletedEvent, type SearchCostAccounting, type SearchFailureReason, type SearchLedger, type SearchLedgerAppendResult, SearchLedgerConflictError, type SearchLedgerEntry, SearchLedgerError, type SearchLedgerEvent, type SearchLedgerHash, SearchLedgerIntegrityError, type SearchLedgerReplay, type SearchModelIdentity, type SearchOperationKind, type SearchOperationRecordedEvent, type SearchPlan, type SearchPlannedEvent, type SearchPlannedOperation, type SearchPlannedTask, type SearchSourceRef, type SearchSurfaceEffect, type SearchSurfaceEvidence, type SearchSurfaceKind, type SearchTaskAttemptedEvent, type SearchTaskOutcome, type SearchTokenAccounting, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SessionScript, type SingleRunLock, type SingleRunLockOptions, type SkillOptOptimizationMethodConfig, type SkillOptRunnerCommand, type SkillOptTrainerConfig, type SurfaceProposer, type TraceSpan, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, acquireSingleRunLock, analyzeCrossSurfaceInteractions, assertCampaignDesign, assertCampaignSplitIdentity, assertCodeSurfaceIdentity, assertComponentSurface, buildAnalystSurfaceDispatch, buildEvidenceVector, buildLoopProvenanceRecord, campaignBreakdown, campaignMeanComposite, campaignMeasurementDigest, campaignScenarioIdentity, campaignSplitDigest, campaignSplitDigestFromIdentities, canonicalDigest, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareOptimizationMethods, compareRankKeys, componentSurfaceIdentityMaterial, composeGate, costFromLedgerSummary, createReferenceEquivalenceJudge, createRunCostLedger, defaultProductionGate, detectScale, dimensionRegressions, discoverEvalFixtures, emitLoopProvenance, externalTextOptimizationMethod, failureModeRecallJudge, fsCampaignStorage, gepaOptimizationMethod, gitWorktreeAdapter, heldOutGate, heldoutSignificance, inMemoryCampaignStorage, isProposedCandidate, isTransientTransportFailure, labelTrustRank, llmJudge, loadEvalFixture, loadEvalFixtureScenarios, loopProvenanceArgsFromResult, loopProvenanceSpans, makePlaybackDispatch, neutralizationGate, neutralizeText, openAutoPr, openSearchLedger, optimizationTokenUsageFromSummary, pairHoldout, paretoPolicy, paretoSignificanceGate, planCampaignRun, planEvalFixtureRun, powerPreflight, provenanceRecordPath, provenanceSpansPath, renderScoreboardMarkdown, renderSurfaceDiff, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runCampaign, runEval, runImprovementLoop, runOptimization, runProfileMatrix, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, sequentialDecide, sequentialPairedGate, skillOptOptimizationMethod, surfaceContentHash, surfaceHash, tangleTracesRoot, userStoryScoreboard, validateSearchLedgerEvent, verifyCodeSurface, verifyLoopProvenanceRecord };
+export { type AnalystArtifact, type AnalystScenario, type AnalyzeCrossSurfaceInteractionsInput, type AxisEvidence, type AxisVerdict, type BuildAnalystSurfaceDispatchOptions, type BuildEvidenceVectorOptions, type BuildLoopProvenanceArgs, type CampaignAggregates, type CampaignArtifactWriter, type CampaignBreakdown, type CampaignCellFailureReceipt, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignRunPlan, type CampaignRunPlanCell, type CampaignScenarioIdentity, type CampaignStorage, type CampaignTokenUsage, type CampaignTraceWriter, type CodeSurface, type CodeSurfaceVerification, type CompareOptimizationMethodsOptions, type ComparisonCost, type ComponentSurface, type CostLedgerHandle, type CrossSurfaceAdditionDecision, type CrossSurfaceAdditionRejectionReason, type CrossSurfaceAttemptCompleteness, type CrossSurfaceBestSingleSelection, type CrossSurfaceBootstrapPolicy, type CrossSurfaceCandidate, type CrossSurfaceCandidateComparison, type CrossSurfaceCandidateEvidence, type CrossSurfaceCandidateOutcome, type CrossSurfaceCandidateSummary, type CrossSurfaceComponent, type CrossSurfaceComponentEvidence, type CrossSurfaceCompositionStep, type CrossSurfaceDistribution, type CrossSurfaceEligibility, type CrossSurfaceEvidenceBreakdown, type CrossSurfaceIneligibilityReason, type CrossSurfaceInteractionAwareSelection, type CrossSurfaceInteractionEffect, type CrossSurfaceInteractionPath, type CrossSurfaceInteractionReport, type CrossSurfaceInteractionTask, type CrossSurfaceNaiveStackSelection, type CrossSurfacePairCompatibility, type CrossSurfacePairEvidence, type CrossSurfacePairIncompatibilityReason, type CrossSurfacePairwiseEntry, type CrossSurfaceRankedSingle, type CrossSurfaceRelativeCost, type CrossSurfaceSelectionPolicy, type CrossSurfaceSelections, type CrossSurfaceTaskRow, type DefaultProductionGateOptions, type DimensionRegression, type DiscriminationScore, type DispatchContext, type DispatchFn, type EmitLoopProvenanceArgs, type EmitLoopProvenanceResult, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type EvidenceVector, type ExternalOptimizationExample, type ExternalTextEvaluationResponse, type ExternalTextOptimizationMethodConfig, type ExternalTextOptimizerContext, type ExternalTextOptimizerResult, type FailureModeRecallJudgeOptions, FileSearchLedger, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaAdaptiveEngineRun, type GepaEngineOptions, type GepaEngineRun, type GepaOptimizationMethodConfig, type GepaOptimizationRecipe, type GepaRunnerCommand, type GitWorktreeAdapterOptions, type HeldOutGateOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type JudgeAggregate, type JudgeConfig, type JudgeDimension, type JudgeScore, type LabelTrust, type LabeledScenarioRecord, type LabeledScenarioSampleArgs, type LabeledScenarioSource, type LabeledScenarioStore, LabeledScenarioStoreError, type LabeledScenarioWrite, type LlmJudgeDimension, type LlmJudgeOptions, type LoadEvalFixtureScenariosOptions, type LoopProvenanceArgsFromResult, type LoopProvenanceBackend, type LoopProvenanceCandidate, type LoopProvenanceEvidence, type LoopProvenanceOptimizationMethod, type LoopProvenanceRecord, type MutableSurface, type NeutralizationGateOptions, type ObjectiveSource, type OpenAICompatibleOptimizerModel, type OpenAutoPrOptions, type OpenAutoPrResult, type OpenSearchLedgerOptions, type OptimizationMethod, type OptimizationMethodComparison, type OptimizationMethodInput, type OptimizationMethodPairwise, type OptimizationMethodProvenance, type OptimizationMethodResult, type OptimizationMethodRunOptions, type OptimizationMethodScore, type OptimizationPackageSource, type OptimizationProposer, type OptimizationTokenUsage, type OptimizerConfig, type OptimizerModelBudget, type PairedHoldout, type ParetoParent, type ParetoSignificanceGateOptions, type PendingCostCallView, type PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PowerPreflight, type PowerPreflightOptions, type PremeasuredOptimizationBaseline, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, type PromotionObjective, type PromotionPolicy, type ProposalTrackContext, type ProposeContext, type ProposedCandidate, type RedactionStatus, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceScenario, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunOptimizationOptions, type RunOptimizationResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, SEARCH_LEDGER_SCHEMA, type Scenario, type ScenarioAggregate, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type ScoredSurfaceOutcome, type SearchAccountingAudit, type SearchArtifactRef, type SearchAttemptAccounting, type SearchCandidateDecidedEvent, type SearchCandidateLineage, type SearchCandidateRegisteredEvent, type SearchCandidateSlot, type SearchCandidateSlotClosedEvent, type SearchCandidateSurface, type SearchCompletedEvent, type SearchCostAccounting, type SearchFailureReason, type SearchLedger, type SearchLedgerAppendResult, SearchLedgerConflictError, type SearchLedgerEntry, SearchLedgerError, type SearchLedgerEvent, type SearchLedgerHash, SearchLedgerIntegrityError, type SearchLedgerReplay, type SearchModelIdentity, type SearchOperationKind, type SearchOperationRecordedEvent, type SearchPlan, type SearchPlannedEvent, type SearchPlannedOperation, type SearchPlannedTask, type SearchSourceRef, type SearchSurfaceEffect, type SearchSurfaceEvidence, type SearchSurfaceKind, type SearchTaskAttemptedEvent, type SearchTaskOutcome, type SearchTokenAccounting, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SessionScript, type SingleRunLock, type SingleRunLockOptions, type SkillOptOptimizationMethodConfig, type SkillOptRunnerCommand, type SkillOptTrainerConfig, type SurfaceProposer, type TraceSpan, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, acquireSingleRunLock, analyzeCrossSurfaceInteractions, assertCampaignDesign, assertCampaignSplitIdentity, assertCodeSurfaceIdentity, assertComponentSurface, buildAnalystSurfaceDispatch, buildEvidenceVector, buildLoopProvenanceRecord, campaignBreakdown, campaignMeanComposite, campaignMeasurementDigest, campaignScenarioIdentity, campaignSplitDigest, campaignSplitDigestFromIdentities, canonicalDigest, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareOptimizationMethods, compareRankKeys, componentSurfaceIdentityMaterial, composeGate, costFromLedgerSummary, createReferenceEquivalenceJudge, createRunCostLedger, defaultProductionGate, detectScale, dimensionRegressions, discoverEvalFixtures, emitLoopProvenance, externalTextOptimizationMethod, failureModeRecallJudge, fsCampaignStorage, gepaOptimizationMethod, gitWorktreeAdapter, heldOutGate, heldoutSignificance, inMemoryCampaignStorage, isProposedCandidate, isTransientTransportFailure, labelTrustRank, llmJudge, loadEvalFixture, loadEvalFixtureScenarios, loopProvenanceArgsFromResult, loopProvenanceSpans, makePlaybackDispatch, neutralizationGate, neutralizeText, openAutoPr, openSearchLedger, optimizationTokenUsageFromSummary, pairHoldout, paretoPolicy, paretoSignificanceGate, planCampaignRun, planEvalFixtureRun, powerPreflight, provenanceRecordPath, provenanceSpansPath, renderScoreboardMarkdown, renderSurfaceDiff, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runCampaign, runEval, runImprovementLoop, runOptimization, runProfileMatrix, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, sequentialDecide, sequentialPairedGate, skillOptOptimizationMethod, surfaceContentHash, surfaceHash, tangleTracesRoot, userStoryScoreboard, validateSearchLedgerEvent, verifyCodeSurface, verifyLoopProvenanceRecord };

package/dist/campaign/index.js

@@ -32,7 +32,7 @@ import {
   userStoryScoreboard,
   validateSearchLedgerEvent,
   verifyCodeSurface
-} from "../chunk-Y5CLI4PY.js";
+} from "../chunk-P6WN2KF5.js";
 import {
   acquireSingleRunLock,
   assertCodeSurfaceIdentity,
@@ -79,7 +79,7 @@ import {
   surfaceContentHash,
   surfaceHash,
   verifyLoopProvenanceRecord
-} from "../chunk-7AN2E7BU.js";
+} from "../chunk-3I74FLK6.js";
 import {
   SearchLedgerConflictError,
   SearchLedgerError,
@@ -96,7 +96,7 @@ import {
   resolveRunDir,
   runCampaign,
   tangleTracesRoot
-} from "../chunk-UCLVDLCH.js";
+} from "../chunk-ZVCHKKOP.js";
 import "../chunk-WGXIEX7P.js";
 import "../chunk-ARU2PZFM.js";
 import "../chunk-J5SQWP6Y.js";

package/dist/{chunk-7AN2E7BU.js → chunk-3I74FLK6.js}

@@ -13,7 +13,7 @@ import {
   runCampaign,
   summarizeAgentReceiptIntegrity,
   tryAcquireAtomicFileLock
-} from "./chunk-UCLVDLCH.js";
+} from "./chunk-ZVCHKKOP.js";
 import {
   clamp01,
   combineAbortSignals,
@@ -2040,6 +2040,17 @@ function assertComparisonControls(opts, seed, resamples, confidence) {
       "compareOptimizationMethods: dispatchRef must be trimmed and non-empty when provided"
     );
   }
+  const optimizationDispatchRef = opts.optimizationRunOptions?.dispatchRef;
+  if (optimizationDispatchRef !== void 0 && (typeof optimizationDispatchRef !== "string" || optimizationDispatchRef.trim().length === 0 || optimizationDispatchRef.trim() !== optimizationDispatchRef)) {
+    throw new Error(
+      "compareOptimizationMethods: optimizationRunOptions.dispatchRef must be trimmed and non-empty when provided"
+    );
+  }
+  if (opts.dispatchRef !== void 0 && optimizationDispatchRef !== void 0 && opts.dispatchRef !== optimizationDispatchRef) {
+    throw new Error(
+      "compareOptimizationMethods: dispatchRef must match optimizationRunOptions.dispatchRef when both are provided"
+    );
+  }
   try {
     surfaceContentHash(opts.baselineSurface);
   } catch (cause) {
@@ -2211,6 +2222,7 @@ function createOptimizationMethodInput(opts, methodName, resolvedRunDir, seed, b
     seed,
     runOptions: Object.freeze({
       ...opts.optimizationRunOptions ?? {},
+      ...opts.optimizationRunOptions?.dispatchRef === void 0 && opts.dispatchRef !== void 0 ? { dispatchRef: opts.dispatchRef } : {},
       ...signal ? { signal } : {}
     }),
     costLedger
@@ -3800,28 +3812,30 @@ function externalTextOptimizationMethod(config) {
         )
       );
       const methodDir = `${input.runDir}/external/${safePathComponent(snapshot.name)}`;
-      const runId = externalOptimizerRunKey({
-        material: {
-          optimizer: {
-            kind: snapshot.source.kind,
-            package: snapshot.source.package,
-            version: snapshot.source.version,
-            ...snapshot.source.sourceUrl ? { sourceUrl: snapshot.source.sourceUrl } : {},
-            ...snapshot.source.revision ? { revision: snapshot.source.revision } : {}
-          },
-          method: snapshot.name,
-          evaluationId: snapshot.evaluationId,
-          objective: snapshot.objective,
-          background: snapshot.background ?? "",
-          seed: input.seed,
-          seedCandidate,
-          trainSet,
-          selectionSet,
-          maxEvaluations: snapshot.maxEvaluations,
-          maxOptimizerCostUsd: snapshot.maxOptimizerCostUsd,
-          maxCandidateChars,
-          maxEvidenceChars
+      const runMaterial = {
+        optimizer: {
+          kind: snapshot.source.kind,
+          package: snapshot.source.package,
+          version: snapshot.source.version,
+          ...snapshot.source.sourceUrl ? { sourceUrl: snapshot.source.sourceUrl } : {},
+          ...snapshot.source.revision ? { revision: snapshot.source.revision } : {}
         },
+        method: snapshot.name,
+        evaluationId: snapshot.evaluationId,
+        dispatchRef: input.runOptions.dispatchRef ?? null,
+        objective: snapshot.objective,
+        background: snapshot.background ?? "",
+        seed: input.seed,
+        seedCandidate,
+        trainSet,
+        selectionSet,
+        maxEvaluations: snapshot.maxEvaluations,
+        maxOptimizerCostUsd: snapshot.maxOptimizerCostUsd,
+        maxCandidateChars,
+        maxEvidenceChars
+      };
+      const runId = externalOptimizerRunKey({
+        material: runMaterial,
         attemptId,
         resumeEnabled: resume !== "never"
       });
@@ -5496,6 +5510,7 @@ function gepaOptimizationMethod(config) {
         runtime: runtimeIdentity,
         method: name,
         evaluationId: config.evaluationId,
+        dispatchRef: input.runOptions.dispatchRef ?? null,
         seed: input.seed,
         recipe: snapshotJson(config.recipe, "GEPA run settings"),
         engineModules: config.engineModules ?? [],
@@ -6090,7 +6105,7 @@ async function runImprovementLoop(opts) {
   const dispatchTimeoutMs = opts.dispatchTimeoutMs ?? DEFAULT_DISPATCH_TIMEOUT_MS;
   const optimization = await runOptimization({ ...opts, dispatchTimeoutMs, costLedger });
   const winnerIsBaseline = optimization.winnerSurfaceHash === surfaceHash(opts.baselineSurface);
-  const { runCampaign: runCampaign2 } = await import("./run-campaign-LVFKZCEU.js");
+  const { runCampaign: runCampaign2 } = await import("./run-campaign-FFRM3RH5.js");
   const holdoutDeferred = (opts.holdout ?? "measured") === "deferred";
   const baselineOnHoldout = holdoutDeferred ? await runCampaign2({
     ...opts,
@@ -7033,6 +7048,7 @@ function skillOptOptimizationMethod(config) {
         runtime: runtimeIdentity,
         method: name,
         evaluationId: config.evaluationId,
+        dispatchRef: input.runOptions.dispatchRef ?? null,
         seed: input.seed,
         trainer: snapshotJson(config.trainer, "SkillOpt run settings"),
         objective: config.objective,
@@ -7325,4 +7341,4 @@ export {
   emitLoopProvenance,
   skillOptOptimizationMethod
 };
-//# sourceMappingURL=chunk-7AN2E7BU.js.map
+//# sourceMappingURL=chunk-3I74FLK6.js.map