@animalabs/context-manager 0.5.4 → 0.5.5

package/src/adaptive/picker.ts

@@ -81,6 +81,19 @@ export interface PickerChunk {
   lockedByAgent: boolean;
   bodyGroupId?: string;
   pinned: boolean;
+  /**
+   * V2 dynamic pin — fix this chunk at EXACTLY this fold level (0 = raw). Set
+   * from a `ProtectedRange.level`. Such a chunk is NOT `pinned` (the controller
+   * must be able to move it to its level), but the KV-stable controller holds it
+   * there and never folds/un-folds it. Ignored by non-kv-stable strategies.
+   */
+  pinLevel?: number;
+  /**
+   * V2 dynamic pin — this chunk may fold no deeper than this level (hard cap).
+   * Set from a `ProtectedRange.maxLevel`. Honored only by the KV-stable
+   * controller (in normal and emergency shedding). Ignored elsewhere.
+   */
+  pinMaxLevel?: number;
   /**
    * The L1 summary covering this chunk, if any. Higher levels are derived
    * by walking parentId pointers in the summary tree.

package/src/adaptive/strategies/kv-stable.ts

@@ -69,20 +69,56 @@ export class KvStableStrategy implements FoldingStrategy {
   private solve(budget: FoldingBudget): Map<ChunkId, number> {
     const tree = new SummaryTree(this.inputs);
 
-    // Flat zone (forced raw, never folded): head, tail, pinned. Frozen (kept at
-    // their carried resolution, never folded): locked.
+    // Flat zone (forced raw, never folded): head, tail, classic pins. Frozen
+    // (kept at their carried resolution, never folded): locked. V2 dynamic pins
+    // (`pinLevel` / `pinMaxLevel`) are honored as a fixed level or a hard fold-
+    // depth cap — see `planControlledFrontier`.
     const rawZone = new Set<ChunkId>();
     const frozen = new Set<ChunkId>();
+    const fixedLevels = new Map<ChunkId, number>();
+    const pinCaps = new Map<ChunkId, number>();
+    const fixedPins: Array<{ id: ChunkId; level: number }> = [];
     let now = 0;
     for (const c of this.inputs.chunks) {
       if (c.sequence > now) now = c.sequence;
       if (this.inputs.headChunkIds.has(c.id) || this.inputs.tailChunkIds.has(c.id) || c.pinned) {
         rawZone.add(c.id);
+      } else if (c.pinLevel !== undefined) {
+        // Pin-at-level-k: fix exactly at k (0 = raw). k=0 is equivalent to a
+        // classic raw pin, so route it through the raw zone; k>0 is resolved to
+        // its whole L_k node below (group-consistent — see the loop after).
+        if (c.pinLevel <= 0) rawZone.add(c.id);
+        else fixedPins.push({ id: c.id, level: c.pinLevel });
+      } else if (c.pinMaxLevel !== undefined) {
+        // Pin-max-level: a hard fold-depth cap. maxLevel 0 ≡ classic raw pin.
+        if (c.pinMaxLevel <= 0) rawZone.add(c.id);
+        else pinCaps.set(c.id, c.pinMaxLevel);
+        if (c.lockedByAgent) frozen.add(c.id);
       } else if (c.lockedByAgent) {
         frozen.add(c.id);
       }
     }
 
+    // Group-consistency for pin-at-level-k: an L_k recall pair is atomic over
+    // its whole covered range, so "cut through the L_k node" (design §7) fixes
+    // EVERY leaf under that node at k — not just the addressed chunk. Fixing a
+    // single sub-chunk while its siblings render raw is an unrenderable (and
+    // non-converging) frontier. Clamp k to the deepest produced level for the
+    // chunk; if none exists, fall back to fixing just the chunk (the controller
+    // clamps it further). Skip leaves already forced raw (head/tail/classic pin).
+    for (const { id, level } of fixedPins) {
+      const eff = Math.min(level, tree.maxLevel(id));
+      if (eff <= 0) { rawZone.add(id); continue; }
+      const node = tree.ancestorAt(id, eff);
+      if (!node) { fixedLevels.set(id, eff); continue; }
+      for (const leaf of node.leafChunkIds) {
+        if (rawZone.has(leaf)) continue;
+        // Finest requirement wins if two pins overlap a leaf.
+        const prev = fixedLevels.get(leaf);
+        fixedLevels.set(leaf, prev === undefined ? eff : Math.min(prev, eff));
+      }
+    }
+
     return planControlledFrontier(this.inputs, tree, {
       previous: this.fPrev,
       // Bidirectional within the slack band: fold when over the hard budget,
@@ -95,6 +131,8 @@ export class KvStableStrategy implements FoldingStrategy {
       reachTokens: this.opts.reachTokens,
       rawZone,
       frozen,
+      fixedLevels,
+      pinCaps,
       now,
       mergeThreshold: this.opts.mergeThreshold,
     }).resolutions;

package/src/context-manager.ts

@@ -16,6 +16,7 @@ import type {
   ContextInjection,
   CompileResult,
   ProtectedRange,
+  PinLevelOptions,
   SearchQuery,
   SearchResult,
   SummaryEntry,
@@ -640,19 +641,29 @@ export class ContextManager {
    *
    * Throws if the active strategy doesn't support pins.
    */
-  pinRange(firstMessageId: MessageId, lastMessageId: MessageId, opts?: { name?: string }): string {
+  pinRange(firstMessageId: MessageId, lastMessageId: MessageId, opts?: PinLevelOptions): string {
     if (!isPinnableStrategy(this.strategy)) {
       throw new Error('Active strategy does not support pins');
     }
     return this.strategy.pinRange(firstMessageId, lastMessageId, opts);
   }
 
+  /**
+   * V2 dynamic pin-at-level-k: fix a range to render at EXACTLY fold level
+   * `level` (0 = raw) — the frontier cut passes through that L_k node. Honored
+   * only by `foldingStrategy: 'kv-stable'`; other strategies fall back to
+   * treating the range as raw. Returns the new pin id.
+   */
+  pinAtLevel(firstMessageId: MessageId, lastMessageId: MessageId, level: number, opts?: { name?: string }): string {
+    return this.pinRange(firstMessageId, lastMessageId, { name: opts?.name, level });
+  }
+
   /**
    * Mark a single message as a "document" (semantically a body of
    * information to retain in full). Same effect as a single-message pin
    * with `kind: 'document'`. Returns the new pin id.
    */
-  markDocument(messageId: MessageId, opts?: { name?: string }): string {
+  markDocument(messageId: MessageId, opts?: PinLevelOptions): string {
     if (!isPinnableStrategy(this.strategy)) {
       throw new Error('Active strategy does not support documents');
     }

package/src/index.ts

@@ -2,6 +2,9 @@
 export { ContextManager } from './context-manager.js';
 export type { ContextManagerConfig } from './context-manager.js';
 
+// Phase channel (liveness-watchdog observability hook)
+export { phaseChannel, enterPhase, withPhase, withPhaseAsync } from './phase-channel.js';
+
 // Storage
 export { MessageStore } from './message-store.js';
 export type { MessageStoreEvent, MessageStoreListener } from './message-store.js';

package/src/phase-channel.ts

@@ -0,0 +1,57 @@
+/**
+ * Phase channel — a process-wide observability hook for labelling the
+ * synchronous operation the main thread is currently running.
+ *
+ * Long synchronous work (context assembly, compression, merge-graph walks) can
+ * wedge the single-threaded event loop. An external liveness watchdog (in the
+ * host/agent-framework) can detect the wedge but not name what was running —
+ * unless the running code labels itself here. This module is a no-op sink by
+ * default; the watchdog installs `report` on start so labels reach its wedge
+ * report. context-manager owns the channel (no upward dependency); the watchdog
+ * (which depends on context-manager) wires it.
+ */
+const stack: string[] = [];
+
+export const phaseChannel: {
+  /** Installed by the watchdog; receives the current (innermost) phase label. */
+  report: (label: string) => void;
+} = {
+  report: () => {},
+};
+
+/** Enter a named phase. Returns a disposer that restores the previous phase. */
+export function enterPhase(label: string): () => void {
+  stack.push(label);
+  phaseChannel.report(label);
+  let done = false;
+  return () => {
+    if (done) return;
+    done = true;
+    // Pop this label (tolerate out-of-order disposal defensively).
+    const idx = stack.lastIndexOf(label);
+    if (idx !== -1) stack.splice(idx, 1);
+    phaseChannel.report(stack[stack.length - 1] ?? 'idle');
+  };
+}
+
+/** Run a synchronous section under a phase label (nesting-safe). */
+export function withPhase<T>(label: string, fn: () => T): T {
+  const leave = enterPhase(label);
+  try {
+    return fn();
+  } finally {
+    leave();
+  }
+}
+
+/** Run an async section under a phase label. Note: this labels across awaits,
+ *  which is what we want — the synchronous spans inside (where a wedge would
+ *  occur) stay attributed to this phase. */
+export async function withPhaseAsync<T>(label: string, fn: () => Promise<T>): Promise<T> {
+  const leave = enterPhase(label);
+  try {
+    return await fn();
+  } finally {
+    leave();
+  }
+}

package/src/strategies/autobiographical.ts

@@ -1,6 +1,7 @@
 import type { JsStore } from '@animalabs/chronicle';
 import type { Membrane, NormalizedRequest, ContentBlock, CompleteOptions } from '@animalabs/membrane';
 import { NativeFormatter } from '@animalabs/membrane';
+import { phaseChannel } from '../phase-channel.js';
 import type {
   ContextStrategy,
   ResettableStrategy,
@@ -15,6 +16,7 @@ import type {
   SummaryLevel,
   SummaryEntry,
   ProtectedRange,
+  PinLevelOptions,
   SearchQuery,
   SearchResult,
   RenderStats,
@@ -252,6 +254,21 @@ export interface AutobiographicalProgressSnapshot {
   pending: boolean;
 }
 
+/**
+ * Validate + normalize the optional V2 pin fold-depth bounds. Returns only the
+ * fields that are present and valid (non-negative integers), so a classic pin
+ * with no bounds persists exactly as before. `level` takes precedence over
+ * `maxLevel` (pin-at-k is stronger than a cap), so they're never both emitted.
+ */
+function normalizePinLevels(opts?: PinLevelOptions): { level?: number; maxLevel?: number } {
+  const clean = (v: number | undefined): number | undefined =>
+    typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : undefined;
+  const level = clean(opts?.level);
+  if (level !== undefined) return { level };
+  const maxLevel = clean(opts?.maxLevel);
+  return maxLevel !== undefined ? { maxLevel } : {};
+}
+
 /**
  * Autobiographical chunking strategy.
  * Compresses old conversation chunks into summaries in the model's own words.
@@ -271,6 +288,14 @@ export class AutobiographicalStrategy implements ResettableStrategy {
   protected pendingCompression: Promise<void> | null = null;
   protected compressionQueue: number[] = [];
   protected _compressionCount = 0;
+  /**
+   * Monotonic counter of tick() operations that actually processed a queue item
+   * (compressed a chunk or executed a merge). `driveSpeculativeDrain` recurses
+   * while this advances — a length-delta check would falsely read "no progress"
+   * when a productive tick also enqueues a follow-on item (net queue length
+   * unchanged), halting the drain with work still queued.
+   */
+  protected _drainProgress = 0;
 
   // Hierarchical state
   protected summaries: SummaryEntry[] = [];
@@ -583,7 +608,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * Pin a range of messages so they aren't compressed and render raw at
    * their original position. Returns the pin id.
    */
-  pinRange(firstMessageId: string, lastMessageId: string, opts?: { name?: string }): string {
+  pinRange(firstMessageId: string, lastMessageId: string, opts?: PinLevelOptions): string {
     const id = `pin-${this.pinIdCounter++}`;
     this.pins.push({
       id,
@@ -592,6 +617,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       kind: 'pin',
       name: opts?.name,
       created: Date.now(),
+      ...normalizePinLevels(opts),
     });
     this.persistPins();
     return id;
@@ -602,7 +628,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * information the agent wants to retain in full. Functionally a
    * single-message pin with `kind: 'document'`.
    */
-  markDocument(messageId: string, opts?: { name?: string }): string {
+  markDocument(messageId: string, opts?: PinLevelOptions): string {
     const id = `pin-${this.pinIdCounter++}`;
     this.pins.push({
       id,
@@ -611,11 +637,22 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       kind: 'document',
       name: opts?.name,
       created: Date.now(),
+      ...normalizePinLevels(opts),
     });
     this.persistPins();
     return id;
   }
 
+  /**
+   * V2 dynamic pin-at-level-k convenience: fix a range to render at EXACTLY
+   * fold level `level` (0 = raw). Honored only by `foldingStrategy: 'kv-stable'`;
+   * other strategies fall back to treating the range as raw. Equivalent to
+   * `pinRange(first, last, { level })`.
+   */
+  pinAtLevel(firstMessageId: string, lastMessageId: string, level: number, opts?: { name?: string }): string {
+    return this.pinRange(firstMessageId, lastMessageId, { name: opts?.name, level });
+  }
+
   /** Remove a pin or document mark by id. Returns true if removed. */
   unpin(pinId: string): boolean {
     const before = this.pins.length;
@@ -735,6 +772,42 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     return out;
   }
 
+  /**
+   * Resolve the V2 dynamic-pin fold-depth bounds (`ProtectedRange.level` /
+   * `maxLevel`) to message positions. Only pins that carry a bound appear; a
+   * classic raw pin (no bound) is absent here and handled by `pinnedPositions`.
+   * When ranges overlap, the FINEST requirement wins (lowest effective level):
+   * a fixed `level` clamps both ends; a `maxLevel` only caps depth. Honored
+   * solely by the KV-stable controller — see `ProtectedRange`.
+   */
+  protected pinLevelBounds(messages: StoredMessage[]): Map<number, { level?: number; maxLevel?: number }> {
+    const out = new Map<number, { level?: number; maxLevel?: number }>();
+    if (this.pins.length === 0) return out;
+    const positionOf = new Map<string, number>();
+    for (let i = 0; i < messages.length; i++) positionOf.set(messages[i].id, i);
+
+    for (const pin of this.pins) {
+      if (pin.level === undefined && pin.maxLevel === undefined) continue;
+      const first = positionOf.get(pin.firstMessageId);
+      const last = positionOf.get(pin.lastMessageId);
+      if (first === undefined || last === undefined) continue;
+      const lo = Math.min(first, last);
+      const hi = Math.max(first, last);
+      for (let i = lo; i <= hi; i++) {
+        const prev = out.get(i) ?? {};
+        // A fixed level is the strongest constraint; when two pins fix the same
+        // position, the shallower (lower) level wins (finest requirement).
+        if (pin.level !== undefined) {
+          prev.level = prev.level === undefined ? pin.level : Math.min(prev.level, pin.level);
+        } else if (pin.maxLevel !== undefined) {
+          prev.maxLevel = prev.maxLevel === undefined ? pin.maxLevel : Math.min(prev.maxLevel, pin.maxLevel);
+        }
+        out.set(i, prev);
+      }
+    }
+    return out;
+  }
+
   /**
    * Append a summary to the in-memory list and to the chronicle AppendLog.
    * Single point so subclasses inherit persistence.
@@ -1004,20 +1077,31 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    */
   protected driveSpeculativeDrain(ctx: StrategyContext): void {
     if (this.pendingCompression) return;
-    if (this.compressionQueue.length === 0 && this.mergeQueue.length === 0) return;
-    if (this.isAtSpeculativeCap()) return;
-    if (!this.shouldCompressPreflight()) return;
-
-    const beforeChunks = this.compressionQueue.length;
-    const beforeMerges = this.mergeQueue.length;
+    // Merges consolidate existing L_k summaries into L_{k+1} and REDUCE the
+    // unmerged-L1 count; L1 compression PRODUCES new unmerged L1s. The
+    // speculation cap / preflight throttle *production* only — they must never
+    // gate merges, otherwise exceeding the cap (e.g. after a manual backfill)
+    // permanently deadlocks the drain: too many unmerged L1s trips the cap,
+    // which blocks the very merges that would bring the count back down.
+    const hasMerges = this.config.hierarchical === true && this.mergeQueue.length > 0;
+    const hasCompression = this.compressionQueue.length > 0;
+    if (!hasCompression && !hasMerges) return;
+    // Only bail when the *sole* available work is L1 compression that the cap
+    // or preflight currently forbids. Merge work always proceeds.
+    if (!hasMerges && (this.isAtSpeculativeCap() || !this.shouldCompressPreflight())) return;
+
+    const progressBefore = this._drainProgress;
 
     this.tick(ctx)
       .then(() => {
-        const afterChunks = this.compressionQueue.length;
-        const afterMerges = this.mergeQueue.length;
-        // Made progress if either queue shrank.
-        const progressed = afterChunks < beforeChunks || afterMerges < beforeMerges;
-        if (!progressed) return;
+        // Progress = the tick actually processed a queue item (compress or
+        // merge), tracked by `_drainProgress`. A queue-length delta is the
+        // wrong signal: a productive merge tick can also enqueue a follow-on
+        // merge, leaving the length unchanged — which the old check misread as
+        // "no progress" and halted the drain mid-backlog. A genuine no-op tick
+        // (empty queues, at-cap with no merges, no membrane) doesn't advance
+        // the counter, so this still stops cleanly (no runaway recursion).
+        if (this._drainProgress === progressBefore) return;
         // Recurse to drain more. queueMicrotask defers until the current
         // task is done, letting other code (the agent's stream consumer)
         // interleave.
@@ -1029,14 +1113,23 @@ export class AutobiographicalStrategy implements ResettableStrategy {
   }
 
   /**
-   * Whether the strategy's pending+queued L1 budget has reached the cap
+   * Whether the count of *produced, unmerged* L1 summaries has reached the cap
    * configured by `maxSpeculativeL1s`. If no cap is set, always false.
+   *
+   * The cap bounds how many L1 summaries may sit un-consolidated before the
+   * strategy must merge them into L_{k+1} (bounding prefix churn / merge debt).
+   * It deliberately does NOT count the pending `compressionQueue`: that queue is
+   * the backlog of work to be *drained*, not produced summaries. Counting it
+   * here would let a large backlog permanently trip the cap and block the very
+   * compression that would clear it — a deadlock (merges relieve the cap, but
+   * compression of the backlog never resumes). The throttle is on produced L1s;
+   * the queue drains freely, with merges keeping the unmerged count under the cap.
    */
   protected isAtSpeculativeCap(): boolean {
     const cap = this.config.maxSpeculativeL1s;
     if (cap === undefined || cap < 0) return false;
     const unmergedL1s = this.summaries.filter(s => s.level === 1 && !s.mergedInto).length;
-    return unmergedL1s + this.compressionQueue.length > cap;
+    return unmergedL1s > cap;
   }
 
   /**
@@ -1050,6 +1143,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
   }
 
   async tick(ctx: StrategyContext): Promise<void> {
+    phaseChannel.report('compress-tick'); // liveness-watchdog phase
     if (this.pendingCompression) return;
 
     if (!ctx.membrane) {
@@ -1057,9 +1151,13 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       return;
     }
 
-    // Priority 1: Compress raw chunks → L1
-    if (this.compressionQueue.length > 0) {
+    // Priority 1: Compress raw chunks → L1. Skipped while at the speculative
+    // cap (maxSpeculativeL1s) so we don't pile up more unmerged L1s; the merge
+    // priority below still runs to consolidate existing L1s and relieve the cap.
+    // No cap configured → isAtSpeculativeCap() is always false → unchanged.
+    if (this.compressionQueue.length > 0 && !this.isAtSpeculativeCap()) {
       const chunkIndex = this.compressionQueue.shift()!;
+      this._drainProgress++; // consumed a queue item (real work or stale-cleanup)
       const chunk = this.chunks[chunkIndex];
 
       if (!chunk || chunk.compressed) return;
@@ -1085,6 +1183,8 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     // and the next tick() retries it.
     if (this.config.hierarchical && this.mergeQueue.length > 0) {
       const merge = this.mergeQueue[0]!;
+      this._drainProgress++; // executing a merge is real work, even if a
+      // follow-on merge gets enqueued and the queue length nets out unchanged
       this.pendingCompression = this.executeMerge(merge.level, merge.sourceIds, ctx);
 
       try {
@@ -1403,6 +1503,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * No system prompt — framing via message structure only.
    */
   protected async compressChunkHierarchical(chunk: Chunk, ctx: StrategyContext): Promise<void> {
+    phaseChannel.report('compress-chunk'); // liveness-watchdog phase
     if (!ctx.membrane) {
       throw new Error('No membrane instance for compression');
     }
@@ -1681,6 +1782,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * summaries when the queue eventually drains.
    */
   protected checkMergeThreshold(): void {
+    phaseChannel.report('merge-threshold'); // liveness-watchdog phase
     if (this.config.speculativeProduction) {
       this.checkMergeThresholdRecursive();
       return;
@@ -2148,6 +2250,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * See `docs/adaptive-resolution-design.md` §3, §5.
    */
   protected selectAdaptive(store: MessageStoreView, budget: TokenBudget): ContextEntry[] {
+    phaseChannel.report('context-build'); // liveness-watchdog phase
     this.rsBegin();
     const entries: ContextEntry[] = [];
     const maxTokens = budget.maxTokens - budget.reserveForResponse;
@@ -2211,6 +2314,11 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     // Pinned-position set so the picker doesn't fold messages the user
     // explicitly marked as keep-raw. Built once and reused.
     const pinnedSet = this.pinnedPositions(messages);
+    // V2 dynamic-pin fold-depth bounds (level / maxLevel). A position with a
+    // bound is NOT a classic force-raw pin — the KV-stable controller must be
+    // able to move it to/within its bound — so it renders as `pinned: false`
+    // carrying `pinLevel` / `pinMaxLevel` instead.
+    const pinBounds = this.pinLevelBounds(messages);
 
     // O(1) summary lookup for findAncestorAt — avoids O(summaries) find()
     // calls during emission.
@@ -2224,13 +2332,18 @@ export class AutobiographicalStrategy implements ResettableStrategy {
       const tokens = msgCap > 0
         ? Math.min(store.estimateTokens(msg), msgCap + 50)
         : store.estimateTokens(msg);
+      const bound = pinBounds.get(i);
       pickerChunks.push({
         id: msg.id,
         sequence: i,
         rawTokens: tokens,
         currentResolution: this.resolutions.get(msg.id) ?? 0,
         lockedByAgent: this.locked.has(msg.id),
-        pinned: pinnedSet.has(i),
+        // A classic pin (in pinnedSet with no level bound) stays force-raw. A
+        // leveled pin is not force-raw; it carries its bound instead.
+        pinned: pinnedSet.has(i) && bound === undefined,
+        pinLevel: bound?.level,
+        pinMaxLevel: bound?.maxLevel,
         l1Id: ch?.summaryId,
       });
     }
@@ -2279,7 +2392,13 @@ export class AutobiographicalStrategy implements ResettableStrategy {
     }
 
     // ----- 4. Run the picker -----
-    const totalBudget = maxTokens - totalTokens; // tokens left after head
+    // The picker's token count ALREADY includes the pinned head+tail (it gets
+    // headTokens/tailTokens in pickerInputs and result.finalTokens covers them).
+    // So the budget it folds against is the full maxTokens — NOT maxTokens-head,
+    // which double-counts the head (reserves it twice: once here, once because
+    // finalTokens already includes it). The old form threw ~head-tokens early at
+    // tight budgets and quietly under-used the budget by ~head everywhere.
+    const totalBudget = maxTokens;
     const slack = this.config.compressionSlackRatio ?? 0.1;
     const foldingBudget: FoldingBudget = {
       totalBudget,
@@ -2819,6 +2938,7 @@ export class AutobiographicalStrategy implements ResettableStrategy {
    * Matches moltbot's budget waterfall: L3 → L2 → L1 with unused budget flowing down.
    */
   protected selectHierarchical(store: MessageStoreView, budget: TokenBudget): ContextEntry[] {
+    phaseChannel.report('context-build'); // liveness-watchdog phase
     this.rsBegin();
     const entries: ContextEntry[] = [];
     const maxTokens = budget.maxTokens - budget.reserveForResponse;

package/src/types/index.ts

@@ -38,6 +38,7 @@ export type {
   KnowledgeConfig,
   ResettableStrategy,
   ProtectedRange,
+  PinLevelOptions,
   SearchQuery,
   SearchResult,
   SearchableStrategy,

package/src/types/strategy.ts

@@ -186,8 +186,8 @@ export function isResettableStrategy(s: ContextStrategy): s is ResettableStrateg
  * original chronological position. Implemented by AutobiographicalStrategy.
  */
 export interface PinnableStrategy extends ContextStrategy {
-  pinRange(firstMessageId: string, lastMessageId: string, opts?: { name?: string }): string;
-  markDocument(messageId: string, opts?: { name?: string }): string;
+  pinRange(firstMessageId: string, lastMessageId: string, opts?: PinLevelOptions): string;
+  markDocument(messageId: string, opts?: PinLevelOptions): string;
   unpin(pinId: string): boolean;
   listPins(): ReadonlyArray<ProtectedRange>;
 }
@@ -596,6 +596,35 @@ export interface ProtectedRange {
   name?: string;
   /** Creation timestamp (ms since epoch). */
   created: number;
+  /**
+   * Pin-AT-level-k (V2 dynamic pins, `docs/best-fit-frontier-resolution.md` §7).
+   * Fix the covered chunks to render at EXACTLY this fold level (0 = raw): the
+   * frontier cut passes through the L_k node — neither folded deeper nor
+   * un-folded shallower. When set, this range is NOT a classic force-raw pin.
+   * Takes precedence over `maxLevel`. Omitted → not a fixed-level pin.
+   *
+   * Honored only by the KV-stable controller (`foldingStrategy: 'kv-stable'`);
+   * other strategies fall back to treating the range as raw (a safe superset).
+   */
+  level?: number;
+  /**
+   * Pin-max-level (V2 dynamic pins): the covered chunks may fold no DEEPER than
+   * this level — raw..L_k allowed, deeper forbidden — a hard cap honored even
+   * under the window-pressure emergency. `maxLevel: 0` ≡ classic pin-raw.
+   * Ignored when `level` is set. Omitted → this pin imposes no depth cap.
+   *
+   * Honored only by the KV-stable controller; see `level`.
+   */
+  maxLevel?: number;
+}
+
+/** Optional fold-depth bounds for a V2 dynamic pin (see `ProtectedRange`). */
+export interface PinLevelOptions {
+  name?: string;
+  /** Pin AT exactly this level (0 = raw). Fixes the cut through the L_k node. */
+  level?: number;
+  /** Fold no deeper than this level (hard cap; `0` ≡ classic pin-raw). */
+  maxLevel?: number;
 }
 
 /**