@rulvar/core 1.53.0 → 1.54.0

package/dist/index.d.ts

@@ -2958,6 +2958,26 @@ type CoreEvents = {
   * charge. Absent means every contributing turn reported exact usage.
   */
   usageApprox?: boolean;
+  /**
+  * The semantic completion lift (RV-207 tail): present when the
+  * workflow reported semantic completion through the completion
+  * envelope contract: an `ok`/`exhausted` run whose result value is
+  * an object carrying a valid `completion` literal, or an `error`
+  * run whose typed error data carries one (the orchestrator
+  * acceptance path emits both). Transport status says whether the
+  * run ran; completion says whether the work is COMPLETE: an
+  * accepted degraded run is `status: 'ok'` with `completion:
+  * 'partial'`. Replay recomputes the same value from the re-executed
+  * workflow, so the field is identical live and replayed. Absent
+  * when the workflow makes no completion claim.
+  */
+  completion?: "complete" | "partial" | "rejected";
+  /**
+  * Settled child statuses by status name, lifted from the same
+  * envelope (or typed error data) when it carries a valid record of
+  * nonnegative integers. Absent otherwise.
+  */
+  childStatusCounts?: Record<string, number>;
 } | {
   type: "phase:start";
   phase: string;
@@ -5313,6 +5333,48 @@ declare function hashRunArgs(args: unknown): string | undefined;
 declare function hashRunOutput(value: unknown): string | undefined;
 declare function createEngine(options: CreateEngineOptions): Engine;
 //#endregion
+//#region src/orchestrator/claims.d.ts
+/**
+* Repeated-claim deduplication (RV-211 remainder): a PURE, deterministic
+* fold that removes byte-repeated claim lines across children BEFORE any
+* model call, so the synthesis invocation never spends context re-reading
+* what several children reported identically. Matching is deliberately
+* conservative: lines compare by whitespace-collapsed exact equality
+* (trim, inner runs of whitespace to one space), never fuzzily, so two
+* DISTINCT claims can never merge; the first occurrence survives verbatim
+* and every later occurrence is dropped and indexed. Empty lines are
+* structure, not claims: they always survive.
+*
+* Public docs: https://docs.rulvar.com/guide/orchestration-modes
+*/
+/** One claim reported more than once across the input rows. */
+interface RepeatedClaim {
+  /** The first-seen line, verbatim. */
+  claim: string;
+  /** Reporters in input order; the first entry made the surviving copy. */
+  nodeIds: string[];
+  /** Total occurrences across all rows, the surviving one included. */
+  count: number;
+}
+interface DedupedClaims {
+  /** The input rows with every repeated line's later occurrences removed. */
+  rows: {
+    nodeId: string;
+    text: string;
+  }[];
+  /** Claims seen more than once, in first-occurrence order. */
+  repeated: RepeatedClaim[];
+}
+/**
+* Removes later occurrences of repeated claim lines across the rows and
+* indexes each repeated claim with its reporters. Deterministic: output
+* depends only on the input order and bytes.
+*/
+declare function dedupeRepeatedClaims(rows: {
+  nodeId: string;
+  text: string;
+}[]): DedupedClaims;
+//#endregion
 //#region src/orchestrator/finish-validators.d.ts
 /**
 * One child as the finish validators see it (the RV-202 provenance
@@ -5945,6 +6007,12 @@ declare const DEFAULT_FINISH_MAX_REPAIRS = 1;
 */
 declare const DEFAULT_SYNTHESIS_MAX_TURNS = 4;
 /**
+* Default maxTurns of ONE incremental synthesis note (RV-211 remainder):
+* a note summarizes a single settled child into a bounded finish call,
+* so it needs less headroom than the full synthesis invocation.
+*/
+declare const DEFAULT_SYNTHESIS_NOTE_MAX_TURNS = 2;
+/**
 * 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;
@@ -6075,9 +6143,71 @@ interface OrchestrateSynthesis {
   * Admission estimate for the synthesize invocation, like
   * AgentOpts.estCost: under a tight orchestrator cap the default
   * reserve (full maxOutputTokens pricing) can refuse the dispatch; an
-  * explicit estimate is the host speaking.
+  * explicit estimate is the host speaking. In 'incremental' mode the
+  * estimate applies to EACH note invocation.
   */
   estCost?: number;
+  /**
+  * The synthesis shape (RV-211 remainder). Default 'single': one
+  * post-fan-in synthesize invocation composes the final result from the
+  * draft and the whole settled digest. 'incremental': every settled
+  * child triggers ONE bounded synthesize-role NOTE invocation as soon
+  * as it settles (concurrent with the still-running fan-out, which is
+  * what moves synthesis wall time off the post-fan-in critical path),
+  * and the FINAL result is a DETERMINISTIC reconciliation, never
+  * another model call: an {@link IncrementalSynthesisResult} envelope
+  * composed from the draft and the notes in spawn order. The tradeoffs
+  * are explicit: notes are paid DURING the run, so an acceptance
+  * rejection can no longer guarantee "a rejected run never paid for
+  * synthesis"; and because the reconciliation has no model-composed
+  * finish, `finishValidation` cannot bind it: configuring both is a
+  * ConfigError at intake. A note that dies falls back to the child's
+  * raw digest summary under a journaled per-child
+  * 'orchestrator_synthesis_note_fallback' decision and a warn log.
+  * Cap paths are unchanged: a capped run settles through the reserved
+  * finalizer and never reconciles.
+  */
+  mode?: "single" | "incremental";
+  /**
+  * Deduplicate repeated claim lines across children BEFORE any model
+  * call (RV-211 remainder; default false, and the prompt stays byte
+  * identical when unset). In 'single' mode the digest entering the
+  * synthesis prompt keeps only the FIRST occurrence of every repeated
+  * line and a REPEATED CLAIMS index (each claim with its reporters)
+  * rides the prompt beside it. In 'incremental' mode the deterministic
+  * reconciliation dedupes the note texts the same way and the envelope
+  * carries the `repeatedClaims` index. Matching is whitespace-collapsed
+  * exact line equality: nothing fuzzy ever merges two distinct claims.
+  */
+  dedupeClaims?: boolean;
+  /**
+  * UsageLimits of ONE incremental note invocation; default
+  * { maxTurns: 2 }. Ignored in 'single' mode.
+  */
+  noteLimits?: UsageLimits;
+}
+/**
+* The deterministic reconciliation envelope an 'incremental' synthesis
+* returns as the run result (RV-211 remainder): the coordination draft
+* plus one section per settled child in spawn order, each carrying the
+* child's terminal status and its note (the note invocation's finish
+* output, or the child's raw digest summary when the note fell back).
+* With `dedupeClaims`, repeated claim lines keep their first occurrence
+* only and the `repeatedClaims` index lists each with its reporters.
+* Everything here derives from journaled state, so a resume reproduces
+* the envelope byte for byte with zero paid calls.
+*/
+interface IncrementalSynthesisResult {
+  synthesis: "incremental";
+  draft: unknown;
+  sections: {
+    nodeId: string;
+    logicalTaskId: string; /** The child's terminal status. */
+    status: string; /** The note invocation's terminal status ('ok' unless it fell back). */
+    noteStatus: string;
+    note: string;
+  }[];
+  repeatedClaims?: RepeatedClaim[];
 }
 declare const ORCHESTRATE_WORKFLOW_NAME = "rulvar-orchestrate";
 /**
@@ -6990,6 +7120,44 @@ declare class GitWorktreeProvider implements IsolationProvider {
   }>;
 }
 //#endregion
+//#region src/tools/research.d.ts
+interface RepositoryResearchToolsetOptions {
+  /** The confining directory root; everything resolves under it. */
+  root: string;
+  /** Rows per list/search/evidence page; default 50. */
+  pageSize?: number;
+  /** Content budget of one read_file page in characters; default 4000. */
+  readPageChars?: number;
+  /** Files larger than this many bytes are refused; default 262144. */
+  maxFileBytes?: number;
+  /** Walk ceiling per call (files visited); default 20000. */
+  maxScannedFiles?: number;
+  /**
+  * Extra ignored basenames (files and directories), merged over the
+  * always-on defaults '.git' and 'node_modules'.
+  */
+  ignore?: string[];
+  /** Walk dot-entries too; default false. */
+  includeHidden?: boolean;
+}
+/** One verified evidence entry recorded by `record_evidence`. */
+interface ResearchEvidenceEntry {
+  claim: string;
+  /** Root-relative POSIX path, verified to exist at record time. */
+  file: string;
+  /** 'N' or 'N-M', 1-based, verified inside the file's line count. */
+  lines?: string;
+  /** Verified verbatim substring of the file at record time. */
+  quote?: string;
+}
+interface RepositoryResearchToolset {
+  /** list_files, search_files, read_file, record_evidence, list_evidence. */
+  tools: ToolDef[];
+  /** Snapshot copy of the evidence collected so far, in record order. */
+  evidence(): ResearchEvidenceEntry[];
+}
+declare function repositoryResearchToolset(options: RepositoryResearchToolsetOptions): RepositoryResearchToolset;
+//#endregion
 //#region src/journal/scope.d.ts
 /**
 * Scope-path grammar (M1-T04): deterministic structural paths, independent
@@ -7756,4 +7924,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, type AgentInvocationRow, AgentOpts, AgentProfile, AgentProfilePermissions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, AuditRunsOptions, 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, type CriticalPath, 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, DEFAULT_SYNTHESIS_MAX_TURNS, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DerivedKey, DeriverRegistry, type DeterminismConfig, DeterminismError, type DeterminismEvents, type DeterminismMode, 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, type ExplorationSummary, 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 InvocationTable, 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, OrchestrateSynthesis, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, type PhaseRow, 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, RUN_SETTLE_DECISION_TYPE, RandIdentityInput, RandPayload, ReconcileOptions, ReconcileResult, 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, RunAuditVerdict, RunBudget, RunEventSink, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStateAudit, 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, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, 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, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, 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, reconcileRunMeta, reduceCriticalPath, reduceInvocationTable, 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 };
+export { AWAIT_SCHEMA, AbandonAttempt, AbandonFold, AbandonPayload, AbandonedSpendView, AbortClass, type AdaptiveEvents, AdmissionController, AdmissionDecision, AdmissionRejectedError, AdmissionStatsBefore, AdmitLineage, AdmitRejectReason, AdmitSpec, AdmitVerdict, AgentCallError, AgentError, type AgentEvents, AgentIdentityInput, type AgentInvocationRow, AgentOpts, AgentProfile, AgentProfilePermissions, AgentResult, AgentResultMeta, AgentStatus, ApproachSignatureInputs, ApprovalDecision, ApprovalIdentityInput, Artifact, AttemptOutcomeClass, AuditRunsOptions, 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, type CriticalPath, 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, DEFAULT_SYNTHESIS_MAX_TURNS, DEFAULT_SYNTHESIS_NOTE_MAX_TURNS, DebitResult, DeclaredLadder, DedupIndex, DedupNote, DedupedClaims, DerivedKey, DeriverRegistry, type DeterminismConfig, DeterminismError, type DeterminismEvents, type DeterminismMode, 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, type ExplorationSummary, 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, IncrementalSynthesisResult, InvalidResolutionError, InvocationRole, type InvocationTable, 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, OrchestrateSynthesis, OrchestratorBudgetSpec, OrchestratorCapConfigError, OrchestratorExtension, OrchestratorExtensionIO, OrchestratorRuntime, Out, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, Part, PendingExternal, PendingToolTurn, PermissionConfig, PermissionGate, PermissionHook, PermissionPreset, PermissionRule, PermissionVerdict, type PhaseRow, 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, RUN_SETTLE_DECISION_TYPE, RandIdentityInput, RandPayload, ReconcileOptions, ReconcileResult, RefEntryAppender, RefEntryClassification, RefusalInfo, RepeatedClaim, ReplayDisposition, ReplayMode, ReplayPlanHashMismatch, Replayer, RepositoryResearchToolset, RepositoryResearchToolsetOptions, ResearchEvidenceEntry, ResolutionArbiter, ResolutionAttempt, ResolutionBy, ResolutionFold, ResolutionLayer, ResolutionOutcome, ResolutionPayload, ResolvedInvocation, ResolvedToolset, ResumeHandle, ResumeOptions, ResumePreview, ResumeReport, RetryClass, RetryPolicy, ReuseConfig, RiskRuleValue, Role, RulvarError, RulvarErrorCode, RunAgentOptions, RunAuditVerdict, RunBudget, RunEventSink, type RunFilter, RunHandle, RunInternals, type RunMeta, RunOptions, RunOutcome, RunProfile, RunStateAudit, 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, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, 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, dedupeRepeatedClaims, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, 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, reconcileRunMeta, reduceCriticalPath, reduceInvocationTable, registryKeyRing, remeasureQueue, replayDisposition, repositoryResearchToolset, 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

@@ -1,13 +1,13 @@
 import { createHash, getRandomValues, randomUUID } from "node:crypto";
-import { appendFileSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve, sep } from "node:path";
+import { appendFileSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path, { dirname, join, resolve, sep } from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
 import { execFile } from "node:child_process";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, readFile, readdir, realpath, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { promisify } from "node:util";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -3297,6 +3297,459 @@ var GitWorktreeProvider = class {
 	}
 };
 //#endregion
+//#region src/tools/research.ts
+/**
+* The standard repository research toolset (RV-210 remainder): paginated
+* list/search/read tools over a confined directory root with STABLE
+* keyset cursors, plus an evidence collector that verifies citations at
+* collection time. Design contract:
+*
+* - Responses are CANONICAL: a page is a pure function of (root
+*   filesystem state, logical window), never of how the window was
+*   addressed, so reading the same page through a cursor and through
+*   fresh arguments returns byte-identical results. That is what makes
+*   the RV-210 `maxNoNewEvidenceCalls` guard measure duplicate-page
+*   reads correctly, and the `maxRepeatedToolSignature` guard already
+*   denies byte-identical repeat calls: deduplication is composition,
+*   not a marker field.
+* - Cursors are keyset cursors (the last path / line, not an offset), so
+*   a page boundary never shifts when unrelated entries appear or
+*   disappear, and every cursor embeds the query identity: replaying a
+*   cursor against different arguments is a typed error result.
+* - Ordering is deterministic byte order (UTF-16 code unit sort), never
+*   locale collation.
+* - The root confines everything: relative paths only, `..` escapes and
+*   symlink escapes are typed error results, symlinked directories are
+*   never walked.
+* - User-level failures (bad path, binary file, oversized file, invalid
+*   cursor, an unverifiable citation) are RETURNED `{ error }` values,
+*   deterministic and visible to the model; only host misconfiguration
+*   throws (ConfigError at construction).
+* - Tool results are journaled at execution time, so replay never
+*   touches the filesystem; live pages read the live tree.
+*
+* Public docs: https://docs.rulvar.com/guide/tools
+*/
+const DEFAULT_PAGE_SIZE = 50;
+const DEFAULT_READ_PAGE_CHARS = 4e3;
+const DEFAULT_MAX_FILE_BYTES = 262144;
+const DEFAULT_MAX_SCANNED_FILES = 2e4;
+const ALWAYS_IGNORED = [".git", "node_modules"];
+const SEARCH_SNIPPET_CHARS = 200;
+const BINARY_SNIFF_BYTES = 8192;
+const LIST_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		dir: {
+			type: "string",
+			description: "Root-relative directory to list; default the root."
+		},
+		cursor: {
+			type: "string",
+			description: "Opaque cursor from a previous page."
+		}
+	}
+};
+const SEARCH_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: ["query"],
+	properties: {
+		query: {
+			type: "string",
+			minLength: 1,
+			description: "Literal substring to find."
+		},
+		dir: {
+			type: "string",
+			description: "Root-relative directory to search; default the root."
+		},
+		cursor: {
+			type: "string",
+			description: "Opaque cursor from a previous page."
+		}
+	}
+};
+const READ_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: ["path"],
+	properties: {
+		path: {
+			type: "string",
+			minLength: 1,
+			description: "Root-relative file path."
+		},
+		cursor: {
+			type: "string",
+			description: "Opaque cursor from a previous page."
+		}
+	}
+};
+const RECORD_EVIDENCE_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: ["claim", "file"],
+	properties: {
+		claim: {
+			type: "string",
+			minLength: 1,
+			description: "The claim this evidence supports."
+		},
+		file: {
+			type: "string",
+			minLength: 1,
+			description: "Root-relative file the claim cites."
+		},
+		lines: {
+			type: "string",
+			description: "Cited line or range, 1-based: '12' or '12-40'."
+		},
+		quote: {
+			type: "string",
+			minLength: 1,
+			description: "Verbatim quote; verified to appear in the file."
+		}
+	}
+};
+const LIST_EVIDENCE_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: { cursor: {
+		type: "string",
+		description: "Opaque cursor from a previous page."
+	} }
+};
+function encodeCursor(payload) {
+	return Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+function decodeCursor(raw) {
+	try {
+		return JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+	} catch {
+		return;
+	}
+}
+function isBinary(buffer) {
+	return buffer.subarray(0, BINARY_SNIFF_BYTES).includes(0);
+}
+/** Split into lines on LF; a trailing CR per line is presentation, not content. */
+function splitLines(text) {
+	return text.split("\n").map((line) => line.endsWith("\r") ? line.slice(0, -1) : line);
+}
+function repositoryResearchToolset(options) {
+	if (typeof options.root !== "string" || options.root.length === 0) throw new ConfigError("repositoryResearchToolset root must be a non-empty string");
+	let realRoot;
+	try {
+		realRoot = realpathSync(path.resolve(options.root));
+	} catch {
+		throw new ConfigError(`repositoryResearchToolset root '${options.root}' does not exist`);
+	}
+	if (!statSync(realRoot).isDirectory()) throw new ConfigError(`repositoryResearchToolset root '${options.root}' is not a directory`);
+	for (const [name, value] of [
+		["pageSize", options.pageSize],
+		["readPageChars", options.readPageChars],
+		["maxFileBytes", options.maxFileBytes],
+		["maxScannedFiles", options.maxScannedFiles]
+	]) if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) throw new ConfigError(`repositoryResearchToolset ${name} must be a positive integer; got ${String(value)}`);
+	const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+	const readPageChars = options.readPageChars ?? DEFAULT_READ_PAGE_CHARS;
+	const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+	const maxScannedFiles = options.maxScannedFiles ?? DEFAULT_MAX_SCANNED_FILES;
+	const includeHidden = options.includeHidden ?? false;
+	const ignored = /* @__PURE__ */ new Set([...ALWAYS_IGNORED, ...options.ignore ?? []]);
+	const evidence = [];
+	/**
+	* Resolves a root-relative POSIX path and confines it: absolute paths,
+	* `..` escapes, and symlink escapes are error strings, never throws.
+	* `mustExist` additionally resolves symlinks and re-checks containment
+	* of the REAL path (the FileTranscriptStore traversal lesson).
+	*/
+	const resolveWithin = async (rel, kind) => {
+		const normalizedInput = rel.replaceAll("\\", "/");
+		if (path.posix.isAbsolute(normalizedInput) || path.isAbsolute(rel)) return { error: `path must be relative to the research root; got '${rel}'` };
+		const normalized = path.posix.normalize(normalizedInput);
+		if (normalized === ".." || normalized.startsWith("../")) return { error: `path escapes the research root: '${rel}'` };
+		const cleaned = normalized === "." ? "" : normalized;
+		if (kind === "file" && cleaned === "") return { error: "path must name a file inside the research root" };
+		const abs = path.resolve(realRoot, cleaned);
+		let real;
+		try {
+			real = await realpath(abs);
+		} catch {
+			return { error: `no such ${kind} under the research root: '${cleaned === "" ? "." : cleaned}'` };
+		}
+		if (real !== realRoot && !real.startsWith(realRoot + path.sep)) return { error: `path escapes the research root: '${rel}'` };
+		try {
+			const info = await stat(real);
+			if (kind === "file" && !info.isFile()) return { error: `not a regular file: '${cleaned}'` };
+			if (kind === "dir" && !info.isDirectory()) return { error: `not a directory: '${cleaned === "" ? "." : cleaned}'` };
+		} catch {
+			return { error: `no such ${kind} under the research root: '${cleaned === "" ? "." : cleaned}'` };
+		}
+		return {
+			abs: real,
+			rel: cleaned
+		};
+	};
+	/**
+	* Deterministic recursive walk: sorted entries, ignored and hidden
+	* names skipped, symlinks never followed, regular files only. Returns
+	* root-relative POSIX paths in byte order, or an error when the walk
+	* exceeds maxScannedFiles.
+	*/
+	const walkFiles = async (absDir, relDir) => {
+		const files = [];
+		let visited = 0;
+		const recurse = async (dirAbs, dirRel) => {
+			let entries;
+			try {
+				entries = await readdir(dirAbs, { withFileTypes: true });
+			} catch {
+				return `directory disappeared during the walk: '${dirRel === "" ? "." : dirRel}'`;
+			}
+			const sorted = [...entries].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+			for (const entry of sorted) {
+				const name = entry.name;
+				if (ignored.has(name)) continue;
+				if (!includeHidden && name.startsWith(".")) continue;
+				const childRel = dirRel === "" ? name : `${dirRel}/${name}`;
+				if (entry.isDirectory()) {
+					const failure = await recurse(path.join(dirAbs, name), childRel);
+					if (failure !== void 0) return failure;
+					continue;
+				}
+				if (!entry.isFile()) continue;
+				visited += 1;
+				if (visited > maxScannedFiles) return `the walk exceeded maxScannedFiles (${String(maxScannedFiles)}); narrow dir or raise the limit`;
+				files.push(childRel);
+			}
+		};
+		const failure = await recurse(absDir, relDir);
+		if (failure !== void 0) return { error: failure };
+		return { files };
+	};
+	const loadTextFile = async (abs, rel) => {
+		let info;
+		try {
+			info = await stat(abs);
+		} catch {
+			return { error: `no such file under the research root: '${rel}'` };
+		}
+		if (info.size > maxFileBytes) return { error: `file '${rel}' is ${String(info.size)} bytes, over the maxFileBytes limit (${String(maxFileBytes)})` };
+		const buffer = await readFile(abs);
+		if (isBinary(buffer)) return { error: `file '${rel}' is binary` };
+		return { text: buffer.toString("utf8") };
+	};
+	return {
+		tools: [
+			tool({
+				name: "list_files",
+				description: "List files under a directory of the research root, recursively, in deterministic byte order, one page at a time. Returns { files, totalFiles, nextCursor? }; pass cursor to continue where the last page ended (the cursor is stable: unrelated changes never shift the boundary).",
+				parameters: LIST_SCHEMA,
+				risk: "read",
+				execute: async (input) => {
+					const params = input;
+					let dir = params.dir ?? "";
+					let after;
+					if (params.cursor !== void 0) {
+						const payload = decodeCursor(params.cursor);
+						if (payload === void 0 || payload.t !== "list" || typeof payload.dir !== "string" || typeof payload.after !== "string" || params.dir !== void 0 && params.dir !== payload.dir) return { error: "invalid cursor: pass the nextCursor of a previous list_files page" };
+						dir = payload.dir;
+						after = payload.after;
+					}
+					const resolved = await resolveWithin(dir, "dir");
+					if ("error" in resolved) return resolved;
+					const walked = await walkFiles(resolved.abs, resolved.rel);
+					if ("error" in walked) return walked;
+					const remaining = after === void 0 ? walked.files : walked.files.filter((file) => file > after);
+					const page = remaining.slice(0, pageSize);
+					const more = remaining.length > pageSize;
+					return {
+						files: page,
+						totalFiles: walked.files.length,
+						...more ? { nextCursor: encodeCursor({
+							t: "list",
+							dir: resolved.rel,
+							after: page[page.length - 1]
+						}) } : {}
+					};
+				}
+			}),
+			tool({
+				name: "search_files",
+				description: "Search files under the research root for a literal substring (case-sensitive, never a regex), one page of matches at a time in deterministic (path, line) order. Returns { matches: [{ file, line, text }], filesScanned, filesSkipped, nextCursor? }; binary and oversized files are skipped and counted.",
+				parameters: SEARCH_SCHEMA,
+				risk: "read",
+				execute: async (input) => {
+					const params = input;
+					let dir = params.dir ?? "";
+					let query = params.query;
+					let after;
+					if (params.cursor !== void 0) {
+						const payload = decodeCursor(params.cursor);
+						if (payload === void 0 || payload.t !== "search" || typeof payload.query !== "string" || typeof payload.dir !== "string" || typeof payload.file !== "string" || typeof payload.line !== "number" || payload.query !== params.query || params.dir !== void 0 && params.dir !== payload.dir) return { error: "invalid cursor: pass the nextCursor of a previous search_files page with the same query and dir" };
+						dir = payload.dir;
+						query = payload.query;
+						after = {
+							file: payload.file,
+							line: payload.line
+						};
+					}
+					if (query.length === 0) return { error: "query must be a non-empty literal substring" };
+					const resolved = await resolveWithin(dir, "dir");
+					if ("error" in resolved) return resolved;
+					const walked = await walkFiles(resolved.abs, resolved.rel);
+					if ("error" in walked) return walked;
+					const matches = [];
+					let filesScanned = 0;
+					let filesSkipped = 0;
+					for (const file of walked.files) {
+						const loaded = await loadTextFile(path.join(realRoot, file), file);
+						if ("error" in loaded) {
+							filesSkipped += 1;
+							continue;
+						}
+						filesScanned += 1;
+						const lines = splitLines(loaded.text);
+						for (let index = 0; index < lines.length; index += 1) if (lines[index].includes(query)) matches.push({
+							file,
+							line: index + 1,
+							text: lines[index].trim().slice(0, SEARCH_SNIPPET_CHARS)
+						});
+					}
+					const remaining = after === void 0 ? matches : matches.filter((match) => match.file > after.file || match.file === after.file && match.line > after.line);
+					const page = remaining.slice(0, pageSize);
+					const more = remaining.length > pageSize;
+					const last = page[page.length - 1];
+					return {
+						matches: page,
+						filesScanned,
+						filesSkipped,
+						...more && last !== void 0 ? { nextCursor: encodeCursor({
+							t: "search",
+							query,
+							dir: resolved.rel,
+							file: last.file,
+							line: last.line
+						}) } : {}
+					};
+				}
+			}),
+			tool({
+				name: "read_file",
+				description: "Read a file of the research root as numbered lines, one page at a time (whole lines up to the page character budget). Returns { path, totalLines, fromLine, toLine, content, nextCursor? }; the same page reads byte-identically however it is addressed, so duplicate reads are visible to the exploration guards.",
+				parameters: READ_SCHEMA,
+				risk: "read",
+				execute: async (input) => {
+					const params = input;
+					let rel = params.path;
+					let fromLine = 1;
+					if (params.cursor !== void 0) {
+						const payload = decodeCursor(params.cursor);
+						if (payload === void 0 || payload.t !== "read" || typeof payload.path !== "string" || typeof payload.after !== "number" || payload.path !== params.path) return { error: "invalid cursor: pass the nextCursor of a previous read_file page for the same path" };
+						rel = payload.path;
+						fromLine = payload.after + 1;
+					}
+					const resolved = await resolveWithin(rel, "file");
+					if ("error" in resolved) return resolved;
+					const loaded = await loadTextFile(resolved.abs, resolved.rel);
+					if ("error" in loaded) return loaded;
+					const lines = splitLines(loaded.text);
+					const totalLines = lines.length;
+					if (fromLine > totalLines) return { error: `fromLine ${String(fromLine)} is past the end of '${resolved.rel}' (${String(totalLines)} lines)` };
+					const rendered = [];
+					let used = 0;
+					let toLine = fromLine - 1;
+					for (let index = fromLine - 1; index < totalLines; index += 1) {
+						const row = `${String(index + 1)}: ${lines[index]}`;
+						if (rendered.length > 0 && used + 1 + row.length > readPageChars) break;
+						rendered.push(row);
+						used += (rendered.length > 1 ? 1 : 0) + row.length;
+						toLine = index + 1;
+					}
+					const more = toLine < totalLines;
+					return {
+						path: resolved.rel,
+						totalLines,
+						fromLine,
+						toLine,
+						content: rendered.join("\n"),
+						...more ? { nextCursor: encodeCursor({
+							t: "read",
+							path: resolved.rel,
+							after: toLine
+						}) } : {}
+					};
+				}
+			}),
+			tool({
+				name: "record_evidence",
+				description: "Record one evidence entry supporting a claim. The citation is VERIFIED at record time: the file must exist under the research root, lines must be a valid 1-based line or range inside it ('12' or '12-40'), and quote (when given) must appear verbatim in the file. Returns { recorded, duplicate, totalEvidence }.",
+				parameters: RECORD_EVIDENCE_SCHEMA,
+				risk: "read",
+				execute: async (input) => {
+					const params = input;
+					if (params.claim.trim().length === 0) return { error: "claim must be a non-empty string" };
+					const resolved = await resolveWithin(params.file, "file");
+					if ("error" in resolved) return resolved;
+					const loaded = await loadTextFile(resolved.abs, resolved.rel);
+					if ("error" in loaded) return loaded;
+					const lines = splitLines(loaded.text);
+					if (params.lines !== void 0) {
+						const match = /^(\d+)(?:-(\d+))?$/u.exec(params.lines);
+						if (match === null) return { error: "lines must be '12' or '12-40' (1-based)" };
+						const from = Number(match[1]);
+						const to = match[2] === void 0 ? from : Number(match[2]);
+						if (from < 1 || to < from || to > lines.length) return { error: `lines '${params.lines}' is outside '${resolved.rel}' (${String(lines.length)} lines)` };
+					}
+					if (params.quote !== void 0 && !loaded.text.includes(params.quote)) return { error: `quote not found verbatim in '${resolved.rel}'; cite what the file actually says` };
+					const entry = {
+						claim: params.claim,
+						file: resolved.rel,
+						...params.lines === void 0 ? {} : { lines: params.lines },
+						...params.quote === void 0 ? {} : { quote: params.quote }
+					};
+					const duplicate = evidence.some((existing) => existing.claim === entry.claim && existing.file === entry.file && existing.lines === entry.lines && existing.quote === entry.quote);
+					if (!duplicate) evidence.push(entry);
+					return {
+						recorded: !duplicate,
+						duplicate,
+						totalEvidence: evidence.length
+					};
+				}
+			}),
+			tool({
+				name: "list_evidence",
+				description: "List the evidence recorded so far, one page at a time in record order. Returns { evidence, totalEvidence, nextCursor? }.",
+				parameters: LIST_EVIDENCE_SCHEMA,
+				risk: "read",
+				execute: (input) => {
+					const params = input;
+					let from = 0;
+					if (params.cursor !== void 0) {
+						const payload = decodeCursor(params.cursor);
+						if (payload === void 0 || payload.t !== "evidence" || typeof payload.after !== "number") return Promise.resolve({ error: "invalid cursor: pass the nextCursor of a previous list_evidence page" });
+						from = payload.after;
+					}
+					const page = evidence.slice(from, from + pageSize);
+					const more = from + pageSize < evidence.length;
+					return Promise.resolve({
+						evidence: page,
+						totalEvidence: evidence.length,
+						...more ? { nextCursor: encodeCursor({
+							t: "evidence",
+							after: from + pageSize
+						}) } : {}
+					});
+				}
+			})
+		],
+		evidence: () => evidence.map((entry) => ({ ...entry }))
+	};
+}
+//#endregion
 //#region src/journal/identity.ts
 /**
 * Content-addressed entry identity (M1-T04): IdentityInput records per
@@ -13265,6 +13718,52 @@ async function executeWorkflow(internals, wf, args) {
 	}
 }
 //#endregion
+//#region src/orchestrator/claims.ts
+/** The conservative matching key: trim plus inner-whitespace collapse. */
+function claimKey(line) {
+	return line.trim().replace(/\s+/gu, " ");
+}
+/**
+* Removes later occurrences of repeated claim lines across the rows and
+* indexes each repeated claim with its reporters. Deterministic: output
+* depends only on the input order and bytes.
+*/
+function dedupeRepeatedClaims(rows) {
+	const seen = /* @__PURE__ */ new Map();
+	const order = [];
+	return {
+		rows: rows.map((row) => {
+			const kept = [];
+			for (const line of row.text.split("\n")) {
+				const key = claimKey(line);
+				if (key === "") {
+					kept.push(line);
+					continue;
+				}
+				const prior = seen.get(key);
+				if (prior === void 0) {
+					const entry = {
+						claim: line,
+						nodeIds: [row.nodeId],
+						count: 1
+					};
+					seen.set(key, entry);
+					order.push(entry);
+					kept.push(line);
+					continue;
+				}
+				prior.count += 1;
+				if (!prior.nodeIds.includes(row.nodeId)) prior.nodeIds.push(row.nodeId);
+			}
+			return {
+				nodeId: row.nodeId,
+				text: kept.join("\n")
+			};
+		}),
+		repeated: order.filter((entry) => entry.count > 1)
+	};
+}
+//#endregion
 //#region src/orchestrator/orchestrate.ts
 /**
 * The mode (c) dynamic orchestrator (M6-T07/T08).
@@ -13291,6 +13790,12 @@ const DEFAULT_FINISH_MAX_REPAIRS = 1;
 * call plus headroom for one validator repair exchange.
 */
 const DEFAULT_SYNTHESIS_MAX_TURNS = 4;
+/**
+* Default maxTurns of ONE incremental synthesis note (RV-211 remainder):
+* a note summarizes a single settled child into a bounded finish call,
+* so it needs less headroom than the full synthesis invocation.
+*/
+const DEFAULT_SYNTHESIS_NOTE_MAX_TURNS = 2;
 const ORCHESTRATE_WORKFLOW_NAME = "rulvar-orchestrate";
 /**
 * One page of a string, for the child result evidence tools: maxChars is
@@ -13350,6 +13855,10 @@ function validateOrchestrateOptions(opts) {
 	}
 	if (opts.synthesis !== void 0) {
 		const synthesis = opts.synthesis;
+		if (synthesis.mode !== void 0 && synthesis.mode !== "single" && synthesis.mode !== "incremental") throw new ConfigError("orchestrate synthesis.mode must be 'single' or 'incremental'; got " + JSON.stringify(synthesis.mode));
+		if (synthesis.mode === "incremental" && opts.finishValidation !== void 0) throw new ConfigError("orchestrate synthesis.mode 'incremental' reconciles deterministically and has no model-composed final finish for finishValidation to bind; configure validators with mode 'single', or drop them");
+		if (synthesis.dedupeClaims !== void 0 && typeof synthesis.dedupeClaims !== "boolean") throw new ConfigError("orchestrate synthesis.dedupeClaims must be a boolean; got " + typeof synthesis.dedupeClaims);
+		if (synthesis.noteLimits !== void 0) validateUsageLimits(synthesis.noteLimits, "orchestrate synthesis.noteLimits");
 		if (synthesis.effort !== void 0 && ![
 			"low",
 			"medium",
@@ -13551,6 +14060,22 @@ function makeOrchestratorWorkflow(goal, opts) {
 		const recoveryDone = new Promise((resolve) => {
 			releaseRecovery = resolve;
 		});
+		/**
+		* Incremental synthesis notes (RV-211 remainder): one bounded
+		* synthesize-role invocation per settled child, keyed by nodeId so a
+		* note can never double-dispatch. The settle hook fires the note the
+		* moment its child settles (overlapping the still-running fan-out);
+		* the deterministic reconciliation is the completeness backstop and
+		* dispatches any note the hook missed. The dispatcher installs right
+		* before the coordination loop because it closes over runtime pieces
+		* built below; these bindings are declared HERE, before
+		* dispatchChild, so a recovered child's settle hook (which can fire
+		* during the recovery scan) never touches a binding in its temporal
+		* dead zone.
+		*/
+		const synthesisNotes = /* @__PURE__ */ new Map();
+		let synthesisNoteDispatcher;
+		let synthesisSettleFrozen = false;
 		let activityChain = Promise.resolve();
 		const childScopeOf = () => {
 			if (orchSeq === void 0) throw new ConfigError("orchestrator dispatch seq unknown before the loop started");
@@ -13636,6 +14161,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			};
 			settledResult.then(async (settled) => {
 				record.settled = settled;
+				if (!synthesisSettleFrozen) synthesisNoteDispatcher?.(record);
 				await runExtensionActivity();
 				for (const listener of [...settleListeners]) listener();
 			});
@@ -14425,33 +14951,198 @@ function makeOrchestratorWorkflow(goal, opts) {
 			};
 		};
 		/**
+		* One incremental synthesis note (RV-211 remainder): a FRESH agent
+		* entry with role 'synthesize' on the finish-only toolset whose
+		* prompt derives deterministically from the goal and the ONE settled
+		* child's digest, so a resume replays it by identity with zero paid
+		* calls. The invocation itself never throws out of here: an infra
+		* failure settles as a synthesized error result and the
+		* reconciliation falls back to the raw digest summary.
+		*/
+		const runSynthesisNote = async (record) => {
+			const spec = opts?.synthesis;
+			const finishOnly = buildOrchestratorTools(orchestratorRuntime, fullCardText).filter((tool) => tool.name === FINISH_TOOL_NAME);
+			const digest = digestOf(record, record.settled);
+			const prompt = [
+				"You are an incremental synthesis note of an orchestrated run. Digest the SINGLE settled child below into a self-contained note for the final deterministic reconciliation by calling finish({ result }) EXACTLY once, where result is a STRING. Preserve concrete evidence and citations; do not invent findings. No other tool exists.",
+				...spec.instructions === void 0 ? [] : [spec.instructions],
+				`GOAL: ${goal}`,
+				`CHILD: ${JSON.stringify(digest)}`
+			].join("\n");
+			const noteState = { ...callingState };
+			if (orchestratorAccount !== void 0) noteState.budgetScope = orchestratorAccount;
+			const noteOpts = {
+				role: "synthesize",
+				result: "full",
+				tools: finishOnly,
+				limits: spec.noteLimits ?? { maxTurns: 2 },
+				...spec.model === void 0 ? {} : { model: spec.model },
+				...spec.effort === void 0 ? {} : { effort: spec.effort },
+				...spec.estCost === void 0 ? {} : { estCost: spec.estCost },
+				[kTerminalTool]: { name: FINISH_TOOL_NAME }
+			};
+			return runtime.runInScope(noteState, () => ctx.agent(prompt, noteOpts));
+		};
+		/**
+		* Note dispatch is idempotent per child: the settle hook and the
+		* reconciliation both come through here, and the map guarantees one
+		* dispatch per nodeId (a concurrent identical dispatch would mint a
+		* second occurrence and PAY twice: the v1.32.0 lesson).
+		*/
+		const ensureSynthesisNote = (record) => {
+			const existing = synthesisNotes.get(record.nodeId);
+			if (existing !== void 0) return existing;
+			const note = runSynthesisNote(record).catch((thrown) => ({
+				status: "error",
+				output: null,
+				usage: {
+					inputTokens: 0,
+					outputTokens: 0,
+					cacheReadTokens: 0,
+					cacheWriteTokens: 0
+				},
+				costUsd: 0,
+				turns: 0,
+				servedBy: "unknown:unknown",
+				transcriptRef: "",
+				errorMessage: thrown instanceof Error ? thrown.message : String(thrown)
+			}));
+			synthesisNotes.set(record.nodeId, note);
+			return note;
+		};
+		if (opts?.synthesis?.mode === "incremental" && capDecisionRef === void 0) synthesisNoteDispatcher = ensureSynthesisNote;
+		/**
+		* The deterministic reconciliation of 'incremental' synthesis: the
+		* final result is a PURE fold of the journaled draft and the note
+		* results in spawn order, never another model call. A note that died
+		* falls back to the child's raw digest summary under a journaled
+		* per-child decision and a warn log. With dedupeClaims, repeated
+		* claim lines keep their first occurrence and the envelope carries
+		* the repeatedClaims index.
+		*/
+		const reconcileIncremental = async (draft, spec) => {
+			synthesisSettleFrozen = true;
+			const settledRecords = [...records.values()].filter((record) => record.settled !== void 0).sort((a, b) => a.spawnOrdinal - b.spawnOrdinal);
+			const sections = [];
+			for (const record of settledRecords) {
+				const settled = record.settled;
+				const note = await ensureSynthesisNote(record);
+				let noteText;
+				if (note.status === "ok") noteText = typeof note.output === "string" ? note.output : JSON.stringify(note.output ?? null);
+				else {
+					const fallbackKey = deriverV2.deriveKey({
+						kind: "orchestrator-synthesis-note-fallback",
+						nodeId: record.nodeId
+					});
+					if (!internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.key === fallbackKey)) await internals.replayer.appendSinglePhase({
+						scope: callingState.scope,
+						key: fallbackKey,
+						kind: "decision",
+						status: "ok",
+						spanId: internals.spans.mint(callingState.spanId),
+						site: "orchestrator-synthesis",
+						value: {
+							decisionType: "orchestrator_synthesis_note_fallback",
+							nodeId: record.nodeId,
+							status: note.status,
+							turnsUsed: note.turns
+						}
+					});
+					internals.events.emit({
+						type: "log",
+						level: "warn",
+						msg: `the synthesis note for child '${record.nodeId}' terminated with status '${note.status}'; falling back to the raw digest summary (journaled decision 'orchestrator_synthesis_note_fallback')`
+					}, callingState.spanId);
+					noteText = digestOf(record, settled).outputSummary;
+				}
+				sections.push({
+					nodeId: record.nodeId,
+					logicalTaskId: record.logicalTaskId,
+					status: settled.status,
+					noteStatus: note.status,
+					note: noteText
+				});
+			}
+			let repeatedClaims;
+			if (spec.dedupeClaims === true) {
+				const deduped = dedupeRepeatedClaims(sections.map((section) => ({
+					nodeId: section.nodeId,
+					text: section.note
+				})));
+				const textByNode = new Map(deduped.rows.map((row) => [row.nodeId, row.text]));
+				for (const section of sections) section.note = textByNode.get(section.nodeId) ?? section.note;
+				repeatedClaims = deduped.repeated;
+			}
+			const draftJson = JSON.stringify(draft ?? null);
+			internals.events.emit({
+				type: "log",
+				level: "debug",
+				msg: "orchestrator synthesis reconciliation",
+				data: {
+					children: sections.length,
+					draftChars: draftJson.length,
+					notesChars: sections.reduce((sum, section) => sum + section.note.length, 0),
+					perChild: sections.map((section) => ({
+						nodeId: section.nodeId,
+						chars: section.note.length
+					})),
+					...repeatedClaims === void 0 ? {} : { repeatedClaims: repeatedClaims.length }
+				}
+			}, callingState.spanId);
+			return {
+				synthesis: "incremental",
+				draft,
+				sections,
+				...repeatedClaims === void 0 ? {} : { repeatedClaims }
+			};
+		};
+		/**
 		* The post-fan-in synthesis invocation (RV-211): a FRESH agent entry
 		* with role 'synthesize' on the finish-only toolset (a distinct
 		* toolsetHash, the reserved-finalizer precedent), its prompt derived
 		* deterministically from the goal, the journaled coordination draft,
 		* and the settled child digest, so a resume replays it by identity
 		* with zero paid calls. Runs strictly AFTER the acceptance verdict
-		* (a rejected run never pays for synthesis) and owns the finish
-		* validators when they are configured. Failure posture: with
-		* validators the run fails typed (the validated path is mandatory);
-		* without them the run falls back to the draft under a journaled
-		* decision and a warn log, never silently.
+		* (a rejected run never pays for synthesis; in 'incremental' mode
+		* the per-child notes are paid DURING the run, so only the
+		* reconciliation itself is deferred) and owns the finish validators
+		* when they are configured. Failure posture: with validators the run
+		* fails typed (the validated path is mandatory); without them the
+		* run falls back to the draft under a journaled decision and a warn
+		* log, never silently.
 		*/
 		const runSynthesis = async (draft) => {
 			const spec = opts?.synthesis;
 			if (spec === void 0) return draft;
 			await recoveryDone;
+			if (spec.mode === "incremental") return await reconcileIncremental(draft, spec);
 			const finishOnly = buildOrchestratorTools(orchestratorRuntime, fullCardText).filter((tool) => tool.name === FINISH_TOOL_NAME);
 			const settledDigests = [...records.values()].filter((record) => record.settled !== void 0).sort((a, b) => a.spawnOrdinal - b.spawnOrdinal).map((record) => digestOf(record, record.settled));
+			let digestRows = settledDigests;
+			let repeatedClaims;
+			if (spec.dedupeClaims === true) {
+				const deduped = dedupeRepeatedClaims(settledDigests.map((row) => ({
+					nodeId: row.nodeId,
+					text: row.outputSummary
+				})));
+				const textByNode = new Map(deduped.rows.map((row) => [row.nodeId, row.text]));
+				digestRows = settledDigests.map((row) => ({
+					...row,
+					outputSummary: textByNode.get(row.nodeId) ?? row.outputSummary
+				}));
+				repeatedClaims = deduped.repeated;
+			}
 			const draftJson = JSON.stringify(draft ?? null);
-			const digestJson = JSON.stringify(settledDigests);
+			const digestJson = JSON.stringify(digestRows);
 			const prompt = [
 				"You are the synthesis invocation of an orchestrated run. Compose the FINAL result of the run from the goal, the coordination draft, and the settled child evidence below by calling finish({ result }) EXACTLY once. Preserve the evidence and citations the draft relies on; do not invent findings. No other tool exists.",
+				...repeatedClaims === void 0 ? [] : ["Repeated claims across children were deduplicated before this prompt: only the first occurrence of each repeated line remains in the digest, and the REPEATED CLAIMS index below lists each one with its reporters."],
 				...spec.instructions === void 0 ? [] : [spec.instructions],
 				...finishValidationPromptLines(validationSpec),
 				`GOAL: ${goal}`,
 				`DRAFT: ${draftJson}`,
-				`DIGEST: ${digestJson}`
+				`DIGEST: ${digestJson}`,
+				...repeatedClaims === void 0 ? [] : [`REPEATED CLAIMS: ${JSON.stringify(repeatedClaims)}`]
 			].join("\n");
 			internals.events.emit({
 				type: "log",
@@ -14462,10 +15153,11 @@ function makeOrchestratorWorkflow(goal, opts) {
 					draftChars: draftJson.length,
 					digestChars: digestJson.length,
 					promptChars: prompt.length,
-					perChild: settledDigests.map((entry) => ({
+					perChild: digestRows.map((entry) => ({
 						nodeId: entry.nodeId,
 						chars: JSON.stringify(entry).length
-					}))
+					})),
+					...repeatedClaims === void 0 ? {} : { repeatedClaims: repeatedClaims.length }
 				}
 			}, callingState.spanId);
 			const synthesisState = { ...callingState };
@@ -14586,6 +15278,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			const required = decision.childPolicy === "all-ok" ? "every child ok" : `at least ${String(decision.childPolicy.minSuccessful)} children ok`;
 			throw new FailRunError(`the orchestrator acceptance policy rejected the finish: ${String(decision.childStatusCounts.ok ?? 0)} children settled 'ok' but the policy requires ${required}; degraded: ${decision.degradedReasons.join("; ")}`, { data: {
 				source: "orchestrator_acceptance",
+				completion: "rejected",
 				childPolicy: decision.childPolicy,
 				childStatusCounts: decision.childStatusCounts,
 				degradedReasons: decision.degradedReasons
@@ -15243,6 +15936,32 @@ function workflowSourceRef(runId) {
 	return `${runId}/workflow-source`;
 }
 /**
+* The completion envelope contract (RV-207 tail): a workflow reports
+* SEMANTIC completion by returning an object result carrying a
+* `completion` literal (and optionally `childStatusCounts`), or by
+* throwing a typed RulvarError whose `data` carries them; the engine
+* lifts the validated fields onto the `run:end` event so telemetry
+* consumers read completeness without parsing workflow-specific result
+* shapes. The orchestrator acceptance path emits this envelope. Pure
+* shape validation: anything malformed is silently absent (the event is
+* telemetry, never authority), and an invalid counts record drops the
+* counts while keeping a valid completion.
+*/
+function liftRunCompletion(candidate) {
+	if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) return;
+	const completion = candidate.completion;
+	if (completion !== "complete" && completion !== "partial" && completion !== "rejected") return;
+	const counts = candidate.childStatusCounts;
+	if (typeof counts === "object" && counts !== null && !Array.isArray(counts)) {
+		const entries = Object.entries(counts);
+		if (entries.every(([, value]) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0)) return {
+			completion,
+			childStatusCounts: Object.fromEntries(entries)
+		};
+	}
+	return { completion };
+}
+/**
 * sha256 hex over the JCS canonical serialization of a run's args: the
 * value the engine records as `RunMeta.argsHash` at genesis, exposed so
 * hosts can verify re-supplied resume args against the recorded hash
@@ -15613,11 +16332,13 @@ function createEngine(options) {
 				}
 			}
 			await putMeta(status).catch(() => void 0);
+			const lifted = liftRunCompletion(status === "ok" || status === "exhausted" ? outcome.value : status === "error" ? wireError?.data : void 0);
 			bus.emit({
 				type: "run:end",
 				status,
 				totalUsd: ledger.usd,
-				...outcome.cost.usageApprox === true ? { usageApprox: true } : {}
+				...outcome.cost.usageApprox === true ? { usageApprox: true } : {},
+				...lifted === void 0 ? {} : lifted
 			}, rootSpanId);
 			bus.end();
 			resumeCtx?.previewResolve({
@@ -16089,4 +16810,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_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, DEFAULT_SYNTHESIS_MAX_TURNS, DedupIndex, DeterminismError, 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, RUN_SETTLE_DECISION_TYPE, 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, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, 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, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, 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, reconcileRunMeta, reduceCriticalPath, reduceInvocationTable, 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 };
+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, DEFAULT_SYNTHESIS_MAX_TURNS, DEFAULT_SYNTHESIS_NOTE_MAX_TURNS, DedupIndex, DeterminismError, 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, RUN_SETTLE_DECISION_TYPE, 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, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, 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, dedupeRepeatedClaims, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, 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, reconcileRunMeta, reduceCriticalPath, reduceInvocationTable, registryKeyRing, remeasureQueue, replayDisposition, repositoryResearchToolset, 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.53.0",
+  "version": "1.54.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",