comisai 1.0.44 → 1.0.46

package/node_modules/@comis/agent/dist/context-engine/constants.js

@@ -6,19 +6,18 @@
  * Each constant uses verbose UPPER_SNAKE_CASE naming and includes
  * a JSDoc comment explaining its purpose and which layer consumes it.
  *
- * Constants are NOT exposed in user config (per locked decision:
- * budget components are internal). Users control the pipeline via
+ * Constants are NOT exposed in user config — budget components are
+ * internal. Users control the pipeline via
  * ContextEngineConfigSchema (enabled, thinkingKeepTurns).
  *
  * @module
  */
 // ---------------------------------------------------------------------------
-// Output Headroom (Layer 0: reasoning-aware output floor — Fix 3 / Phase 166)
+// Output Headroom (Layer 0: reasoning-aware output floor)
 // ---------------------------------------------------------------------------
 /** Minimum visible output tokens guaranteed on every LLM dispatch — the
  *  non-reasoning floor (the answer/tool-call body that must survive after the
- *  thinking block). Used by: output-headroom.ts + config-resolver.ts clamp.
- *  Design ref: design/small-model-context-fidelity.md §4 Fix 3 item 1. */
+ *  thinking block). Used by: output-headroom.ts + config-resolver.ts clamp. */
 export const MIN_VISIBLE_OUTPUT_TOKENS = 768;
 // ---------------------------------------------------------------------------
 // Token Budget Algebra (Layer 0: budget computation)
@@ -122,8 +121,8 @@ export function resolveToolMaskingTier(toolName) {
  *  3.5 better matches Anthropic's tokenizer (measured 38.8% overcount at 4.0
  *  against production dashboard data). Aligned with estimateBlockTokens().
  *
- *  Ratios are Latin-calibrated and stay flat here; since Phase 179 (TOK-01),
- *  call sites with source text in scope modulate the divisor by
+ *  Ratios are Latin-calibrated and stay flat here; call sites with
+ *  source text in scope modulate the divisor by
  *  scriptTokenFactor(text) from @comis/core (dense scripts — Hebrew/Arabic/
  *  CJK/etc — carry ~2-3× tokens per char). Sites without text in scope are
  *  marked flat-by-design at the call site. */
@@ -141,7 +140,7 @@ export const SYSTEM_PROMPT_HASH_LENGTH = 16;
 /**
  * Warn if bootstrap content exceeds this percentage of estimated total prompt input.
  *
- * F4: denominator is `systemPromptChars + toolDefOverheadChars` (system prompt + tool schemas),
+ * The denominator is `systemPromptChars + toolDefOverheadChars` (system prompt + tool schemas),
  * not raw system prompt alone. Threshold lowered from 85→40: fires only when bootstrap is
  * genuinely disproportionate to the full assembled input, eliminating the 100% false-alarm
  * rate on small-model turns (compact-secure system prompt ~2.8K vs ~12K bootstrap).
@@ -213,10 +212,10 @@ export const DEFAULT_COMPACTION_PREFIX_ANCHOR_TURNS = 2;
  *  Below this threshold, compaction is skipped since savings are negligible.
  *  Used by: llm-compaction layer. */
 export const MIN_MIDDLE_MESSAGES_FOR_COMPACTION = 3;
-/** SUMW-01 (Phase 178): reserved token allowance for the summarizer prompt
+/** Reserved token allowance for the summarizer prompt
  *  TEMPLATE around the input span — the SDK generateSummary instruction
  *  template (order of a few hundred tokens), reserved with margin. The
- *  threaded previousSummary is NOT covered by this constant (review WR-03: it
+ *  threaded previousSummary is NOT covered by this constant (it
  *  can itself be ~target-sized — 1_200 leaf / 2_000 condense defaults, and
  *  `condensedTargetTokens` allows 10_000 — so a flat reserve cannot cover it
  *  by its own arithmetic); both LCD clamp sites subtract the ACTUAL
@@ -231,22 +230,22 @@ export const MIN_MIDDLE_MESSAGES_FOR_COMPACTION = 3;
  *  (leaf chunk clamp), lcd-condense-trigger (condense prefix clamp). */
 export const SUMMARIZER_PROMPT_OVERHEAD_TOKENS = 2_048;
 // ---------------------------------------------------------------------------
-// LCD Leaf Summarization Escalation (Phase 129, C1)
+// LCD Leaf Summarization Escalation
 // ---------------------------------------------------------------------------
 /** Bounded token target for the deterministic Level-3 leaf-summary truncation —
- *  the guaranteed-shrink floor (LOSSLESS-CLAW §5). When both LLM summarization
+ *  the guaranteed-shrink floor. When both LLM summarization
  *  levels fail to reduce the chunk (oversized output or throws), Level 3 builds a
  *  count-only note capped at this size so the leaf summary ALWAYS ends up strictly
  *  smaller than the chunk it replaces (the escalation terminator — never loops).
  *  Used by: lcd-leaf-summarizer (Level-3 deterministic truncation). */
 export const LEAF_FALLBACK_TARGET_TOKENS = 512;
 /** Marker string prefixed onto the deterministic Level-3 leaf truncation output so
- *  a fallback (non-LLM) leaf summary is identifiable downstream (Phase 132
- *  taint-escapes it; the assembler/store record `fallback: true`). The two LLM
+ *  a fallback (non-LLM) leaf summary is identifiable downstream (the summarizer
+ *  wrapper taint-escapes it; the assembler/store record `fallback: true`). The two LLM
  *  levels never emit this marker — its presence means the deterministic floor ran.
  *  Used by: lcd-leaf-summarizer (Level-3 marker). */
 export const LEAF_FALLBACK_SUMMARY_MARKER = "[lcd-leaf-fallback]";
-/** B-2: hard cap on the number of leaf passes one afterTurn drain may fire (the
+/** Hard cap on the number of leaf passes one afterTurn drain may fire (the
  *  infinite-loop backstop). The drain loops `runOneLeafPass` — re-resolving the
  *  model-facing view each iteration so utilization reflects the prior pass's
  *  compaction — and terminates on the FIRST of: utilization ≤ contextThreshold
@@ -259,10 +258,10 @@ export const LEAF_FALLBACK_SUMMARY_MARKER = "[lcd-leaf-fallback]";
  *  is enough to drain a few back-to-back large turns' backlog under threshold in one
  *  turn while bounding worst-case added latency; a sustained over-threshold load that
  *  the cap cannot fully drain in one turn simply continues draining on the next
- *  afterTurn (the leaf gate stays armed) rather than stalling at one pass forever
- *  (the B-2 stall this fixes). Used by: lcd-compaction-trigger (the drain loop cap). */
+ *  afterTurn (the leaf gate stays armed) rather than stalling at one pass forever.
+ *  Used by: lcd-compaction-trigger (the drain loop cap). */
 export const LCD_MAX_LEAF_PASSES_PER_TURN = 4;
-/** TRUSTED-HEADER marker (R2, Phase 132) appended to a fallback summary's
+/** TRUSTED-HEADER marker appended to a fallback summary's
  *  `summaryRefToMessage` header — OUTSIDE the `wrapExternalContent` untrusted
  *  region — so the model is honestly told the summary is an emergency, degraded
  *  truncation (the breaker/spend-cap floor or the deterministic Level-3 floor
@@ -273,17 +272,17 @@ export const LCD_MAX_LEAF_PASSES_PER_TURN = 4;
  *  Distinct concern from {@link LEAF_FALLBACK_SUMMARY_MARKER} (the in-CONTENT
  *  Level-3 prefix); this is the header equivalent. Used by: lcd-assembler. */
 export const LCD_FALLBACK_HEADER_MARKER = "fallback=emergency-truncation";
-/** B-8: per-tool-RESULT character cap for tool results sitting in the LCD `dag`
+/** Per-tool-RESULT character cap for tool results sitting in the LCD `dag`
  *  assembler's UNCONDITIONAL fresh tail. The dag assembly path runs NEITHER the
  *  pipeline observation masker NOR the dead-content evictor (those are wired only
  *  in the pipeline branch), and the fresh tail is concatenated verbatim and
- *  UNCONDITIONALLY (`[...budgeted, ...freshTail]`, A1/A3) — so a turn whose last
+ *  UNCONDITIONALLY (`[...budgeted, ...freshTail]`) — so a turn whose last
  *  `freshTailTurns` steps carry a huge tool output (a 200K-char file read, a giant
  *  command dump) can overflow the model window before any budget pass sees it.
  *  This cap bounds each oversized fresh-tail tool RESULT's total text via the
  *  shared `createToolResultSizeGuard()` (head+tail+honest marker — NOT hand-rolled)
- *  while every result that fits passes through byte-identical (A1 preserved for
- *  what fits).
+ *  while every result that fits passes through byte-identical (verbatim
+ *  fresh-tail fidelity preserved for what fits).
  *
  *  Value = {@link TOOL_RESULT_HARD_CAP_CHARS} (100_000), the same absolute
  *  per-result ceiling the pipeline microcompaction guard enforces — chosen for
@@ -295,10 +294,10 @@ export const LCD_FALLBACK_HEADER_MARKER = "fallback=emergency-truncation";
  *  per result at {@link CHARS_PER_TOKEN_RATIO}, so even a fresh tail of several
  *  capped results fits any modern window's fresh-tail allowance — masking is
  *  acceptable ONLY because the LCD store keeps the full content losslessly and
- *  `ctx_expand` recovers it. Used by: lcd-assembler (B-8 fresh-tail bounding). */
+ *  `ctx_expand` recovers it. Used by: lcd-assembler (fresh-tail bounding). */
 export const LCD_FRESH_TAIL_MAX_TOOL_RESULT_CHARS = TOOL_RESULT_HARD_CAP_CHARS;
 // ---------------------------------------------------------------------------
-// LCD Condensation Escalation (Phase 130, C2) — the depth>0 summary-of-summaries
+// LCD Condensation Escalation — the depth>0 summary-of-summaries
 // ---------------------------------------------------------------------------
 /** Bounded token target for the deterministic Level-3 CONDENSATION truncation —
  *  the guaranteed-shrink floor mirroring {@link LEAF_FALLBACK_TARGET_TOKENS}. When
@@ -310,7 +309,7 @@ export const LCD_FRESH_TAIL_MAX_TOOL_RESULT_CHARS = TOOL_RESULT_HARD_CAP_CHARS;
 export const CONDENSED_FALLBACK_TARGET_TOKENS = 512;
 /** Marker string prefixed onto the deterministic Level-3 condensation truncation
  *  output so a fallback (non-LLM) condensed summary is identifiable downstream
- *  (Phase 132 taint-escapes it; the store records `fallback: true`). The two LLM
+ *  (the summarizer wrapper taint-escapes it; the store records `fallback: true`). The two LLM
  *  levels never emit this marker — its presence means the deterministic floor ran.
  *  Distinct from the leaf marker so the two tiers' floors are separable in logs +
  *  the synthetic-session gate. Used by: lcd-condense (Level-3 marker). */

package/node_modules/@comis/agent/dist/context-engine/context-engine.js

@@ -156,15 +156,15 @@ function getCallbackSnapshot(state) {
  * @returns ContextEngine with a `transformContext` function for the SDK hook
  */
 export function createContextEngine(config, deps) {
-    // Pass-through when disabled (per locked decision: zero overhead)
+    // Pass-through when disabled (zero overhead by contract)
     if (!config.enabled) {
         return { transformContext: async (msgs) => msgs, lastBreakpointIndex: undefined, lastTrimOffset: 0 };
     }
-    // DAG/LCD mode (the default since Phase 133): when a ContextStorePort +
+    // DAG/LCD mode (the default): when a ContextStorePort +
     // conversationId are wired (the daemon injects the concrete createLcdStore
     // unconditionally), return the LCD assembly engine -- history reconstructed
-    // from the store via the codec, verbatim fresh tail, transcript repair last
-    // (the corrected loop fix). With NO store wired (unit tests / non-daemon
+    // from the store via the codec, verbatim fresh tail, transcript repair last.
+    // With NO store wired (unit tests / non-daemon
     // callers) it must NOT crash and must NOT no-op: it WARN-logs
     // (errorKind: "config") and falls through to the pipeline assembly below --
     // the storeless safety net that makes the dag-default flip non-breaking
@@ -199,13 +199,13 @@ export function createContextEngine(config, deps) {
     // Build layers array based on model capabilities
     const layers = [];
     // Thinking block cleaner: skip entirely for non-thinking providers
-    // (zero overhead per locked decision)
+    // (zero overhead for models that never emit thinking blocks)
     let thinkingCleaner;
     if (model.reasoning) {
         thinkingCleaner = createThinkingBlockCleaner(config.thinkingKeepTurns, (stats) => { callbackState.thinking = stats; }, deps.getThinkingKeepTurnsOverride);
         layers.push(thinkingCleaner);
     }
-    // Signature replay scrubber (R5 re-wire): strip signed thinking blocks
+    // Signature replay scrubber: strip signed thinking blocks
     // from EVERY assistant message (latest included) before the next API call.
     // Always-on (not gated by model.reasoning): Gemini's thoughtSignature on
     // toolCall blocks requires this even for non-reasoning models.
@@ -217,7 +217,7 @@ export function createContextEngine(config, deps) {
             deps.onSignatureReplayScrubbed?.(stats);
         },
     }));
-    // Signature surrogate guard (Fix #3): scrub thinkingSignature from blocks
+    // Signature surrogate guard: scrub thinkingSignature from blocks
     // whose text contains unpaired UTF-16 surrogates so pi-ai's
     // sanitizeSurrogates() does not produce a sanitized-text-with-original-
     // signature mismatch on replay. Always active — cost is one walk over
@@ -282,7 +282,7 @@ export function createContextEngine(config, deps) {
     if (deps.objective) {
         layers.push(createObjectiveReinforcementLayer(deps.objective));
     }
-    // Transcript repair (A2) -- the ABSOLUTE FINAL pipeline layer, mirroring the
+    // Transcript repair -- the ABSOLUTE FINAL pipeline layer, mirroring the
     // DAG/LCD path where `sanitizeToolUseResultPairing` runs last (lcd-assembler).
     // The pipeline previously had NO final pairing repair: its layers only AVOID
     // CREATING orphans during windowing/eviction; none DROPS a PRE-EXISTING orphan
@@ -330,7 +330,7 @@ export function createContextEngine(config, deps) {
     }
     // Create session-scoped circuit breaker
     const breaker = createLayerCircuitBreaker(LAYER_CIRCUIT_BREAKER_THRESHOLD, deps.logger);
-    // Log startup info (per locked decision)
+    // Log the active layer set + config once at startup (INFO)
     deps.logger.info({
         thinkingKeepTurns: config.thinkingKeepTurns,
         historyTurns,
@@ -377,7 +377,7 @@ export function createContextEngine(config, deps) {
                 /* eslint-disable @typescript-eslint/no-explicit-any */
                 const initialChars = estimateContextCharsWithDualRatio(messages);
                 /* eslint-enable @typescript-eslint/no-explicit-any */
-                // flat-by-design: pipeline cold-start aggregate (same window as llm-compaction trigger; anchor self-corrects) (TOK-01)
+                // flat-by-design: pipeline cold-start aggregate (same window as llm-compaction trigger; anchor self-corrects)
                 const charBasedTokens = Math.ceil(initialChars / CHARS_PER_TOKEN_RATIO);
                 const anchor = deps.getTokenAnchor?.() ?? null;
                 tokensLoaded = estimateWithAnchor(anchor, messages, charBasedTokens);
@@ -426,7 +426,7 @@ export function createContextEngine(config, deps) {
             catch {
                 // Estimation failure should not block the pipeline
             }
-            // flat-by-design: aggregate observability stat — numbers-only log, not budget math (TOK-01)
+            // flat-by-design: aggregate observability stat — numbers-only log, not budget math
             const resultTokens = Math.ceil(resultChars / CHARS_PER_TOKEN_RATIO);
             const budgetUtilization = budget.availableHistoryTokens > 0
                 ? resultTokens / budget.availableHistoryTokens
@@ -440,7 +440,7 @@ export function createContextEngine(config, deps) {
             // compacted context are likely the system-adjacent prefix that's still cached.
             if (snap.compaction !== null) {
                 const prevFence = engine.lastBreakpointIndex;
-                // Review WR-05: `result` IS the compacted array the fence indexes into; the old Array.isArray(snap.compaction) read the stats OBJECT (always false), silently resetting the fence to -1.
+                // `result` IS the compacted array the fence indexes into; never gate this on the compaction stats OBJECT (e.g. Array.isArray(snap.compaction) is always false and would silently reset the fence to -1).
                 const compactedLength = result.length;
                 engine.lastBreakpointIndex = compactedLength > 0
                     ? Math.max(0, Math.floor(compactedLength / 3))
@@ -490,13 +490,13 @@ export function createContextEngine(config, deps) {
                 // Re-read detection failure should not block the pipeline
             }
             // Build metrics
-            // flat-by-design: aggregate observability stat — numbers-only log, not budget math (TOK-01)
+            // flat-by-design: aggregate observability stat — numbers-only log, not budget math
             const tokensMasked = snap.masker ? Math.ceil(snap.masker.totalChars / CHARS_PER_TOKEN_RATIO) : 0;
             const tokensCompacted = snap.compaction
-                // flat-by-design: aggregate observability stat — numbers-only log, not budget math (TOK-01)
+                // flat-by-design: aggregate observability stat — numbers-only log, not budget math
                 ? Math.max(0, tokensLoaded - Math.ceil(resultChars / CHARS_PER_TOKEN_RATIO))
                 : 0;
-            // flat-by-design: aggregate observability stat — numbers-only log, not budget math (TOK-01)
+            // flat-by-design: aggregate observability stat — numbers-only log, not budget math
             const tokensEvicted = snap.evictor ? Math.ceil(snap.evictor.evictedChars / CHARS_PER_TOKEN_RATIO) : 0;
             const durationMs = systemNowMs() - pipelineStart;
             const metrics = {
@@ -561,9 +561,9 @@ export function createContextEngine(config, deps) {
                     deps.eventBus.emit("context:overflow", {
                         agentId,
                         sessionKey,
-                        // flat-by-design: aggregate observability stat — numbers-only log, not budget math (TOK-01)
+                        // flat-by-design: aggregate observability stat — numbers-only log, not budget math
                         contextTokens: Math.ceil(snap.overflow.contextChars / CHARS_PER_TOKEN_RATIO),
-                        // flat-by-design: aggregate observability stat — numbers-only log, not budget math (TOK-01)
+                        // flat-by-design: aggregate observability stat — numbers-only log, not budget math
                         budgetTokens: Math.ceil(snap.overflow.budgetChars / CHARS_PER_TOKEN_RATIO),
                         recoveryAction: snap.overflow.recoveryAction,
                         timestamp,

package/node_modules/@comis/agent/dist/context-engine/errors.d.ts

@@ -1,5 +1,5 @@
 /**
- * Context-engine error types (Phase 166 CWF-02).
+ * Context-engine error types.
  *
  * These named error classes cross the transformContext boundary so the executor
  * can map them to the correct finishReason without inspecting string messages.
@@ -8,28 +8,28 @@ import type { ContextWindowCapInfo } from "./types-core.js";
 /**
  * Stable prefix of every ContextExhaustionError message.
  *
- * HR-01 (v2.19): when this error is thrown by the pre-flight during a MID-TURN
+ * When this error is thrown by the pre-flight during a MID-TURN
  * continuation, the pi-ai SDK converts the throw into a turn_end with
  * stopReason:"error" and a STRING errorMessage — the `instanceof` is lost, so
  * the top-level handleEnvelopeException mapping never runs. The bridge recovers
  * the signal at that boundary via `isContextExhaustionErrorMessage()`. Sharing
  * this prefix between the constructor and the predicate keeps the contract from
- * drifting (no magic literal in the bridge). See design/small-model-orchestration-fidelity.md §4.
+ * drifting (no magic literal in the bridge).
  */
 export declare const CONTEXT_EXHAUSTION_MESSAGE_PREFIX: "Context exhausted: assembled";
 /**
- * Issue-6 (small-model e2e 2026-06-12 UC-3): WHY the fit failed, so the
- * degraded reply can point at the right knob. The generic "narrow the ask"
- * advice was actively misleading when the offender was a persisted oversized
- * message in HISTORY (the ask was tiny).
+ * WHY the fit failed, so the degraded reply can point at the right knob.
+ * The generic "narrow the ask" advice is actively misleading when the
+ * offender is a persisted oversized message in HISTORY (the ask may be
+ * tiny).
  *
  *  - `oversized_input`: the CURRENT user message alone cannot fit — "narrow
  *    the ask" / "shorten the message" is the correct remedy.
  *  - `oversized_history_message`: a SINGLE earlier message alone cannot fit —
- *    only clearing the session (or raising the window) helps; with the Issue-1
- *    assembly bound in place this cause should no longer occur, but the
- *    classification stays for robustness (e.g. an operator-cranked cap).
- *  - `fixed_overhead_exceeds_window` (2026-06-22 root-cause fix): the
+ *    only clearing the session (or raising the window) helps; with the
+ *    fresh-tail assembly bound in place this cause should no longer occur, but
+ *    the classification stays for robustness (e.g. an operator-cranked cap).
+ *  - `fixed_overhead_exceeds_window`: the
  *    NON-EVICTABLE fixed overhead — the system prompt + tool schemas (S =
  *    getSystemTokensEstimate) — ALONE exceeds the bound, so the turn is
  *    infeasible regardless of history, thinking level, OR message size. The
@@ -39,38 +39,37 @@ export declare const CONTEXT_EXHAUSTION_MESSAGE_PREFIX: "Context exhausted: asse
  *    text. The window-aware tool-budget fit pass (executor-tool-assembly.ts
  *    enforceToolBudgetFit) defers tools to prevent this on adequate windows; the
  *    degenerate window<prompt case still throws, and this cause makes it HONEST
- *    (it was previously mis-classified `oversized_input`, blaming the message).
+ *    (classifying it as `oversized_input` would wrongly blame the message).
  *  - `aggregate`: the conversation + tools collectively overflow — compaction /
- *    cap-raise / fewer tools advice applies (the historical behavior).
+ *    cap-raise / fewer tools advice applies (the default classification).
  */
 export type ContextExhaustionCause = "oversized_input" | "oversized_history_message" | "fixed_overhead_exceeds_window" | "aggregate";
 /**
  * Recover the {@link ContextExhaustionCause} from an exhaustion message string
  * that crossed a type-stripping boundary (`result.errorContext.originalError`
- * on the top-level path, `lastLlmErrorMessage` on the HR-01 mid-turn path).
+ * on the top-level path, `lastLlmErrorMessage` on the mid-turn path).
  * Pure; tolerant of undefined/untagged input (→ "aggregate").
  */
 export declare function parseContextExhaustionCause(message: string | undefined): ContextExhaustionCause;
 /** Returns the capped-window suffix for the exhaustion message, or "" when
  *  uncapped/unknown. Exported for reuse by the pre-flight WARN hint.
- *  KNOB-02: branched by source — the served bind gets the Ollama remedy and
+ *  Branched by source — the served bind gets the Ollama remedy and
  *  the capabilityClass bind gets the pin remedy ("raise it (0 = uncapped)" is
  *  the WRONG knob for both: served lives in Ollama, and the executor's class
- *  cap reads only the operator's capabilityClass pin — WR-01). A budget-knob
+ *  cap reads only the operator's capabilityClass pin). A budget-knob
  *  bind with served provenance names the full chain (configured → served → cap). */
 export declare function describeWindowCap(effectiveWindow: number, capInfo?: ContextWindowCapInfo): string;
 /** Thrown by lcd-assembler.transformContext when assembled input cannot fit in the
  *  effective window even after eviction, preamble trimming, and thinking down-shift.
- *  Caught by the executor and mapped to finishReason: "context_exhausted".
- *  Design ref: design/small-model-context-fidelity.md §4 Fix 3 item 2d. */
+ *  Caught by the executor and mapped to finishReason: "context_exhausted". */
 export declare class ContextExhaustionError extends Error {
     readonly effectiveWindow: number;
     readonly assembledTokens: number;
-    /** Issue-6: why the fit failed (default "aggregate" — the historical shape). */
+    /** Why the fit failed (default "aggregate" — the unmarked shape). */
     readonly exhaustionCause: ContextExhaustionCause;
     name: "ContextExhaustionError";
     constructor(effectiveWindow: number, assembledTokens: number, capInfo?: ContextWindowCapInfo, 
-    /** Issue-6: why the fit failed (default "aggregate" — the historical shape). */
+    /** Why the fit failed (default "aggregate" — the unmarked shape). */
     exhaustionCause?: ContextExhaustionCause);
 }
 /**

package/node_modules/@comis/agent/dist/context-engine/errors.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Context-engine error types (Phase 166 CWF-02).
+ * Context-engine error types.
  *
  * These named error classes cross the transformContext boundary so the executor
  * can map them to the correct finishReason without inspecting string messages.
@@ -8,28 +8,28 @@
 /**
  * Stable prefix of every ContextExhaustionError message.
  *
- * HR-01 (v2.19): when this error is thrown by the pre-flight during a MID-TURN
+ * When this error is thrown by the pre-flight during a MID-TURN
  * continuation, the pi-ai SDK converts the throw into a turn_end with
  * stopReason:"error" and a STRING errorMessage — the `instanceof` is lost, so
  * the top-level handleEnvelopeException mapping never runs. The bridge recovers
  * the signal at that boundary via `isContextExhaustionErrorMessage()`. Sharing
  * this prefix between the constructor and the predicate keeps the contract from
- * drifting (no magic literal in the bridge). See design/small-model-orchestration-fidelity.md §4.
+ * drifting (no magic literal in the bridge).
  */
 export const CONTEXT_EXHAUSTION_MESSAGE_PREFIX = "Context exhausted: assembled";
 /**
  * The `[cause: …]` tag appended to the exhaustion message. Like
  * {@link CONTEXT_EXHAUSTION_MESSAGE_PREFIX}, the tag is a SHARED CONTRACT
  * between the constructor and {@link parseContextExhaustionCause}: the error
- * crosses the SDK's turn_end-error boundary as a bare STRING (HR-01), so the
+ * crosses the SDK's turn_end-error boundary as a bare STRING, so the
  * cause must survive inside the message text. "aggregate" is the unmarked
- * default — historical messages (no tag) parse as aggregate.
+ * default — untagged messages parse as aggregate.
  */
 const CAUSE_TAG_PATTERN = /\[cause: (oversized_input|oversized_history_message|fixed_overhead_exceeds_window)\]/;
 /**
  * Recover the {@link ContextExhaustionCause} from an exhaustion message string
  * that crossed a type-stripping boundary (`result.errorContext.originalError`
- * on the top-level path, `lastLlmErrorMessage` on the HR-01 mid-turn path).
+ * on the top-level path, `lastLlmErrorMessage` on the mid-turn path).
  * Pure; tolerant of undefined/untagged input (→ "aggregate").
  */
 export function parseContextExhaustionCause(message) {
@@ -40,11 +40,11 @@ export function parseContextExhaustionCause(message) {
  * Maps a WindowCapSource onto the exact knob an operator must turn — the
  * message must name the KNOB, not just the number, so an operator (or an
  * LLM agent reading the log) can fix it without reading budget-capacity-cap.ts
- * (W1 obs-llm-troubleshooting; the live incident reported "effective window
- * 32000" against a configured contextWindow of 131072 with no link between them).
- * KNOB-02: the cap-class entries are `contextEngine.budget.*` config keys; the
+ * (a log line reporting "effective window 32000" against a configured
+ * contextWindow of 131072 with no link between them is undiagnosable).
+ * The cap-class entries are `contextEngine.budget.*` config keys; the
  * `served` entry names the OLLAMA knobs (env / Modelfile); the
- * `capabilityClass` entry (WR-01) names the operator's
+ * `capabilityClass` entry names the operator's
  * `providers.entries.<id>.capabilities.capabilityClass` PIN — the executor's
  * DEFAULT_EFFECTIVE_CAP_BY_CLASS cap never reads the budget knobs, so
  * "raise contextEngine.budget.effectiveContextCapSmall" is a DEAD lever on
@@ -59,10 +59,10 @@ const CAP_KNOB_BY_SOURCE = {
 };
 /** Returns the capped-window suffix for the exhaustion message, or "" when
  *  uncapped/unknown. Exported for reuse by the pre-flight WARN hint.
- *  KNOB-02: branched by source — the served bind gets the Ollama remedy and
+ *  Branched by source — the served bind gets the Ollama remedy and
  *  the capabilityClass bind gets the pin remedy ("raise it (0 = uncapped)" is
  *  the WRONG knob for both: served lives in Ollama, and the executor's class
- *  cap reads only the operator's capabilityClass pin — WR-01). A budget-knob
+ *  cap reads only the operator's capabilityClass pin). A budget-knob
  *  bind with served provenance names the full chain (configured → served → cap). */
 export function describeWindowCap(effectiveWindow, capInfo) {
     if (capInfo === undefined || capInfo.windowCapSource === "none")
@@ -74,7 +74,7 @@ export function describeWindowCap(effectiveWindow, capInfo) {
     }
     const knob = CAP_KNOB_BY_SOURCE[capInfo.windowCapSource];
     const servedClause = capInfo.servedWindowTokens !== undefined ? `, Ollama serves ${capInfo.servedWindowTokens},` : "";
-    // WR-01: the remedy must match the lever that actually moves the window —
+    // The remedy must match the lever that actually moves the window —
     // the budget knobs are numeric ("raise it, 0 = uncapped"); the capability
     // pin is a class name (raise/remove the pin; the budget knob is inert here).
     const remedy = capInfo.windowCapSource === "capabilityClass"
@@ -85,20 +85,19 @@ export function describeWindowCap(effectiveWindow, capInfo) {
 }
 /** Thrown by lcd-assembler.transformContext when assembled input cannot fit in the
  *  effective window even after eviction, preamble trimming, and thinking down-shift.
- *  Caught by the executor and mapped to finishReason: "context_exhausted".
- *  Design ref: design/small-model-context-fidelity.md §4 Fix 3 item 2d. */
+ *  Caught by the executor and mapped to finishReason: "context_exhausted". */
 export class ContextExhaustionError extends Error {
     effectiveWindow;
     assembledTokens;
     exhaustionCause;
     name = "ContextExhaustionError";
     constructor(effectiveWindow, assembledTokens, capInfo, 
-    /** Issue-6: why the fit failed (default "aggregate" — the historical shape). */
+    /** Why the fit failed (default "aggregate" — the unmarked shape). */
     exhaustionCause = "aggregate") {
         super(`${CONTEXT_EXHAUSTION_MESSAGE_PREFIX} ${assembledTokens} tokens leaves no room in effective window ${effectiveWindow}` +
             describeWindowCap(effectiveWindow, capInfo) +
-            // The tag must survive the HR-01 string boundary; "aggregate" stays
-            // unmarked so historical message shapes are byte-identical.
+            // The tag must survive the turn_end string boundary; "aggregate" stays
+            // unmarked — the parser treats an untagged message as aggregate.
             (exhaustionCause === "aggregate" ? "" : ` [cause: ${exhaustionCause}]`));
         this.effectiveWindow = effectiveWindow;
         this.assembledTokens = assembledTokens;

package/node_modules/@comis/agent/dist/context-engine/factored-message-tokens.d.ts

@@ -3,14 +3,15 @@
  * check (lcd-preflight.ts) and the protected-fresh-tail total bound
  * (lcd-fresh-tail-bound.ts `boundFreshTailTotalToResidual`).
  *
- * ISSUE #3 (2026-06-22): these two had DIFFERENT estimators — the pre-flight used
- * `ceil(chars / (CHARS_PER_TOKEN_RATIO × scriptTokenFactor))` (≈3.5:1) while the
- * fresh-tail bound used `estimateMessageTokens` (≈4:1) plus a ×0.83 fudge to absorb
- * the gap. The ABSOLUTE gap scales with the residual, so on a SMALL system prompt
- * (large residual — e.g. OpenAI gpt-5-nano S=1145 → residual ~6279) the fudge was
- * insufficient and the bounded fresh tail still measured over the pre-flight bound →
- * exhaustion. Single-sourcing the estimator here makes the bound == the measure for
- * ANY system-prompt size, with no fudge factor and no possibility of future drift.
+ * The two consumers MUST share one estimator. With different estimators — e.g.
+ * `ceil(chars / (CHARS_PER_TOKEN_RATIO × scriptTokenFactor))` (≈3.5:1) in the
+ * pre-flight but a ≈4:1 `estimateMessageTokens` plus a ×0.83 fudge in the
+ * fresh-tail bound — the ABSOLUTE gap scales with the residual, so on a SMALL
+ * system prompt (large residual — e.g. OpenAI gpt-5-nano S=1145 → residual
+ * ~6279) the fudge is insufficient and the bounded fresh tail still measures
+ * over the pre-flight bound → exhaustion. Single-sourcing the estimator here
+ * makes the bound == the measure for ANY system-prompt size, with no fudge
+ * factor and no possibility of future drift.
  *
  * Pure leaf — depends only on the chars/token ratio constant, the script factor, and
  * the `AgentMessage` type. No cycle risk (imports nothing from lcd-preflight /
@@ -21,17 +22,17 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 /**
  * The exact text of one message that the factored estimate counts: string content,
- * or the `text ?? content` field of each array block (the IN-01 multi-part /
+ * or the `text ?? content` field of each array block (the multi-part /
  * tool-result shape — NOT text+content summed). The concatenation feeds
  * scriptTokenFactor so the factor is computed over precisely the chars whose length
- * is divided (TOK-01 identity-by-construction).
+ * is divided (identity-by-construction).
  */
 export declare function messageText(m: AgentMessage): string;
 /**
  * The factored token estimate for one message: `ceil(chars / (CHARS_PER_TOKEN_RATIO
  * × scriptTokenFactor(text)))`. This is the pre-flight's per-message formula
  * (lcd-preflight.ts freshTailMsgTokens) — the authority for "does the fresh tail fit
- * the window". TOK-01: dense scripts carry ~2-3× tokens/char; ASCII factor 1.0 →
+ * the window". Dense scripts carry ~2-3× tokens/char; ASCII factor 1.0 →
  * the bare `ceil(chars / 3.5)` form.
  */
 export declare function factoredMessageTokens(m: AgentMessage): number;

package/node_modules/@comis/agent/dist/context-engine/factored-message-tokens.js

@@ -2,10 +2,10 @@ import { scriptTokenFactor } from "@comis/core";
 import { CHARS_PER_TOKEN_RATIO } from "./constants.js";
 /**
  * The exact text of one message that the factored estimate counts: string content,
- * or the `text ?? content` field of each array block (the IN-01 multi-part /
+ * or the `text ?? content` field of each array block (the multi-part /
  * tool-result shape — NOT text+content summed). The concatenation feeds
  * scriptTokenFactor so the factor is computed over precisely the chars whose length
- * is divided (TOK-01 identity-by-construction).
+ * is divided (identity-by-construction).
  */
 export function messageText(m) {
     const content = m.content;
@@ -29,7 +29,7 @@ export function messageText(m) {
  * The factored token estimate for one message: `ceil(chars / (CHARS_PER_TOKEN_RATIO
  * × scriptTokenFactor(text)))`. This is the pre-flight's per-message formula
  * (lcd-preflight.ts freshTailMsgTokens) — the authority for "does the fresh tail fit
- * the window". TOK-01: dense scripts carry ~2-3× tokens/char; ASCII factor 1.0 →
+ * the window". Dense scripts carry ~2-3× tokens/char; ASCII factor 1.0 →
  * the bare `ceil(chars / 3.5)` form.
  */
 export function factoredMessageTokens(m) {

package/node_modules/@comis/agent/dist/context-engine/lcd-arbiter-seam.d.ts

@@ -1,19 +1,20 @@
 /**
- * RETR-02/03/05 — the relevance-first eviction seam, extracted from `lcd-assembler.ts`
+ * The relevance-first eviction seam, extracted from `lcd-assembler.ts`
  * so the assembler stays under the 800-line file-size cap (the "keep the body THIN" rule;
  * mirrors `recall-provenance.ts` / `lcd-store-provenance.ts` extractions). The assembler
  * CALLS {@link evictUnderArbiter} on the relevance-first path and keeps the verbatim
- * `evictHistoryUnderBudget` call on the frontier/mid path (byte-identical, LOCKED #2).
+ * `evictHistoryUnderBudget` call on the frontier/mid path (a locked byte-identical contract).
  *
  * This module wraps the pure {@link marginArbitrate} allocator with the assembly-path
- * glue: it separates the S4 security-pinned items (RETR-05) out of the relevance-evictable
+ * glue: it separates the security-pinned items out of the relevance-evictable
  * band as unconditional floors (mirroring `lcd-preflight.ts:114-121`), passes EMPTY LTM/KG
- * candidate lanes (the C2 boundary — the assembler holds no cross-session LTM; the recall
+ * candidate lanes (the assembler holds no cross-session LTM; the recall
  * path owns LTM ranking), and builds the relevance query for the arbiter.
  *
  * Architecture cuts: lives in `context-engine/`, imports only `@comis/core` types +
  * in-package context-engine modules — never `@comis/memory` (agent↛memory) and never the
- * `rag/` layer (I2). The relevance scorer is INJECTED (`deps.relevanceScorer`); on the C2
+ * `rag/` layer (the context-engine ↮ rag cut). The relevance scorer is INJECTED
+ * (`deps.relevanceScorer`); on the
  * assembly path the LTM/KG lanes are empty so the scorer is never actually invoked.
  *
  * @module
@@ -29,31 +30,31 @@ export interface ArbiterSeamResult {
 }
 /**
  * Run the margin arbiter at the eviction seam for a relevance-first class, and emit the
- * content-free `context:arbitrated` Glass-Box event.
+ * content-free `context:arbitrated` observability event.
  *
- * RETR-05: S4 security-pinned items (detected fail-closed by `isSecurityRelevantMessage`
+ * Security-pinned items (detected fail-closed by `isSecurityRelevantMessage`
  * against `deps.securityPinMarkers`) are excluded from the relevance-evictable band and
  * passed as UNCONDITIONAL floors. When no markers are threaded, nothing is pinned here
  * (the pre-flight harder-eviction remains the backstop).
  *
- * RETR-02 event: per-tier kept COUNTS + the discretionary pool TOKENS (OFFERED via
- * `discretionaryPoolTokens` AND CONSUMED via `poolTokensUsed`, WR-03) + the floor-token
- * weight + the kept LTM/KG ids (WR-02) + the relevanceFirst BOOLEAN + a timestamp ONLY —
- * NEVER message/memory/query content (AGENTS.md §2.2/§2.7; T-173-03-04; ids are opaque
+ * The event carries per-tier kept COUNTS + the discretionary pool TOKENS (OFFERED via
+ * `discretionaryPoolTokens` AND CONSUMED via `poolTokensUsed`) + the floor-token
+ * weight + the kept LTM/KG ids + the relevanceFirst BOOLEAN + a timestamp ONLY —
+ * NEVER message/memory/query content (AGENTS.md §2.2/§2.7; ids are opaque
  * memory keys). Reuses the caller's entry-clock read `startMs` (no new ambient clock —
  * the globals gate). Frontier/mid never call this → the event never fires for them.
  *
  * @param deps - the context-engine deps (relevanceScorer, securityPinMarkers, eventBus).
  * @param evictable - the evictable history band (T0/T1/T2) with supplied tokens.
- * @param poolTokens - the discretionary pool (budget.availableHistoryTokens, post-Fix-3).
+ * @param poolTokens - the discretionary pool (budget.availableHistoryTokens).
  * @param liveMessages - the live message array (source of the relevance query).
  * @param startMs - the assembler's entry-clock read, reused for the event timestamp.
  * @returns the kept history (the event is emitted as a side effect).
  */
 export declare function evictUnderArbiter(deps: ContextEngineDeps, evictable: BudgetItem[], poolTokens: number, liveMessages: AgentMessage[], startMs: number): ArbiterSeamResult;
 /**
- * Emit the EXISTING content-free `context:evicted` event from the LCD eviction seam (O1;
- * parity with the pipeline engine) when eviction actually dropped history — shared by BOTH
+ * Emit the EXISTING content-free `context:evicted` event from the LCD eviction seam
+ * (parity with the pipeline engine) when eviction actually dropped history — shared by BOTH
  * the recency and the arbiter paths. `evictedChars` is derived ONLY from each dropped item's
  * pre-computed `tokens` (× CHARS_PER_TOKEN_RATIO) — the message text is NEVER read or emitted
  * (AGENTS.md §2.2 / the lossless store). Reuses the caller's entry-clock `startMs` (no new