comisai 1.0.44 → 1.0.46

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

@@ -19,19 +19,19 @@ export type { TokenAnchor };
  * - O = outputReserveTokens (reserved for model output)
  * - M = safetyMarginTokens (percentage-based with absolute floor)
  * - R = contextRotBufferTokens (percentage-based decay buffer)
- * - P = freshTailPreambleTokens (the WHOLE fresh-tail preamble estimate; I1/WR-01)
+ * - P = freshTailPreambleTokens (the WHOLE fresh-tail preamble estimate)
  * - H = availableHistoryTokens (remaining budget for conversation history)
  */
 /**
  * What clamped the effective window below the model's configured contextWindow.
  * "none" = no clamp (frontier/mid, explicit 0 = uncapped, or the configured
- * window already fits). Closed union — but the member names are NO LONGER all
- * `contextEngine.budget.*` knob names (KNOB-02 ended that invariant):
+ * window already fits). Closed union — but the member names are NOT all
+ * `contextEngine.budget.*` knob names:
  * `effectiveContextCapSmall` / `effectiveContextCapNano` ARE knob names (the
  * budget's OWN cap bit — raising that config key genuinely works), while
  * `"served"` means the Ollama-served window bound (its knobs live in Ollama:
  * the `OLLAMA_CONTEXT_LENGTH` env on `ollama serve`, or a Modelfile
- * `PARAMETER num_ctx`) and `"capabilityClass"` (WR-01) means the EXECUTOR-side
+ * `PARAMETER num_ctx`) and `"capabilityClass"` means the EXECUTOR-side
  * `DEFAULT_EFFECTIVE_CAP_BY_CLASS` cap bound upstream because the operator
  * pinned `providers.entries.<id>.capabilities.capabilityClass` — that pin is
  * the only working lever; the budget knob is inert on this branch. Consumers
@@ -43,8 +43,8 @@ export type { TokenAnchor };
 export type WindowCapSource = "effectiveContextCapSmall" | "effectiveContextCapNano" | "served" | "capabilityClass" | "none";
 /**
  * Window provenance threaded from the executor's resolveEffectiveContextWindow
- * reconcile (pi-executor) into computeTokenBudgetForProfile (KNOB-02). Absent ⇒
- * byte-identical pre-provenance behavior (I3 frontier/mid pin). reconcileSource
+ * reconcile (pi-executor) into computeTokenBudgetForProfile. Absent ⇒ the
+ * budget reports the profile window as raw with no cap provenance. reconcileSource
  * reuses the EffectiveContextWindowResult.source vocabulary.
  */
 export interface WindowProvenance {
@@ -58,10 +58,10 @@ export interface WindowProvenance {
     reconcileSource: "configured" | "served" | "capability";
 }
 /**
- * Capped-window provenance carried into the exhaustion throw / WARN / events
- * (W1 obs-llm-troubleshooting). A strict subset of TokenBudget so call sites
+ * Capped-window provenance carried into the exhaustion throw / WARN / events.
+ * A strict subset of TokenBudget so call sites
  * can pass the budget's own fields without re-deriving anything.
- * servedWindowTokens (KNOB-02) lets the double-cap message name the whole
+ * servedWindowTokens lets the double-cap message name the whole
  * chain (configured → served → class cap).
  */
 export type ContextWindowCapInfo = Pick<TokenBudget, "rawContextWindowTokens" | "windowCapSource" | "servedWindowTokens">;
@@ -71,13 +71,13 @@ export interface TokenBudget {
     /** The model's DECLARED contextWindow before any capability-class cap was
      *  applied (== windowTokens when no cap bit). Lets the exhaustion error and
      *  budget logs name the clamp instead of reporting a window the operator
-     *  never configured (W1 obs-llm-troubleshooting). */
+     *  never configured. */
     rawContextWindowTokens: number;
     /** Which knob clamped windowTokens below rawContextWindowTokens ("none" when
      *  uncapped). See WindowCapSource. */
     windowCapSource: WindowCapSource;
-    /** Ollama-served num_ctx when served-window provenance was threaded
-     *  (KNOB-02); absent otherwise. */
+    /** Ollama-served num_ctx when served-window provenance was threaded;
+     *  absent otherwise. */
     servedWindowTokens?: number;
     /** S: estimated tokens consumed by system prompt and tool definitions. */
     systemTokens: number;
@@ -87,7 +87,7 @@ export interface TokenBudget {
     safetyMarginTokens: number;
     /** R: context rot buffer tokens (percentage-based). */
     contextRotBufferTokens: number;
-    /** P: fresh-tail preamble tokens subtracted from H (I1 / WR-01) — the WHOLE
+    /** P: fresh-tail preamble tokens subtracted from H — the WHOLE
      *  `dynamicPreamble` + `inlineMemory` block prepended into the latest user
      *  message by envelope-wrapper (skills XML, MCP instructions, deferred-tools
      *  context, date/channel lines, recalled memory, …), NOT just recalled memory.
@@ -184,15 +184,15 @@ export interface ContextEngineDeps {
     eventBus?: {
         emit(event: string, data: unknown): void;
     };
-    /** Agent ID for event attribution and structured logging. Also the R4 read
-     *  scope (132-03): the dag assembler builds a ContextStoreScope from it so LCD
-     *  reads are agent-isolated (WR-02). */
+    /** Agent ID for event attribution and structured logging. Also the LCD read
+     *  scope: the dag assembler builds a ContextStoreScope from it so LCD
+     *  reads are agent-isolated. */
     agentId?: string;
     /** Formatted session key for event correlation and structured logging. */
     sessionKey?: string;
-    /** Tenant ID for the R4 LCD read scope (132-03). The dag assembler builds a
+    /** Tenant ID for the LCD read scope. The dag assembler builds a
      *  ContextStoreScope { conversationId, agentId, tenantId, sessionKey } from it
-     *  so reads filter by tenant + agent (WR-02). Threaded from
+     *  so reads filter by tenant + agent. Threaded from
      *  executor-context-engine-setup.ts (the same source executor-post-execution
      *  uses: deps.tenantId ?? sessionKey.tenantId). */
     tenantId?: string;
@@ -200,12 +200,12 @@ export interface ContextEngineDeps {
     objective?: string;
     /** Lazy getter for the estimated system prompt + tool definition tokens.
      *  Called on each pipeline run so the value can update after prompt assembly.
-     *  Returns 0 when not provided (backward-compatible). */
+     *  Returns 0 when not provided. */
     getSystemTokensEstimate?: () => number;
     /** Lazy getter for the WHOLE fresh-tail preamble token estimate (the
      *  `dynamicPreamble` + `inlineMemory` block prepended by envelope-wrapper —
      *  skills XML, MCP instructions, deferred-tools context, date/channel lines,
-     *  recalled memory, …, NOT just recall; see WR-01). Called on each run.
+     *  recalled memory, …, NOT just recall). Called on each run.
      *  Subtracted from H as a SEPARATE budget term (NOT folded into S — preserves
      *  the recall-dag-budget-partition invariant). Returns 0 when not provided. */
     getFreshTailPreambleTokensEstimate?: () => number;
@@ -251,71 +251,68 @@ export interface ContextEngineDeps {
      *  daemon threads its `ClockPort` here via setupContextEngine. Falls back to
      *  `Date.now()` only when absent (a unit context with no injected clock). */
     clock?: import("@comis/core").ClockPort;
-    /** C1 (Phase 152/165): the resolved ModelProfile for the current turn.
+    /** The resolved ModelProfile for the current turn.
      *  Used by the dag assembler to call computeTokenBudgetForProfile (profile-aware
-     *  budget with 8K-starvation fix and 256K-overfill cap for small/nano).
+     *  budget that prevents 8K starvation and caps 256K overfill for small/nano).
      *  Absent ⇒ lcd-assembler applies the fail-closed nano cap + emits a config WARN. */
     modelProfile?: import("../executor/model-profile.js").ModelProfile;
-    /** KNOB-02 (Phase 176): window provenance from the executor's
+    /** Window provenance from the executor's
      *  resolveEffectiveContextWindow reconcile, passed as the 7th argument to
      *  computeTokenBudgetForProfile so a served-bound budget reports the TRUE
      *  configured window and names "served" as the cap source.
-     *  Absent ⇒ budget reports profile.contextWindow as raw (pre-KNOB-02 behavior). */
+     *  Absent ⇒ budget reports profile.contextWindow as raw. */
     windowProvenance?: WindowProvenance;
-    /** Phase 166 T-S4: security-pin markers for the dag eviction filter.
+    /** Security-pin markers for the dag eviction filter.
      *  When provided, messages containing canaryToken/contentDelimiter/senderTrustPrefix
      *  are NEVER evicted from history, regardless of window pressure.
      *  Source: deps.canaryToken threaded from pi-executor at the setupContextEngine call site.
      *  isSecurityRelevantMessage is fail-closed: absent/empty content → pin. */
     securityPinMarkers?: import("./security-context-pinner.js").SecurityPinMarkers;
-    /** Phase 166: callback invoked by the pre-flight fit check when assembled input tokens
-     *  are measured. Plan 04 sets a getter here so config-resolver can clamp max_tokens. */
+    /** Callback invoked by the pre-flight fit check when assembled input tokens
+     *  are measured. The executor wiring sets a getter here so config-resolver can clamp max_tokens. */
     onAssembledInputTokens?: (tokens: number) => void;
-    /** Phase 166: callback invoked when the effective window is known (budget.windowTokens).
-     *  Plan 04 sets this to populate effectiveWindowRef for dynamic max_tokens clamping.
+    /** Callback invoked when the effective window is known (budget.windowTokens).
+     *  The executor wiring sets this to populate effectiveWindowRef for dynamic max_tokens clamping.
      *  ONE callback per transformContext call — emit after budget is computed. */
     onEffectiveWindow?: (windowTokens: number) => void;
-    /** Phase 166: callback invoked when the thinking-effort governor down-shifts thinkingLevel.
-     *  Plan 04 sets this to call session.setThinkingLevel(level) for the current dispatch.
+    /** Callback invoked when the thinking-effort governor down-shifts thinkingLevel.
+     *  The executor wiring sets this to call session.setThinkingLevel(level) for the current dispatch.
      *  Wired at the pi-executor.ts setupContextEngine call site where the SDK session object
      *  is in scope (setupStreamWrappers only receives sm: SessionManager, not the SDK session). */
     onThinkingDownshifted?: (level: string) => void;
-    /** Phase 166: getter returning the current thinking level for this dispatch.
+    /** Getter returning the current thinking level for this dispatch.
      *  Source: the agent config's thinkingLevel field, read at call time.
      *  When absent, the pre-flight check falls back to "medium" (conservative). */
     getThinkingLevel?: () => string | undefined;
-    /** WR-02 (Phase 166): operator-configurable minimum visible output token floor.
+    /** Operator-configurable minimum visible output token floor.
      *  Sourced from contextEngine.budget.minVisibleOutputTokens in the agent config.
      *  When absent, the pre-flight check uses the compile-time constant MIN_VISIBLE_OUTPUT_TOKENS (768).
      *  This makes the schema field live rather than dead config. Frontier/mid: default 768
      *  → byte-identical result (MIN_VISIBLE_OUTPUT_TOKENS=768). */
     minVisibleOutputTokens?: number;
-    /** RETR-02/03 (Phase 173): the resolved relevance-first policy signal for this turn.
+    /** The resolved relevance-first policy signal for this turn.
      *  Resolved ONCE in scaffold-defaults (the capability + supportsPromptCache gate;
      *  explicit > capability-default > off) and threaded from setupContextEngine — the
      *  assembler CONSUMES the boolean, it does NOT recompute the gate. When `true` (small/
      *  nano non-caching, or an explicit opt-in) the dag assembler runs the margin arbiter
      *  (marginArbitrate) at the evict seam instead of evictHistoryUnderBudget; when `false`
      *  or ABSENT (frontier/mid + caching) the existing recency-first eviction runs VERBATIM
-     *  — frontier/mid byte-identical (LOCKED #2: the arbiter does not run for them). */
+     *  — frontier/mid byte-identical (deliberate: the arbiter never runs for them). */
     relevanceFirst?: boolean;
-    /** RETR-02 (Phase 173): the shared relevance scorer (scoreRelevance) injected for the
+    /** The shared relevance scorer (scoreRelevance) injected for the
      *  margin arbiter's FUSED-RANK cross-tier allocation. INJECTED from setupContextEngine
-     *  (executor/, which may import the rag layer) so the context-engine never imports `rag/`
-     *  (the I2 cut). On the C2 assembly path the LTM/KG candidate lanes are EMPTY, so the
+     *  (executor/, which may import the rag layer) so the context-engine never imports `rag/`.
+     *  On the dag assembly path the LTM/KG candidate lanes are EMPTY, so the
      *  scorer is never actually invoked (the history band is recency-ordered within its slot);
-     *  it is threaded for forward-compat (Phase 174 flows LTM candidates to assembly). Absent
+     *  it is threaded for forward-compat (flowing LTM candidates to assembly). Absent
      *  ⇒ the arbiter uses a no-op identity scorer (safe — never called with empty lanes). */
     relevanceScorer?: import("./margin-arbiter.js").RelevanceScorerFn;
 }
 /**
  * Metrics collected during a single context engine pipeline run.
  *
- * Extended in later phases as layers are added:
- * - microcompaction metrics
- * - observation masking metrics
- * - cache optimization metrics
- * - full observability dashboard
+ * Covers the pipeline layers end-to-end: thinking-block cleaning, observation
+ * masking, compaction, eviction, cache activity, and per-layer timing.
  */
 export interface ContextEngineMetrics {
     /** Number of thinking blocks removed by the thinking cleaner. */
@@ -361,8 +358,9 @@ export interface ContextEngineMetrics {
 /**
  * Per-session cache hit rate accumulator.
  *
- * Runtime accumulation deferred -- event infrastructure (observability:token_usage)
- * now carries cacheReadTokens/cacheWriteTokens for downstream consumers to aggregate.
+ * Runtime accumulation is intentionally not performed here -- the event
+ * infrastructure (observability:token_usage) carries cacheReadTokens/cacheWriteTokens
+ * for downstream consumers to aggregate.
  */
 export interface CacheSessionStats {
     totalCalls: number;
@@ -376,9 +374,6 @@ export interface CacheSessionStats {
  * Complete output of the context engine pipeline.
  *
  * Contains the transformed messages, computed budget, and collected metrics.
- * Extended in later phases:
- * - adds cache key and hit/miss stats
- * - adds per-layer timing breakdown
  */
 export interface AssembledContext {
     /** Transformed messages after all layers have been applied. */
@@ -436,7 +431,7 @@ export interface CacheOptimizationMetrics {
  * Observation masker metrics from a single pipeline run.
  *
  * Populated by `createObservationMaskerLayer()` after each `apply()` call.
- * Used for observability ( dashboard) and integration testing.
+ * Used for observability and integration testing.
  */
 export interface ObservationMasker {
     /** Number of tool results masked in the last pipeline run. */

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

@@ -1,25 +1,25 @@
 /**
- * FLOOR-01 (Phase 176): boot-time minViable viable-floor check.
+ * Boot-time minViable viable-floor check.
  *
  * Computes
  *   minViable = bootstrapTotalTokens + toolSchemaTokens + outputHeadroomFloor
  *             + freshTailReserve + safetyMargin
  * per agent at boot and emits ONE WARN when the effective context window cannot
  * fit even the scaffold floor — so an infeasible window surfaces at boot instead
- * of on the first real message (the CWF-02 preflight runs only at turn time).
+ * of on the first real message (the pre-flight fit check runs only at turn time).
  *
- * I8 single-sourcing: every term imports its turn-time home module — never a
+ * Single-sourcing: every term imports its turn-time home module — never a
  * parallel formula. {@link VIABLE_FLOOR_SHARED_SOURCES} is the drift-pin
  * surface: viable-floor.test.ts asserts FUNCTION-REFERENCE IDENTITY against
- * each home module, so a re-derived local copy cannot pass (Pitfall 8).
- * WR-03 extends I8 from the formula to its INPUT: the toolSchemaTokens term
+ * each home module, so a re-derived local copy cannot pass.
+ * The same single-sourcing extends from the formula to its INPUT: the toolSchemaTokens term
  * measures the same CONVERTED ToolDefinition corpus the turn-time S estimate
  * measures (lean descriptions + guidelines) via
  * {@link AgentBootWindowInfo.convertTools} — the daemon binds the executor's
  * own convertTools closure, so formula AND corpus are shared.
  *
- * WARN-only (I1/D-02 adapt-down moat): this module never throws on the
- * infeasible branch and never refuses boot. The daemon wiring (plan 176-05)
+ * WARN-only (adapt down, never refuse): this module never throws on the
+ * infeasible branch and never refuses boot. The daemon wiring
  * wraps the per-agent evaluation in a fail-open try/catch and threads
  * {@link collectAgentBootWindowInfo} beside the per-agent registry.
  *
@@ -33,7 +33,7 @@ import { resolveModelProfile } from "../executor/model-profile.js";
 import type { ModelProfile, CapabilityClass } from "../executor/model-profile.js";
 import { resolveScaffoldDefaults } from "../executor/scaffold-defaults.js";
 /**
- * Drift-pin surface (I8/R-3): the floor's term functions ARE these imports.
+ * Drift-pin surface: the floor's term functions ARE these imports.
  * viable-floor.test.ts asserts reference identity against each home module —
  * a re-derived local copy cannot pass.
  */
@@ -64,21 +64,21 @@ export interface AgentBootWindowInfo {
     windowSource: "served" | "capability" | "configured";
     /** Profile resolved on the RECONCILED window, exactly like pi-executor.ts:363-368. */
     modelProfile: ModelProfile;
-    /** bootstrapTotalMaxChars ?? bootstrapMaxChars from resolveScaffoldDefaults (A2). */
+    /** bootstrapTotalMaxChars ?? bootstrapMaxChars from resolveScaffoldDefaults. */
     scaffoldBootstrapChars: number;
-    /** E1: the class's active-tool ceiling from resolveScaffoldDefaults (small→24, nano/mid/frontier→
+    /** The class's active-tool ceiling from resolveScaffoldDefaults (small→24, nano/mid/frontier→
      *  undefined). Makes the floor's toolSchemaTokens term deferral-aware (see computeMinViableEquation). */
     activeToolCeiling?: number;
     /** contextEngine.budget.minVisibleOutputTokens when configured. */
     minVisibleOutputTokens?: number;
-    /** WR-03 (176 review): convert the raw boot toolset to the SAME
+    /** Convert the raw boot toolset to the SAME
      *  ToolDefinition corpus the turn-time S estimate measures (lean-description
      *  swap + promptGuidelines append — tool-definition-adapter.ts). The daemon
      *  wiring binds the EXACT closure PiExecutorDeps.convertTools receives, so
      *  the boot toolSchemaTokens term and the turn-time S term measure ONE
-     *  corpus by construction (I8 extended from the formula to its input —
-     *  pre-fix the boot term ran the shared reduce over RAW descriptions, which
-     *  are typically much longer than lean ones, systematically over-counting).
+     *  corpus by construction (single-sourcing extended from the formula to its
+     *  input — running the shared reduce over RAW descriptions, which are
+     *  typically much longer than lean ones, would systematically over-count).
      *  Absent ⇒ the floor measures the raw toolset (conservative over-count;
      *  production wiring always binds it). */
     convertTools?: (tools: ReadonlyArray<ToolOverheadInput>) => ReadonlyArray<ToolOverheadInput>;
@@ -92,7 +92,7 @@ export interface AgentBootWindowInfo {
  *
  * Mirroring the executor by construction (same resolver imports, same `?? 8_192`
  * fallback, same normalize step) means the boot floor and the first real turn
- * cannot disagree about the window (Pitfall 5).
+ * cannot disagree about the window.
  */
 export declare function collectAgentBootWindowInfo(params: {
     agentId: string;
@@ -113,7 +113,7 @@ export declare function collectAgentBootWindowInfo(params: {
     explicitCapabilityClass: string | undefined;
     /** PerAgentConfig — scaffold + budget knobs (read defensively). */
     agentConfig: Parameters<typeof resolveScaffoldDefaults>[1];
-    /** WR-03: the executor's convertTools closure — see AgentBootWindowInfo.convertTools. */
+    /** The executor's convertTools closure — see AgentBootWindowInfo.convertTools. */
     convertTools?: (tools: ReadonlyArray<ToolOverheadInput>) => ReadonlyArray<ToolOverheadInput>;
 }): AgentBootWindowInfo;
 /** The five named terms, their sum, and the largest term's name. */
@@ -131,7 +131,7 @@ export interface MinViableEquation {
 /**
  * Compute the boot minViable equation. Pure — no I/O, no logging.
  *
- * Every term is single-sourced from its turn-time home (I8):
+ * Every term is single-sourced from its turn-time home:
  *   - bootstrapTotalTokens: scaffold chars ÷ CHARS_PER_TOKEN_RATIO (constants.ts)
  *   - toolSchemaTokens: toolDefOverheadChars (tool-overhead.ts — the same function
  *     the turn-time S estimate uses) ÷ CHARS_PER_TOKEN_RATIO
@@ -150,7 +150,7 @@ export declare function computeMinViableEquation(params: {
     capabilityClass: string;
     effectiveWindow: number;
     minVisibleOutputTokens?: number;
-    /** E1 (obs-sweep): the class's active-tool ceiling (scaffold-defaults). When finite and the
+    /** The class's active-tool ceiling (scaffold-defaults). When finite and the
      *  toolset exceeds it, the floor measures only the deferred (active) corpus — see below. */
     activeToolCeiling?: number;
 }): MinViableEquation;
@@ -158,12 +158,12 @@ export declare function computeMinViableEquation(params: {
  * Evaluate the viable floor for one agent and WARN once when the effective
  * window is below minViable.
  *
- * Healthy (effectiveWindow >= minViable) → returns undefined, emits NOTHING
- * (R-4). Infeasible → ONE structured WARN (I7: every term named with its value,
+ * Healthy (effectiveWindow >= minViable) → returns undefined, emits NOTHING.
+ * Infeasible → ONE structured WARN (every term named with its value,
  * the binding window source, the per-source knob sentence, and — when tool
  * schemas dominate — the active-tool-ceiling lever) and returns the equation.
  *
- * Never throws on the emit path (I1/D-02): errorKind "config" (A5) — the
+ * Never throws on the emit path: errorKind "config" — the
  * window/scaffold mismatch is configuration, not a runtime resource failure.
  */
 export declare function evaluateViableFloorForAgent(params: {

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

@@ -1,26 +1,26 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * FLOOR-01 (Phase 176): boot-time minViable viable-floor check.
+ * Boot-time minViable viable-floor check.
  *
  * Computes
  *   minViable = bootstrapTotalTokens + toolSchemaTokens + outputHeadroomFloor
  *             + freshTailReserve + safetyMargin
  * per agent at boot and emits ONE WARN when the effective context window cannot
  * fit even the scaffold floor — so an infeasible window surfaces at boot instead
- * of on the first real message (the CWF-02 preflight runs only at turn time).
+ * of on the first real message (the pre-flight fit check runs only at turn time).
  *
- * I8 single-sourcing: every term imports its turn-time home module — never a
+ * Single-sourcing: every term imports its turn-time home module — never a
  * parallel formula. {@link VIABLE_FLOOR_SHARED_SOURCES} is the drift-pin
  * surface: viable-floor.test.ts asserts FUNCTION-REFERENCE IDENTITY against
- * each home module, so a re-derived local copy cannot pass (Pitfall 8).
- * WR-03 extends I8 from the formula to its INPUT: the toolSchemaTokens term
+ * each home module, so a re-derived local copy cannot pass.
+ * The same single-sourcing extends from the formula to its INPUT: the toolSchemaTokens term
  * measures the same CONVERTED ToolDefinition corpus the turn-time S estimate
  * measures (lean descriptions + guidelines) via
  * {@link AgentBootWindowInfo.convertTools} — the daemon binds the executor's
  * own convertTools closure, so formula AND corpus are shared.
  *
- * WARN-only (I1/D-02 adapt-down moat): this module never throws on the
- * infeasible branch and never refuses boot. The daemon wiring (plan 176-05)
+ * WARN-only (adapt down, never refuse): this module never throws on the
+ * infeasible branch and never refuses boot. The daemon wiring
  * wraps the per-agent evaluation in a fail-open try/catch and threads
  * {@link collectAgentBootWindowInfo} beside the per-agent registry.
  *
@@ -36,10 +36,10 @@ import { DEFAULT_EFFECTIVE_CAP_BY_CLASS } from "./budget-capacity-cap.js";
 import { PREAMBLE_WARN_THRESHOLD_BY_CLASS } from "../executor/executor-tool-assembly.js";
 import { normalizeModelId } from "../provider/model-id-normalize.js";
 // ---------------------------------------------------------------------------
-// I8 drift-pin surface
+// Drift-pin surface
 // ---------------------------------------------------------------------------
 /**
- * Drift-pin surface (I8/R-3): the floor's term functions ARE these imports.
+ * Drift-pin surface: the floor's term functions ARE these imports.
  * viable-floor.test.ts asserts reference identity against each home module —
  * a re-derived local copy cannot pass.
  */
@@ -63,7 +63,7 @@ export const VIABLE_FLOOR_SHARED_SOURCES = {
  *
  * Mirroring the executor by construction (same resolver imports, same `?? 8_192`
  * fallback, same normalize step) means the boot floor and the first real turn
- * cannot disagree about the window (Pitfall 5).
+ * cannot disagree about the window.
  */
 export function collectAgentBootWindowInfo(params) {
     const normalizedId = normalizeModelId(params.providerId, params.modelId).modelId;
@@ -80,7 +80,7 @@ export function collectAgentBootWindowInfo(params) {
     });
     const modelProfile = resolveModelProfile(resolved ? { ...resolved, contextWindow: effectiveWindow } : undefined, explicitClass);
     const scaffold = resolveScaffoldDefaults(modelProfile, params.agentConfig);
-    // A2: small/nano → bootstrapTotalMaxChars (5_000); frontier/mid → undefined,
+    // small/nano → bootstrapTotalMaxChars (5_000); frontier/mid → undefined,
     // fall back to bootstrapMaxChars (always a number — the 20_000 sentinel).
     const scaffoldBootstrapChars = scaffold.bootstrapTotalMaxChars ?? scaffold.bootstrapMaxChars;
     const minVisibleOutputTokens = params.agentConfig.contextEngine?.budget?.minVisibleOutputTokens;
@@ -102,7 +102,7 @@ export function collectAgentBootWindowInfo(params) {
 /**
  * Compute the boot minViable equation. Pure — no I/O, no logging.
  *
- * Every term is single-sourced from its turn-time home (I8):
+ * Every term is single-sourced from its turn-time home:
  *   - bootstrapTotalTokens: scaffold chars ÷ CHARS_PER_TOKEN_RATIO (constants.ts)
  *   - toolSchemaTokens: toolDefOverheadChars (tool-overhead.ts — the same function
  *     the turn-time S estimate uses) ÷ CHARS_PER_TOKEN_RATIO
@@ -115,18 +115,18 @@ export function collectAgentBootWindowInfo(params) {
  *     MIN_SAFETY_MARGIN_TOKENS) against the boot effectiveWindow
  */
 export function computeMinViableEquation(params) {
-    // flat-by-design: boot viable-floor over machine bootstrap/tool-schema chars (Latin by construction) (TOK-01)
+    // flat-by-design: boot viable-floor over machine bootstrap/tool-schema chars (Latin by construction)
     const bootstrapTotalTokens = Math.ceil(params.scaffoldBootstrapChars / CHARS_PER_TOKEN_RATIO);
-    // E1 (obs-sweep package-delivery-20260628): DEFERRAL-AWARE tool-schema floor. At turn time
+    // DEFERRAL-AWARE tool-schema floor. At turn time
     // applyToolDeferral (tool-deferral.ts) defers by COUNT against `activeToolCeiling`, shipping only
     // ~ceiling active tools + a wire-stripped discover_tools stub (toolDefOverheadChars already skips
-    // the stubs). The boot floor was fed the RAW full toolset, so it counted the FULL pre-deferral
-    // corpus (~26K tokens) and false-WARNed a small-class agent that runs fine via discover_tools.
+    // the stubs). Fed the RAW full toolset, the boot floor would count the FULL pre-deferral
+    // corpus (~26K tokens) and false-WARN a small-class agent that runs fine via discover_tools.
     // Mirror the deferral: when a finite ceiling is exceeded, count only the `ceiling` LARGEST tools by
     // individual overhead — a CONSERVATIVE upper bound on the active set (applyToolDeferral chooses by
     // COUNT, not size, so the real active corpus is ≤ this), so the floor tracks deferral without ever
     // under-warning a genuinely-infeasible window. Single-sources the ceiling from scaffold-defaults
-    // (the same knob the turn uses). flat-by-design (TOK-01).
+    // (the same knob the turn uses). flat-by-design.
     const ceiling = params.activeToolCeiling;
     const toolChars = ceiling !== undefined && Number.isFinite(ceiling) && params.tools.length > ceiling
         ? params.tools
@@ -135,7 +135,7 @@ export function computeMinViableEquation(params) {
             .slice(0, ceiling)
             .reduce((sum, n) => sum + n, 0)
         : toolDefOverheadChars(params.tools);
-    // flat-by-design: tool-schema overhead chars (machine-rendered JSON, Latin by construction) (TOK-01)
+    // flat-by-design: tool-schema overhead chars (machine-rendered JSON, Latin by construction)
     const toolSchemaTokens = Math.ceil(toolChars / CHARS_PER_TOKEN_RATIO);
     // Post-downshift minimum thinking level: native → "low", none → "off".
     // When minVisibleOutputTokens is not configured, call with TWO args so
@@ -145,10 +145,10 @@ export function computeMinViableEquation(params) {
     const outputHeadroomFloor = params.minVisibleOutputTokens === undefined
         ? computeOutputHeadroom(params.reasoningStyle, floorLevel)
         : computeOutputHeadroom(params.reasoningStyle, floorLevel, params.minVisibleOutputTokens);
-    // A1: the per-class preamble threshold doubles as the fresh-tail reserve.
+    // The per-class preamble threshold doubles as the fresh-tail reserve.
     // frontier's Infinity means "the preamble WARN never fires", NOT "infinite
     // preamble" — mapping Infinity → 0 keeps frontier's minViable finite and its
-    // boot WARN practically unreachable (R-4: healthy boots stay silent).
+    // boot WARN practically unreachable (healthy boots stay silent).
     const thresholdByClass = PREAMBLE_WARN_THRESHOLD_BY_CLASS;
     const threshold = thresholdByClass[params.capabilityClass] ?? 0;
     const freshTailReserve = Number.isFinite(threshold) ? threshold : 0;
@@ -184,17 +184,17 @@ export function computeMinViableEquation(params) {
  * Evaluate the viable floor for one agent and WARN once when the effective
  * window is below minViable.
  *
- * Healthy (effectiveWindow >= minViable) → returns undefined, emits NOTHING
- * (R-4). Infeasible → ONE structured WARN (I7: every term named with its value,
+ * Healthy (effectiveWindow >= minViable) → returns undefined, emits NOTHING.
+ * Infeasible → ONE structured WARN (every term named with its value,
  * the binding window source, the per-source knob sentence, and — when tool
  * schemas dominate — the active-tool-ceiling lever) and returns the equation.
  *
- * Never throws on the emit path (I1/D-02): errorKind "config" (A5) — the
+ * Never throws on the emit path: errorKind "config" — the
  * window/scaffold mismatch is configuration, not a runtime resource failure.
  */
 export function evaluateViableFloorForAgent(params) {
     const { info } = params;
-    // WR-03: measure the corpus the turn actually ships. The turn-time S term
+    // Measure the corpus the turn actually ships. The turn-time S term
     // runs the shared toolDefOverheadChars over the CONVERTED ToolDefinition[]
     // (lean descriptions + guidelines, via the executor's convertTools); the
     // daemon loop feeds this function the RAW AgentTool[], so without the same
@@ -208,16 +208,16 @@ export function evaluateViableFloorForAgent(params) {
         capabilityClass: info.modelProfile.capabilityClass,
         effectiveWindow: info.effectiveWindow,
         minVisibleOutputTokens: info.minVisibleOutputTokens,
-        // E1: deferral-aware — when the class pins a finite ceiling, the floor measures the deferred
-        // (active) corpus, not the full pre-deferral toolset (which false-WARNed small-class agents).
+        // Deferral-aware — when the class pins a finite ceiling, the floor measures the deferred
+        // (active) corpus, not the full pre-deferral toolset (which would false-WARN small-class agents).
         ...(info.activeToolCeiling !== undefined && { activeToolCeiling: info.activeToolCeiling }),
     });
     if (info.effectiveWindow >= eq.minViable) {
-        return undefined; // R-4: healthy boots stay silent.
+        return undefined; // Healthy boots stay silent.
     }
     // Per-source knob sentence — fixed-string templates + numbers + knob names
-    // only (I7/T-176-08: no schema bodies, no message content, no env values).
-    // IN-06 (WR-01 principle): the capability branch leads with the PIN — the
+    // only (no schema bodies, no message content, no env values).
+    // The capability branch leads with the PIN — the
     // boot resolver (like the executor reconcile) reads only
     // DEFAULT_EFFECTIVE_CAP_BY_CLASS[pinned class]; the contextEngine.budget.*
     // caps can only clamp FURTHER and cannot raise this bind, so they are a
@@ -229,7 +229,7 @@ export function evaluateViableFloorForAgent(params) {
             : `Raise the model's configured window: providers.entries.${info.providerId}.models[].contextWindow. `;
     const dominanceSentence = eq.dominantTerm === "toolSchemaTokens"
         ? info.activeToolCeiling !== undefined
-            ? // E1: the floor is already deferral-aware (measures the ${ceiling}-tool active corpus), so a
+            ? // The floor is already deferral-aware (measures the ${ceiling}-tool active corpus), so a
                 // WARN here means even the DEFERRED surface does not fit — "pin small" is already in effect.
                 `Tool schemas dominate the floor EVEN AFTER deferral to the ${info.activeToolCeiling}-tool active ceiling — the deferred active corpus still does not fit. Disable unused MCP servers / builtin tool groups, or raise the window.`
             : `Tool schemas dominate the floor — reduce the active tool surface: pin capabilityClass (small defers to a 24-tool active ceiling via discover_tools) or disable unused MCP servers / builtin tool groups.`

package/node_modules/@comis/agent/dist/executor/adaptive-cache-retention.d.ts

@@ -22,7 +22,7 @@ export interface AdaptiveCacheRetentionConfig {
     escalationThreshold: number;
     /** Called once when retention escalates from cold to warm. */
     onEscalated?: () => void;
-    /** Design 2.4: Minimum turns before escalation. Default: 3. */
+    /** Minimum turns before escalation. Default: 3. */
     escalationTurnThreshold?: number;
 }
 /** Threshold for consecutive baseline-only cache reads
@@ -44,7 +44,7 @@ export interface AdaptiveCacheRetention {
     /** Set cost gate state. When false, escalation requires
      *  escalationTurnThreshold + 2 turns. The fast-path is exempt. */
     setCostGateOpen(open: boolean): void;
-    /** Design 2.4: Record a completed turn for turn-count-based escalation. */
+    /** Record a completed turn for turn-count-based escalation. */
     recordTurn(): void;
     /** Record a completed turn with its cache write token count.
      *  Fast-path: if first turn wrote >FAST_PATH_CACHE_WRITE_THRESHOLD tokens,

package/node_modules/@comis/agent/dist/executor/adaptive-cache-retention.js

@@ -18,7 +18,7 @@ export const FAST_PATH_CACHE_WRITE_THRESHOLD = 20_000;
  *  baseline for this many turns, the prefix is unstable and 1h writes are wasted. */
 export const PREFIX_INSTABILITY_THRESHOLD = 5;
 export function createAdaptiveCacheRetention(config) {
-    const turnThreshold = config.escalationTurnThreshold ?? 3; // Design 2.4: require 3+ turns
+    const turnThreshold = config.escalationTurnThreshold ?? 3; // require 3+ turns before escalation
     let totalCacheReads = 0;
     let turnCount = 0;
     let lastCacheWriteTokens = 0;

package/node_modules/@comis/agent/dist/executor/cache-break-diff-writer.d.ts

@@ -42,13 +42,13 @@ export interface CacheBreakDiffPayload {
     agentId: string;
     sessionKey: string;
     timestamp: number;
-    /** DIFF-CONTENT: Serialized previous system prompt content (for diff generation). Capped at 50K chars. */
+    /** Serialized previous system prompt content (for diff generation). Capped at 50K chars. */
     previousSystem?: string;
-    /** DIFF-CONTENT: Serialized current system prompt content (for diff generation). Capped at 50K chars. */
+    /** Serialized current system prompt content (for diff generation). Capped at 50K chars. */
     currentSystem?: string;
-    /** DIFF-CONTENT: Serialized previous tools JSON (for diff generation). Capped at 50K chars. */
+    /** Serialized previous tools JSON (for diff generation). Capped at 50K chars. */
     previousTools?: string;
-    /** DIFF-CONTENT: Serialized current tools JSON (for diff generation). Capped at 50K chars. */
+    /** Serialized current tools JSON (for diff generation). Capped at 50K chars. */
     currentTools?: string;
     /** Effort value from detection pipeline for downstream analytics. */
     effortValue?: string;

package/node_modules/@comis/agent/dist/executor/cache-break-diff-writer.js

@@ -14,7 +14,7 @@ import { createPatch } from "diff";
 import { safePath, resolveModelPricing, ZERO_COST, systemDateFrom } from "@comis/core";
 import { ensureContainedDir, writeRegularFile } from "@comis/observability";
 const MAX_DIFF_FILES = 50;
-/** DIFF-CONTENT: Maximum chars per category (system, tools) for snapshot content before diffing. */
+/** Maximum chars per category (system, tools) for snapshot content before diffing. */
 const MAX_SNAPSHOT_CHARS = 50_000;
 /**
  * Build a combined diffable text snapshot from system prompt and tools content.
@@ -46,7 +46,8 @@ export function createCacheBreakDiffWriter(config) {
         try {
             if (!dirEnsured) {
                 // Route through the shared fs-safe substrate so
-                // `~/.comis/cache-breaks/` honors the §1.4 `0o700` invariant.
+                // `~/.comis/cache-breaks/` honors the owner-only `0o700`
+                // directory-mode invariant for artifacts under `~/.comis/`.
                 // Failure is non-fatal — log + skip this event so the detection
                 // flow upstream stays unaffected (existing fault-tolerance
                 // contract: I/O errors are never propagated).
@@ -107,7 +108,7 @@ export function createCacheBreakDiffWriter(config) {
                     metadataChanged: event.changes.metadataChanged,
                     headersChanged: event.changes.headersChanged,
                     extraBodyChanged: event.changes.extraBodyChanged,
-                    // New attribution fields (use ?? false for backward compat with older payloads)
+                    // Optional attribution fields default to false when absent from the payload
                     effortChanged: event.changes.effortChanged ?? false,
                     cacheControlChanged: event.changes.cacheControlChanged ?? false,
                 },
@@ -148,7 +149,7 @@ export function createCacheBreakDiffWriter(config) {
                 },
             };
             // Route the JSON write through the fs-safe substrate
-            // so each cache-break diff file lands at mode `0o600` per §1.4.
+            // so each cache-break diff file lands at owner-only mode `0o600`.
             // Failure is non-fatal — log + continue to attempt the .diff
             // sibling so a partial-write at the JSON layer does not block the
             // unified-diff artifact.
@@ -164,10 +165,10 @@ export function createCacheBreakDiffWriter(config) {
                     errorKind: "resource",
                 }, "Cache break diff JSON write failed");
             }
-            // DIFF-CONTENT: Generate unified diff file alongside JSON
+            // Generate unified diff file alongside JSON
             const diffSections = [];
             // Generate diffs for ANY break event that has serialized content available
-            // (not just system/tools changes). Effort, retention, header changes etc. now also
+            // (not just system/tools changes). Effort, retention, header changes etc. also
             // produce diffs when content was materialized by the lazy getter.
             const hasAnyContent = event.previousSystem !== undefined || event.currentSystem !== undefined ||
                 event.previousTools !== undefined || event.currentTools !== undefined;