dsh-context-compression-improved 0.4.0 → 0.5.1

package/packages/selector/src/index.ts

@@ -12,6 +12,7 @@ import {
   ContextCompressionSettingsSchema,
 } from './runtime/config.ts'
 import { resolveReviewPruner, type ReviewPrunerFace } from './runtime/tokenpilot/review-registry.ts'
+import { getAdvisorState } from './runtime/tokenpilot/advisor-state.ts'
 
 // The settings namespace literal and the settings schema are owned by the
 // runtime config module. Both were once inlined/replaced here to dodge a
@@ -45,6 +46,12 @@ const REVIEW_DECIDE_ROUTES = [
   '/api/dsh-context-compression-improved/review-decide',
 ] as const
 
+// Advisory advisor: one read-only report route, dual prefixed like the others.
+const ADVISOR_REPORT_ROUTES = [
+  '/endpoint/dsh-context-compression-improved/advisor-report',
+  '/api/dsh-context-compression-improved/advisor-report',
+] as const
+
 /**
  * The review faces of the pruner service the routes consume. Owned by the
  * review registry, which the routes also fall back to when no top-level
@@ -301,6 +308,96 @@ function registerReviewQueueRoutes(ctx: Context): void {
   log('warn', 'context-compression webServer not active yet — review routes pending: %s', REVIEW_QUEUE_ROUTES.join(', '))
 }
 
+/**
+ * Serve the advisory advisor's read-only report route (same registration
+ * skeleton as the review routes):
+ *
+ * `GET .../advisor-report?sessionId=…` → the session's prefix-decay figure,
+ * the todolist-bound task summary, and the score distribution. Content-free
+ * by construction: task semantics are LLM-derived summaries, never message
+ * text, and no score reason or candidate preview is ever returned.
+ * Unknown session → 404; no agents service → 503. A session whose advisor
+ * never ran reports nulls and empty arrays, not an error.
+ */
+function registerAdvisorReportRoute(ctx: Context): void {
+  const readService = (name: string): unknown => {
+    try {
+      return (ctx as unknown as { get: (service: string) => unknown }).get(name)
+    } catch {
+      return undefined
+    }
+  }
+  const log = (level: 'info' | 'warn', message: string, ...args: unknown[]): void => {
+    console[level](message, ...args)
+  }
+
+  const getHandler = (req: unknown, res: unknown): void => {
+    const agents = readService('agents') as AgentsServiceLike | undefined
+    if (typeof agents?.get !== 'function') {
+      reviewJson(res, 503, { ok: false, error: 'advisor report unavailable' })
+      return
+    }
+    let sessionId = ''
+    try {
+      const url = new URL(String((req as { url?: string }).url ?? ''), 'http://localhost')
+      sessionId = url.searchParams.get('sessionId') ?? ''
+    } catch {
+      // Malformed URL: fall through with the empty sessionId already set.
+    }
+    if (sessionId === '') {
+      reviewJson(res, 400, { ok: false, error: 'sessionId is required' })
+      return
+    }
+    const session = sessionFor(readService, sessionId)
+    if (session === undefined) {
+      reviewJson(res, 404, { ok: false, error: 'unknown session' })
+      return
+    }
+    const state = getAdvisorState(session as Parameters<typeof getAdvisorState>[0])
+    reviewJson(res, 200, {
+      ok: true,
+      sessionId,
+      advisor: {
+        summary: state.summary ?? null,
+        decay: state.lastDecay?.decay ?? null,
+        weightedChars: state.lastDecay?.weightedChars ?? null,
+        decayTurn: state.lastDecay?.turn ?? null,
+        scores: [...state.scores].map(([seq, entry]) => ({ seq, score: entry.score, turn: entry.turn })),
+        lowRelevanceSeqs: [...state.recertified.keys()],
+      },
+    })
+  }
+
+  const register = (webServer: WebServerLike): void => {
+    const table = [...ADVISOR_REPORT_ROUTES].map(path => ({ path, handler: getHandler }))
+    const disposers = table
+      .map(entry => webServer.register({ kind: 'exact', path: entry.path, handler: entry.handler }))
+      .filter((off): off is () => void => typeof off === 'function')
+    ctx.effect(
+      () => () => { for (const off of disposers) off() },
+      'contextCompressionSelector.advisor report route',
+    )
+    log('info', 'context-compression advisor report route registered: %s', ADVISOR_REPORT_ROUTES.join(', '))
+  }
+
+  const active = asWebServer(readService('webServer'))
+  if (active !== undefined) {
+    register(active)
+    return
+  }
+
+  ctx.inject(['webServer'], (injected) => {
+    const webServer = asWebServer((injected as { webServer?: unknown }).webServer)
+    if (webServer === undefined) {
+      log('warn', 'context-compression webServer exposes no register() — advisor report route not registered')
+      return
+    }
+    register(webServer)
+  })
+
+  log('warn', 'context-compression webServer not active yet — advisor report route pending: %s', ADVISOR_REPORT_ROUTES.join(', '))
+}
+
 /**
  * The one service the catalog route actually needs. `llm` and
  * `agentDefaultModel` are payload enrichment the handler resolves per request,
@@ -484,6 +581,13 @@ export interface Config {
    * transport and simply never appears.
    */
   reviewQueueRoute?: boolean
+  /**
+   * Register the advisory advisor's read-only HTTP report route (decay
+   * figure, task summary, score distribution). Same Bundle opt-in semantics
+   * as `reviewQueueRoute`; the advisor itself stays off until the user turns
+   * it on through the `presetOptions.advisor*` settings keys.
+   */
+  advisorReportRoute?: boolean
 }
 
 /** Loader validation for the standalone Bundle opt-in. */
@@ -491,6 +595,7 @@ export const Config: z<Config> = z.object({
   presetOverlay: z.boolean().default(false),
   estimatorCatalogRoute: z.boolean().default(false),
   reviewQueueRoute: z.boolean().default(false),
+  advisorReportRoute: z.boolean().default(false),
 })
 
 /** Register the persisted default read by the currently mounted root pruner. */
@@ -514,6 +619,9 @@ export function apply(ctx: Context, config: Config = {}): void {
     // config JSDoc for the opt-in semantics).
     if (config.reviewQueueRoute === true) registerReviewQueueRoutes(ctx)
 
+    // Advisory advisor: read-only decay/score report (opt-in, like review).
+    if (config.advisorReportRoute === true) registerAdvisorReportRoute(ctx)
+
     if (config.presetOverlay !== true) return
 
     ctx.inject(['agentPresets'], (presetsCtx) => {

package/packages/selector/src/preset-overlay.ts

@@ -116,6 +116,16 @@ export function standingStampMs(identity: string): number {
   return standingStampMsAtWindow(identity, 0)
 }
 
+/**
+ * True for the filesystem errors a concurrent publish can raise on Windows:
+ * `MoveFileEx` reports a lost race — or a reader holding the destination open —
+ * as EPERM/EBUSY/EACCES, where POSIX `rename` simply replaces the destination.
+ */
+function isPublishRace(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code
+  return code === 'EPERM' || code === 'EBUSY' || code === 'EACCES' || code === 'EEXIST'
+}
+
 const COMPRESSION_IDS = new Set([
   'compaction',
   'compaction-basic',
@@ -224,7 +234,7 @@ class PresetOverlayStore {
       // still private. No reader can observe a colliding {mtimeMs,size}
       // between rename and a later corrective utimes call.
       await this.disambiguateStamp(staging, identity)
-      await rename(staging, path)
+      await this.publish(staging, path)
     } catch (error) {
       // A failed publish must not leak its staging file into the store; the
       // cleanup must never mask the original failure either.
@@ -238,6 +248,55 @@ class PresetOverlayStore {
     return { ...preset, path }
   }
 
+  /** In-flight publish chains, one per destination path. */
+  private readonly publishChains = new Map<string, Promise<void>>()
+
+  /**
+   * Publish one stamped staging file to its final path, serialized per path.
+   *
+   * POSIX `rename` replaces an existing destination atomically, so concurrent
+   * composers of one identity are naturally idempotent there. Windows
+   * `MoveFileEx` instead fails the loser of that race with EPERM/EBUSY, which
+   * surfaced as `standingKeyFor()` throwing during concurrent composition.
+   * Every composer of one identity writes identical bytes and re-derives the
+   * same deterministic identity stamp, so a destination that already observes
+   * this staging file's {mtimeMs, size} key IS the intended end state: confirm
+   * it and treat the lost race as success. Every other outcome still throws, so
+   * a silently reused generation stays forbidden, and the caller still removes
+   * the staging file when this rejects.
+   */
+  private publish(staging: string, path: string): Promise<void> {
+    const previous = this.publishChains.get(path) ?? Promise.resolve()
+    const queued = previous.catch(() => undefined).then(async () => {
+      try {
+        await rename(staging, path)
+        return
+      } catch (error) {
+        if (!isPublishRace(error)) throw error
+        try {
+          const intended = await this.metadataIo.read(staging)
+          const published = await this.metadataIo.read(path)
+          // Sub-second precision survives a wrapped seconds field, but NTFS
+          // rounds it to 100ns, so compare the standing key within that
+          // rounding rather than by exact float equality.
+          if (published.size === intended.size
+            && Math.abs(published.mtimeMs - intended.mtimeMs) < 2) {
+            await rm(staging, { force: true })
+            return
+          }
+        } catch {
+          // The destination is unreadable: report the original publish failure.
+        }
+        throw error
+      }
+    })
+    const tracked = queued.finally(() => {
+      if (this.publishChains.get(path) === tracked) this.publishChains.delete(path)
+    })
+    this.publishChains.set(path, tracked)
+    return tracked
+  }
+
   /** Observed {mtimeMs,size} keys published by this store, per identity. */
   private readonly standingKeys = new Map<string, string>()
 

package/packages/selector/src/profiles.ts

@@ -140,6 +140,13 @@ export interface PresetOptionsSettings {
   readonly reviewTimeoutTurns?: number
   readonly cacheHitDiscountAlpha?: number
   readonly reviewHighImpactTokens?: number
+  /** Advisory advisor channel; `''` (the default) keeps the advisor off. */
+  readonly advisorMode?: '' | 'host' | 'direct'
+  readonly advisorTimeoutMs?: number
+  readonly advisorRefreshTurns?: number
+  readonly advisorScoreThreshold?: number
+  readonly advisorSampleLimit?: number
+  readonly advisorMinTokens?: number
 }
 
 /**
@@ -154,6 +161,8 @@ export function decodePresetOptionsSettings(value: unknown): PresetOptionsSettin
     'dedupeToolResults', 'summaryLocator', 'prefixStabilizer', 'readState', 'estimatorMode',
     'estimatorProvider', 'estimatorModel', 'estimatorBaseUrl', 'estimatorApiKey', 'estimatorTimeoutMs',
     'reviewMode', 'reviewTimeoutTurns', 'cacheHitDiscountAlpha', 'reviewHighImpactTokens',
+    'advisorMode', 'advisorTimeoutMs', 'advisorRefreshTurns', 'advisorScoreThreshold', 'advisorSampleLimit',
+    'advisorMinTokens',
   ])
   if (Object.keys(value).some(key => !allowed.has(key))) return undefined
   for (const key of ['dedupeToolResults', 'summaryLocator', 'prefixStabilizer', 'readState', 'reviewMode'] as const) {
@@ -164,6 +173,10 @@ export function decodePresetOptionsSettings(value: unknown): PresetOptionsSettin
   if (estimatorMode !== undefined && estimatorMode !== '' && estimatorMode !== 'host' && estimatorMode !== 'direct') {
     return undefined
   }
+  const advisorMode = value.advisorMode
+  if (advisorMode !== undefined && advisorMode !== '' && advisorMode !== 'host' && advisorMode !== 'direct') {
+    return undefined
+  }
   for (const key of ['estimatorProvider', 'estimatorModel', 'estimatorBaseUrl', 'estimatorApiKey'] as const) {
     const entry = value[key]
     if (entry !== undefined && typeof entry !== 'string') return undefined
@@ -191,6 +204,35 @@ export function decodePresetOptionsSettings(value: unknown): PresetOptionsSettin
       || reviewHighImpactTokens < 0)) {
     return undefined
   }
+  const advisorTimeoutMs = value.advisorTimeoutMs
+  if (advisorTimeoutMs !== undefined
+    && (typeof advisorTimeoutMs !== 'number' || !Number.isSafeInteger(advisorTimeoutMs)
+      || advisorTimeoutMs < 100 || advisorTimeoutMs > 60_000)) {
+    return undefined
+  }
+  const advisorRefreshTurns = value.advisorRefreshTurns
+  if (advisorRefreshTurns !== undefined
+    && (typeof advisorRefreshTurns !== 'number' || !Number.isSafeInteger(advisorRefreshTurns)
+      || advisorRefreshTurns < 1)) {
+    return undefined
+  }
+  const advisorScoreThreshold = value.advisorScoreThreshold
+  if (advisorScoreThreshold !== undefined
+    && (typeof advisorScoreThreshold !== 'number' || !Number.isFinite(advisorScoreThreshold)
+      || advisorScoreThreshold <= 0 || advisorScoreThreshold >= 1)) {
+    return undefined
+  }
+  const advisorSampleLimit = value.advisorSampleLimit
+  if (advisorSampleLimit !== undefined
+    && (typeof advisorSampleLimit !== 'number' || !Number.isSafeInteger(advisorSampleLimit)
+      || advisorSampleLimit < 1 || advisorSampleLimit > 64)) {
+    return undefined
+  }
+  const advisorMinTokens = value.advisorMinTokens
+  if (advisorMinTokens !== undefined
+    && (typeof advisorMinTokens !== 'number' || !Number.isSafeInteger(advisorMinTokens) || advisorMinTokens < 1)) {
+    return undefined
+  }
   const decoded: {
     -readonly [K in keyof PresetOptionsSettings]: PresetOptionsSettings[K]
   } = {}
@@ -208,6 +250,12 @@ export function decodePresetOptionsSettings(value: unknown): PresetOptionsSettin
   if (reviewTimeoutTurns !== undefined) decoded.reviewTimeoutTurns = reviewTimeoutTurns as number
   if (cacheHitDiscountAlpha !== undefined) decoded.cacheHitDiscountAlpha = cacheHitDiscountAlpha as number
   if (reviewHighImpactTokens !== undefined) decoded.reviewHighImpactTokens = reviewHighImpactTokens as number
+  if (advisorMode !== undefined) decoded.advisorMode = advisorMode as '' | 'host' | 'direct'
+  if (advisorTimeoutMs !== undefined) decoded.advisorTimeoutMs = advisorTimeoutMs as number
+  if (advisorRefreshTurns !== undefined) decoded.advisorRefreshTurns = advisorRefreshTurns as number
+  if (advisorScoreThreshold !== undefined) decoded.advisorScoreThreshold = advisorScoreThreshold as number
+  if (advisorSampleLimit !== undefined) decoded.advisorSampleLimit = advisorSampleLimit as number
+  if (advisorMinTokens !== undefined) decoded.advisorMinTokens = advisorMinTokens as number
   return decoded
 }
 

package/packages/selector/src/pruner/state.ts

@@ -9,6 +9,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
 import type { DedupeTable } from '../runtime/tokenpilot/dedup.ts'
 import type { EstimatorFailures } from '../runtime/tokenpilot/estimator.ts'
 import type { ReviewQueue, ReviewQueueStore } from '../runtime/tokenpilot/review-queue.ts'
+import type { SideChannel } from '../runtime/tokenpilot/sidechannel.ts'
 import type {
   ContextCompressionSettings,
   ResolvedConfig,
@@ -65,6 +66,8 @@ export interface PrunerState {
   readonly reviewClocks: WeakMap<Session, number>
   /** Estimator-reported remaining turns Ŝ per Session; advisory only. */
   readonly estimatorRemainingTurns: WeakMap<Session, number>
+  /** Per-session advisor side channel, constructed once with the advisor overrides. */
+  readonly advisorChannels: WeakMap<Session, SideChannel>
   /** Four-state outcome counters per Session (floating-window summary row). */
   readonly reviewSummaries: WeakMap<Session, ReviewSessionSummary>
 }

package/packages/selector/src/pruner.ts

@@ -80,6 +80,14 @@ import {
 } from './runtime/tokenpilot/review-queue.ts'
 import { registerReviewPruner, sharedReviewStore } from './runtime/tokenpilot/review-registry.ts'
 import { openReviewStorage } from './runtime/tokenpilot/review-storage.ts'
+import { SideChannel } from './runtime/tokenpilot/sidechannel.ts'
+import {
+  advisorCandidatePreview,
+  collectTailText,
+  collectTaskSemantics,
+  runSessionAdvisorPass,
+} from './runtime/tokenpilot/advisor.ts'
+import { getAdvisorState } from './runtime/tokenpilot/advisor-state.ts'
 
 import {
   DedupeTable,
@@ -237,6 +245,7 @@ export class ToolResultPruner extends Service {
       reviewQueues: new WeakMap(),
       reviewClocks: new WeakMap(),
       estimatorRemainingTurns: new WeakMap(),
+      advisorChannels: new WeakMap(),
       reviewSummaries: new WeakMap(),
     }
 
@@ -333,6 +342,10 @@ export class ToolResultPruner extends Service {
       // 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)
+      // Advisory relevance advisor: statistics and suggestions only — its
+      // summaries, scores, and decay figure never touch any decision path.
+      // Strictly fire-and-forget, with its own backoff state.
+      void this.postflightAdvisorPass(agent.session, turn, signal).catch(() => undefined)
     })
   }
 
@@ -644,6 +657,106 @@ export class ToolResultPruner extends Service {
     })
   }
 
+  // ─────────── Advisory relevance advisor (statistics & suggestions only) ───────────
+
+  /**
+   * Advisory advisor pass at the turn boundary, strictly fire-and-forget.
+   * Produces todolist-bound tail-task summaries, incremental relevance
+   * scores, and a prefix-decay figure — all observational. Every short
+   * circuit below (mode off, re-entry, cooldown, no task semantics, no
+   * direct endpoint) returns without touching any state the pruning chain
+   * reads, so the default configuration adds exactly zero behavior.
+   */
+  private async postflightAdvisorPass(session: Session, turn: number, signal: AbortSignal): Promise<void> {
+    const policy = this.activePolicy(session)
+    const presetOptions = policy?.presetOptions
+    const advisor = presetOptions?.advisor
+    if (policy === undefined || presetOptions === undefined || advisor === undefined || advisor.mode === '') return
+    const advisorState = getAdvisorState(session)
+    if (advisorState.inFlight) return
+    if (isCoolingDown(advisorState.failures, Date.now())) return
+
+    const events = sessionEvents(session)
+    const task = collectTaskSemantics(events)
+    if (task === undefined) return
+
+    const settings = this.activeSettings(session).presetOptions ?? {}
+    if (advisor.mode === 'direct'
+      && (settings.estimatorBaseUrl === undefined || settings.estimatorBaseUrl.length === 0
+        || settings.estimatorModel === undefined || settings.estimatorModel.length === 0)) {
+      // The advisor reuses the estimator's direct endpoint; when it is not
+      // configured there is nothing to ask, so record the aligned reason and
+      // back off instead of re-emitting the audit at every turn.
+      emitCompressionAudit(this.ctx.logger, {
+        schemaVersion: 1,
+        kind: 'advisor-outcome',
+        sessionId: String(session.id),
+        phase: 'summary',
+        channel: 'direct',
+        ok: false,
+        turnIndex: turn,
+        reason: 'no-direct-endpoint',
+        latencyMs: 0,
+      })
+      advisorState.failures = {
+        failures: (advisorState.failures?.failures ?? 0) + 1,
+        cooldownUntil: Date.now() + backoffCooldownMs((advisorState.failures?.failures ?? 0) + 1),
+      }
+      return
+    }
+
+    let channel = this.state.advisorChannels.get(session)
+    if (channel === undefined) {
+      channel = new SideChannel(this.ctx, settings, {
+        mode: advisor.mode,
+        timeoutMs: advisor.timeoutMs,
+        maxTokens: 512,
+      })
+      this.state.advisorChannels.set(session, channel)
+    }
+
+    const view = measureForCompaction(this.ctx, session)
+    const candidates = this.snapshot(session, view)
+      .filter(candidate => !this.isRecoveryExempt(session, candidate))
+      .map(candidate => ({
+        seq: candidate.seq,
+        characterPressure: candidate.characterPressure,
+        preview: advisorCandidatePreview(candidate.call.name, candidate.event.data.message.content),
+      }))
+
+    let sawFailure = false
+    const outcome = await runSessionAdvisorPass(session, channel, record => {
+      if (record.ok === false) sawFailure = true
+      emitCompressionAudit(this.ctx.logger, record)
+    }, {
+      profile: policy.profile,
+      sessionId: String(session.id),
+      turn,
+      candidates,
+      task: {
+        source: task.source,
+        todoVersion: task.todoVersion,
+        taskText: task.taskText,
+      },
+      advisor: {
+        refreshTurns: advisor.refreshTurns,
+        scoreThreshold: advisor.scoreThreshold,
+        sampleLimit: advisor.sampleLimit,
+        minTokens: advisor.minTokens,
+      },
+      tailText: collectTailText(events),
+      signal,
+    })
+    if (outcome === undefined && sawFailure && signal.aborted === false) {
+      advisorState.failures = {
+        failures: (advisorState.failures?.failures ?? 0) + 1,
+        cooldownUntil: Date.now() + backoffCooldownMs((advisorState.failures?.failures ?? 0) + 1),
+      }
+    } else if (outcome !== undefined) {
+      advisorState.failures = undefined
+    }
+  }
+
   // ─────────── TokenPilot-inspired R4: human-gated review pipeline ───────────
 
   /**

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

@@ -183,6 +183,27 @@ export interface EstimatorOutcomeAuditRecord extends CompressionAuditBase {
   readonly ok: boolean
 }
 
+/** One background relevance-advisor pass. Only numeric metadata — never prompts, keys, or content. */
+export interface AdvisorOutcomeAuditRecord extends CompressionAuditBase {
+  readonly kind: 'advisor-outcome'
+  /** Which advisory stage produced this record. */
+  readonly phase: 'summary' | 'scoring' | 'decay'
+  /** LLM channel; omitted for the locally computed 'decay' phase. */
+  readonly channel?: 'host' | 'direct'
+  readonly ok: boolean
+  /** Whether the pass found candidates to sample (scoring phase). */
+  readonly sampledCount?: number
+  /** Prefix-decay figure in [0, 1] (decay phase; also emitted by summary/scoring on success). */
+  readonly decay?: number
+  /** Weighted surface the decay was computed over, in Unicode code points. */
+  readonly weightedChars?: number
+  /** Turn index the pass ran at. */
+  readonly turnIndex?: number
+  /** Aligned failure/skip reason code (e.g. 'no-direct-endpoint', 'parse-failed'). */
+  readonly reason?: string
+  readonly latencyMs: number
+}
+
 /** Lifecycle of one human-gated review proposal. Only numeric and enum fields — never content. */
 export interface ReviewOutcomeAuditRecord extends CompressionAuditBase {
   readonly kind: 'review-outcome'
@@ -219,6 +240,7 @@ export type CompressionAuditRecord =
   | NativeAutoCompactAuditRecord
   | SummaryLocatorAuditRecord
   | EstimatorOutcomeAuditRecord
+  | AdvisorOutcomeAuditRecord
   | ReviewOutcomeAuditRecord
 
 /** Minimal logger method consumed by the audit publisher. */

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

@@ -128,6 +128,8 @@ export function parsePresetOptionsSettings(value: unknown): PresetOptionsSetting
     'dedupeToolResults', 'summaryLocator', 'prefixStabilizer', 'readState', 'estimatorMode',
     'estimatorProvider', 'estimatorModel', 'estimatorBaseUrl', 'estimatorApiKey', 'estimatorTimeoutMs',
     'reviewMode', 'reviewTimeoutTurns', 'cacheHitDiscountAlpha', 'reviewHighImpactTokens',
+    'advisorMode', 'advisorTimeoutMs', 'advisorRefreshTurns', 'advisorScoreThreshold', 'advisorSampleLimit',
+    'advisorMinTokens',
   ])
   const unknown = Object.keys(value).find(key => !allowed.has(key))
   if (unknown !== undefined) {
@@ -144,6 +146,39 @@ export function parsePresetOptionsSettings(value: unknown): PresetOptionsSetting
   if (estimatorMode !== undefined && estimatorMode !== '' && estimatorMode !== 'host' && estimatorMode !== 'direct') {
     throw new TypeError('Context-compression presetOptions.estimatorMode must be "", "host", or "direct"')
   }
+  const advisorMode = value.advisorMode
+  if (advisorMode !== undefined && advisorMode !== '' && advisorMode !== 'host' && advisorMode !== 'direct') {
+    throw new TypeError('Context-compression presetOptions.advisorMode must be "", "host", or "direct"')
+  }
+  const advisorTimeoutMs = value.advisorTimeoutMs
+  if (advisorTimeoutMs !== undefined
+    && (typeof advisorTimeoutMs !== 'number' || !Number.isSafeInteger(advisorTimeoutMs)
+      || advisorTimeoutMs < 100 || advisorTimeoutMs > 60_000)) {
+    throw new TypeError('Context-compression presetOptions.advisorTimeoutMs must be an integer between 100 and 60000')
+  }
+  const advisorRefreshTurns = value.advisorRefreshTurns
+  if (advisorRefreshTurns !== undefined
+    && (typeof advisorRefreshTurns !== 'number' || !Number.isSafeInteger(advisorRefreshTurns)
+      || advisorRefreshTurns < 1)) {
+    throw new TypeError('Context-compression presetOptions.advisorRefreshTurns must be an integer of at least 1')
+  }
+  const advisorScoreThreshold = value.advisorScoreThreshold
+  if (advisorScoreThreshold !== undefined
+    && (typeof advisorScoreThreshold !== 'number' || !Number.isFinite(advisorScoreThreshold)
+      || advisorScoreThreshold <= 0 || advisorScoreThreshold >= 1)) {
+    throw new TypeError('Context-compression presetOptions.advisorScoreThreshold must be a number strictly between 0 and 1')
+  }
+  const advisorSampleLimit = value.advisorSampleLimit
+  if (advisorSampleLimit !== undefined
+    && (typeof advisorSampleLimit !== 'number' || !Number.isSafeInteger(advisorSampleLimit)
+      || advisorSampleLimit < 1 || advisorSampleLimit > 64)) {
+    throw new TypeError('Context-compression presetOptions.advisorSampleLimit must be an integer between 1 and 64')
+  }
+  const advisorMinTokens = value.advisorMinTokens
+  if (advisorMinTokens !== undefined
+    && (typeof advisorMinTokens !== 'number' || !Number.isSafeInteger(advisorMinTokens) || advisorMinTokens < 1)) {
+    throw new TypeError('Context-compression presetOptions.advisorMinTokens must be a positive integer')
+  }
   const estimatorTimeoutMs = value.estimatorTimeoutMs
   if (estimatorTimeoutMs !== undefined
     && (typeof estimatorTimeoutMs !== 'number' || !Number.isSafeInteger(estimatorTimeoutMs)
@@ -190,6 +225,12 @@ export function parsePresetOptionsSettings(value: unknown): PresetOptionsSetting
   if (reviewTimeoutTurns !== undefined) result.reviewTimeoutTurns = reviewTimeoutTurns as number
   if (cacheHitDiscountAlpha !== undefined) result.cacheHitDiscountAlpha = cacheHitDiscountAlpha as number
   if (reviewHighImpactTokens !== undefined) result.reviewHighImpactTokens = reviewHighImpactTokens as number
+  if (advisorMode !== undefined) result.advisorMode = advisorMode as '' | 'host' | 'direct'
+  if (advisorTimeoutMs !== undefined) result.advisorTimeoutMs = advisorTimeoutMs as number
+  if (advisorRefreshTurns !== undefined) result.advisorRefreshTurns = advisorRefreshTurns as number
+  if (advisorScoreThreshold !== undefined) result.advisorScoreThreshold = advisorScoreThreshold as number
+  if (advisorSampleLimit !== undefined) result.advisorSampleLimit = advisorSampleLimit as number
+  if (advisorMinTokens !== undefined) result.advisorMinTokens = advisorMinTokens as number
   return result
 }
 
@@ -463,6 +504,15 @@ const PRESET_OPTION_DEFAULTS: PresetOptions = deepFreeze({
   reviewTimeoutTurns: 6,
   cacheHitDiscountAlpha: 0.1,
   reviewHighImpactTokens: 4000,
+  // Advisory advisor ships off: statistics and suggestions only, never a gate.
+  advisor: {
+    mode: '',
+    timeoutMs: 8_000,
+    refreshTurns: 8,
+    scoreThreshold: 0.35,
+    sampleLimit: 16,
+    minTokens: 250,
+  },
 })
 
 /**
@@ -484,6 +534,14 @@ function mergePresetOptions(overrides: PresetOptionsSettings | undefined): Prese
     reviewTimeoutTurns: overrides.reviewTimeoutTurns ?? PRESET_OPTION_DEFAULTS.reviewTimeoutTurns,
     cacheHitDiscountAlpha: overrides.cacheHitDiscountAlpha ?? PRESET_OPTION_DEFAULTS.cacheHitDiscountAlpha,
     reviewHighImpactTokens: overrides.reviewHighImpactTokens ?? PRESET_OPTION_DEFAULTS.reviewHighImpactTokens,
+    advisor: {
+      mode: overrides.advisorMode ?? PRESET_OPTION_DEFAULTS.advisor.mode,
+      timeoutMs: overrides.advisorTimeoutMs ?? PRESET_OPTION_DEFAULTS.advisor.timeoutMs,
+      refreshTurns: overrides.advisorRefreshTurns ?? PRESET_OPTION_DEFAULTS.advisor.refreshTurns,
+      scoreThreshold: overrides.advisorScoreThreshold ?? PRESET_OPTION_DEFAULTS.advisor.scoreThreshold,
+      sampleLimit: overrides.advisorSampleLimit ?? PRESET_OPTION_DEFAULTS.advisor.sampleLimit,
+      minTokens: overrides.advisorMinTokens ?? PRESET_OPTION_DEFAULTS.advisor.minTokens,
+    },
   })
 }