comisai 1.0.44 → 1.0.46

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
-// @allow-throw: wrapSummarizerWithFailover (SUM-03) re-throws the last provider error after the fallback list is exhausted (lcd-leaf-summarizer.ts:746); consumed by the summarizer-spend-breaker safety boundary (packages/agent/src/safety/summarizer-spend-breaker.ts), which catches the throw and records EXACTLY ONE per-tenant breaker failure — the existing summarizer-failure contract (a throw is how a summarization failure is signalled to the breaker).
+// @allow-throw: wrapSummarizerWithFailover re-throws the last provider error after the fallback list is exhausted (lcd-leaf-summarizer.ts:746); consumed by the summarizer-spend-breaker safety boundary (packages/agent/src/safety/summarizer-spend-breaker.ts), which catches the throw and records EXACTLY ONE per-tenant breaker failure — the existing summarizer-failure contract (a throw is how a summarization failure is signalled to the breaker).
 /**
- * LCD leaf summarization unit (Phase 129, C1).
+ * LCD leaf summarization unit.
  *
  * Two pure-ish responsibilities, both proven by a STUB summarizer (no network):
  *
@@ -16,25 +16,25 @@
  *  2. {@link summarizeLeafChunk} — run the mandatory 3-level escalation
  *     (normal → aggressive → deterministic truncation) that ALWAYS reduces
  *     tokens or falls back deterministically. The structural model is
- *     `compactWithFallback` (`llm-compaction.ts:545-607`), but C1 ADDS a
- *     per-level token-reduction assertion (LOSSLESS-CLAW §5: "If output > input,
- *     retry aggressive then truncate") and a BOUNDED Level-3 output (a count-only
+ *     `compactWithFallback` (`llm-compaction.ts:545-607`), but this unit ADDS a
+ *     per-level token-reduction assertion (if output > input, retry aggressive
+ *     then truncate) and a BOUNDED Level-3 output (a count-only
  *     note prefixed with `LEAF_FALLBACK_SUMMARY_MARKER`, capped at
  *     `LEAF_FALLBACK_TARGET_TOKENS`) — the guaranteed-shrink terminator. The
  *     ladder is FINITE (Level 1 ≤ 1+COMPACTION_MAX_RETRIES attempts → Level 2 one
  *     attempt → Level 3 deterministic); it never loops without a floor.
  *
  * The LLM summarizer is INJECTED as ONE function ({@link LeafSummarizer}) so
- * Phase 132 can wrap it with spend governance / a circuit breaker by swapping a
- * single seam (the binding constraint; the Security DoS row T-129-08). 129 calls
- * it inline and non-fatally: an error at Levels 1+2 is caught (WARN, errorKind
+ * the production wiring can wrap it with spend governance / a circuit breaker
+ * by swapping a single seam (the binding DoS-containment constraint). This unit
+ * calls it inline and non-fatally: an error at Levels 1+2 is caught (WARN, errorKind
  * `dependency`) and the pass falls through to the deterministic Level 3 — it
  * NEVER throws out of the pass.
  *
  * Architecture cut (agent↛memory): this file imports ONLY the agent-side token
  * estimators + the escalation constants; it NEVER imports `@comis/memory`. It
  * also NEVER logs `chunkMessages` content or the summary `content` — ids, counts,
- * level, and durations only (AGENTS.md §2.2; T-129-10). It reads NO wall clock of
+ * level, and durations only (AGENTS.md §2.2). It reads NO wall clock of
  * its own — the leaf time-range (`earliestAt`/`latestAt`) is derived purely from
  * the injected `LeafChunkItem.createdAt` values, so there is no globals-gate
  * surface here (the caller's injected clock stamps timestamps upstream).
@@ -55,11 +55,11 @@ import { estimateMessageTokens, estimateMessageChars, CHARS_PER_TOKEN, } from ".
  * (`estimateMessageTokens` of a 1–4-char user string), so a chunk must be ≥ 2
  * tokens for any non-empty summary to be strictly smaller. A 1-token chunk is
  * already trivially tiny — there is nothing to gain — so the caller skips the
- * pass entirely (WR-01) rather than emitting a degenerate empty/larger fallback.
+ * pass entirely rather than emitting a degenerate empty/larger fallback.
  */
 export const MIN_SHRINKABLE_LEAF_CHUNK_TOKENS = 2;
 /**
- * B-4 (260605-ney): the fraction of a chunk's rendered shrink ceiling used as the
+ * The fraction of a chunk's rendered shrink ceiling used as the
  * EFFECTIVE summarize target. The configured `reserveTokens` (= `leafTargetTokens`
  * / `condensedTargetTokens`) can EXCEED a small chunk — telling the model to write
  * a summary larger than what it compresses → a guaranteed non-reduction → the
@@ -71,7 +71,7 @@ export const MIN_SHRINKABLE_LEAF_CHUNK_TOKENS = 2;
  */
 export const SHRINK_TARGET_FRACTION = 0.5;
 /**
- * Compute the self-consistent shrink bounds for a chunk (B-4, 260605-ney). Shared
+ * Compute the self-consistent shrink bounds for a chunk. Shared
  * by {@link summarizeLeafChunk} and `summarizeCondensedChunk` (the rule of three
  * is met — both summarizers need the identical bounding).
  *
@@ -79,9 +79,9 @@ export const SHRINK_TARGET_FRACTION = 0.5;
  *
  *  - `shrinkCeilingTokens` — the accept-test ceiling, measured the SAME way the
  *    candidate summary is (`estimateMessageTokens` of a user string = 4:1 prose):
- *    `ceil(renderedChars / CHARS_PER_TOKEN)`. The prior code compared a 4:1-prose
- *    candidate against the chunk's MIXED-ratio STORED `tokenCount` (3:1 structured
- *    / 4:1 text) — inconsistent units. This makes the comparison like-for-like.
+ *    `ceil(renderedChars / CHARS_PER_TOKEN)`. Comparing a 4:1-prose candidate
+ *    against the chunk's MIXED-ratio STORED `tokenCount` (3:1 structured
+ *    / 4:1 text) would be inconsistent units; this keeps the comparison like-for-like.
  *    NOTE: the STORED Σ `tokenCount` remains the BUDGET / before-size / floor
  *    authority everywhere else (utilization, eviction, the deterministic Level-3
  *    note + its strict ceiling) — only the accept-test ceiling moves here.
@@ -97,7 +97,7 @@ export const SHRINK_TARGET_FRACTION = 0.5;
  * @returns the rendered-4:1 accept ceiling + the bounded effective target.
  */
 export function computeShrinkBounds(renderedChars, configuredReserveTokens) {
-    // flat-by-design: shrink-ceiling convergence bound over aggregate renderedChars (correctness comes from the shrink loop, see docstring) (TOK-01)
+    // flat-by-design: shrink-ceiling convergence bound over aggregate renderedChars (correctness comes from the shrink loop, see docstring)
     const shrinkCeilingTokens = Math.ceil(renderedChars / CHARS_PER_TOKEN);
     const effectiveReserveTokens = Math.min(configuredReserveTokens, Math.max(1, Math.floor(shrinkCeilingTokens * SHRINK_TARGET_FRACTION)));
     return { shrinkCeilingTokens, effectiveReserveTokens };
@@ -117,19 +117,19 @@ export function computeShrinkBounds(renderedChars, configuredReserveTokens) {
  * messages up to the cap, then walks forward past a trailing assistant
  * `tool_use` and its `toolResult`s (never crossing the fresh-tail boundary).
  *
- * S4: if `pinnedMessageIds` is provided, chunks containing ANY pinned message
+ * If `pinnedMessageIds` is provided, chunks containing ANY pinned message
  * are skipped entirely — pinned messages are NEVER selected as eviction candidates.
  *
  * @param history - the evictable history items (seq order, oldest first)
  * @param freshTailSteps - the number of trailing STEPS protected from eviction
  * @param leafChunkTokens - the chunk token cap
- * @param pinnedMessageIds - S4: message ids that must never be selected for eviction
+ * @param pinnedMessageIds - message ids that must never be selected for eviction
  * @returns the selected chunk, or `undefined` when nothing is evictable
  */
 export function selectLeafChunk(history, freshTailSteps, leafChunkTokens, pinnedMessageIds) {
     if (history.length === 0)
         return undefined;
-    // S4: build a version of history that excludes pinned messages from the selectable set.
+    // Build a version of history that excludes pinned messages from the selectable set.
     // Pinned messages are moved to "protected" — they remain in the store but cannot be
     // selected as eviction candidates. If ALL messages are pinned, return undefined.
     const evictableHistory = pinnedMessageIds && pinnedMessageIds.size > 0
@@ -240,10 +240,11 @@ function roleOf(m) {
 /**
  * Summarize a leaf chunk via the mandatory 3-level escalation. ALWAYS returns a
  * summary whose token count is STRICTLY LESS than the chunk's token count (the
- * C1 invariant) — accepting an LLM summary only when it actually reduces, and
- * otherwise falling through to the deterministic, bounded Level-3 truncation.
+ * strict-shrink invariant) — accepting an LLM summary only when it actually
+ * reduces, and otherwise falling through to the deterministic, bounded Level-3
+ * truncation.
  *
- * B-4 (260605-ney): the EFFECTIVE summarize target is bounded below the chunk's
+ * The EFFECTIVE summarize target is bounded below the chunk's
  * rendered shrink ceiling ({@link computeShrinkBounds}) so the model is never asked
  * to write more than it compresses (the spurious-floor fix), and the accept-test
  * ceiling is the RENDERED 4:1 measure — self-consistent with the candidate's units.
@@ -260,16 +261,17 @@ export async function summarizeLeafChunk(chunkItems, deps, opts) {
     const messageIds = chunkItems.map((it) => it.id);
     const createdAts = chunkItems.map((it) => it.createdAt);
     // Before-size authority: the caller's pre-computed per-message tokens (counts
-    // F3 thinking on store-sourced rows, which re-estimation would under-count).
+    // persisted thinking/reasoning on store-sourced rows, which re-estimation
+    // would under-count).
     // This stays the BUDGET / floor authority — the deterministic Level-3 floor must
     // still beat the REAL stored before-size (NOT the smaller rendered ceiling).
     const chunkTokens = chunkItems.reduce((acc, it) => acc + it.tokens, 0);
     const earliestAt = createdAts.length > 0 ? Math.min(...createdAts) : 0;
     const latestAt = createdAts.length > 0 ? Math.max(...createdAts) : 0;
-    // B-4: self-consistent shrink bounds from the chunk's RENDERED chars. The
+    // Self-consistent shrink bounds from the chunk's RENDERED chars. The
     // accept ceiling (`shrinkCeilingTokens`) is measured the SAME way the candidate
     // summary is (4:1 prose); the EFFECTIVE target is bounded below the chunk so the
-    // summarizer is never asked to write more than it compresses (the dominant fix).
+    // summarizer is never asked to write more than it compresses (the spurious-floor guard).
     const renderedChars = messages.reduce((acc, m) => acc + estimateMessageChars(m), 0);
     const { shrinkCeilingTokens, effectiveReserveTokens } = computeShrinkBounds(renderedChars, opts.reserveTokens);
     const base = {
@@ -294,7 +296,7 @@ export async function summarizeLeafChunk(chunkItems, deps, opts) {
     // --- Level 2: aggressive — one best-effort retry. Prefer the oversized-filtered
     //     set (dropping huge messages often lets the model reduce), but when EVERY
     //     message is oversized the filter empties the set; rather than skip Level 2
-    //     and drop straight to the count-only floor (WR-03), make the one aggressive
+    //     and drop straight to the count-only floor, make the one aggressive
     //     attempt on the FULL (unfiltered) set. An aggressive LLM summary — even of
     //     large inputs — is strictly better context than the deterministic floor,
     //     and continuity (`previousSummary`) is forwarded either way.
@@ -334,7 +336,7 @@ export async function summarizeLeafChunk(chunkItems, deps, opts) {
 /**
  * Attempt one summarizer call and accept it ONLY when the produced summary is
  * strictly smaller (in tokens) than `shrinkCeilingTokens` — the chunk's RENDERED
- * 4:1 measure (B-4, 260605-ney), so the candidate (a 4:1-prose user string) and
+ * 4:1 measure, so the candidate (a 4:1-prose user string) and
  * the ceiling are like-for-like units. Non-fatal: a throwing summarizer is caught
  * (WARN, errorKind `dependency`) and reported as "not accepted" so the ladder
  * escalates rather than failing.
@@ -345,7 +347,7 @@ async function tryLevel(deps, messages, opts, shrinkCeilingTokens, attempt) {
         const tokenCount = estimateMessageTokens({ role: "user", content: summary });
         if (tokenCount < shrinkCeilingTokens)
             return { content: summary, tokenCount };
-        // Non-reduction → escalate (LOSSLESS-CLAW §5).
+        // Non-reduction → escalate (never accept a summary that fails to shrink).
         deps.logger.debug({
             step: "lcd-leaf-escalate",
             attempt,
@@ -370,12 +372,12 @@ async function tryLevel(deps, messages, opts, shrinkCeilingTokens, attempt) {
  * it NEVER exceeds the chunk and NEVER calls an LLM.
  *
  * The bound is the token ESTIMATOR ITSELF, not a hand-derived chars-per-token
- * ceiling (WR-01 / IN-03): the prior code clamped chars with `CHARS_PER_TOKEN_RATIO`
- * (3.5) while the result is measured by `estimateMessageTokens` (4:1 for a
- * user-role string), and a `Math.max(MARKER.length, …)` floor overrode the clamp
- * for tiny chunks — so a 3-token chunk produced a 19-char marker = 5 tokens,
- * LARGER than the chunk. Truncating the note in a loop that re-measures with the
- * estimator until it is strictly below the chunk removes both the 3.5-vs-4
+ * ceiling: clamping chars with `CHARS_PER_TOKEN_RATIO` (3.5) would disagree
+ * with `estimateMessageTokens` (4:1 for a user-role string), and a
+ * `Math.max(MARKER.length, …)` floor would override the clamp for tiny chunks —
+ * a 3-token chunk would get a 19-char marker = 5 tokens, LARGER than the
+ * chunk. Truncating the note in a loop that re-measures with the
+ * estimator until it is strictly below the chunk avoids both the 3.5-vs-4
  * mismatch and the marker-floor overshoot. The marker survives intact for any
  * normal-size chunk; only a sub-marker chunk truncates it (and a chunk too small
  * to ever shrink with non-empty content is skipped by the {@link summarizeLeafChunk}
@@ -418,11 +420,12 @@ function buildDeterministicFallback(messageCount, chunkTokens) {
 // ---------------------------------------------------------------------------
 /**
  * Construct the PRODUCTION {@link LeafSummarizer} — the seam that wraps the SDK
- * `generateSummary`. Phase 132 swaps THIS factory's output for a spend-governed /
- * circuit-broken variant; 129 calls `generateSummary` directly. The override
+ * `generateSummary`. The production wiring swaps THIS factory's output for a
+ * spend-governed / circuit-broken variant; the bare factory calls
+ * `generateSummary` directly. The override
  * model + key are used when {@link LeafSummarizerDeps.overrideModel} is present
  * (a cheaper compaction model resolved by the operation-model chain), else the
- * primary REAL model (`getRealModel`) + `getApiKey` (B-5 — a real pi-ai
+ * primary REAL model (`getRealModel`) + `getApiKey` (a real pi-ai
  * `Model<any>`, never the 4-field snapshot). Mirrors `compactWithFallback`'s call shape
  * (`llm-compaction.ts:561`); the 8th param threads `previousSummary` for
  * continuity. The function may return a too-large string — the escalation ladder
@@ -434,7 +437,7 @@ function buildDeterministicFallback(messageCount, chunkTokens) {
  */
 export function buildLeafSummarizeFn(deps) {
     return async (messages, opts) => {
-        // B-5: resolve a REAL Model<any> for generateSummary — prefer the cheaper
+        // Resolve a REAL Model<any> for generateSummary — prefer the cheaper
         // override's real Model when the operation chain picked one (parity with
         // getCompactionDeps), else the PRIMARY real model (the executor-resolved
         // `resolvedModel`, threaded via deps.getRealModel). The bare 4-field
@@ -454,16 +457,16 @@ export function buildLeafSummarizeFn(deps) {
     };
 }
 /**
- * SUM-03: wraps a primary {@link LeafSummarizer} with an ordered fallback list.
+ * Wraps a primary {@link LeafSummarizer} with an ordered fallback list.
  *
  * On primary failure, tries each fallback in sequence (ordered by the caller's
  * `fallbacks` array). Only when ALL providers in the list are exhausted does the
  * wrapper throw the last error — so the per-tenant circuit breaker that wraps the
  * OUTER spend-governed seam records exactly ONE failure per exhausted-list event
- * (Pitfall 4 in 171-RESEARCH: throw-last, not throw-per-provider).
+ * (throw-last, not throw-per-provider).
  *
  * Content-free: logs `providerIndex`, `totalProviders`, and `errorKind: "dependency"`
- * only — NEVER message content, summary text, or provider credentials (T-171-09).
+ * only — NEVER message content, summary text, or provider credentials.
  *
  * @param primary - the primary LeafSummarizer (already spend-governed by the outer seam)
  * @param fallbacks - ordered list of fallback LeafSummarizer callables

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

@@ -1,8 +1,8 @@
 /**
- * Pre-flight fit check for the LCD dag assembler (Phase 166 CWF-02).
+ * Pre-flight fit check for the LCD dag assembler.
  *
  * Enforces the invariant: assembledInputTokens ≤ effectiveWindow − outputHeadroom.
- * Security-pinned messages (T-S4) are NEVER evicted in the harder-eviction pass.
+ * Security-pinned messages are NEVER evicted in the harder-eviction pass.
  *
  * Escalation ladder:
  *  (a) Evict harder with security-pinned messages excluded.
@@ -11,7 +11,7 @@
  *
  * Separated from lcd-assembler.ts to keep that file ≤ 820 lines.
  *
- * Root-cause context-exhaustion guard (2026-06-22): the NON-EVICTABLE fixed
+ * Root-cause context-exhaustion guard: the NON-EVICTABLE fixed
  * overhead S (system prompt + tool schemas) is the dominant term on small
  * windows. The window-aware tool-budget fit pass (executor-tool-assembly.ts
  * `enforceToolBudgetFit`) defers tools so S fits BEFORE this pre-flight runs,
@@ -25,8 +25,7 @@
  * guidance, keep identity + essential behavior) would let the agent still reply
  * on a window < full-prompt. Deferred: it is deeply invasive in the 1954-line
  * prompt-assembly.ts (per-session bootstrap snapshot + once-per-session
- * systemPromptOverride). Tracked against the codex nano-window context-exhaustion
- * incident. Until then the degenerate case fails honestly (above).
+ * systemPromptOverride). Until then the degenerate case fails honestly (above).
  *
  * @module
  */
@@ -34,7 +33,7 @@ import { type BudgetItem } from "./lcd-budget-eviction.js";
 import type { ContextEngineDeps, ContextWindowCapInfo } from "./types.js";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 /**
- * Run the CWF-02 pre-flight fit check.
+ * Run the pre-flight fit check.
  *
  * @param deps              - ContextEngineDeps (reads securityPinMarkers, callbacks, logger).
  * @param effectiveWindow   - budget.windowTokens for this turn.
@@ -45,14 +44,14 @@ import type { AgentMessage } from "@earendil-works/pi-agent-core";
  *                            The NEWEST keptCount items from evictable were kept.
  * @param freshTail         - The unconditional fresh-tail messages.
  * @param reasoningStyle    - profile.reasoningStyle ("none" | "native").
- * @param capInfo           - W1 cap provenance (budget.rawContextWindowTokens +
+ * @param capInfo           - Window-cap provenance (budget.rawContextWindowTokens +
  *                            budget.windowCapSource). When the effective window was
  *                            clamped by a capability-class cap, the exhaustion throw
  *                            and WARN name the raw window and the exact config knob.
  *
  * Throws ContextExhaustionError if infeasible even at the thinking-level floor.
  * Emits onEffectiveWindow, onThinkingDownshifted, onAssembledInputTokens callbacks as side effects.
- * Returns the ORIGINAL assembled input token count (CR-03 — what is actually
- * dispatched) so the assembler's INFO line can log the budget equation (W5).
+ * Returns the ORIGINAL assembled input token count (what is actually
+ * dispatched) so the assembler's INFO line can log the budget equation.
  */
 export declare function runPreflightFitCheck(deps: ContextEngineDeps, effectiveWindow: number, evictable: BudgetItem[], keptCount: number, freshTail: AgentMessage[], reasoningStyle: "none" | "native", capInfo?: ContextWindowCapInfo): number;

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

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
-// @allow-throw: ContextExhaustionError is a control-flow signal caught by handleEnvelopeException and mapped to finishReason:context_exhausted (design Fix 3/5)
+// @allow-throw: ContextExhaustionError is a control-flow signal caught by handleEnvelopeException and mapped to finishReason:context_exhausted
 /**
- * Pre-flight fit check for the LCD dag assembler (Phase 166 CWF-02).
+ * Pre-flight fit check for the LCD dag assembler.
  *
  * Enforces the invariant: assembledInputTokens ≤ effectiveWindow − outputHeadroom.
- * Security-pinned messages (T-S4) are NEVER evicted in the harder-eviction pass.
+ * Security-pinned messages are NEVER evicted in the harder-eviction pass.
  *
  * Escalation ladder:
  *  (a) Evict harder with security-pinned messages excluded.
@@ -13,7 +13,7 @@
  *
  * Separated from lcd-assembler.ts to keep that file ≤ 820 lines.
  *
- * Root-cause context-exhaustion guard (2026-06-22): the NON-EVICTABLE fixed
+ * Root-cause context-exhaustion guard: the NON-EVICTABLE fixed
  * overhead S (system prompt + tool schemas) is the dominant term on small
  * windows. The window-aware tool-budget fit pass (executor-tool-assembly.ts
  * `enforceToolBudgetFit`) defers tools so S fits BEFORE this pre-flight runs,
@@ -27,8 +27,7 @@
  * guidance, keep identity + essential behavior) would let the agent still reply
  * on a window < full-prompt. Deferred: it is deeply invasive in the 1954-line
  * prompt-assembly.ts (per-session bootstrap snapshot + once-per-session
- * systemPromptOverride). Tracked against the codex nano-window context-exhaustion
- * incident. Until then the degenerate case fails honestly (above).
+ * systemPromptOverride). Until then the degenerate case fails honestly (above).
  *
  * @module
  */
@@ -39,7 +38,7 @@ import { evictHistoryUnderBudget } from "./lcd-budget-eviction.js";
 import { factoredMessageTokens } from "./factored-message-tokens.js";
 const VALID_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 /**
- * Run the CWF-02 pre-flight fit check.
+ * Run the pre-flight fit check.
  *
  * @param deps              - ContextEngineDeps (reads securityPinMarkers, callbacks, logger).
  * @param effectiveWindow   - budget.windowTokens for this turn.
@@ -50,26 +49,26 @@ const VALID_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
  *                            The NEWEST keptCount items from evictable were kept.
  * @param freshTail         - The unconditional fresh-tail messages.
  * @param reasoningStyle    - profile.reasoningStyle ("none" | "native").
- * @param capInfo           - W1 cap provenance (budget.rawContextWindowTokens +
+ * @param capInfo           - Window-cap provenance (budget.rawContextWindowTokens +
  *                            budget.windowCapSource). When the effective window was
  *                            clamped by a capability-class cap, the exhaustion throw
  *                            and WARN name the raw window and the exact config knob.
  *
  * Throws ContextExhaustionError if infeasible even at the thinking-level floor.
  * Emits onEffectiveWindow, onThinkingDownshifted, onAssembledInputTokens callbacks as side effects.
- * Returns the ORIGINAL assembled input token count (CR-03 — what is actually
- * dispatched) so the assembler's INFO line can log the budget equation (W5).
+ * Returns the ORIGINAL assembled input token count (what is actually
+ * dispatched) so the assembler's INFO line can log the budget equation.
  */
 export function runPreflightFitCheck(deps, effectiveWindow, evictable, keptCount, freshTail, reasoningStyle, capInfo) {
-    // Emit effectiveWindow callback so Plan 04 can clamp max_tokens dynamically.
+    // Emit effectiveWindow callback so the caller can clamp max_tokens dynamically.
     deps.onEffectiveWindow?.(effectiveWindow);
     const rawThinkingLevel = deps.getThinkingLevel?.() ?? "medium";
     const thinkingLevelInput = VALID_LEVELS.includes(rawThinkingLevel)
         ? rawThinkingLevel
         : "medium";
-    // WR-02: use the operator-configurable floor (from contextEngine.budget.minVisibleOutputTokens)
-    // when provided; otherwise fall back to the compile-time constant (768). Frontier/mid:
-    // default 768 → byte-identical result.
+    // Use the operator-configurable floor (from contextEngine.budget.minVisibleOutputTokens)
+    // when provided; otherwise fall back to the compile-time constant (768), which is
+    // what frontier/mid deployments (no explicit config) run with.
     const minVisibleFloor = deps.minVisibleOutputTokens;
     let effectiveThinkingLevel = thinkingLevelInput;
     let outputHeadroom = computeOutputHeadroom(reasoningStyle, effectiveThinkingLevel, minVisibleFloor);
@@ -80,34 +79,33 @@ export function runPreflightFitCheck(deps, effectiveWindow, evictable, keptCount
     const budgetedTokens = evictable.slice(keptStart).reduce((s, b) => s + b.tokens, 0);
     // Estimate fresh tail token count via the shared factored per-message estimator
     // (factored-message-tokens.ts): ceil(chars / (CHARS_PER_TOKEN_RATIO × scriptTokenFactor))
-    // over each message's OWN extracted text (string + array multi-part/tool-result content,
-    // IN-01; dense scripts carry ~2-3× tokens/char, ASCII factor 1.0 → the bare 3.5:1 form, TOK-01).
-    // Per-message counts are kept (not just the sum) so the Issue-6 cause classifier below
+    // over each message's OWN extracted text (string + array multi-part/tool-result content;
+    // dense scripts carry ~2-3× tokens/char, ASCII factor 1.0 → the bare 3.5:1 form).
+    // Per-message counts are kept (not just the sum) so the exhaustion-cause classifier below
     // can tell a single-oversized-message failure from an aggregate overflow.
-    // ISSUE #3: factoredMessageTokens is the SINGLE shared estimator — boundFreshTailTotalToResidual
+    // factoredMessageTokens is the SINGLE shared estimator — boundFreshTailTotalToResidual
     // uses the SAME function, so the fresh-tail BOUND and this MEASURE can never diverge
     // (no estimator gap → no fudge factor needed in the bound).
     const freshTailMsgTokens = freshTail.map((m) => factoredMessageTokens(m));
     const freshTailTokens = freshTailMsgTokens.reduce((s, t) => s + t, 0);
-    // OF-01 (v2.19): count the FULL SDK prompt, not just history+freshTail. The
+    // Count the FULL SDK prompt, not just history+freshTail. The
     // dominant term is the system prompt + tool schemas (S = getSystemTokensEstimate)
-    // — the SAME value the eviction budget subtracts (lcd-assembler `S`). The
-    // fit-check previously OMITTED it, so a real ~31.5K prompt (S≈25584 + history +
-    // freshTail) looked like ~6.5K, passed the check, and the model truncated
+    // — the SAME value the eviction budget subtracts (lcd-assembler `S`). Omitting
+    // it makes a real ~31.5K prompt (S≈25584 + history +
+    // freshTail) look like ~6.5K, pass the check, and the model truncates
     // silently at stopReason:length — the governor / clamp / context-exhausted
-    // ladder never engaged. S is non-evictable (system+tools), so it also enters
+    // ladder never engages. S is non-evictable (system+tools), so it also enters
     // the harder-eviction budget below and the reported assembled count.
-    // See design/small-model-orchestration-fidelity.md §6 Fix 1.
     const systemTokens = deps.getSystemTokensEstimate?.() ?? 0;
-    // CR-03: save the ORIGINAL assembled count (what is actually dispatched to the LLM)
+    // Save the ORIGINAL assembled count (what is actually dispatched to the LLM)
     // BEFORE any simulation in step (a). onAssembledInputTokens must always report this
     // value — NOT the simulated undercount from the security-pin harder-eviction pass.
     const originalAssembledInputTokens = systemTokens + budgetedTokens + freshTailTokens;
     let assembledInputTokens = originalAssembledInputTokens;
-    // W2 (obs-llm-troubleshooting): emit the budget equation once per fit check —
+    // Emit the budget equation once per fit check —
     // "fits"/"downshifted" at the end, "exhausted" right before the throw — so the
     // trajectory carries the numbers obs.explain needs to explain a degraded turn
-    // (they previously existed only as daemon-log DEBUG lines).
+    // (a daemon-log DEBUG line alone would be invisible at the default level).
     let governorFired = false;
     const emitBudgetComputed = (verdict, assembled, headroom) => {
         deps.eventBus?.emit("context:budget_computed", {
@@ -129,16 +127,16 @@ export function runPreflightFitCheck(deps, effectiveWindow, evictable, keptCount
         // (a) Evict harder against the room that ACTUALLY remains after the
         // non-evictable S (system+tools) and the unconditionally-shipped fresh tail.
         //
-        // ISSUE #1 (multi-turn nano, 2026-06-22): this rung MUST run UNCONDITIONALLY.
-        // It was previously gated on `if (deps.securityPinMarkers)`, so on a fresh
-        // session with no canary (markers undefined — the common case) the harder
-        // eviction was SKIPPED entirely: the looser history-budget eviction from the
+        // This rung MUST run UNCONDITIONALLY — never gate it on
+        // `if (deps.securityPinMarkers)`. Gated, a fresh
+        // session with no canary (markers undefined — the common case) skips the harder
+        // eviction entirely: the looser history-budget eviction from the
         // assembler (H = W−S−O−M−R−P + the 8K-starvation add-back ≈ 4096 on an 8192
-        // nano window) leaked through, assembled stayed > the bound, and the turn threw
+        // nano window) leaks through, assembled stays > the bound, and the turn throws
         // on EVICTABLE history that could have been trimmed. Accumulated evictable
         // history must NEVER cause exhaustion — it evicts down to whatever fits (even
         // to near-zero → a degraded-but-running stateless turn). Security-pinned
-        // messages (T-S4) are still excluded from the harder pass when markers exist;
+        // messages are still excluded from the harder pass when markers exist;
         // with no markers, NO item is pinned (pinnedItems = [], pinnedTokens = 0) and
         // ALL evictable history is trimmed under the tighter budget.
         const markers = deps.securityPinMarkers;
@@ -149,7 +147,7 @@ export function runPreflightFitCheck(deps, effectiveWindow, evictable, keptCount
             ? evictable.filter((item) => !isSecurityRelevantMessage(item.msg, markers))
             : evictable;
         const pinnedTokens = pinnedItems.reduce((s, b) => s + b.tokens, 0);
-        // OF-01: S (system+tools) is non-evictable — reserve it in the harder-eviction
+        // S (system+tools) is non-evictable — reserve it in the harder-eviction
         // budget so history is evicted against the room that ACTUALLY remains.
         const tighterBudget = Math.max(0, headroomBound - systemTokens - pinnedTokens - freshTailTokens);
         const hardEvictedMsgs = evictHistoryUnderBudget(nonPinnedItems, tighterBudget);
@@ -194,7 +192,7 @@ export function runPreflightFitCheck(deps, effectiveWindow, evictable, keptCount
         const finalHeadroom = computeOutputHeadroom(reasoningStyle, effectiveThinkingLevel, minVisibleFloor);
         const finalBound = effectiveWindow - finalHeadroom;
         if (assembledInputTokens > finalBound) {
-            // Issue-6: classify WHY. A single item whose tokens alone (on top of the
+            // Classify WHY. A single item whose tokens alone (on top of the
             // non-evictable S) exceed the bound is an oversized-MESSAGE failure —
             // eviction/narrowing other content can never fix it, so the generic
             // "narrow the ask" advice would mislead. Distinguish the current input
@@ -202,10 +200,10 @@ export function runPreflightFitCheck(deps, effectiveWindow, evictable, keptCount
             // actionable) from an earlier message (only a session reset helps).
             // Everything else is the historical aggregate overflow.
             //
-            // ROOT-CAUSE fix (2026-06-22): the FIXED overhead S (system prompt + tool
+            // The FIXED overhead S (system prompt + tool
             // schemas) is NON-EVICTABLE. When S alone exceeds the bound, the turn is
             // infeasible regardless of history/thinking/message — so this must be
-            // classified FIRST, before the message/history branches. Pre-fix this fell
+            // classified FIRST, before the message/history branches. Otherwise it falls
             // through to oversized_input because `singleItemBound = finalBound − S`
             // goes NEGATIVE (any message token count > a negative number), producing
             // the misleading "your message alone is larger than this model's context
@@ -213,13 +211,13 @@ export function runPreflightFitCheck(deps, effectiveWindow, evictable, keptCount
             // is the WINDOW or the agent's tool/prompt footprint — never the message.
             const singleItemBound = finalBound - systemTokens;
             const lastUserIdx = findLastUserIndex(freshTail);
-            // ISSUE #2b (2026-06-22): when history is FULLY evicted (keptCount==0 and nothing
-            // evictable remains — Fix C did its job) and the protected fresh tail is the SOLE
+            // When history is FULLY evicted (keptCount==0 and nothing
+            // evictable remains) and the protected fresh tail is the SOLE
             // overflow, "aggregate" misleads: the remedy is to shrink the user's input, not to
             // reset a (now-empty) conversation. Reclassify as oversized_input when the LAST
             // user message DOMINATES the fresh-tail tokens (> half) — distinguishing "one large
             // current message (+ a tiny recent turn)" from a genuine many-comparable-messages
-            // aggregate (the live turn-14 residual after the preamble drop: a ~2000-tok message
+            // aggregate (e.g. a ~2000-tok message
             // just under the single-item bound + a small prior turn). The dominance test keeps
             // the existing aggregate case (5 comparable messages, each ~20% of the sum) intact.
             const lastUserTokens = lastUserIdx >= 0 ? (freshTailMsgTokens[lastUserIdx] ?? 0) : 0;
@@ -259,13 +257,13 @@ export function runPreflightFitCheck(deps, effectiveWindow, evictable, keptCount
             throw new ContextExhaustionError(effectiveWindow, assembledInputTokens, capInfo, cause);
         }
     }
-    // CR-03: always report the ORIGINAL assembled count (what is actually dispatched).
+    // Always report the ORIGINAL assembled count (what is actually dispatched).
     // The simulated harder-eviction in step (a) only measures feasibility; it does NOT
     // change the actual context array dispatched (that is built from `repaired` in
     // lcd-assembler.ts). Reporting the simulated count would give config-resolver a
     // stale undercount → dynamicMax set too high → silent LLM truncation.
     deps.onAssembledInputTokens?.(originalAssembledInputTokens);
-    // W2: the non-throw outcomes. `outputHeadroom` holds the downshifted value when
+    // The non-throw outcomes. `outputHeadroom` holds the downshifted value when
     // the governor fired (the loop reassigns it), so the event reports the headroom
     // the dispatch will actually run with.
     emitBudgetComputed(governorFired ? "downshifted" : "fits", originalAssembledInputTokens, outputHeadroom);

package/node_modules/@comis/agent/dist/context-engine/lcd-summary-render.d.ts

@@ -2,37 +2,36 @@
  * Summary-ref rendering for the dag assembler — extracted VERBATIM from
  * `lcd-assembler.ts` (file-size cap, ≤800 lines) so the assembler keeps only
  * resolve/assemble flow. {@link summaryRefToMessage} stays the ONE resolution
- * point Phase 130 swapped in; the assembler's `resolveContextItem` is its sole
- * caller.
+ * point; the assembler's `resolveContextItem` is its sole caller.
  *
  * @module
  */
 import type { LcdSummary } from "@comis/core";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 /**
- * Render a summary as an HONEST, TAINT-SAFE `user`-role message (P1) — the ONE
- * seam Phase 130 swaps from the plain text passthrough Phase 129 left here.
+ * Render a summary as an HONEST, TAINT-SAFE `user`-role message — the ONE
+ * resolution seam for summary refs (never a plain-text passthrough).
  *
  * The honesty markers (depth / descendant_count / ISO time-range / trust, plus
- * R2's `fallback=emergency-truncation` when `summary.fallback`) are computed from
+ * `fallback=emergency-truncation` when `summary.fallback`) are computed from
  * the STORE ROW (`summary.depth`/`descendantCount`/`earliestAt`/`latestAt`/
  * `fallback`), NEVER parsed from `content`, and placed in the TRUSTED header +
  * footer OUTSIDE the `wrapExternalContent` untrusted region. A poisoned summary
  * body therefore cannot forge them: the per-session random hex delimiter is
  * unpredictable, and `replaceMarkers` neutralizes any injected `<<<UNTRUSTED_…>>>`
- * / `<<<END_UNTRUSTED_…>>>` marker the content tries to smuggle in (RED-proven:
+ * / `<<<END_UNTRUSTED_…>>>` marker the content tries to smuggle in (test-proven:
  * a body forging `trust=trusted` / `fallback=emergency-truncation` + a fake
  * end-delimiter still renders the real `trust=untrusted` + the real fallback flag
  * and the forged delimiter collapses to `[[END_MARKER_SANITIZED]]`).
  *
- * Role stays `"user"` — the documented ceiling (T-129-14): a summary derived from
+ * Role stays `"user"` — the documented ceiling: a summary derived from
  * possibly-untrusted history is carried untrusted-by-role, NEVER `system`/
  * `assistant`. The body is wrapped via `wrapExternalContent` (the AGENTS.md §2.2
  * taint primitive) rather than hand-rolled XML escaping.
  *
  * The expand footer is an honest ADVERTISEMENT of WHAT was compressed (depth +
- * count + time-range); the recovery TOOLS (`ctx_*`) are Phase 131 — DECISION
- * GATE #3 / RESEARCH A4: do NOT name them here. Keep this the single resolution
- * point so future swaps touch one function.
+ * count + time-range); it deliberately does NOT name the recovery TOOLS
+ * (`ctx_*`) — their descriptions own that surface. Keep this the single
+ * resolution point so future swaps touch one function.
  */
 export declare function summaryRefToMessage(summary: LcdSummary): AgentMessage;

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

@@ -2,42 +2,41 @@
  * Summary-ref rendering for the dag assembler — extracted VERBATIM from
  * `lcd-assembler.ts` (file-size cap, ≤800 lines) so the assembler keeps only
  * resolve/assemble flow. {@link summaryRefToMessage} stays the ONE resolution
- * point Phase 130 swapped in; the assembler's `resolveContextItem` is its sole
- * caller.
+ * point; the assembler's `resolveContextItem` is its sole caller.
  *
  * @module
  */
 import { scrubSecretsFromText, systemDateFrom, wrapExternalContent } from "@comis/core";
 import { LCD_FALLBACK_HEADER_MARKER } from "./constants.js";
 /**
- * Render a summary as an HONEST, TAINT-SAFE `user`-role message (P1) — the ONE
- * seam Phase 130 swaps from the plain text passthrough Phase 129 left here.
+ * Render a summary as an HONEST, TAINT-SAFE `user`-role message — the ONE
+ * resolution seam for summary refs (never a plain-text passthrough).
  *
  * The honesty markers (depth / descendant_count / ISO time-range / trust, plus
- * R2's `fallback=emergency-truncation` when `summary.fallback`) are computed from
+ * `fallback=emergency-truncation` when `summary.fallback`) are computed from
  * the STORE ROW (`summary.depth`/`descendantCount`/`earliestAt`/`latestAt`/
  * `fallback`), NEVER parsed from `content`, and placed in the TRUSTED header +
  * footer OUTSIDE the `wrapExternalContent` untrusted region. A poisoned summary
  * body therefore cannot forge them: the per-session random hex delimiter is
  * unpredictable, and `replaceMarkers` neutralizes any injected `<<<UNTRUSTED_…>>>`
- * / `<<<END_UNTRUSTED_…>>>` marker the content tries to smuggle in (RED-proven:
+ * / `<<<END_UNTRUSTED_…>>>` marker the content tries to smuggle in (test-proven:
  * a body forging `trust=trusted` / `fallback=emergency-truncation` + a fake
  * end-delimiter still renders the real `trust=untrusted` + the real fallback flag
  * and the forged delimiter collapses to `[[END_MARKER_SANITIZED]]`).
  *
- * Role stays `"user"` — the documented ceiling (T-129-14): a summary derived from
+ * Role stays `"user"` — the documented ceiling: a summary derived from
  * possibly-untrusted history is carried untrusted-by-role, NEVER `system`/
  * `assistant`. The body is wrapped via `wrapExternalContent` (the AGENTS.md §2.2
  * taint primitive) rather than hand-rolled XML escaping.
  *
  * The expand footer is an honest ADVERTISEMENT of WHAT was compressed (depth +
- * count + time-range); the recovery TOOLS (`ctx_*`) are Phase 131 — DECISION
- * GATE #3 / RESEARCH A4: do NOT name them here. Keep this the single resolution
- * point so future swaps touch one function.
+ * count + time-range); it deliberately does NOT name the recovery TOOLS
+ * (`ctx_*`) — their descriptions own that surface. Keep this the single
+ * resolution point so future swaps touch one function.
  */
 export function summaryRefToMessage(summary) {
     // `trust` is ALWAYS "untrusted" (the row is untrusted-by-derivation; the value
-    // is derived, never widened to "trusted"). R2 (Phase 132): when the row's
+    // is derived, never widened to "trusted"). When the row's
     // `fallback` flag is set — the breaker/spend-cap bypass or the deterministic
     // Level-3 floor produced this summary with NO LLM — append the unspoofable
     // `LCD_FALLBACK_HEADER_MARKER` so the model is honestly told the summary is a
@@ -54,13 +53,13 @@ export function summaryRefToMessage(summary) {
         `${range}, trust=${trust}${fallbackMarker}]`;
     // The body is UNTRUSTED — scrub secrets, THEN wrap it. `source: "unknown"`
     // (label "External") is the generic untrusted-text source; the
-    // `ExternalContentSource` union has no `lcd_summary` label and a P1 plan does not
-    // edit the core security enum. The honesty markers live OUTSIDE this wrapped
-    // region (the trusted header/footer), so no `includeWarning` wall is needed per
-    // summary — the header + the P2 system clause carry the policy.
+    // `ExternalContentSource` union has no `lcd_summary` label and this rendering
+    // layer does not edit the core security enum. The honesty markers live OUTSIDE
+    // this wrapped region (the trusted header/footer), so no `includeWarning` wall
+    // is needed per summary — the header + the system-prompt clause carry the policy.
     //
-    // Egress scrub (FIX 2c): a summary is DERIVED from a region that can legitimately
-    // contain a credential (the F1 lossless store keeps the raw conversation). The
+    // Egress scrub: a summary is DERIVED from a region that can legitimately
+    // contain a credential (the lossless base store keeps the raw conversation). The
     // summary re-enters the model context every turn it is assembled, so the derived
     // body must never carry the secret verbatim — scrub this egress copy (the base
     // store stays lossless), mirroring the ctx_expand / ctx_search egress scrub.