comisai 1.0.44 → 1.0.46

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

@@ -31,7 +31,7 @@ export interface CompactionLayerConfig {
     /** Turns to wait before re-triggering compaction. */
     compactionCooldownTurns: number;
     /** Number of user-turn cycles at conversation head to preserve during compaction.
-     *  0 = old behavior (tail-only). */
+     *  0 = tail-only compaction (no preserved head). */
     compactionPrefixAnchorTurns: number;
     /** The agent's capability class (from ModelProfile). Defaults to "frontier" (unchanged behavior). */
     capabilityClass?: CapabilityClass;

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

@@ -106,14 +106,14 @@ export function validateCompactionSummary(summary) {
  * (or at the very front when `headCount === 0`), removes EXACTLY the message
  * entries named by `removeMessageOrdinals`, and calls `_rewriteFile()` once.
  *
- * Review WR-01: removal is by IDENTITY — the caller passes the file-order
- * message ordinals of the SUMMARIZED span — never by count. The previous
- * count-based removal took the first (pinned + span) middle entries
- * positionally, which deleted un-summarized REMAINDER entries from the durable
- * session file whenever an S4-pinned message sat later in the middle: durable
- * history deletion the summary does not cover (Pitfall 3). With identity
- * removal, pinned messages AND the remainder survive in the file regardless of
- * interleaving; only content the summary actually covers is removed.
+ * Removal is by IDENTITY — the caller passes the file-order message ordinals
+ * of the SUMMARIZED span — never by count. A count-based removal would take
+ * the first (pinned + span) middle entries positionally, which deletes
+ * un-summarized REMAINDER entries from the durable session file whenever a
+ * security-pinned message sits later in the middle: durable history deletion
+ * the summary does not cover. With identity removal, pinned messages AND the
+ * remainder survive in the file regardless of interleaving; only content the
+ * summary actually covers is removed.
  *
  * This is safe because `transformContext` runs within the `withSession()` write lock.
  */
@@ -134,8 +134,8 @@ function persistCompaction(sm, summaryText, removeMessageOrdinals, headCount, di
         },
     };
     // Single walk over fileEntries: drop the named message ordinals, insert the
-    // compaction entry immediately after the headCount-th message entry (the
-    // pre-existing placement), or prepend when there is no preserved head.
+    // compaction entry immediately after the headCount-th message entry, or
+    // prepend when there is no preserved head.
     const newEntries = [];
     let inserted = false;
     if (headCount === 0) {
@@ -204,7 +204,7 @@ export function createLlmCompactionLayer(config, deps) {
                     /* eslint-disable @typescript-eslint/no-explicit-any */
                     const contextChars = estimateContextCharsWithDualRatio(messages);
                     /* eslint-enable @typescript-eslint/no-explicit-any */
-                    // flat-by-design: aggregate cold-start compare, no text in scope; anti-conservative for ONE unanchored turn — estimateWithAnchor self-corrects from turn 2 (TOK-01, design §4)
+                    // flat-by-design: aggregate cold-start compare, no text in scope; anti-conservative for ONE unanchored turn — estimateWithAnchor self-corrects from turn 2
                     const charBasedTokens = Math.ceil(contextChars / CHARS_PER_TOKEN_RATIO);
                     const anchor = deps.getTokenAnchor?.() ?? null;
                     contextTokens = estimateWithAnchor(anchor, messages, charBasedTokens);
@@ -213,8 +213,8 @@ export function createLlmCompactionLayer(config, deps) {
                         return messages;
                     }
                 }
-                // Step 4: Resolve model. INT-W1: the served-window truth rides the SAME
-                // branch as the model selection (gated per candidate at the wiring site).
+                // Step 4: Resolve model. The served-window truth rides the SAME branch
+                // as the model selection (gated per candidate at the wiring site).
                 /* eslint-disable @typescript-eslint/no-explicit-any */
                 let model;
                 let apiKey;
@@ -297,9 +297,9 @@ export function createLlmCompactionLayer(config, deps) {
                     turnsSinceLastCompaction = 0;
                     return messages;
                 }
-                // S4: filter security-pinned messages out of the middle zone.
+                // Filter security-pinned messages out of the middle zone.
                 // pinned[] is hoisted to outer scope so the output assembly can re-insert them
-                // (see result assembly below — S4 invariant: pinned messages MUST appear in output).
+                // (see result assembly below — invariant: pinned messages MUST appear in output).
                 // Must run before the capability gate so pinnedCount is accurate for the event.
                 const pinned = [];
                 let evictableMiddle = middleMessages;
@@ -319,7 +319,7 @@ export function createLlmCompactionLayer(config, deps) {
                     securityPinnedCount = pinned.length;
                     evictableMiddle = evictable;
                 }
-                // C4: resolve the compaction strategy based on capability class.
+                // Resolve the compaction strategy based on capability class.
                 const compactionStrategy = resolveCompactionStrategy(config.capabilityClass ?? "frontier", config.preferEvictionByCapability ?? true, config.strongerSummarizerModel ?? "");
                 if (compactionStrategy === "eviction" || compactionStrategy === "deterministic") {
                     // Small/nano: skip LLM call — use deterministic Level-3 fallback.
@@ -347,25 +347,24 @@ export function createLlmCompactionLayer(config, deps) {
                     turnsSinceLastCompaction = 0;
                     return messages;
                 }
-                // SUMW-01 (Phase 178): clamp the summarized span to the RESOLVED
-                // summarizer's window. Reads the LOCAL `model` resolved at Step 4 — the
-                // SAME variable handed to generateSummary (the try/catch override
-                // fallback already decided which model summarizes; re-resolving here
-                // could disagree — Pitfall 2). With an `operationModels.compaction`
-                // override the summarizer's window (e.g. 8K) can be far smaller than
-                // the middle zone — feeding the whole span is a provider overflow.
-                // INT-W1: the configured window is min()'d with the Phase-176 SERVED
-                // window bound to the SAME Step-4 candidate (a served-bound PRIMARY —
-                // num_ctx 8_192 under a configured 131_072 — clamps too, not just
-                // overrides). Neither valid → clamp OFF (never invent a window). The 85%
-                // trigger + cooldown re-fire until the remainder backlog drains (the
-                // cut===0 escalation guarantees every evaluation makes progress).
+                // Clamp the summarized span to the RESOLVED summarizer's window. Reads
+                // the LOCAL `model` resolved at Step 4 — the SAME variable handed to
+                // generateSummary (the try/catch override fallback already decided
+                // which model summarizes; re-resolving here could disagree). With an
+                // `operationModels.compaction` override the summarizer's window (e.g.
+                // 8K) can be far smaller than the middle zone — feeding the whole span
+                // is a provider overflow. The configured window is min()'d with the
+                // SERVED window bound to the SAME Step-4 candidate (a served-bound
+                // PRIMARY — num_ctx 8_192 under a configured 131_072 — clamps too, not
+                // just overrides). Neither valid → clamp OFF (never invent a window).
+                // The 85% trigger + cooldown re-fire until the remainder backlog drains
+                // (the cut===0 escalation guarantees every evaluation makes progress).
                 const summarizerWindow = effectiveSummarizerWindow(model?.contextWindow, servedSummarizerWindow);
-                // Review CR-01: the summary-output reserve must be SUMMARIZER-sized, not
+                // The summary-output reserve must be SUMMARIZER-sized, not
                 // session-sized — subtracting the session's outputReserveTokens (8_192 on
                 // any frontier session) from an 8K summarizer's window goes permanently
-                // negative and silently disables compaction forever (a regression vs the
-                // pre-clamp Level-2/3 floor). Reserve at most a QUARTER of the resolved
+                // negative and silently disables compaction forever (losing even the
+                // Level-2/3 fallback floor). Reserve at most a QUARTER of the resolved
                 // summarizer's own window, and pass the SAME value to compactWithFallback
                 // below so the clamp and the generateSummary reserveTokens agree.
                 const summaryReserve = summarizerWindow === undefined
@@ -376,17 +375,17 @@ export function createLlmCompactionLayer(config, deps) {
                 if (summarizerWindow !== undefined) {
                     const maxSpanTokens = summarizerWindow - summaryReserve - SUMMARIZER_PROMPT_OVERHEAD_TOKENS;
                     // Oldest-first prefix walk over the evictable middle: cut at the
-                    // first message that would exceed maxSpanTokens. Review WR-04: each
-                    // message is measured with the SAME dual-ratio estimate the layer's
-                    // own 85% trigger uses (toolResult chars weighted ×2 before the 3.5
+                    // first message that would exceed maxSpanTokens. Each message is
+                    // measured with the SAME dual-ratio estimate the layer's own 85%
+                    // trigger uses (toolResult chars weighted ×2 before the 3.5
                     // divide) — a flat chars/3.5 walk under-counts structured content by
                     // ~15-17%, re-opening the provider-overflow class on toolResult-heavy
                     // middles. One estimator per layer (single-sourced with the trigger).
-                    // TOK-01 (Phase 179): the divisor is modulated by scriptTokenFactor
-                    // over the message's extracted text — a Hebrew message carries ~1.8×
-                    // the tokens the flat measure admits, the same under-count class the
-                    // WR-04 dual-ratio fix closed for toolResults. The dual-ratio CHAR
-                    // walk stays authoritative (ASCII factor 1.0 → byte-identical cut).
+                    // The divisor is modulated by scriptTokenFactor over the message's
+                    // extracted text — a Hebrew message carries ~1.8× the tokens the
+                    // flat measure admits, the same under-count class the dual-ratio
+                    // estimate closes for toolResults. The dual-ratio CHAR walk stays
+                    // authoritative (ASCII factor 1.0 → byte-identical cut).
                     let spanTokens = 0;
                     let cut = 0;
                     for (const m of evictableMiddle) {
@@ -401,7 +400,7 @@ export function createLlmCompactionLayer(config, deps) {
                         cut++;
                     }
                     if (cut === 0) {
-                        // Review CR-01 (convergence): even the OLDEST evictable message alone
+                        // Convergence guarantee: even the OLDEST evictable message alone
                         // exceeds the span budget (or the window is below reserve + overhead).
                         // Skipping here would disarm compaction PERMANENTLY — the oldest
                         // message never leaves the middle's head, so every later evaluation
@@ -458,13 +457,13 @@ export function createLlmCompactionLayer(config, deps) {
                     ? "LLM compaction triggered: message count exceeds cache lookback threshold"
                     : "LLM compaction triggered: context exceeds 85% threshold");
                 // Step 7: Summarize ONLY the clamped middle span (do NOT pass head or tail
-                // to generateSummary). spanToSummarize is the SUMW-01 oldest-first prefix of
+                // to generateSummary). spanToSummarize is the oldest-first prefix of
                 // evictableMiddle that fits the resolved summarizer's window (security-pinned
-                // messages already excluded via S4 filtering above); when the clamp does not
+                // messages already excluded via the filtering above); when the clamp does not
                 // bind it IS evictableMiddle. summaryReserve is the SAME summarizer-sized
-                // reserve the clamp budgeted (review CR-01) — clamp and call always agree.
+                // reserve the clamp budgeted — clamp and call always agree.
                 const compactionResult = await compactWithFallback(spanToSummarize, model, apiKey, summaryReserve, deps.logger);
-                // OBS-01 (Phase 180): the small-model G4 detector at the PIPELINE site
+                // Small-model language-drift detection at the PIPELINE site
                 // (depth -1). The summary is now final (post-validate inside
                 // compactWithFallback); when a non-Latin source span produced a Latin
                 // summary, emit context:summary_language_mismatch. Source = the SAME span
@@ -489,13 +488,13 @@ export function createLlmCompactionLayer(config, deps) {
                     discoveredTools,
                 };
                 // Assemble: head + pinned + summary + remainingMiddle + tail
-                // S4: pinned messages from the middle zone are excluded from summarization
+                // Security-pinned messages from the middle zone are excluded from summarization
                 // but MUST be preserved in the output so they are never evicted from context.
                 // They are placed before the summary (surviving context, not part of the summary).
-                // SUMW-01: the un-summarized remainder of the middle zone is NEVER dropped
-                // (Pitfall 3 — a dropped remainder is silent, unrecoverable history deletion);
+                // The un-summarized remainder of the middle zone is NEVER dropped
+                // (a dropped remainder is silent, unrecoverable history deletion);
                 // it sits between the summary and the tail in original order. When the clamp
-                // does not bind, remainingMiddle is [] → output identical to before SUMW-01.
+                // does not bind, remainingMiddle is [] → output identical to an unclamped run.
                 // head stays at original positions for cache prefix stability.
                 const headMessages = messages.slice(0, headEndIndex);
                 const tailMessages = messages.slice(tailStartIndex);
@@ -507,13 +506,13 @@ export function createLlmCompactionLayer(config, deps) {
                     ...tailMessages,
                 ];
                 // Step 8: Persist compaction to SessionManager
-                // SUMW-01 / review WR-01: durable-side conservation is by IDENTITY —
+                // Durable-side conservation is by IDENTITY —
                 // messages[i] corresponds 1:1 to the i-th message entry in fileEntries
                 // (the positional model the head/tail counts already relied on), so we
                 // remove EXACTLY the summarized span's entries. Pinned messages and the
                 // un-summarized remainder survive in the durable file regardless of how
                 // they interleave; removing anything else would be durable history
-                // deletion the summary does not cover (the Pitfall-3 data loss).
+                // deletion the summary does not cover — silent data loss.
                 try {
                     const sm = deps.getSessionManager();
                     if (sm) {
@@ -539,7 +538,7 @@ export function createLlmCompactionLayer(config, deps) {
                     originalMessages: messages.length,
                     keptHeadMessages: headMessages.length,
                     keptTailMessages: tailMessages.length,
-                    // SUMW-01: counts reflect the CLAMPED span actually summarized, plus
+                    // Counts reflect the CLAMPED span actually summarized, plus
                     // the preserved un-summarized remainder (counts only — never content).
                     middleSummarized: spanToSummarize.length,
                     middleRemainder: remainingMiddle.length,

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

@@ -1,23 +1,23 @@
 /**
- * RETR-02 — the pure tiered margin arbiter.
+ * The pure tiered margin arbiter.
  *
  * The relevance-first sibling of {@link evictHistoryUnderBudget}. Where the recency
  * allocator keeps the NEWEST whole steps that fit a flat history budget, the arbiter
  * spends the SAME discretionary pool (`budget.availableHistoryTokens`) across multiple
  * candidate TIERS by FUSED RANK, with the unconditional floors guaranteed:
  *
- *   - T0 fresh-tail + S4-pinned items ({@link ArbiterFloors}) are UNCONDITIONAL floors
+ *   - T0 fresh-tail + security-pinned items ({@link ArbiterFloors}) are UNCONDITIONAL floors
  *     — always kept, NEVER relevance candidates, regardless of fused rank or pool
  *     contention. They mirror the `lcd-preflight.ts:114-121` harder-eviction exclusion:
- *     a security-pinned item survives even when it dwarfs the pool (the Fix-3 pre-flight
- *     already reserved room for it; the arbiter must not drop it). WR-04 (Phase 173-05):
+ *     a security-pinned item survives even when it dwarfs the pool (the output-headroom
+ *     pre-flight already reserved room for it; the arbiter must not drop it). Additionally,
  *     floors are STEP-ATOMIC — a floor flagged on one message in a step (a pinned
  *     `tool_use` whose `toolResult` is not separately pinned, or vice-versa) promotes the
  *     WHOLE step to a floor, so the inseparable pair is never split and `poolTokensUsed`
  *     bills only the genuinely-discretionary (non-floor) middle band.
  *   - The middle history band (T1/T2) + the cross-session LTM (T3) + KG (T4) candidate
  *     lanes share the remaining DISCRETIONARY pool, allocated by FUSED RANK (RRF via the
- *     Plan-02 scorer — `scoreRelevance`/`fuse`, injected as the `scorer` dep; per-tier
+ *     shared scorer — `scoreRelevance`/`fuse`, injected as the `scorer` dep; per-tier
  *     weights default 1.0; NEVER a raw cross-corpus score comparison: `lcd_messages_fts`/
  *     `memory_fts` BM25 stats are incomparable).
  *   - Per-tier minimum slots: each represented tier gets at least one slot when the pool
@@ -25,23 +25,23 @@
  *     long history band, and vice versa.
  *
  * The arbiter WRAPS, never rewrites, `computeTokenBudgetForProfile`: it consumes the
- * pre-computed `poolTokens` (already post-outputHeadroom — the Fix-3 pre-flight at
+ * pre-computed `poolTokens` (already post-outputHeadroom — the pre-flight at
  * `lcd-preflight.ts` validated it) and NEVER over-allocates then reclaims. The
  * DISCRETIONARY allocation (non-floor) is bounded `≤ poolTokens` (`poolTokensUsed`);
- * the unconditional floors ride on top (they are a security/A1 guarantee, not a budget
- * line). Step-atomic fill reuses the {@link BudgetItem} token authority — it never splits
- * a `tool_use`/`tool_result` pair (history is kept whole-step, recency-ordered within its
- * slot BY DEFAULT; the within-history relevance eviction of the middle band — DEPTH-01's
- * now-live `rankMiddleBandByRelevance` — is supplied as the optional injected
+ * the unconditional floors ride on top (they are a security/fresh-tail guarantee, not a
+ * budget line). Step-atomic fill reuses the {@link BudgetItem} token authority — it never
+ * splits a `tool_use`/`tool_result` pair (history is kept whole-step, recency-ordered
+ * within its slot BY DEFAULT; the within-history relevance eviction of the middle band —
+ * `rankMiddleBandByRelevance` — is supplied as the optional injected
  * {@link MarginArbitrateInput.middleBandRanker}, which keeps this allocator pure while
- * re-ranking the evictable middle band cache-safely — see the C2 boundary note below).
+ * re-ranking the evictable middle band cache-safely — see the boundary note below).
  *
  * Purity (and the architecture cuts): no I/O, no clock, no estimator, no globals; the
  * input arrays (and their items) are NEVER mutated; a new array is returned; same input →
  * same output. This module lives in `context-engine/` and obeys TWO cuts:
  *   - agent↛memory: it imports only `@comis/core` types + in-package context-engine
  *     modules — never `@comis/memory` (forbidden by `test/architecture` "agent → memory").
- *   - I2 (context-engine ↮ rag): the LCD engine and the recall/RAG layer share ZERO code
+ *   - context-engine ↮ rag: the LCD engine and the recall/RAG layer share ZERO code
  *     (`lcd-recall-boundary.test.ts`). So the shared relevance scorer (`rag/relevance-scorer.ts`)
  *     is NOT imported — it is INJECTED as the `scorer` dep (DI at the budget boundary), and
  *     the `FusionLane`/`RelevanceQuery` shapes are declared LOCALLY here as the minimal
@@ -55,7 +55,7 @@ import type { MemorySearchResult, ComisLogger } from "@comis/core";
 import type { BudgetItem } from "./lcd-budget-eviction.js";
 /**
  * The minimal STRUCTURAL shape of a fusion lane the arbiter ranks — structurally
- * identical to `rag/fuse.ts`'s `FusionLane`, declared locally to honor the I2
+ * identical to `rag/fuse.ts`'s `FusionLane`, declared locally to honor the
  * context-engine ↮ rag cut (the engine must not import the rag layer). The injected
  * `scorer` (`scoreRelevance`) consumes/returns exactly this shape.
  */
@@ -68,7 +68,7 @@ export interface ArbiterFusionLane {
 /**
  * The minimal STRUCTURAL shape of the relevance query the scorer consumes —
  * structurally identical to `rag/relevance-scorer.ts`'s `RelevanceQuery`, declared
- * locally for the I2 cut. `degraded` (low-signal) → the scorer falls back to
+ * locally for the same cut. `degraded` (low-signal) → the scorer falls back to
  * recency-first fusion (a deterministic recency signal).
  */
 export interface ArbiterRelevanceQuery {
@@ -91,10 +91,10 @@ export interface ArbiterScorerOptions {
  */
 export type RelevanceScorerFn = (lanes: ArbiterFusionLane[], query: ArbiterRelevanceQuery, opts?: ArbiterScorerOptions) => MemorySearchResult[];
 /**
- * The UNCONDITIONAL arbiter floors (RETR-05). Both are guaranteed to survive
+ * The UNCONDITIONAL arbiter floors. Both are guaranteed to survive
  * arbitration and are NEVER relevance candidates:
- *  - `freshTailItems`: the T0 fresh-tail-protected history items (A1).
- *  - `pinnedItems`: the S4 security-pinned history items (canary / delimiter /
+ *  - `freshTailItems`: the T0 fresh-tail-protected history items.
+ *  - `pinnedItems`: the security-pinned history items (canary / delimiter /
  *    safety / sender-trust — detected fail-closed by `isSecurityRelevantMessage`).
  * Both are subsets of `historyItems` (the caller filters them out of the relevance
  * band and passes them here). Identity-compared against `historyItems` entries.
@@ -102,7 +102,7 @@ export type RelevanceScorerFn = (lanes: ArbiterFusionLane[], query: ArbiterRelev
 export interface ArbiterFloors {
     /** T0 fresh-tail-protected history items (unconditional). */
     freshTailItems: BudgetItem[];
-    /** S4 security-pinned history items (unconditional; never relevance candidates). */
+    /** Security-pinned history items (unconditional; never relevance candidates). */
     pinnedItems: BudgetItem[];
 }
 /** The arbiter input (a single object so the seam call stays readable). */
@@ -113,7 +113,7 @@ export interface MarginArbitrateInput {
     ltmCandidates: ArbiterFusionLane[];
     /** Knowledge-graph candidate lanes (T4) — fused by rank. Empty on the assembly path. */
     kgCandidates: ArbiterFusionLane[];
-    /** The unconditional floors (T0 fresh-tail + S4 pins). */
+    /** The unconditional floors (T0 fresh-tail + security pins). */
     floors: ArbiterFloors;
     /** The discretionary pool (budget.availableHistoryTokens — already post-outputHeadroom). */
     poolTokens: number;
@@ -130,12 +130,12 @@ export interface MarginArbitrateInput {
     minTierSlots?: number;
     /** Optional content-free logger forwarded to the scorer's degraded log. */
     scorerOptions?: ArbiterScorerOptions;
-    /** DEPTH-01: the injected middle-band fill. Default = the pure recency
+    /** The injected middle-band fill. Default = the pure recency
      *  {@link evictHistoryUnderBudget}. On the relevance-first path the seam
      *  (`lcd-arbiter-seam.evictUnderArbiter`) injects
      *  `rankMiddleBandByRelevance` (cache-stable relevance ranking + chronological
      *  restore + step-atomic fill), keeping this allocator PURE — the ranker is a
-     *  dep, the relevance scorer lives behind the I2 cut. The signature mirrors the
+     *  dep, the relevance scorer lives behind the context-engine ↮ rag cut. The signature mirrors the
      *  recency fill `(band, pool) => AgentMessage[]` so the default is a drop-in. */
     middleBandRanker?: (band: BudgetItem[], pool: number) => AgentMessage[];
 }
@@ -151,8 +151,8 @@ export interface MarginArbitrateResult {
     };
     /** Discretionary (non-floor) tokens allocated from the pool — always ≤ poolTokens. */
     poolTokensUsed: number;
-    /** WR-03 (Phase 173-05): the UNCONDITIONAL floor weight — the summed tokens of every
-     *  kept floor item (T0 fresh-tail + S4-pinned, STEP-atomic). These ride ON TOP of the
+    /** The UNCONDITIONAL floor weight — the summed tokens of every
+     *  kept floor item (T0 fresh-tail + security-pinned, STEP-atomic). These ride ON TOP of the
      *  pool (NOT counted in poolTokensUsed), so surfacing them lets an operator see when the
      *  pinned floors dwarf the discretionary pool (the small-model context-exhaustion signal). */
     floorTokensUsed: number;
@@ -163,7 +163,7 @@ export interface MarginArbitrateResult {
 }
 /**
  * Allocate the discretionary history pool across tiers by fused rank, with the T0
- * fresh-tail + S4-pinned floors unconditional. See the module doc for the full contract.
+ * fresh-tail + security-pinned floors unconditional. See the module doc for the full contract.
  *
  * @param input - the tiered candidates + floors + pool + scorer (see {@link MarginArbitrateInput}).
  * @returns the kept messages + per-tier counts + the discretionary tokens used.

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

@@ -1,24 +1,24 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * RETR-02 — the pure tiered margin arbiter.
+ * The pure tiered margin arbiter.
  *
  * The relevance-first sibling of {@link evictHistoryUnderBudget}. Where the recency
  * allocator keeps the NEWEST whole steps that fit a flat history budget, the arbiter
  * spends the SAME discretionary pool (`budget.availableHistoryTokens`) across multiple
  * candidate TIERS by FUSED RANK, with the unconditional floors guaranteed:
  *
- *   - T0 fresh-tail + S4-pinned items ({@link ArbiterFloors}) are UNCONDITIONAL floors
+ *   - T0 fresh-tail + security-pinned items ({@link ArbiterFloors}) are UNCONDITIONAL floors
  *     — always kept, NEVER relevance candidates, regardless of fused rank or pool
  *     contention. They mirror the `lcd-preflight.ts:114-121` harder-eviction exclusion:
- *     a security-pinned item survives even when it dwarfs the pool (the Fix-3 pre-flight
- *     already reserved room for it; the arbiter must not drop it). WR-04 (Phase 173-05):
+ *     a security-pinned item survives even when it dwarfs the pool (the output-headroom
+ *     pre-flight already reserved room for it; the arbiter must not drop it). Additionally,
  *     floors are STEP-ATOMIC — a floor flagged on one message in a step (a pinned
  *     `tool_use` whose `toolResult` is not separately pinned, or vice-versa) promotes the
  *     WHOLE step to a floor, so the inseparable pair is never split and `poolTokensUsed`
  *     bills only the genuinely-discretionary (non-floor) middle band.
  *   - The middle history band (T1/T2) + the cross-session LTM (T3) + KG (T4) candidate
  *     lanes share the remaining DISCRETIONARY pool, allocated by FUSED RANK (RRF via the
- *     Plan-02 scorer — `scoreRelevance`/`fuse`, injected as the `scorer` dep; per-tier
+ *     shared scorer — `scoreRelevance`/`fuse`, injected as the `scorer` dep; per-tier
  *     weights default 1.0; NEVER a raw cross-corpus score comparison: `lcd_messages_fts`/
  *     `memory_fts` BM25 stats are incomparable).
  *   - Per-tier minimum slots: each represented tier gets at least one slot when the pool
@@ -26,23 +26,23 @@
  *     long history band, and vice versa.
  *
  * The arbiter WRAPS, never rewrites, `computeTokenBudgetForProfile`: it consumes the
- * pre-computed `poolTokens` (already post-outputHeadroom — the Fix-3 pre-flight at
+ * pre-computed `poolTokens` (already post-outputHeadroom — the pre-flight at
  * `lcd-preflight.ts` validated it) and NEVER over-allocates then reclaims. The
  * DISCRETIONARY allocation (non-floor) is bounded `≤ poolTokens` (`poolTokensUsed`);
- * the unconditional floors ride on top (they are a security/A1 guarantee, not a budget
- * line). Step-atomic fill reuses the {@link BudgetItem} token authority — it never splits
- * a `tool_use`/`tool_result` pair (history is kept whole-step, recency-ordered within its
- * slot BY DEFAULT; the within-history relevance eviction of the middle band — DEPTH-01's
- * now-live `rankMiddleBandByRelevance` — is supplied as the optional injected
+ * the unconditional floors ride on top (they are a security/fresh-tail guarantee, not a
+ * budget line). Step-atomic fill reuses the {@link BudgetItem} token authority — it never
+ * splits a `tool_use`/`tool_result` pair (history is kept whole-step, recency-ordered
+ * within its slot BY DEFAULT; the within-history relevance eviction of the middle band —
+ * `rankMiddleBandByRelevance` — is supplied as the optional injected
  * {@link MarginArbitrateInput.middleBandRanker}, which keeps this allocator pure while
- * re-ranking the evictable middle band cache-safely — see the C2 boundary note below).
+ * re-ranking the evictable middle band cache-safely — see the boundary note below).
  *
  * Purity (and the architecture cuts): no I/O, no clock, no estimator, no globals; the
  * input arrays (and their items) are NEVER mutated; a new array is returned; same input →
  * same output. This module lives in `context-engine/` and obeys TWO cuts:
  *   - agent↛memory: it imports only `@comis/core` types + in-package context-engine
  *     modules — never `@comis/memory` (forbidden by `test/architecture` "agent → memory").
- *   - I2 (context-engine ↮ rag): the LCD engine and the recall/RAG layer share ZERO code
+ *   - context-engine ↮ rag: the LCD engine and the recall/RAG layer share ZERO code
  *     (`lcd-recall-boundary.test.ts`). So the shared relevance scorer (`rag/relevance-scorer.ts`)
  *     is NOT imported — it is INJECTED as the `scorer` dep (DI at the budget boundary), and
  *     the `FusionLane`/`RelevanceQuery` shapes are declared LOCALLY here as the minimal
@@ -70,28 +70,28 @@ function isMember(item, set) {
 }
 /**
  * Allocate the discretionary history pool across tiers by fused rank, with the T0
- * fresh-tail + S4-pinned floors unconditional. See the module doc for the full contract.
+ * fresh-tail + security-pinned floors unconditional. See the module doc for the full contract.
  *
  * @param input - the tiered candidates + floors + pool + scorer (see {@link MarginArbitrateInput}).
  * @returns the kept messages + per-tier counts + the discretionary tokens used.
  */
 export function marginArbitrate(input) {
     const { historyItems, ltmCandidates, kgCandidates, floors, poolTokens, scorer, query, ltmTokensPerCandidate = 0, kgTokensPerCandidate = 0, minTierSlots = DEFAULT_MIN_TIER_SLOTS, scorerOptions, 
-    // DEPTH-01: the middle-band fill — defaults to the pure recency allocator so
+    // The middle-band fill — defaults to the pure recency allocator so
     // every caller that does NOT inject a ranker (frontier/mid never reach here)
     // is byte-identical; the relevance-first seam injects rankMiddleBandByRelevance.
     middleBandRanker = evictHistoryUnderBudget, } = input;
     // -------------------------------------------------------------------------
-    // 1. Reserve the UNCONDITIONAL floors (T0 fresh-tail + S4 pins).
+    // 1. Reserve the UNCONDITIONAL floors (T0 fresh-tail + security pins).
     //
     // These survive regardless of the pool: a security-pinned / fresh-tail item is
-    // NEVER a relevance candidate and is kept even when it exceeds the pool (the Fix-3
+    // NEVER a relevance candidate and is kept even when it exceeds the pool (the
     // pre-flight already reserved room for it — mirrors lcd-preflight.ts:114-121). They
     // do NOT consume the DISCRETIONARY pool budget (poolTokensUsed), so the discretionary
     // fill below stays bounded ≤ poolTokens (no over-allocate-then-reclaim).
     // -------------------------------------------------------------------------
     const isMessageFloor = (it) => isMember(it, floors.freshTailItems) || isMember(it, floors.pinnedItems);
-    // WR-04 (Phase 173-05): expand floors to STEP granularity. A floor flagged on a single
+    // Expand floors to STEP granularity. A floor flagged on a single
     // message inside a step (e.g. a pinned assistant `tool_use` whose `toolResult` is NOT
     // separately pinned, or a pinned `toolResult` whose `tool_use` is not) would otherwise
     // leave the rest of that step in the relevance-evictable middle band, where the step
@@ -103,8 +103,8 @@ export function marginArbitrate(input) {
     const stepFloorIds = expandFloorsToStepIds(historyItems, isMessageFloor);
     const isFloor = (it) => stepFloorIds.has(it);
     // The non-floor history band (the relevance-evictable middle, T1/T2) — fed to the
-    // injected middleBandRanker. NB (C2 boundary): the WITHIN-history relevance eviction of
-    // this middle band is DEPTH-01's now-live `rankMiddleBandByRelevance`, supplied as the
+    // injected middleBandRanker. NB (allocator/ranker boundary): the WITHIN-history
+    // relevance eviction of this middle band is `rankMiddleBandByRelevance`, supplied as the
     // `middleBandRanker` dep (default = the recency `evictHistoryUnderBudget`). The arbiter
     // ALLOCATES the discretionary pool across tiers by fused rank with the floors guaranteed;
     // the ranker re-orders the history slot cache-safely (recency on a caching profile,
@@ -167,18 +167,18 @@ export function marginArbitrate(input) {
         }
     }
     // --- Tier: history middle band (T1/T2) — step-atomic fill via the injected ranker. ---
-    // DEPTH-01: call the injected `middleBandRanker` (default = the recency
+    // Call the injected `middleBandRanker` (default = the recency
     // `evictHistoryUnderBudget`; the relevance-first seam injects `rankMiddleBandByRelevance`)
-    // over the REMAINING pool. BOTH the default and the DEPTH-01 ranker keep the kept history
+    // over the REMAINING pool. BOTH the default and the relevance ranker keep the kept history
     // step-atomic (a tool_use/tool_result pair is never split) AND in chronological order.
     // History is the FINAL tier — it consumes whatever pool the LTM/KG tiers left, so
     // `remainingPool` is not decremented again after this (it is the last reader).
     const keptMiddle = middleBandRanker(middleBand, remainingPool);
-    // WR-04 (Phase 173-05): bill the kept middle band from ACTUAL set membership, not the
+    // Bill the kept middle band from ACTUAL set membership, not the
     // positional `sumKeptTokens(band, count)` shortcut. With STEP-atomic floors (above) the
-    // two now agree, but membership is the honest accounting (it sums the tokens of the exact
+    // two agree, but membership is the honest accounting (it sums the tokens of the exact
     // BudgetItems whose msg is in keptMiddle) and cannot drift if step boundaries ever shift —
-    // so `poolTokensUsed` always equals the true discretionary consumption (the RETR-02 claim).
+    // so `poolTokensUsed` always equals the true discretionary consumption (the arbiter's claim).
     const keptMiddleSetForTokens = new Set(keptMiddle);
     const keptMiddleTokens = middleBand.reduce((sum, it) => (keptMiddleSetForTokens.has(it.msg) ? sum + it.tokens : sum), 0);
     poolTokensUsed += keptMiddleTokens;
@@ -191,7 +191,7 @@ export function marginArbitrate(input) {
     const keptMiddleSet = new Set(keptMiddle);
     const kept = [];
     let historyKeptCount = 0;
-    // WR-03: accumulate the floor weight (the unconditional floor steps' tokens) so the
+    // Accumulate the floor weight (the unconditional floor steps' tokens) so the
     // event can report it alongside the discretionary poolTokensUsed. Floors are STEP-atomic
     // (stepFloorIds) and ride on top of the pool — never billed to poolTokensUsed.
     let floorTokensUsed = 0;
@@ -225,7 +225,7 @@ function roleOf(it) {
     return it.msg.role;
 }
 /**
- * WR-04 (Phase 173-05): expand a per-MESSAGE floor predicate to STEP granularity. Walks
+ * Expand a per-MESSAGE floor predicate to STEP granularity. Walks
  * `historyItems` into the SAME steps the eviction step grouper uses (a step starts at any
  * non-`toolResult` message and absorbs the immediately-following `toolResult`s — the
  * inseparable result tail of an assistant `tool_use`), and returns the identity set of EVERY

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

@@ -16,7 +16,7 @@
  * Hard cap: 100K chars (TOOL_RESULT_HARD_CAP_CHARS) -- truncated before offload.
  *
  * - Tool results exceeding inline threshold saved to disk
- * - Per-tool thresholds applied (8K/5K/15K)
+ * - Per-tool thresholds applied (8K/15K/15K)
  * - Hard cap (100K) truncation applied before disk offload
  * - Inline reference contains disk path for read tool recovery
  *
@@ -47,7 +47,7 @@ export declare function getInlineThreshold(toolName: string): number;
  * @param dataDir - Confinement base for fs-safe substrate writes
  *   (typically `~/.comis/`). Threaded as `confinedBaseDir` on every
  *   `ensureContainedDir` + `writeRegularFile` call so the ancestor-
- *   symlink escape is rejected — closes the §1.4 confused-deputy gap
+ *   symlink escape is rejected — closes the confused-deputy gap
  *   that O_NOFOLLOW + parent-`lstat` together do NOT cover.
  * @param logger - Logger for WARN/DEBUG-level offload events
  */

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

@@ -17,7 +17,7 @@
  * Hard cap: 100K chars (TOOL_RESULT_HARD_CAP_CHARS) -- truncated before offload.
  *
  * - Tool results exceeding inline threshold saved to disk
- * - Per-tool thresholds applied (8K/5K/15K)
+ * - Per-tool thresholds applied (8K/15K/15K)
  * - Hard cap (100K) truncation applied before disk offload
  * - Inline reference contains disk path for read tool recovery
  *
@@ -53,8 +53,8 @@ export function getInlineThreshold(toolName) {
  * Save tool result content to disk as raw concatenated text.
  *
  * Agents read offloaded files expecting raw content matching the head/tail
- * previews shown in the inline reference. Writing a JSON envelope caused
- * parse failures when agents assumed raw text on disk.
+ * previews shown in the inline reference. Writing a JSON envelope would cause
+ * parse failures for agents that assume raw text on disk.
  *
  * Uses synchronous file I/O because `appendMessage()` is synchronous.
  * Path construction uses `safePath()` to prevent traversal attacks.
@@ -64,7 +64,7 @@ export function getInlineThreshold(toolName) {
  *   `written` is `false` when the parent-dir or file write was rejected
  *   (e.g. confinement-base escape), so the caller can suppress the
  *   `tool:result_offloaded` trajectory emit instead of recording a phantom
- *   pointer at a file that does not exist (WR-151-04).
+ *   pointer at a file that does not exist.
  */
 function saveToDisk(sessionDir, dataDir, toolCallId, _toolName, _originalChars, content) {
     const diskPath = safePath(sessionDir, "tool-results", `${toolCallId}.json`);
@@ -166,7 +166,7 @@ function createInlineReference(original, totalChars, diskPath) {
  * @param dataDir - Confinement base for fs-safe substrate writes
  *   (typically `~/.comis/`). Threaded as `confinedBaseDir` on every
  *   `ensureContainedDir` + `writeRegularFile` call so the ancestor-
- *   symlink escape is rejected — closes the §1.4 confused-deputy gap
+ *   symlink escape is rejected — closes the confused-deputy gap
  *   that O_NOFOLLOW + parent-`lstat` together do NOT cover.
  * @param logger - Logger for WARN/DEBUG-level offload events
  */
@@ -262,15 +262,15 @@ export function installMicrocompactionGuard(sm, sessionDir, dataDir, logger, onO
             const truncatedMsg = { ...toolResultMsg, content: truncatedContent };
             const reference = createInlineReference(truncatedMsg, totalChars, diskPath);
             // Pass only a WORKSPACE-RELATIVE pointer (sessionDir-relative) — the
-            // absolute diskPath leaks the host filesystem layout (T-151-05) and is
+            // absolute diskPath leaks the host filesystem layout and is
             // not a stable drill-down target. This guard holds no event bus and no
-            // clock (T-151-07): it computes the payload and hands it to onOffloaded;
+            // clock: it computes the payload and hands it to onOffloaded;
             // the executor callback (which has both) performs the trajectory emit.
             //
-            // Only emit when the disk write actually persisted (WR-151-04): a
+            // Only emit when the disk write actually persisted: a
             // best-effort write failure (confinement-base escape, fs error) returns
             // `written: false` and the file does not exist, so emitting
-            // tool:result_offloaded would record a phantom pointer the Phase 153
+            // tool:result_offloaded would record a phantom pointer the
             // IncidentReport.offloads[] drill-down cannot open. Log+suppress instead.
             if (written) {
                 const diskPathRel = relative(sessionDir, diskPath); // "tool-results/<toolCallId>.json"
@@ -285,7 +285,7 @@ export function installMicrocompactionGuard(sm, sessionDir, dataDir, logger, onO
                     errorKind: "resource",
                 }, "Tool result offload write failed -- suppressing offload event");
             }
-            // PIPELINE-FIX: Propagate compact reference to in-memory message object.
+            // Propagate the compact reference to the in-memory message object.
             // Without this, currentContext.messages in the agent loop still holds the
             // raw oversized content, causing the bouncer to re-truncate on the next
             // LLM call. By mutating the original content array, both
@@ -311,7 +311,7 @@ export function installMicrocompactionGuard(sm, sessionDir, dataDir, logger, onO
             }, "Tool result offloaded to disk");
             // Same residency-safe pointer at the threshold branch — its own diskPath
             // is in scope (returned by the saveToDisk above). Workspace-relative only.
-            // Suppress the offload event on a failed write (WR-151-04) so the
+            // Suppress the offload event on a failed write so the
             // trajectory never records a pointer at a file that was not persisted.
             if (written) {
                 const diskPathRel = relative(sessionDir, diskPath); // "tool-results/<toolCallId>.json"
@@ -326,7 +326,7 @@ export function installMicrocompactionGuard(sm, sessionDir, dataDir, logger, onO
                     errorKind: "resource",
                 }, "Tool result offload write failed -- suppressing offload event");
             }
-            // PIPELINE-FIX: Propagate compact reference to in-memory message object.
+            // Propagate the compact reference to the in-memory message object.
             // Without this, currentContext.messages in the agent loop still holds the
             // raw oversized content, causing the bouncer to re-truncate on the next
             // LLM call. By mutating the original content array, both