@rulvar/core 1.42.0 → 1.44.0

package/dist/index.d.ts

@@ -3242,9 +3242,24 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
   * tool ends the loop with status ok; the call's validated `result`
   * argument becomes the agent output (the orchestrator finish
   * tool). The tool's execute never runs, mirroring escalate.
+  * `validate` is the optional host judgment over a schema valid call
+  * (the RV-204 finish validators): ok finishes as before; a rejection
+  * becomes the call's error tool result and the turn continues, so the
+  * model can repair and call the terminal tool again. The hook owns
+  * bounding and journaling; the loop stays policy only and never
+  * throws.
   */
   terminalTool?: {
     name: string;
+    validate?: (call: {
+      id: string;
+      result: unknown;
+    }) => Promise<{
+      ok: true;
+    } | {
+      ok: false;
+      feedback: Record<string, unknown>;
+    }>;
   };
   agentType?: string;
   /** The primary invocation role of the tool loop; default 'loop' (M6-T05). */
@@ -4995,6 +5010,130 @@ declare function workflowSourceRef(runId: string): string;
 declare function hashRunArgs(args: unknown): string | undefined;
 declare function createEngine(options: CreateEngineOptions): Engine;
 //#endregion
+//#region src/orchestrator/finish-validators.d.ts
+/**
+* One child as the finish validators see it (the RV-202 provenance
+* contract): a pure read of the durable state the orchestrator already
+* tracks, identical live and on replay.
+*/
+interface FinishValidationChild {
+  /** The spawn handle (the journal seq, stable across resume). */
+  readonly handle: number;
+  /** The child's node identity, the same one acceptance reasons use. */
+  readonly nodeId: string;
+  /** The terminal status, or 'running' for a child unsettled at finish time. */
+  readonly status: string;
+  /**
+  * The child's full output serialized (a raw string verbatim, anything
+  * else JSON; a failed child's errorMessage), '' while unsettled. The
+  * same serialization the child result evidence tools page.
+  */
+  readonly text: string;
+}
+/** What a {@link FinishValidator} judges. */
+interface FinishValidationInput {
+  /** The finish call's `result` argument exactly as the model passed it. */
+  readonly result: Json | null;
+  /**
+  * The result as text: a string result verbatim, anything else its JSON
+  * serialization (the same convention the child result evidence tools
+  * use), so textual validators never re-implement serialization.
+  */
+  readonly text: string;
+  /**
+  * Every spawned child at finish time, in spawn order (the RV-202
+  * provenance contract). Optional in the TYPE only so hand built
+  * inputs stay source compatible; the orchestrator runtime always
+  * supplies it, so validators can hold the finish result against the
+  * evidence the children actually produced.
+  */
+  readonly children?: readonly FinishValidationChild[];
+}
+/** The verdict of one validator over one finish attempt. */
+type FinishValidationVerdict = {
+  ok: true;
+} | {
+  ok: false;
+  reasons: string[];
+};
+/**
+* A deterministic host validator of the orchestrator finish result.
+* `validate` must be pure, synchronous host code: no model calls, no
+* clock, no filesystem, because a verdict must reproduce on replay and a
+* throwing validator is a host defect that fails the run as ConfigError
+* (never journaled, never granted a repair turn).
+*/
+interface FinishValidator {
+  /**
+  * Unique within one orchestrate call; appears in the journaled
+  * verdicts, the repair feedback, and the orchestrator prompt.
+  */
+  readonly name: string;
+  validate(input: FinishValidationInput): FinishValidationVerdict;
+}
+/**
+* Requires every named section to appear LITERALLY in the result text
+* (a heading like 'FINDINGS' or any marker the goal demands). Default
+* name 'required-sections'; pass `name` to run several instances.
+*/
+declare function requiredSectionsValidator(options: {
+  sections: string[];
+  name?: string;
+}): FinishValidator;
+/**
+* Requires the result to be a JSON object carrying every named field
+* with a substantial value: present, not null, and not an empty or
+* whitespace only string (empty arrays, zero, and false COUNT as
+* present; emptiness rules beyond strings belong to a custom
+* validator). Default name 'required-fields'.
+*/
+declare function requiredFieldsValidator(options: {
+  fields: string[];
+  name?: string;
+}): FinishValidator;
+/** The default citation shape: a path with an extension, a colon, a line number. */
+declare const DEFAULT_CITATION_PATTERN = "[\\w./-]+\\.\\w+:\\d+";
+/** The default preserved share, the improvement plan's RV-202 gate. */
+declare const DEFAULT_EVIDENCE_MIN_SHARE = .95;
+/**
+* The RV-202 evidence preservation contract: the finish result must
+* PRESERVE the citations the children actually produced. Distinct
+* matches of `pattern` are collected across the outputs of children
+* settled 'ok' (spawn order); at least `minShare` of them (default
+* {@link DEFAULT_EVIDENCE_MIN_SHARE}, the plan's 95 percent gate,
+* compared as a ceiling on the required count so an exact boundary like
+* 19 of 20 passes) must appear literally in the result text. Zero child
+* citations pass vacuously. With `requireKnown: true` the contract also
+* runs in reverse: every citation in the RESULT must appear in some
+* child's output, so a fabricated but pattern valid citation is
+* rejected instead of silently counting as evidence. Rejection reasons
+* list the missing (and unknown) citations, capped at 20, so the repair
+* turn can restore them. Purely textual and deterministic; checking
+* that cited targets EXIST on disk is host territory (a custom
+* validator), not this contract. Default name 'evidence-preserved'.
+*/
+declare function evidencePreservedValidator(options?: {
+  pattern?: string;
+  flags?: string;
+  minShare?: number;
+  requireKnown?: boolean;
+  name?: string;
+}): FinishValidator;
+/**
+* Requires at least `min` matches of `pattern` in the result text (the
+* plan's citation and source count checks: a file:line pattern, a URL
+* pattern). The pattern compiles at construction (invalid patterns are a
+* ConfigError before any run exists) and matches globally; `min` is a
+* positive integer. Default name 'min-matches'; pass `name` to run
+* several instances, because names must be unique per orchestrate call.
+*/
+declare function minMatchesValidator(options: {
+  pattern: string;
+  flags?: string;
+  min: number;
+  name?: string;
+}): FinishValidator;
+//#endregion
 //#region src/orchestrator/handles.d.ts
 /** The per-child digest handed to the orchestrator. */
 interface TaskDigest {
@@ -5495,6 +5634,47 @@ interface OrchestrateAcceptance {
     minSuccessful: number;
   };
 }
+/** How many rejected finishes are repaired by default: the plan's repair once. */
+declare const DEFAULT_FINISH_MAX_REPAIRS = 1;
+/**
+* The opt in deterministic validation of the orchestrator finish result
+* (the v1.40.0 improvement plan's RV-204 slice). Every SCHEMA valid
+* finish({ result }) call first passes the configured host validators;
+* a rejection returns the failure reasons to the model as the call's
+* error tool result and the turn continues (a repair turn: the model
+* fixes the result and calls finish again), bounded by maxRepairs. A
+* rejection past the bound fails the run with the typed FailRunError
+* (code 'fail_run', data.source 'orchestrator_finish_validation'),
+* BEFORE the acceptance settle, so acceptance never judges a finish the
+* validators rejected. Every verdict journals as ONE decision entry
+* keyed by the finish call id (decisionType
+* 'orchestrator_finish_validation'), so a resume rolls the SAME
+* verdicts forward without re-running validator code, and the whole
+* exchange replays without new paid calls. The toolset never changes
+* (the contract rides the orchestrator prompt), zero configuration adds
+* zero journal entries, and the budget cap paths keep their posture:
+* the reserved finalize dispatch is never validated, exactly as
+* acceptance never judges it. Repair turns spend from the
+* orchestrator's ordinary limits and ceilings (maxTurns, budget caps,
+* the root budgetUsd); maxRepairs is the explicit bound, and a
+* dedicated repair budget reserve is deliberately out of scope here.
+*/
+interface FinishValidationSpec {
+  /**
+  * Run in configuration order on every schema valid finish call; names
+  * must be unique (pass `name` to a factory to run several instances).
+  * A validator that THROWS is a host defect: the run fails as
+  * ConfigError, nothing journals, and no repair turn is granted.
+  */
+  validators: FinishValidator[];
+  /**
+  * How many rejected finishes are returned to the model for repair
+  * before the run fails; a nonnegative integer, default
+  * {@link DEFAULT_FINISH_MAX_REPAIRS}. Zero means the first rejected
+  * finish fails the run.
+  */
+  maxRepairs?: number;
+}
 interface OrchestrateOptions {
   model?: ModelSpec;
   /** Registered profile names to advertise; default: every profile. */
@@ -5529,6 +5709,11 @@ interface OrchestrateOptions {
   /** The opt in child completion policy; see {@link OrchestrateAcceptance}. */
   acceptance?: OrchestrateAcceptance;
   /**
+  * The opt in deterministic host validation of the finish result, with
+  * bounded repair; see {@link FinishValidationSpec}.
+  */
+  finishValidation?: FinishValidationSpec;
+  /**
   * Opt in to the evidence tools `get_child_result` and
   * `read_child_artifact` (the v1.40.0 improvement plan's narrow RV-201
   * slice). The digest an await returns is a wake signal truncated to 400
@@ -7039,4 +7224,4 @@ interface SandboxBridge {
 declare const SANDBOX_AGENT_OPT_KEYS: readonly string[];
 declare function createSandboxBridge(ctx: Ctx<never>, options: SandboxBridgeOptions): SandboxBridge;
 //#endregion
-export { AWAIT_SCHEMA, AbandonAttempt, AbandonFold, AbandonPayload, AbandonedSpendView, AbortClass, type AdaptiveEvents, AdmissionController, AdmissionDecision, AdmissionRejectedError, AdmissionStatsBefore, AdmitLineage, AdmitRejectReason, AdmitSpec, AdmitVerdict, AgentCallError, AgentError, type AgentEvents, AgentIdentityInput, AgentOpts, AgentProfile, AgentProfilePermissions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, BUDGET_ABORT_REASON, BaseAppend, BriefOpts, BudgetAccountView, BudgetDefaults, BudgetExhaustedError, BudgetExhaustionDiagnostics, BudgetHooks, BudgetReserve, type Bytes, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, CacheHint, CacheTtl, CanUseTool, CanonicalId, CanonicalIdentity, CanonicalLadderSpec, CanonicalModelSpec, ChatEvent, ChatRequest, CheckpointState, ChildArtifactPage, ChildIdentityInput, ChildResultPage, type ClaimClass, type ClaimOp, type ClaimStatus, ClaimValidationOptions, CollectOpts, CollectedTurn, CompactionConfig, CompiledPermissionChain, CompiledWorkflow, ConfigError, type CoreEvents, CostAttribution, CostAttributionFacts, CostReport, CreateEngineOptions, Ctx, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DerivedKey, DeriverRegistry, DispositionRule, DispositionTable, DonorCandidate, DonorRef, DroppedItem, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EffectiveUsageLimits, Effort, Engine, EngineDefaults, EntryKind, EntryRef, EntryStatus, ErrorClass, ErrorCode, ErrorPolicy, EscalatedResult, EscalationDecision, EscalationDecisionAbortedError, EscalationDigest, EscalationKind, EscalationLimits, EscalationOptions, EscalationReport, EscalationRequest, EventBus, type EvidenceRef, ExtensionAppendInput, ExtensionDispatchSpec, ExternalIdentityInput, ExternalRegistry, ExtractNecessityInput, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FailoverTarget, FailoverTrigger, FallbackField, FallbackTrigger, FileModelKnowledgeStore, FileModelKnowledgeStoreOptions, FileTranscriptStore, FinishInfo, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, Gate, GateAudit, type GateRecord, GitWorktreeProvider, GitWorktreeProviderOptions, GraftBoot, HashVersion, HookVerdict, INBOX_PROPOSAL_TTL_DAYS, IdentityInput, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, InvocationRole, type IsolationProvider, type IsolationSpec, Issue$1 as Issue, JournalCompatSubCode, JournalCompatibilityError, JournalEntry, JournalMatcher, JournalMissError, JournalOperation, JournalOrderViolation, JournalSerializationHook, type JournalStore, type Json, JsonSchema, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, type KbProposal, type KbProposalTrigger, KeyDeriver, KeyRing, KeyedLimiter, KnowledgeCasError, type KnowledgeSnapshot, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LadderSpec, type LeasableStore, type Lease, LeaseHeldError, Ledger, LineageCounters, LineageIndex, LineageRef, LineageRelation, LineageStats, LogicalTaskId, MASKED_SECRET, MAX_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, MatchResult, McpConfig, McpToolSource, MechanicalGateProfile, MechanicalGateVerdict, type MetaLookupStore, type ModelCaps, ModelChoice, type ModelClaim, ModelEpochInputs, type ModelKnowledgeHandle, type ModelKnowledgeStore, ModelListConstraint, ModelRef, ModelRetry, ModelSpec, Msg, NoProgressDetector, NodeId, NodeLinkValue, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OnEscalation, OperationDisposition, OrchestrateAcceptance, OrchestrateOptions, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, PhaseTarget, PipelineCollected, PipelineOpts, PlanInvariantError, PriceTable, PricedUsage, type Pricing, type PricingTier, type ProviderAdapter, QualityFloors, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RandIdentityInput, RandPayload, RefEntryAppender, RefEntryClassification, RefusalInfo, ReplayDisposition, ReplayMode, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionAttempt, ResolutionBy, ResolutionFold, ResolutionLayer, ResolutionOutcome, ResolutionPayload, ResolvedInvocation, ResolvedToolset, ResumeHandle, ResumeOptions, ResumePreview, ResumeReport, RetryClass, RetryPolicy, ReuseConfig, RiskRuleValue, Role, RulvarError, RulvarErrorCode, RunAgentOptions, RunBudget, RunEventSink, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStatus, RuntimeEventSink, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxBridge, SandboxBridgeOptions, SandboxError, SandboxHostToWorker, SandboxMethod, SandboxWorkerToHost, SchemaPair, SchemaSpec, SchemaValidationResult, ScopeSegment, ScriptRejected, ScriptRunner, ScrubNote, Semaphore, SerializationHook, Settled, ShellPatternRules, ShellSegment, ShellVerdict, SinglePhaseAppend, SpanMinter, SpanRegistry, SpawnAdmissionValue, SpawnAgentParams, SpawnKey, SpawnLineage, SpawnLineageOpt, SpawnOrigin, SpawnRecord, Spend, Stage, type StandardJSONSchemaV1, type StandardSchemaV1, StepIdentityInput, StructuredOutputTier, SuspendedAppend, SuspensionState, TOOL_NAME_PATTERN, type TaskClass, TaskDigest, TaskSpec, TerminalPatch, TerminationAccount, TerminationAccountSnapshot, TerminationDeniedValue, TerminationDeniedWriter, TerminationInitValue, TerminationLimits, TerminationResource, ToolCallRequest, ToolChoice, type ToolContext, ToolContextSeed, ToolContract, type ToolDef, type ToolEvents, type ToolExecutor, ToolInit, type ToolRisk, ToolRuntime, type ToolSource, type ToolSourceSession, ToolsOption, TranscriptSerializationHook, type TranscriptStore, TriggerClass, TtlState, Usage, UsageLimits, UsageSlice, VerifiedRecommendation, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, WakeBudgetBlock, WakeDigest, WakeTrigger, WireError, Workflow, WorkflowCallOpts, type WorkflowEvent, type WorkflowEventBody, WorkflowRegistry, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, atCompactionThreshold, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hasMetaLookup, hashRunArgs, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, metaMatchesFilter, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readRunMeta, readTerminationInit, registryKeyRing, remeasureQueue, replayDisposition, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };
+export { AWAIT_SCHEMA, AbandonAttempt, AbandonFold, AbandonPayload, AbandonedSpendView, AbortClass, type AdaptiveEvents, AdmissionController, AdmissionDecision, AdmissionRejectedError, AdmissionStatsBefore, AdmitLineage, AdmitRejectReason, AdmitSpec, AdmitVerdict, AgentCallError, AgentError, type AgentEvents, AgentIdentityInput, AgentOpts, AgentProfile, AgentProfilePermissions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, BUDGET_ABORT_REASON, BaseAppend, BriefOpts, BudgetAccountView, BudgetDefaults, BudgetExhaustedError, BudgetExhaustionDiagnostics, BudgetHooks, BudgetReserve, type Bytes, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, CacheHint, CacheTtl, CanUseTool, CanonicalId, CanonicalIdentity, CanonicalLadderSpec, CanonicalModelSpec, ChatEvent, ChatRequest, CheckpointState, ChildArtifactPage, ChildIdentityInput, ChildResultPage, type ClaimClass, type ClaimOp, type ClaimStatus, ClaimValidationOptions, CollectOpts, CollectedTurn, CompactionConfig, CompiledPermissionChain, CompiledWorkflow, ConfigError, type CoreEvents, CostAttribution, CostAttributionFacts, CostReport, CreateEngineOptions, Ctx, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_CITATION_PATTERN, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_EVIDENCE_MIN_SHARE, DEFAULT_FINISH_MAX_REPAIRS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DerivedKey, DeriverRegistry, DispositionRule, DispositionTable, DonorCandidate, DonorRef, DroppedItem, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EffectiveUsageLimits, Effort, Engine, EngineDefaults, EntryKind, EntryRef, EntryStatus, ErrorClass, ErrorCode, ErrorPolicy, EscalatedResult, EscalationDecision, EscalationDecisionAbortedError, EscalationDigest, EscalationKind, EscalationLimits, EscalationOptions, EscalationReport, EscalationRequest, EventBus, type EvidenceRef, ExtensionAppendInput, ExtensionDispatchSpec, ExternalIdentityInput, ExternalRegistry, ExtractNecessityInput, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FailoverTarget, FailoverTrigger, FallbackField, FallbackTrigger, FileModelKnowledgeStore, FileModelKnowledgeStoreOptions, FileTranscriptStore, FinishInfo, FinishValidationChild, FinishValidationInput, FinishValidationSpec, FinishValidationVerdict, FinishValidator, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, Gate, GateAudit, type GateRecord, GitWorktreeProvider, GitWorktreeProviderOptions, GraftBoot, HashVersion, HookVerdict, INBOX_PROPOSAL_TTL_DAYS, IdentityInput, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, InvocationRole, type IsolationProvider, type IsolationSpec, Issue$1 as Issue, JournalCompatSubCode, JournalCompatibilityError, JournalEntry, JournalMatcher, JournalMissError, JournalOperation, JournalOrderViolation, JournalSerializationHook, type JournalStore, type Json, JsonSchema, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, type KbProposal, type KbProposalTrigger, KeyDeriver, KeyRing, KeyedLimiter, KnowledgeCasError, type KnowledgeSnapshot, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LadderSpec, type LeasableStore, type Lease, LeaseHeldError, Ledger, LineageCounters, LineageIndex, LineageRef, LineageRelation, LineageStats, LogicalTaskId, MASKED_SECRET, MAX_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, MatchResult, McpConfig, McpToolSource, MechanicalGateProfile, MechanicalGateVerdict, type MetaLookupStore, type ModelCaps, ModelChoice, type ModelClaim, ModelEpochInputs, type ModelKnowledgeHandle, type ModelKnowledgeStore, ModelListConstraint, ModelRef, ModelRetry, ModelSpec, Msg, NoProgressDetector, NodeId, NodeLinkValue, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OnEscalation, OperationDisposition, OrchestrateAcceptance, OrchestrateOptions, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, PhaseTarget, PipelineCollected, PipelineOpts, PlanInvariantError, PriceTable, PricedUsage, type Pricing, type PricingTier, type ProviderAdapter, QualityFloors, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RandIdentityInput, RandPayload, RefEntryAppender, RefEntryClassification, RefusalInfo, ReplayDisposition, ReplayMode, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionAttempt, ResolutionBy, ResolutionFold, ResolutionLayer, ResolutionOutcome, ResolutionPayload, ResolvedInvocation, ResolvedToolset, ResumeHandle, ResumeOptions, ResumePreview, ResumeReport, RetryClass, RetryPolicy, ReuseConfig, RiskRuleValue, Role, RulvarError, RulvarErrorCode, RunAgentOptions, RunBudget, RunEventSink, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStatus, RuntimeEventSink, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxBridge, SandboxBridgeOptions, SandboxError, SandboxHostToWorker, SandboxMethod, SandboxWorkerToHost, SchemaPair, SchemaSpec, SchemaValidationResult, ScopeSegment, ScriptRejected, ScriptRunner, ScrubNote, Semaphore, SerializationHook, Settled, ShellPatternRules, ShellSegment, ShellVerdict, SinglePhaseAppend, SpanMinter, SpanRegistry, SpawnAdmissionValue, SpawnAgentParams, SpawnKey, SpawnLineage, SpawnLineageOpt, SpawnOrigin, SpawnRecord, Spend, Stage, type StandardJSONSchemaV1, type StandardSchemaV1, StepIdentityInput, StructuredOutputTier, SuspendedAppend, SuspensionState, TOOL_NAME_PATTERN, type TaskClass, TaskDigest, TaskSpec, TerminalPatch, TerminationAccount, TerminationAccountSnapshot, TerminationDeniedValue, TerminationDeniedWriter, TerminationInitValue, TerminationLimits, TerminationResource, ToolCallRequest, ToolChoice, type ToolContext, ToolContextSeed, ToolContract, type ToolDef, type ToolEvents, type ToolExecutor, ToolInit, type ToolRisk, ToolRuntime, type ToolSource, type ToolSourceSession, ToolsOption, TranscriptSerializationHook, type TranscriptStore, TriggerClass, TtlState, Usage, UsageLimits, UsageSlice, VerifiedRecommendation, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, WakeBudgetBlock, WakeDigest, WakeTrigger, WireError, Workflow, WorkflowCallOpts, type WorkflowEvent, type WorkflowEventBody, WorkflowRegistry, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, atCompactionThreshold, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hasMetaLookup, hashRunArgs, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, metaMatchesFilter, minMatchesValidator, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readRunMeta, readTerminationInit, registryKeyRing, remeasureQueue, replayDisposition, requiredFieldsValidator, requiredSectionsValidator, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };

package/dist/index.js

@@ -8920,6 +8920,21 @@ async function runAgent(options) {
 					}));
 					continue;
 				}
+				const finishArgs = validation.value;
+				const hostVerdict = options.terminalTool.validate === void 0 ? void 0 : await options.terminalTool.validate({
+					id: call.id,
+					result: finishArgs.result ?? null
+				});
+				if (hostVerdict !== void 0 && !hostVerdict.ok) {
+					events?.emit({
+						type: "tool:end",
+						toolName: gatedCall.name,
+						outcome: "error",
+						durationMs: now() - gateStartedAt
+					});
+					parts.push(errorPart(call, hostVerdict.feedback));
+					continue;
+				}
 				events?.emit({
 					type: "tool:end",
 					toolName: gatedCall.name,
@@ -8935,7 +8950,7 @@ async function runAgent(options) {
 				return {
 					parts,
 					limitHit: false,
-					finished: validation.value.result ?? null
+					finished: finishArgs.result ?? null
 				};
 			}
 			toolCallsUsed += 1;
@@ -10569,6 +10584,163 @@ var AdmissionController = class {
 	}
 };
 //#endregion
+//#region src/orchestrator/finish-validators.ts
+/**
+* Deterministic host validation of the orchestrator finish result (the
+* v1.40.0 improvement plan's RV-204 slice). A validator is plain
+* synchronous host code judging the finish({ result }) argument; the
+* orchestrator runtime runs the configured set on every schema valid
+* finish call, returns the failure reasons to the model as the call's
+* error tool result (a bounded repair turn), and fails the run with a
+* typed error when the repair bound is exhausted. Verdicts journal as
+* decision entries, so a resume rolls the SAME verdicts forward without
+* re-running validator code.
+*/
+const ok = { ok: true };
+function requireNonEmptyStrings(values, what) {
+	if (!Array.isArray(values) || values.length === 0) throw new ConfigError(`${what} must be a non empty array of strings`);
+	for (const value of values) if (typeof value !== "string" || value.length === 0) throw new ConfigError(`${what} must contain only non empty strings`);
+	return values;
+}
+/**
+* Requires every named section to appear LITERALLY in the result text
+* (a heading like 'FINDINGS' or any marker the goal demands). Default
+* name 'required-sections'; pass `name` to run several instances.
+*/
+function requiredSectionsValidator(options) {
+	const sections = requireNonEmptyStrings(options.sections, "requiredSectionsValidator sections");
+	return {
+		name: options.name ?? "required-sections",
+		validate: (input) => {
+			const missing = sections.filter((section) => !input.text.includes(section));
+			return missing.length === 0 ? ok : {
+				ok: false,
+				reasons: missing.map((section) => `required section '${section}' is missing`)
+			};
+		}
+	};
+}
+/**
+* Requires the result to be a JSON object carrying every named field
+* with a substantial value: present, not null, and not an empty or
+* whitespace only string (empty arrays, zero, and false COUNT as
+* present; emptiness rules beyond strings belong to a custom
+* validator). Default name 'required-fields'.
+*/
+function requiredFieldsValidator(options) {
+	const fields = requireNonEmptyStrings(options.fields, "requiredFieldsValidator fields");
+	return {
+		name: options.name ?? "required-fields",
+		validate: (input) => {
+			const result = input.result;
+			if (typeof result !== "object" || result === null || Array.isArray(result)) return {
+				ok: false,
+				reasons: ["the finish result is not a JSON object"]
+			};
+			const record = result;
+			const reasons = [];
+			for (const field of fields) {
+				const value = record[field];
+				if (value === void 0 || value === null) reasons.push(`required field '${field}' is missing`);
+				else if (typeof value === "string" && value.trim().length === 0) reasons.push(`required field '${field}' is empty`);
+			}
+			return reasons.length === 0 ? ok : {
+				ok: false,
+				reasons
+			};
+		}
+	};
+}
+/** The default citation shape: a path with an extension, a colon, a line number. */
+const DEFAULT_CITATION_PATTERN = "[\\w./-]+\\.\\w+:\\d+";
+/** The default preserved share, the improvement plan's RV-202 gate. */
+const DEFAULT_EVIDENCE_MIN_SHARE = .95;
+const MAX_LISTED_CITATIONS = 20;
+function listCitations(values) {
+	return values.length <= MAX_LISTED_CITATIONS ? values.join(", ") : `${values.slice(0, MAX_LISTED_CITATIONS).join(", ")} and ${String(values.length - MAX_LISTED_CITATIONS)} more`;
+}
+/**
+* The RV-202 evidence preservation contract: the finish result must
+* PRESERVE the citations the children actually produced. Distinct
+* matches of `pattern` are collected across the outputs of children
+* settled 'ok' (spawn order); at least `minShare` of them (default
+* {@link DEFAULT_EVIDENCE_MIN_SHARE}, the plan's 95 percent gate,
+* compared as a ceiling on the required count so an exact boundary like
+* 19 of 20 passes) must appear literally in the result text. Zero child
+* citations pass vacuously. With `requireKnown: true` the contract also
+* runs in reverse: every citation in the RESULT must appear in some
+* child's output, so a fabricated but pattern valid citation is
+* rejected instead of silently counting as evidence. Rejection reasons
+* list the missing (and unknown) citations, capped at 20, so the repair
+* turn can restore them. Purely textual and deterministic; checking
+* that cited targets EXIST on disk is host territory (a custom
+* validator), not this contract. Default name 'evidence-preserved'.
+*/
+function evidencePreservedValidator(options) {
+	const pattern = options?.pattern ?? "[\\w./-]+\\.\\w+:\\d+";
+	const flags = options?.flags ?? "";
+	const globalFlags = flags.includes("g") ? flags : `${flags}g`;
+	try {
+		new RegExp(pattern, globalFlags);
+	} catch (thrown) {
+		throw new ConfigError(`evidencePreservedValidator pattern does not compile: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+	}
+	const minShare = options?.minShare ?? .95;
+	if (typeof minShare !== "number" || !Number.isFinite(minShare) || minShare <= 0 || minShare > 1) throw new ConfigError(`evidencePreservedValidator minShare must be a number in (0, 1]; got ${String(minShare)}`);
+	return {
+		name: options?.name ?? "evidence-preserved",
+		validate: (input) => {
+			const cited = /* @__PURE__ */ new Set();
+			for (const child of input.children ?? []) {
+				if (child.status !== "ok") continue;
+				for (const match of child.text.match(new RegExp(pattern, globalFlags)) ?? []) cited.add(match);
+			}
+			const reasons = [];
+			if (cited.size > 0) {
+				const missing = [...cited].filter((citation) => !input.text.includes(citation));
+				const preserved = cited.size - missing.length;
+				if (preserved < Math.ceil(minShare * cited.size - 1e-9)) reasons.push(`evidence preservation ${String(preserved)} of ${String(cited.size)} child citations is below the required share ${String(minShare)}; missing: ${listCitations(missing)}`);
+			}
+			if (options?.requireKnown === true) {
+				const fabricated = [...new Set(input.text.match(new RegExp(pattern, globalFlags)) ?? [])].filter((citation) => !cited.has(citation));
+				if (fabricated.length > 0) reasons.push(`unknown citations not present in any child report: ${listCitations(fabricated)}`);
+			}
+			return reasons.length === 0 ? ok : {
+				ok: false,
+				reasons
+			};
+		}
+	};
+}
+/**
+* Requires at least `min` matches of `pattern` in the result text (the
+* plan's citation and source count checks: a file:line pattern, a URL
+* pattern). The pattern compiles at construction (invalid patterns are a
+* ConfigError before any run exists) and matches globally; `min` is a
+* positive integer. Default name 'min-matches'; pass `name` to run
+* several instances, because names must be unique per orchestrate call.
+*/
+function minMatchesValidator(options) {
+	const flags = options.flags ?? "";
+	const globalFlags = flags.includes("g") ? flags : `${flags}g`;
+	try {
+		new RegExp(options.pattern, globalFlags);
+	} catch (thrown) {
+		throw new ConfigError(`minMatchesValidator pattern does not compile: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+	}
+	if (!Number.isInteger(options.min) || options.min < 1) throw new ConfigError(`minMatchesValidator min must be a positive integer; got ${String(options.min)}`);
+	return {
+		name: options.name ?? "min-matches",
+		validate: (input) => {
+			const found = input.text.match(new RegExp(options.pattern, globalFlags))?.length ?? 0;
+			return found >= options.min ? ok : {
+				ok: false,
+				reasons: [`expected at least ${String(options.min)} matches of /${options.pattern}/${flags}; found ${String(found)}`]
+			};
+		}
+	};
+}
+//#endregion
 //#region src/orchestrator/handles.ts
 /**
 * The committed WakeDigest render budget (Appendix A: 400
@@ -10929,7 +11101,9 @@ const kOnRunning = Symbol("rulvar.onRunning");
 /**
 * Internal AgentOpts channel (M6-T07): names the terminal tool whose
 * accepted call ends the loop with status ok (the orchestrator finish
-* tool). Never part of the public AgentOpts surface.
+* tool), plus the optional host validation hook over the accepted call
+* (the RV-204 finish validators). Never part of the public AgentOpts
+* surface.
 */
 const kTerminalTool = Symbol("rulvar.terminalTool");
 /**
@@ -12549,6 +12723,8 @@ async function executeWorkflow(internals, wf, args) {
 * cap, maxDepth, and the budget layers apply; no termination.init is
 * written; escalated children simply settle into their digests.
 */
+/** How many rejected finishes are repaired by default: the plan's repair once. */
+const DEFAULT_FINISH_MAX_REPAIRS = 1;
 const ORCHESTRATE_WORKFLOW_NAME = "rulvar-orchestrate";
 /**
 * One page of a string, for the child result evidence tools: maxChars is
@@ -12593,6 +12769,19 @@ function validateOrchestrateOptions(opts) {
 		if (policy !== "all-ok" && minSuccessful === void 0) throw new ConfigError(`orchestrate acceptance.childPolicy must be 'all-ok' or { minSuccessful: N }; got ${JSON.stringify(policy)}`);
 		if (policy !== "all-ok") requirePositiveInteger(minSuccessful, "orchestrate acceptance.childPolicy.minSuccessful");
 	}
+	if (opts.finishValidation !== void 0) {
+		const fv = opts.finishValidation;
+		if (!Array.isArray(fv.validators) || fv.validators.length === 0) throw new ConfigError("orchestrate finishValidation.validators must be a non empty array of validators");
+		const seen = /* @__PURE__ */ new Set();
+		for (const candidate of fv.validators) {
+			const validator = candidate;
+			if (typeof validator.name !== "string" || validator.name.length === 0) throw new ConfigError("every orchestrate finish validator must carry a non empty string name");
+			if (typeof validator.validate !== "function") throw new ConfigError(`orchestrate finish validator '${validator.name}' has no validate function`);
+			if (seen.has(validator.name)) throw new ConfigError(`orchestrate finishValidation.validators names must be unique; '${validator.name}' repeats (pass name to the factory to run several instances)`);
+			seen.add(validator.name);
+		}
+		if (fv.maxRepairs !== void 0) requireNonNegativeInteger(fv.maxRepairs, "orchestrate finishValidation.maxRepairs");
+	}
 	const spec = opts.budget;
 	if (spec === void 0) return;
 	if (spec.capUsd !== void 0) requireNonNegativeNumber(spec.capUsd, "orchestrate budget.capUsd");
@@ -12614,6 +12803,18 @@ function orchestratorPrompt(goal, maxSpawns, extensionLines) {
 	].join("\n");
 }
 /**
+* The finish validation contract rides the PROMPT, never the toolset:
+* the finish tool definition stays byte identical in every
+* configuration, so the orchestrator toolset hash never moves (stricter
+* than the evidence tools opt in, which changes it by design).
+*/
+function finishValidationPromptLines(spec) {
+	if (spec === void 0) return [];
+	const names = spec.validators.map((validator) => validator.name).join(", ");
+	const repairs = spec.maxRepairs ?? 1;
+	return [`The host validates every finish({ result }) with deterministic validators: ${names}.`, "A rejected finish returns the failure reasons as the tool error result; repair the result and call finish again. " + (repairs === 0 ? "No repair attempt is granted: the first rejected finish fails the run." : repairs === 1 ? "At most one repair attempt is granted before the run fails." : `At most ${String(repairs)} repair attempts are granted before the run fails.`)];
+}
+/**
 * Resolves per-spawn dispatch options against the engine registries
 * (registered SchemaSpec and tool profile names; M7-T05). An
 * unknown ref is a typed ConfigError, surfaced as a tool error to the
@@ -13448,10 +13649,116 @@ function makeOrchestratorWorkflow(goal, opts) {
 				}
 			});
 		}
+		const tools = [...buildOrchestratorTools(orchestratorRuntime, fullCardText, { childResultTools: opts?.exposeChildResultTools === true }), ...extension?.tools(io) ?? []];
+		/**
+		* The RV-204 finish validation hook, installed on the terminal tool
+		* channel only when validators are configured (zero configuration =
+		* zero new journal entries and byte identical loop behavior; the
+		* toolset never changes either way). Verdicts are decision entries
+		* keyed by the finish call id: a replayed call returns the JOURNALED
+		* verdict without re-running validator code, so the accepted result,
+		* every repair exchange, and the final rejection reproduce on resume
+		* even when the live validators drifted (the acceptance precedent).
+		* The final rejection journals verdict 'rejected', arms the typed
+		* FailRunError, and aborts the loop; the settle path throws it
+		* BEFORE the acceptance settle (and the boot scan covers the crash
+		* window between the entry and the run terminal), so acceptance
+		* never judges a finish the validators rejected. A THROWING
+		* validator is a host defect: the run fails as ConfigError, nothing
+		* journals, and no repair turn is granted, so a fixed validator
+		* re-runs live on the next resume.
+		*/
+		const validationSpec = opts?.finishValidation;
+		const validationAbort = new AbortController();
+		let validationTermination;
+		const finishValidationError = (decision) => new FailRunError(`the orchestrator finish failed host validation with all ${String(decision.maxRepairs)} repair attempts spent: ` + decision.failed.map((f) => `validator '${f.name}' rejected: ${f.reasons.join("; ")}`).join("; "), { data: {
+			source: "orchestrator_finish_validation",
+			callId: decision.callId,
+			failed: decision.failed,
+			repairsUsed: decision.repairsUsed,
+			maxRepairs: decision.maxRepairs
+		} });
+		const validationDecisions = () => internals.replayer.snapshot().filter((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.value?.decisionType === "orchestrator_finish_validation").map((entry) => entry.value);
+		const validateFinish = async (call) => {
+			if (validationSpec === void 0) return { ok: true };
+			const maxRepairs = validationSpec.maxRepairs ?? 1;
+			const known = validationDecisions();
+			let decision = known.find((candidate) => candidate.callId === call.id);
+			if (decision === void 0) {
+				const result = call.result ?? null;
+				const children = [...records.values()].sort((a, b) => a.spawnOrdinal - b.spawnOrdinal).map((record) => ({
+					handle: record.handle,
+					nodeId: record.nodeId,
+					status: record.settled?.status ?? "running",
+					text: record.settled === void 0 ? "" : serializeChildOutput(record.settled)
+				}));
+				const input = {
+					result,
+					text: typeof result === "string" ? result : JSON.stringify(result),
+					children
+				};
+				const failed = [];
+				for (const validator of validationSpec.validators) {
+					let verdict;
+					try {
+						verdict = validator.validate(input);
+					} catch (thrown) {
+						validationTermination = new ConfigError(`finish validator '${validator.name}' threw instead of returning a verdict: ` + (thrown instanceof Error ? thrown.message : String(thrown)));
+						validationAbort.abort("rulvar:finish-validation");
+						return {
+							ok: false,
+							feedback: { error: `finish validator '${validator.name}' is defective; the run fails` }
+						};
+					}
+					if (!verdict.ok) failed.push({
+						name: validator.name,
+						reasons: verdict.reasons
+					});
+				}
+				const repairsUsed = known.filter((candidate) => candidate.verdict !== "accepted").length;
+				decision = {
+					decisionType: "orchestrator_finish_validation",
+					callId: call.id,
+					verdict: failed.length === 0 ? "accepted" : repairsUsed < maxRepairs ? "repair" : "rejected",
+					failed,
+					repairsUsed,
+					maxRepairs
+				};
+				await internals.replayer.appendSinglePhase({
+					scope: callingState.scope,
+					key: `finish-validation:${call.id}`,
+					kind: "decision",
+					status: "ok",
+					spanId: internals.spans.mint(callingState.spanId),
+					site: "orchestrator-finish-validation",
+					value: decision
+				});
+			}
+			if (decision.verdict === "accepted") return { ok: true };
+			if (decision.verdict === "rejected") {
+				validationTermination = finishValidationError(decision);
+				validationAbort.abort("rulvar:finish-validation");
+				return {
+					ok: false,
+					feedback: {
+						error: "the finish result failed host validation and the repair bound is exhausted; the run fails",
+						failed: decision.failed
+					}
+				};
+			}
+			return {
+				ok: false,
+				feedback: {
+					error: "the finish result failed host validation; repair the result and call finish again",
+					failed: decision.failed,
+					repairsRemaining: decision.maxRepairs - decision.repairsUsed - 1
+				}
+			};
+		};
 		const agentOpts = {
 			role: "orchestrate",
 			result: "full",
-			tools: [...buildOrchestratorTools(orchestratorRuntime, fullCardText, { childResultTools: opts?.exposeChildResultTools === true }), ...extension?.tools(io) ?? []],
+			tools,
 			...capState === void 0 ? {} : { estCost: capState.effectiveCapUsd - (orchestratorAccount === void 0 ? 0 : internals.budget.accountView(orchestratorAccount)?.finalizeReserveUsd ?? 0) },
 			...opts?.model === void 0 ? {} : { model: opts.model },
 			...opts?.limits === void 0 ? {} : { limits: opts.limits },
@@ -13460,7 +13767,10 @@ function makeOrchestratorWorkflow(goal, opts) {
 				orchSeq = seq;
 				recover().then(releaseRecovery, releaseRecovery);
 			},
-			[kTerminalTool]: { name: FINISH_TOOL_NAME },
+			[kTerminalTool]: {
+				name: FINISH_TOOL_NAME,
+				...validationSpec === void 0 ? {} : { validate: validateFinish }
+			},
 			...(() => {
 				const priorCancelledRoot = internals.replayer.snapshot().filter((entry) => entry.kind === "agent" && entry.scope === callingState.scope && entry.status === "cancelled" && entry.checkpointRef !== void 0).at(-1);
 				return priorCancelledRoot?.checkpointRef === void 0 ? {} : { [kBootCheckpoint]: priorCancelledRoot.checkpointRef };
@@ -13468,7 +13778,8 @@ function makeOrchestratorWorkflow(goal, opts) {
 		};
 		const orchestratorState = { ...callingState };
 		if (orchestratorAccount !== void 0) orchestratorState.budgetScope = orchestratorAccount;
-		orchestratorState.signal = callingState.signal === void 0 ? forcedFinishController.signal : AbortSignal.any([callingState.signal, forcedFinishController.signal]);
+		const loopBreakSignal = validationSpec === void 0 ? forcedFinishController.signal : AbortSignal.any([forcedFinishController.signal, validationAbort.signal]);
+		orchestratorState.signal = callingState.signal === void 0 ? loopBreakSignal : AbortSignal.any([callingState.signal, loopBreakSignal]);
 		/**
 		* The reserved final wake: a FRESH agent entry on
 		* the restricted single-tool toolset (a different toolsetHash), a
@@ -13556,10 +13867,16 @@ function makeOrchestratorWorkflow(goal, opts) {
 		const bootTermination = extensionTermination;
 		if (bootTermination !== void 0) throw bootTermination;
 		if (capDecisionRef !== void 0) return await settleCapOutcome();
-		const result = await runtime.runInScope(orchestratorState, () => ctx.agent(orchestratorPrompt(goal, opts?.maxSpawns, extension?.promptLines?.()), agentOpts));
+		if (validationSpec !== void 0) {
+			const priorRejection = validationDecisions().find((decision) => decision.verdict === "rejected");
+			if (priorRejection !== void 0) throw finishValidationError(priorRejection);
+		}
+		const promptLines = [...extension?.promptLines?.() ?? [], ...finishValidationPromptLines(validationSpec)];
+		const result = await runtime.runInScope(orchestratorState, () => ctx.agent(orchestratorPrompt(goal, opts?.maxSpawns, promptLines.length === 0 ? void 0 : promptLines), agentOpts));
 		const liveTermination = extensionTermination;
 		if (liveTermination !== void 0) throw liveTermination;
 		if (capDecisionRef !== void 0) return await settleCapOutcome();
+		if (validationTermination !== void 0) throw validationTermination;
 		if (orchestratorAccount !== void 0) internals.cost.orchestrator.spentUsd = internals.budget.accountView(orchestratorAccount)?.spentUsd ?? 0;
 		if (result.status !== "ok") throw new ConfigError(`the orchestrator agent terminated with status '${result.status}'` + (result.errorMessage === void 0 ? "" : `: ${result.errorMessage}`));
 		if (opts?.acceptance === void 0) return result.output;
@@ -14782,4 +15099,4 @@ function createSandboxBridge(ctx, options) {
 	};
 }
 //#endregion
-export { AWAIT_SCHEMA, AdmissionController, AdmissionRejectedError, AgentCallError, BUDGET_ABORT_REASON, BudgetExhaustedError, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, ConfigError, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DedupIndex, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EscalationDecisionAbortedError, EventBus, ExternalRegistry, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FileModelKnowledgeStore, FileTranscriptStore, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, GitWorktreeProvider, INBOX_PROPOSAL_TTL_DAYS, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, JournalCompatibilityError, JournalMatcher, JournalMissError, JournalOrderViolation, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, KeyedLimiter, KnowledgeCasError, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LeaseHeldError, LineageIndex, MASKED_SECRET, MAX_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, ModelRetry, NoProgressDetector, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OrchestratorCapConfigError, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, PlanInvariantError, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionFold, RulvarError, RunBudget, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxError, ScriptRejected, Semaphore, SpanRegistry, TOOL_NAME_PATTERN, TerminationAccount, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, atCompactionThreshold, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hasMetaLookup, hashRunArgs, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, metaMatchesFilter, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readRunMeta, readTerminationInit, registryKeyRing, remeasureQueue, replayDisposition, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };
+export { AWAIT_SCHEMA, AdmissionController, AdmissionRejectedError, AgentCallError, BUDGET_ABORT_REASON, BudgetExhaustedError, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, ConfigError, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_CITATION_PATTERN, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_EVIDENCE_MIN_SHARE, DEFAULT_FINISH_MAX_REPAIRS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DedupIndex, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EscalationDecisionAbortedError, EventBus, ExternalRegistry, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FileModelKnowledgeStore, FileTranscriptStore, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, GitWorktreeProvider, INBOX_PROPOSAL_TTL_DAYS, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, JournalCompatibilityError, JournalMatcher, JournalMissError, JournalOrderViolation, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, KeyedLimiter, KnowledgeCasError, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LeaseHeldError, LineageIndex, MASKED_SECRET, MAX_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, ModelRetry, NoProgressDetector, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OrchestratorCapConfigError, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, PlanInvariantError, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionFold, RulvarError, RunBudget, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxError, ScriptRejected, Semaphore, SpanRegistry, TOOL_NAME_PATTERN, TerminationAccount, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, atCompactionThreshold, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hasMetaLookup, hashRunArgs, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, metaMatchesFilter, minMatchesValidator, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readRunMeta, readTerminationInit, registryKeyRing, remeasureQueue, replayDisposition, requiredFieldsValidator, requiredSectionsValidator, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.42.0",
+  "version": "1.44.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",