dsh-context-compression-improved 0.3.0 → 0.4.0-beta.1

package/packages/selector/src/pruner.ts

@@ -33,7 +33,7 @@ import {
   tailTrimStub,
 } from './runtime/tail-trim.ts'
 import { installContextCompressionRetrieve } from './runtime/retrieve.ts'
-import type { PrunerState } from './pruner/state.ts'
+import type { PrunerState, ReviewSessionSummary } from './pruner/state.ts'
 import { countOmittedLines, CAPACITY_PRESSURE_RATIO } from './pruner/tuning.ts'
 import type { ToolCallInfo, SnapshotCandidate, PlannedReplacement, HistoryPlanOutcome } from './pruner/types.ts'
 import {
@@ -67,10 +67,22 @@ import {
   buildEstimatorSystemPrompt,
   buildEstimatorUserPrompt,
   isCoolingDown,
-  parseEstimatorAnswer,
+  parseEstimatorAnswerDetailed,
   type EstimatorFailures,
   type EstimatorSample,
 } from './runtime/tokenpilot/estimator.ts'
+import {
+  classifyCandidates,
+  contentDigest,
+} from './runtime/tokenpilot/proposal.ts'
+import {
+  MemoryReviewStore,
+  ReviewQueue,
+  type ReviewProposalRecord,
+  type ReviewQueueStore,
+  type ReviewReceipt,
+} from './runtime/tokenpilot/review-queue.ts'
+import { openReviewStorage } from './runtime/tokenpilot/review-storage.ts'
 
 import {
   DedupeTable,
@@ -222,7 +234,23 @@ export class ToolResultPruner extends Service {
       activeRequestBoundaries: new WeakMap(),
       tailTrimBoundaryAttempts: new WeakMap(),
       policyResolutionAudits: new WeakMap(),
-    }
+      reviewStore: new MemoryReviewStore(),
+      reviewQueues: new WeakMap(),
+      reviewClocks: new WeakMap(),
+      estimatorRemainingTurns: new WeakMap(),
+      reviewSummaries: new WeakMap(),
+    }
+
+    // TokenPilot-inspired R4: upgrade the review queue to durable storage when
+    // the optional storageDomain seam is available; the memory fallback above
+    // serves every session until (and unless) that open succeeds.
+    void openReviewStorage(name => this.ctx.get(name as never))
+      .then(store => {
+        if (store !== undefined) this.state.reviewStore = store
+      })
+      .catch(() => {
+        this.ctx.logger.warn('context-compression review storage unavailable; keeping in-memory review queue')
+      })
 
     ctx.on('session/event', (session, event) => {
       this.scanForSeededNativeSummary(session)
@@ -255,6 +283,7 @@ export class ToolResultPruner extends Service {
             // Only the immediately preceding step can contain results that have
             // not yet been exposed. This freezes both REDUCE and KEEP decisions:
             // older original events are never reconsidered after a profile change.
+            this.reviewClock(agent.session, turn)
             this.runRequestBoundary(agent.session, turn, step - 1, signal)
           } catch (error: unknown) {
             this.auditFailure(agent.session, 'fresh', 'request-boundary', error)
@@ -283,6 +312,16 @@ export class ToolResultPruner extends Service {
         this.auditFailure(agent.session, 'fresh', 'terminal-pass', error)
         ctx.logger.warn('context-compression terminal pass failed open: %o', error)
       }
+      // TokenPilot-inspired R4: review-pipeline housekeeping at the turn
+      // boundary, strictly fail-open — expire stale pendings, then execute
+      // every approved proposal as one merged batch. Order matters: expiring
+      // first keeps just-expired proposals from executing.
+      try {
+        this.expireReviewProposals(agent.session, turn)
+        this.applyApprovedProposals(agent.session)
+      } catch (error: unknown) {
+        ctx.logger.warn('context-compression review turn-boundary pass failed open: %o', error)
+      }
       // TokenPilot-inspired E1: advisory estimator pass, strictly off the
       // synchronous chain. Verdicts only feed the next pressure pass.
       void this.postflightEstimatorPass(agent.session, signal).catch(() => undefined)
@@ -341,7 +380,7 @@ export class ToolResultPruner extends Service {
       const planned = eligible
         .map(candidate => this.planNative(candidate, session, stage, policy, view))
         .filter((entry): entry is PlannedReplacement => entry !== null)
-      landed.push(...this.landAll(session, planned))
+      landed.push(...this.landAll(session, this.triageForReview(session, policy, planned)))
       if (landed.length === 0) {
         const exact = eligible.flatMap(candidate => candidate.count.kind === 'exact-tokenizer'
           ? [candidate.count.tokens] : [])
@@ -377,7 +416,7 @@ export class ToolResultPruner extends Service {
           capacityPressure,
         )
         if (historyAllowed) {
-          landed.push(...this.landAll(session, historyOutcome.plans))
+          landed.push(...this.landAll(session, this.triageForReview(session, policy, historyOutcome.plans)))
         }
       }
     } else {
@@ -385,7 +424,7 @@ export class ToolResultPruner extends Service {
       if (historyAllowed) {
         historyOutcome = this.planHistoricalAging(session, policy, view)
         if (historyOutcome.kind === 'planned') {
-          landed.push(...this.landAll(session, historyOutcome.plans))
+          landed.push(...this.landAll(session, this.triageForReview(session, policy, historyOutcome.plans)))
         }
       }
     }
@@ -569,7 +608,13 @@ export class ToolResultPruner extends Service {
         verdicts = new Map()
         this.state.estimatorVerdicts.set(session, verdicts)
       }
-      for (const verdict of parseEstimatorAnswer(answer)) {
+      const detailed = parseEstimatorAnswerDetailed(answer)
+      // TokenPilot-inspired R4: the optional session-level Ŝ rides on the same
+      // answer; it only sharpens the benefit model and is never required.
+      if (detailed.expectedRemainingTurns !== undefined) {
+        this.state.estimatorRemainingTurns.set(session, detailed.expectedRemainingTurns)
+      }
+      for (const verdict of detailed.verdicts) {
         if (verdicts.has(verdict.seq)) continue
         verdicts.set(verdict.seq, verdict.expired)
         if (verdict.expired) expired += 1
@@ -594,6 +639,367 @@ export class ToolResultPruner extends Service {
     })
   }
 
+  // ─────────── TokenPilot-inspired R4: human-gated review pipeline ───────────
+
+  /**
+   * The per-session review queue, or `undefined` while review mode is off
+   * (every review path must then behave exactly like before).
+   */
+  private reviewQueueFor(session: Session, policy: CompressionPolicy | undefined): ReviewQueue | undefined {
+    const presetOptions = policy?.presetOptions
+    if (presetOptions?.reviewMode !== true) return undefined
+    let queue = this.state.reviewQueues.get(session)
+    if (queue === undefined) {
+      queue = new ReviewQueue(this.state.reviewStore, { timeoutTurns: presetOptions.reviewTimeoutTurns })
+      this.state.reviewQueues.set(session, queue)
+    }
+    return queue
+  }
+
+  /**
+   * Monotonic per-session turn clock for review patience and expiry. Bumped by
+   * the agent loop payloads (`pre-step` / `turn-stopping`); passes without a
+   * turn coordinate reuse the last observed value.
+   */
+  private reviewClock(session: Session, turn?: number): number {
+    const previous = this.state.reviewClocks.get(session) ?? 0
+    const next = typeof turn === 'number' && Number.isSafeInteger(turn) && turn > previous ? turn : previous
+    this.state.reviewClocks.set(session, next)
+    return next
+  }
+
+  private auditReviewOutcome(
+    session: Session,
+    proposal: Pick<ReviewProposalRecord, 'id' | 'kind' | 'items'>,
+    event: 'enqueue' | 'expire' | 'decide' | 'apply-void' | 'apply-receipt',
+    extra: {
+      decision?: 'approved' | 'rejected' | 'ignored' | undefined
+      receiptStatus?: 'applied' | 'deferred' | undefined
+      reasonCode?: string | undefined
+    } = {},
+    turnIndex?: number,
+  ): void {
+    const tokensBefore = proposal.items.reduce((sum, item) => sum + item.tokensBefore, 0)
+    const tokensAfter = proposal.items.reduce((sum, item) => sum + item.tokensAfter, 0)
+    emitCompressionAudit(this.ctx.logger, {
+      schemaVersion: 1,
+      kind: 'review-outcome',
+      sessionId: String(session.id),
+      proposalId: proposal.id,
+      proposalKind: proposal.kind,
+      event,
+      ...extra.decision === undefined ? {} : { decision: extra.decision },
+      ...extra.receiptStatus === undefined ? {} : { receiptStatus: extra.receiptStatus },
+      ...extra.reasonCode === undefined ? {} : { reasonCode: extra.reasonCode },
+      itemSeqs: proposal.items.map(item => item.seq),
+      tokensBefore,
+      tokensAfter,
+      ...turnIndex === undefined ? {} : { turnIndex },
+    })
+  }
+
+  /**
+   * Review-mode triage hook: classify one pass's planned replacements and
+   * withhold the review bucket from landing, enqueuing it for human approval
+   * instead. With review mode off (or nothing planned) this is the identity.
+   *
+   * The digest freezes each candidate's ORIGINAL surface content, so the apply
+   * point can prove "what is removed now is what was approved then".
+   */
+  private triageForReview(
+    session: Session,
+    policy: CompressionPolicy,
+    plans: readonly PlannedReplacement[],
+  ): readonly PlannedReplacement[] {
+    const queue = this.reviewQueueFor(session, policy)
+    if (queue === undefined || plans.length === 0) return plans
+    const presetOptions = policy.presetOptions!
+    const estimatorVerdicts = this.state.estimatorVerdicts.get(session)
+    const estimatorSeqs = new Set<number>([...(estimatorVerdicts?.entries() ?? [])]
+      .filter(([, expired]) => expired)
+      .map(([seq]) => seq))
+    const input = {
+      alpha: presetOptions.cacheHitDiscountAlpha,
+      // One-phase approximation of the tail that a mutation must refill: the
+      // frozen protected recent-token tail (findings.md, 约束与依赖).
+      tailTokens: Math.max(1, policy.historyKeepRecentTokens),
+      reviewHighImpactTokens: presetOptions.reviewHighImpactTokens,
+      ...this.state.estimatorRemainingTurns.get(session) === undefined
+        ? {}
+        : { remainingTurns: this.state.estimatorRemainingTurns.get(session) },
+      estimatorSeqs,
+    }
+    const classified = classifyCandidates(plans.map(plan => ({
+      sourceSeq: plan.sourceSeq,
+      tokensBefore: plan.tokensBefore,
+      tokensAfter: plan.tokensAfter,
+      component: plan.component,
+      reducer: plan.reducer,
+      content: plan.candidate.event.data.message.content[0].content,
+    })), input)
+    const autoSeqs = new Set(classified.auto.map(candidate => candidate.sourceSeq))
+    const clock = this.reviewClock(session)
+    for (const skeleton of classified.review) {
+      const enqueued = queue.enqueue(String(session.id), skeleton, clock)
+      if (enqueued) {
+        this.auditReviewOutcome(session, {
+          id: skeleton.id,
+          kind: skeleton.kind,
+          items: skeleton.items,
+        }, 'enqueue', {}, clock)
+      }
+    }
+    return plans.filter(plan => autoSeqs.has(plan.sourceSeq))
+  }
+
+  /**
+   * Execute every approved proposal of one session as ONE merged replacement
+   * batch at the current turn boundary, following the upstream applied-receipt
+   * discipline: applied receipts are built only from real mutation evidence —
+   * estimates never cross into applied savings.
+   *
+   * Per proposal: every item's frozen digest is re-checked against the current
+   * surface content; any mismatch voids the whole proposal (deferred with a
+   * reason code) instead of deleting something the user never approved.
+   * Fail-open: any unexpected error only logs and leaves the queue intact.
+   */
+  applyApprovedProposals(session: Session): void {
+    const policy = this.activePolicy(session)
+    const queue = this.reviewQueueFor(session, policy)
+    if (queue === undefined) return
+    const sessionId = String(session.id)
+    const approved = [...queue.listApproved(sessionId)]
+    if (approved.length === 0) return
+    try {
+      const view = measureForCompaction(this.ctx, session)
+      const candidatesBySeq = new Map(this.snapshot(session, view).map(candidate => [candidate.seq, candidate]))
+      const plans: PlannedReplacement[] = []
+      const settled: {
+        proposal: ReviewProposalRecord
+        auditItems?: ReviewProposalRecord['items']
+        receipt: ReviewReceipt
+      }[] = []
+      const now = new Date().toISOString()
+      for (const proposal of approved) {
+        // Digest re-check at the execution point (the approval point cannot
+        // protect against later mutations of the same seq).
+        const voidedReason = this.reviewProposalVoided(session, proposal)
+        if (voidedReason !== undefined) {
+          settled.push({
+            proposal,
+            receipt: {
+              status: 'deferred',
+              reasonCode: voidedReason,
+              estimatedTokens: proposal.benefit.recoveredTokens,
+              updatedAt: now,
+            },
+          })
+          continue
+        }
+        // One merged batch: every still-valid proposal takes the same
+        // whole-result placeholder path in a single landAll call, so the tail
+        // refill penalty is paid once for the whole approval set.
+        const batchPlans: PlannedReplacement[] = []
+        let planned = true
+        for (const item of proposal.items) {
+          const candidate = candidatesBySeq.get(item.seq)
+          if (candidate === undefined) {
+            planned = false
+            break
+          }
+          const plan = this.planAggregate(
+            candidate,
+            session,
+            view,
+            'review-approved-whole-result',
+            'pressure',
+            undefined,
+            'history',
+            policy?.historyMode,
+          )
+          if (plan === null) {
+            planned = false
+            break
+          }
+          batchPlans.push(plan)
+        }
+        if (!planned || batchPlans.length === 0) {
+          settled.push({
+            proposal,
+            receipt: {
+              status: 'deferred',
+              reasonCode: 'review_receipt_execution_invalid',
+              estimatedTokens: proposal.benefit.recoveredTokens,
+              updatedAt: now,
+            },
+          })
+          continue
+        }
+        const landed = this.landAll(session, batchPlans)
+        if (landed.length === 0) {
+          settled.push({
+            proposal,
+            receipt: {
+              status: 'deferred',
+              reasonCode: 'review_receipt_execution_invalid',
+              estimatedTokens: proposal.benefit.recoveredTokens,
+              updatedAt: now,
+            },
+          })
+          continue
+        }
+        const landedForProposal = new Map(landed.map(entry => [entry.originalSeq, entry]))
+        const measuredItems = proposal.items.map((item) => {
+          const entry = landedForProposal.get(item.seq)
+          return entry === undefined ? item : {
+            ...item,
+            tokensBefore: entry.tokensBefore,
+            tokensAfter: entry.tokensAfter,
+          }
+        })
+        const appliedTokens = measuredItems.reduce(
+          (sum, item) => sum + item.tokensBefore - item.tokensAfter,
+          0,
+        )
+        settled.push({
+          proposal,
+          // The audit face carries the MEASURED numbers of the executed
+          // mutation; estimates never cross into applied savings.
+          auditItems: measuredItems,
+          receipt: {
+            status: 'applied',
+            estimatedTokens: proposal.benefit.recoveredTokens,
+            appliedTokens,
+            updatedAt: now,
+          },
+        })
+      }
+      for (const { proposal, auditItems, receipt } of settled) {
+        queue.recordReceipt(sessionId, proposal.id, receipt)
+        const summary = this.reviewSummaryFor(session)
+        if (receipt.status === 'applied') summary.reviewApplied += 1
+        else summary.voided += 1
+        this.auditReviewOutcome(
+          session,
+          auditItems === undefined
+            ? proposal
+            : { ...proposal, items: auditItems },
+          receipt.status === 'applied' ? 'apply-receipt' : 'apply-void',
+          receipt.status === 'applied'
+            ? { receiptStatus: 'applied' }
+            : { receiptStatus: 'deferred', reasonCode: receipt.reasonCode },
+        )
+      }
+    } catch (error: unknown) {
+      // Fail-open: a broken apply must never break the turn or the queue.
+      this.ctx.logger.warn('context-compression review apply failed open: %o', error)
+    }
+  }
+
+  /**
+   * Current surface content at one seq: the newest covering replacement's
+   * blocks when the seq was rewritten, otherwise the original event's blocks.
+   */
+  private surfaceContentAt(session: Session, seq: number): ContentBlock[] | undefined {
+    let content: ContentBlock[] | undefined
+    for (const event of sessionEvents(session)) {
+      if (event.type !== 'tool/result') continue
+      const op = event.surfaceOp
+      if (typeof op === 'object' && op.op === 'replace' && op.startSeq <= seq && seq <= op.endSeq) {
+        content = event.data.message.content[0].content
+      }
+    }
+    if (content !== undefined) return content
+    const original = sessionEvents(session).find(entry => entry.seq === seq)
+    return original?.type === 'tool/result' ? original.data.message.content[0].content : undefined
+  }
+
+  /**
+   * The execution-point digest check: `undefined` when every item's frozen
+   * digest still matches the current surface content, otherwise the aligned
+   * reason code explaining the void.
+   */
+  private reviewProposalVoided(
+    session: Session,
+    proposal: ReviewProposalRecord,
+  ): 'review_receipt_digest_invalid' | 'review_receipt_missing_candidate' | undefined {
+    for (const item of proposal.items) {
+      const current = this.surfaceContentAt(session, item.seq)
+      if (current === undefined) return 'review_receipt_missing_candidate'
+      if (contentDigest(current) !== item.digest) return 'review_receipt_digest_invalid'
+    }
+    return undefined
+  }
+
+  private reviewSummaryFor(session: Session): ReviewSessionSummary {
+    let summary = this.state.reviewSummaries.get(session)
+    if (summary === undefined) {
+      summary = { autoApplied: 0, reviewApplied: 0, expired: 0, voided: 0 }
+      this.state.reviewSummaries.set(session, summary)
+    }
+    return summary
+  }
+
+  /** Live pending review proposals of one session; empty when review mode is off. */
+  listReviewProposals(session: Session): readonly ReviewProposalRecord[] {
+    const queue = this.reviewQueueFor(session, this.activePolicy(session))
+    return queue?.listPending(String(session.id)) ?? []
+  }
+
+  /**
+   * Every session's live pending proposals, for the floating window's
+   * aggregate badge (the client carries no session id of its own).
+   */
+  listAllReviewProposals(): readonly { readonly sessionId: string, readonly proposals: readonly ReviewProposalRecord[] }[] {
+    const ids = this.state.reviewStore.ids?.() ?? []
+    const reader = new ReviewQueue(this.state.reviewStore, { timeoutTurns: 1 })
+    return ids
+      .map(sessionId => ({ sessionId, proposals: [...reader.listPending(sessionId)] }))
+      .filter(entry => entry.proposals.length > 0)
+  }
+
+  /** Four-state outcome counters of one session (floating-window summary row). */
+  reviewSummary(session: Session): ReviewSessionSummary {
+    return { ...this.reviewSummaryFor(session) }
+  }
+
+  /**
+   * Record one human decision. Returns the outcome, or `undefined` when
+   * review mode is off for this session (the route maps that to 503).
+   */
+  decideReviewProposal(
+    session: Session,
+    proposalId: string,
+    decision: 'approved' | 'rejected' | 'ignored',
+  ): { ok: true } | { ok: false, reason: 'unknown-proposal' | 'not-pending' } | undefined {
+    const queue = this.reviewQueueFor(session, this.activePolicy(session))
+    if (queue === undefined) return undefined
+    const sessionId = String(session.id)
+    const pending = queue.listPending(sessionId).find(entry => entry.id === proposalId)
+    const outcome = queue.decide(sessionId, proposalId, decision)
+    if (outcome.ok && pending !== undefined) {
+      this.auditReviewOutcome(session, pending, 'decide', { decision }, this.reviewClock(session))
+    }
+    return outcome
+  }
+
+  /**
+   * Expire stale pending proposals at one turn boundary and audit each.
+   * Public because tests drive it directly; the turn-stopping handler calls
+   * it with the loop's own turn index.
+   */
+  expireReviewProposals(session: Session, turnIndex?: number): readonly ReviewProposalRecord[] {
+    const queue = this.reviewQueueFor(session, this.activePolicy(session))
+    if (queue === undefined) return []
+    const clock = this.reviewClock(session, turnIndex)
+    const expired = queue.expireTurn(String(session.id), clock)
+    if (expired.length > 0) this.reviewSummaryFor(session).expired += expired.length
+    for (const proposal of expired) {
+      this.auditReviewOutcome(session, proposal, 'expire', {}, clock)
+    }
+    return expired
+  }
+
   private activePolicy(
     session: Session,
     contextWindowTokens?: number,
@@ -601,8 +1007,15 @@ export class ToolResultPruner extends Service {
   ): CompressionPolicy | undefined {
     const settings = this.activeSettings(session)
     try {
+      // R4 bridge: the persisted settings document's presetOptions (the
+      // settings-card writes, including reviewMode) must reach the policy —
+      // before this bridge only the estimator endpoint read them directly and
+      // every policy consumer saw the deployment defaults. User settings win
+      // over deployment config; absent fields inherit via mergePresetOptions.
       const policy = resolvePolicy(
-        this.state.config,
+        settings.presetOptions === undefined
+          ? this.state.config
+          : { ...this.state.config, presetOptions: settings.presetOptions },
         settings.profile,
         settings.custom,
         {
@@ -1053,9 +1466,10 @@ export class ToolResultPruner extends Service {
       }
     }
 
-    const landed = this.landAll(session, candidates
+    const freshCandidates = candidates
       .map(candidate => plans.get(candidate.seq))
-      .filter((plan): plan is PlannedReplacement => plan !== undefined))
+      .filter((plan): plan is PlannedReplacement => plan !== undefined)
+    const landed = this.landAll(session, this.triageForReview(session, policy, freshCandidates))
     const freshLanded = landed.some(entry => entry.stage === 'fresh'
       && plans.get(entry.originalSeq)?.component === 'fresh')
     const aggregateLanded = landed.some(entry => entry.stage === 'fresh'
@@ -1890,6 +2304,12 @@ export class ToolResultPruner extends Service {
       tokenizerId: plan.tokenizerId,
       tokenizerRevision: plan.tokenizerRevision,
     })
+    // R4: the four-state summary counts automatic-path rewrites at the single
+    // landing chokepoint; the review-approved batch settles its own counters
+    // in applyApprovedProposals.
+    if (plan.reducer !== 'review-approved-whole-result') {
+      this.reviewSummaryFor(session).autoApplied += 1
+    }
     return {
       originalSeq: candidate.seq,
       sourceSeq: plan.sourceSeq,

package/packages/selector/src/runtime/audit.ts

@@ -167,6 +167,32 @@ export interface EstimatorOutcomeAuditRecord extends CompressionAuditBase {
   readonly ok: boolean
 }
 
+/** Lifecycle of one human-gated review proposal. Only numeric and enum fields — never content. */
+export interface ReviewOutcomeAuditRecord extends CompressionAuditBase {
+  readonly kind: 'review-outcome'
+  /** Stable proposal id (sha-256 digest cut, 12 hex chars). */
+  readonly proposalId: string
+  /** Reduction kind the proposal came from. */
+  readonly proposalKind: 'estimator' | 'dedup' | 'read-state'
+  readonly event:
+    | 'enqueue'
+    | 'expire'
+    | 'decide'
+    | 'apply-void'
+    | 'apply-receipt'
+  /** Human decision (decide events only). */
+  readonly decision?: 'approved' | 'rejected' | 'ignored'
+  /** Execution receipt state (apply-receipt only). */
+  readonly receiptStatus?: 'applied' | 'deferred'
+  /** Aligned reason code (deferred receipts and void applications only). */
+  readonly reasonCode?: string
+  readonly itemSeqs: readonly number[]
+  readonly tokensBefore: number
+  readonly tokensAfter: number
+  /** Turn index the event happened at. */
+  readonly turnIndex?: number
+}
+
 /** Closed version-one context-compression audit vocabulary. */
 export type CompressionAuditRecord =
   | CompressionPolicyFrozenAuditRecord
@@ -177,6 +203,7 @@ export type CompressionAuditRecord =
   | NativeAutoCompactAuditRecord
   | SummaryLocatorAuditRecord
   | EstimatorOutcomeAuditRecord
+  | ReviewOutcomeAuditRecord
 
 /** Minimal logger method consumed by the audit publisher. */
 export interface CompressionAuditLogger {

package/packages/selector/src/runtime/config.ts

@@ -127,12 +127,13 @@ export function parsePresetOptionsSettings(value: unknown): PresetOptionsSetting
   const allowed = new Set([
     'dedupeToolResults', 'summaryLocator', 'prefixStabilizer', 'readState', 'estimatorMode',
     'estimatorProvider', 'estimatorModel', 'estimatorBaseUrl', 'estimatorApiKey', 'estimatorTimeoutMs',
+    'reviewMode', 'reviewTimeoutTurns', 'cacheHitDiscountAlpha', 'reviewHighImpactTokens',
   ])
   const unknown = Object.keys(value).find(key => !allowed.has(key))
   if (unknown !== undefined) {
     throw new TypeError(`Context-compression presetOptions: unknown key "${unknown}"`)
   }
-  const booleans = ['dedupeToolResults', 'summaryLocator', 'prefixStabilizer', 'readState'] as const
+  const booleans = ['dedupeToolResults', 'summaryLocator', 'prefixStabilizer', 'readState', 'reviewMode'] as const
   for (const key of booleans) {
     const entry = value[key]
     if (entry !== undefined && typeof entry !== 'boolean') {
@@ -149,6 +150,23 @@ export function parsePresetOptionsSettings(value: unknown): PresetOptionsSetting
       || estimatorTimeoutMs < 100 || estimatorTimeoutMs > 60_000)) {
     throw new TypeError('Context-compression presetOptions.estimatorTimeoutMs must be an integer between 100 and 60000')
   }
+  const reviewTimeoutTurns = value.reviewTimeoutTurns
+  if (reviewTimeoutTurns !== undefined
+    && (typeof reviewTimeoutTurns !== 'number' || !Number.isSafeInteger(reviewTimeoutTurns) || reviewTimeoutTurns < 1)) {
+    throw new TypeError('Context-compression presetOptions.reviewTimeoutTurns must be an integer of at least 1')
+  }
+  const cacheHitDiscountAlpha = value.cacheHitDiscountAlpha
+  if (cacheHitDiscountAlpha !== undefined
+    && (typeof cacheHitDiscountAlpha !== 'number' || !Number.isFinite(cacheHitDiscountAlpha)
+      || cacheHitDiscountAlpha <= 0 || cacheHitDiscountAlpha >= 1)) {
+    throw new TypeError('Context-compression presetOptions.cacheHitDiscountAlpha must be a number strictly between 0 and 1')
+  }
+  const reviewHighImpactTokens = value.reviewHighImpactTokens
+  if (reviewHighImpactTokens !== undefined
+    && (typeof reviewHighImpactTokens !== 'number' || !Number.isSafeInteger(reviewHighImpactTokens)
+      || reviewHighImpactTokens < 0)) {
+    throw new TypeError('Context-compression presetOptions.reviewHighImpactTokens must be a non-negative integer')
+  }
   for (const key of ['estimatorProvider', 'estimatorModel', 'estimatorBaseUrl', 'estimatorApiKey'] as const) {
     const entry = value[key]
     if (entry !== undefined && typeof entry !== 'string') {
@@ -168,6 +186,10 @@ export function parsePresetOptionsSettings(value: unknown): PresetOptionsSetting
   if (value.estimatorBaseUrl !== undefined) result.estimatorBaseUrl = value.estimatorBaseUrl as string
   if (value.estimatorApiKey !== undefined) result.estimatorApiKey = value.estimatorApiKey as string
   if (estimatorTimeoutMs !== undefined) result.estimatorTimeoutMs = estimatorTimeoutMs as number
+  if (value.reviewMode !== undefined) result.reviewMode = value.reviewMode as boolean
+  if (reviewTimeoutTurns !== undefined) result.reviewTimeoutTurns = reviewTimeoutTurns as number
+  if (cacheHitDiscountAlpha !== undefined) result.cacheHitDiscountAlpha = cacheHitDiscountAlpha as number
+  if (reviewHighImpactTokens !== undefined) result.reviewHighImpactTokens = reviewHighImpactTokens as number
   return result
 }
 
@@ -415,6 +437,12 @@ const PRESET_OPTION_DEFAULTS: PresetOptions = deepFreeze({
   prefixStabilizer: true,
   readState: true,
   estimator: { mode: '' },
+  // Review pipeline (beta) ships off: pending proposals never block the
+  // automatic path until the user opts in.
+  reviewMode: false,
+  reviewTimeoutTurns: 6,
+  cacheHitDiscountAlpha: 0.1,
+  reviewHighImpactTokens: 4000,
 })
 
 /**
@@ -432,6 +460,10 @@ function mergePresetOptions(overrides: PresetOptionsSettings | undefined): Prese
     prefixStabilizer: overrides.prefixStabilizer ?? PRESET_OPTION_DEFAULTS.prefixStabilizer,
     readState: overrides.readState ?? PRESET_OPTION_DEFAULTS.readState,
     estimator: { mode: overrides.estimatorMode ?? PRESET_OPTION_DEFAULTS.estimator.mode },
+    reviewMode: overrides.reviewMode ?? PRESET_OPTION_DEFAULTS.reviewMode,
+    reviewTimeoutTurns: overrides.reviewTimeoutTurns ?? PRESET_OPTION_DEFAULTS.reviewTimeoutTurns,
+    cacheHitDiscountAlpha: overrides.cacheHitDiscountAlpha ?? PRESET_OPTION_DEFAULTS.cacheHitDiscountAlpha,
+    reviewHighImpactTokens: overrides.reviewHighImpactTokens ?? PRESET_OPTION_DEFAULTS.reviewHighImpactTokens,
   })
 }