comisai 1.0.42 → 1.0.44

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

@@ -0,0 +1,175 @@
+/**
+ * FLOOR-01 (Phase 176): 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).
+ *
+ * I8 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
+ * 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)
+ * wraps the per-agent evaluation in a fail-open try/catch and threads
+ * {@link collectAgentBootWindowInfo} beside the per-agent registry.
+ *
+ * @module
+ */
+import { toolDefOverheadChars } from "../executor/tool-overhead.js";
+import type { ToolOverheadInput } from "../executor/tool-overhead.js";
+import { computeOutputHeadroom } from "./output-headroom.js";
+import { resolveEffectiveContextWindow } from "../model/effective-context-window.js";
+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.
+ * viable-floor.test.ts asserts reference identity against each home module —
+ * a re-derived local copy cannot pass.
+ */
+export declare const VIABLE_FLOOR_SHARED_SOURCES: {
+    readonly toolDefOverheadChars: typeof toolDefOverheadChars;
+    readonly computeOutputHeadroom: typeof computeOutputHeadroom;
+    readonly resolveEffectiveContextWindow: typeof resolveEffectiveContextWindow;
+    readonly resolveScaffoldDefaults: typeof resolveScaffoldDefaults;
+    readonly resolveModelProfile: typeof resolveModelProfile;
+    readonly PREAMBLE_WARN_THRESHOLD_BY_CLASS: Readonly<Record<CapabilityClass, number>>;
+    readonly CHARS_PER_TOKEN_RATIO: 3.5;
+    readonly SAFETY_MARGIN_PERCENT: 5;
+    readonly MIN_SAFETY_MARGIN_TOKENS: 2048;
+};
+/** Per-agent boot window snapshot — the inputs the floor evaluation consumes. */
+export interface AgentBootWindowInfo {
+    agentId: string;
+    providerId: string;
+    /** The normalize-resolved model id (the id the registry find ran against). */
+    modelId: string;
+    /** Registry-enriched configured window (`find(...)?.contextWindow ?? 8_192`). */
+    configuredWindow: number;
+    /** Probe-served window — undefined when the probe did not run for this provider. */
+    served?: number;
+    /** min(configured, served?, capabilityCap) — same resolver as pi-executor. */
+    effectiveWindow: number;
+    /** Which constraint bound the effective window. */
+    windowSource: "served" | "capability" | "configured";
+    /** Profile resolved on the RECONCILED window, exactly like pi-executor.ts:363-368. */
+    modelProfile: ModelProfile;
+    /** bootstrapTotalMaxChars ?? bootstrapMaxChars from resolveScaffoldDefaults (A2). */
+    scaffoldBootstrapChars: number;
+    /** E1: 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
+     *  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).
+     *  Absent ⇒ the floor measures the raw toolset (conservative over-count;
+     *  production wiring always binds it). */
+    convertTools?: (tools: ReadonlyArray<ToolOverheadInput>) => ReadonlyArray<ToolOverheadInput>;
+}
+/**
+ * Resolve the boot-side window + profile snapshot for one agent — the boot
+ * mirror of the executor's turn-time resolution chain (pi-executor.ts:344-368):
+ * normalize → registry find → capability cap (ONLY when the operator pinned
+ * capabilityClass) → resolveEffectiveContextWindow → resolveModelProfile on the
+ * RECONCILED window → resolveScaffoldDefaults.
+ *
+ * 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).
+ */
+export declare function collectAgentBootWindowInfo(params: {
+    agentId: string;
+    providerId: string;
+    modelId: string;
+    /** The per-agent pi ModelRegistry find (registry-enriched contextWindow). */
+    findModel: (provider: string, modelId: string) => {
+        id: string;
+        provider: string;
+        contextWindow?: number;
+        maxTokens?: number;
+        reasoning?: boolean;
+        input?: readonly string[];
+    } | undefined;
+    /** servedWindowByProvider.get(providerId) — undefined when the probe did not run. */
+    served: number | undefined;
+    /** providers.entries.<id>.capabilities.capabilityClass — the operator pin. */
+    explicitCapabilityClass: string | undefined;
+    /** PerAgentConfig — scaffold + budget knobs (read defensively). */
+    agentConfig: Parameters<typeof resolveScaffoldDefaults>[1];
+    /** WR-03: 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. */
+export interface MinViableEquation {
+    terms: {
+        bootstrapTotalTokens: number;
+        toolSchemaTokens: number;
+        outputHeadroomFloor: number;
+        freshTailReserve: number;
+        safetyMargin: number;
+    };
+    minViable: number;
+    dominantTerm: keyof MinViableEquation["terms"];
+}
+/**
+ * Compute the boot minViable equation. Pure — no I/O, no logging.
+ *
+ * Every term is single-sourced from its turn-time home (I8):
+ *   - 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
+ *   - outputHeadroomFloor: computeOutputHeadroom (output-headroom.ts) at the
+ *     post-downshift MINIMUM level — the governor floors native reasoning at
+ *     "low" (downshiftThinkingLevel), so "low" is the honest floor; "none"
+ *     reserves the visible floor only. WARN only when even the floor cannot fit.
+ *   - freshTailReserve: PREAMBLE_WARN_THRESHOLD_BY_CLASS (executor-tool-assembly.ts)
+ *   - safetyMargin: the token-budget.ts M formula (SAFETY_MARGIN_PERCENT +
+ *     MIN_SAFETY_MARGIN_TOKENS) against the boot effectiveWindow
+ */
+export declare function computeMinViableEquation(params: {
+    tools: ReadonlyArray<ToolOverheadInput>;
+    scaffoldBootstrapChars: number;
+    reasoningStyle: "none" | "native";
+    capabilityClass: string;
+    effectiveWindow: number;
+    minVisibleOutputTokens?: number;
+    /** E1 (obs-sweep): 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;
+/**
+ * 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,
+ * 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
+ * window/scaffold mismatch is configuration, not a runtime resource failure.
+ */
+export declare function evaluateViableFloorForAgent(params: {
+    info: AgentBootWindowInfo;
+    tools: ReadonlyArray<ToolOverheadInput>;
+    logger: {
+        warn(obj: Record<string, unknown>, msg: string): void;
+    };
+}): MinViableEquation | undefined;

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

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * FLOOR-01 (Phase 176): 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).
+ *
+ * I8 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
+ * 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)
+ * wraps the per-agent evaluation in a fail-open try/catch and threads
+ * {@link collectAgentBootWindowInfo} beside the per-agent registry.
+ *
+ * @module
+ */
+import { toolDefOverheadChars } from "../executor/tool-overhead.js";
+import { computeOutputHeadroom } from "./output-headroom.js";
+import { CHARS_PER_TOKEN_RATIO, SAFETY_MARGIN_PERCENT, MIN_SAFETY_MARGIN_TOKENS, } from "./constants.js";
+import { resolveEffectiveContextWindow } from "../model/effective-context-window.js";
+import { resolveModelProfile } from "../executor/model-profile.js";
+import { resolveScaffoldDefaults } from "../executor/scaffold-defaults.js";
+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 (I8/R-3): 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.
+ */
+export const VIABLE_FLOOR_SHARED_SOURCES = {
+    toolDefOverheadChars,
+    computeOutputHeadroom,
+    resolveEffectiveContextWindow,
+    resolveScaffoldDefaults,
+    resolveModelProfile,
+    PREAMBLE_WARN_THRESHOLD_BY_CLASS,
+    CHARS_PER_TOKEN_RATIO,
+    SAFETY_MARGIN_PERCENT,
+    MIN_SAFETY_MARGIN_TOKENS,
+};
+/**
+ * Resolve the boot-side window + profile snapshot for one agent — the boot
+ * mirror of the executor's turn-time resolution chain (pi-executor.ts:344-368):
+ * normalize → registry find → capability cap (ONLY when the operator pinned
+ * capabilityClass) → resolveEffectiveContextWindow → resolveModelProfile on the
+ * RECONCILED window → resolveScaffoldDefaults.
+ *
+ * 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).
+ */
+export function collectAgentBootWindowInfo(params) {
+    const normalizedId = normalizeModelId(params.providerId, params.modelId).modelId;
+    const resolved = params.findModel(params.providerId, normalizedId);
+    const configured = resolved?.contextWindow ?? 8_192;
+    // Capability cap ONLY when the operator explicitly pinned a class — mirrors
+    // pi-executor.ts:344-347 (no pin → Infinity → no class constraint).
+    const explicitClass = params.explicitCapabilityClass;
+    const capabilityCap = explicitClass != null ? (DEFAULT_EFFECTIVE_CAP_BY_CLASS[explicitClass] ?? Infinity) : Infinity;
+    const { effectiveWindow, source } = resolveEffectiveContextWindow({
+        configured,
+        served: params.served,
+        capabilityCap,
+    });
+    const modelProfile = resolveModelProfile(resolved ? { ...resolved, contextWindow: effectiveWindow } : undefined, explicitClass);
+    const scaffold = resolveScaffoldDefaults(modelProfile, params.agentConfig);
+    // A2: 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;
+    return {
+        agentId: params.agentId,
+        providerId: params.providerId,
+        modelId: normalizedId,
+        configuredWindow: configured,
+        served: params.served,
+        effectiveWindow,
+        windowSource: source,
+        modelProfile,
+        scaffoldBootstrapChars,
+        ...(scaffold.activeToolCeiling !== undefined && { activeToolCeiling: scaffold.activeToolCeiling }),
+        minVisibleOutputTokens,
+        ...(params.convertTools !== undefined && { convertTools: params.convertTools }),
+    };
+}
+/**
+ * Compute the boot minViable equation. Pure — no I/O, no logging.
+ *
+ * Every term is single-sourced from its turn-time home (I8):
+ *   - 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
+ *   - outputHeadroomFloor: computeOutputHeadroom (output-headroom.ts) at the
+ *     post-downshift MINIMUM level — the governor floors native reasoning at
+ *     "low" (downshiftThinkingLevel), so "low" is the honest floor; "none"
+ *     reserves the visible floor only. WARN only when even the floor cannot fit.
+ *   - freshTailReserve: PREAMBLE_WARN_THRESHOLD_BY_CLASS (executor-tool-assembly.ts)
+ *   - safetyMargin: the token-budget.ts M formula (SAFETY_MARGIN_PERCENT +
+ *     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)
+    const bootstrapTotalTokens = Math.ceil(params.scaffoldBootstrapChars / CHARS_PER_TOKEN_RATIO);
+    // E1 (obs-sweep package-delivery-20260628): 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.
+    // 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).
+    const ceiling = params.activeToolCeiling;
+    const toolChars = ceiling !== undefined && Number.isFinite(ceiling) && params.tools.length > ceiling
+        ? params.tools
+            .map((t) => toolDefOverheadChars([t]))
+            .sort((a, b) => b - a)
+            .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)
+    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
+    // computeOutputHeadroom's own default (MIN_VISIBLE_OUTPUT_TOKENS) applies —
+    // single-source; do NOT re-import the default here.
+    const floorLevel = params.reasoningStyle === "native" ? "low" : "off";
+    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.
+    // 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).
+    const thresholdByClass = PREAMBLE_WARN_THRESHOLD_BY_CLASS;
+    const threshold = thresholdByClass[params.capabilityClass] ?? 0;
+    const freshTailReserve = Number.isFinite(threshold) ? threshold : 0;
+    // The token-budget.ts:84-87 M formula against the boot effectiveWindow.
+    const safetyMargin = Math.max(Math.ceil((params.effectiveWindow * SAFETY_MARGIN_PERCENT) / 100), MIN_SAFETY_MARGIN_TOKENS);
+    const terms = {
+        bootstrapTotalTokens,
+        toolSchemaTokens,
+        outputHeadroomFloor,
+        freshTailReserve,
+        safetyMargin,
+    };
+    const minViable = bootstrapTotalTokens + toolSchemaTokens + outputHeadroomFloor + freshTailReserve + safetyMargin;
+    // Dominant term: max value; FIRST wins on tie (fixed key order as listed).
+    const ordered = [
+        ["bootstrapTotalTokens", bootstrapTotalTokens],
+        ["toolSchemaTokens", toolSchemaTokens],
+        ["outputHeadroomFloor", outputHeadroomFloor],
+        ["freshTailReserve", freshTailReserve],
+        ["safetyMargin", safetyMargin],
+    ];
+    let dominant = ordered[0];
+    for (const entry of ordered) {
+        if (entry[1] > dominant[1])
+            dominant = entry;
+    }
+    return { terms, minViable, dominantTerm: dominant[0] };
+}
+// ---------------------------------------------------------------------------
+// WARN emitter
+// ---------------------------------------------------------------------------
+/**
+ * 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,
+ * 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
+ * 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
+    // 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
+    // conversion the boot term systematically over-counts (raw descriptions ≫
+    // lean) and the WARN false-positives on agents that genuinely fit.
+    const floorTools = info.convertTools ? info.convertTools(params.tools) : params.tools;
+    const eq = computeMinViableEquation({
+        tools: floorTools,
+        scaffoldBootstrapChars: info.scaffoldBootstrapChars,
+        reasoningStyle: info.modelProfile.reasoningStyle,
+        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).
+        ...(info.activeToolCeiling !== undefined && { activeToolCeiling: info.activeToolCeiling }),
+    });
+    if (info.effectiveWindow >= eq.minViable) {
+        return undefined; // R-4: 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
+    // 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
+    // dead lever here (named only as a does-not-move note).
+    const knobSentence = info.windowSource === "served"
+        ? `Raise the served window: OLLAMA_CONTEXT_LENGTH=${info.configuredWindow} ollama serve, or Modelfile 'PARAMETER num_ctx ${info.configuredWindow}'. `
+        : info.windowSource === "capability"
+            ? `Pin a higher class (or remove the pin) via providers.entries.${info.providerId}.capabilities.capabilityClass — the contextEngine.budget.* caps do not move this bind. `
+            : `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
+                // 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.`
+        : "";
+    params.logger.warn({
+        agentId: info.agentId,
+        effectiveWindow: info.effectiveWindow,
+        windowSource: info.windowSource,
+        minViable: eq.minViable,
+        ...eq.terms,
+        dominantTerm: eq.dominantTerm,
+        errorKind: "config",
+        submodule: "viable-floor",
+        hint: `minViable = bootstrapTotalTokens(${eq.terms.bootstrapTotalTokens}) + toolSchemaTokens(${eq.terms.toolSchemaTokens})` +
+            ` + outputHeadroomFloor(${eq.terms.outputHeadroomFloor}) + freshTailReserve(${eq.terms.freshTailReserve})` +
+            ` + safetyMargin(${eq.terms.safetyMargin}) = ${eq.minViable} exceeds effectiveWindow ${info.effectiveWindow}` +
+            ` [source: ${info.windowSource}]. ${knobSentence}${dominanceSentence}`,
+    }, "Boot viable-floor check: effective window below minViable — agent will degrade on real turns (WARN-only, boot continues)");
+    return eq;
+}

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

@@ -60,12 +60,29 @@ export interface CacheBreakDiffPayload {
         message: number;
         sdkAuto: number;
     };
+    /**
+     * Breakpoint pressure as a fraction of the SDK's 4-breakpoint ceiling.
+     * Computed by the writer from `breakpointBudget.total / 4` and clamped
+     * to [0, 1]. Surfaced in the diff record so dashboards can pivot on
+     * pressure without re-deriving from raw markers. Omitted when
+     * `breakpointBudget` is absent.
+     */
+    breakpointPressureRatio?: number;
     /** Model ID for per-model cost attribution. Populated by pi-event-bridge.ts. */
     model?: string;
 }
 export interface CacheBreakDiffWriterConfig {
     /** Directory for diff files (e.g., ~/.comis/cache-breaks) */
     outputDir: string;
+    /**
+     * Confinement base for the cache-breaks directory. Threaded from
+     * `deps.dataDir` (typically `~/.comis/`). Required by the fs-safe
+     * substrate (`ensureContainedDir` / `writeRegularFile` confinement
+     * check) so the resolved real path of every artifact stays inside
+     * the operator's data root — closes the ancestor-symlink escape
+     * that O_NOFOLLOW + parent-`lstat` together do NOT cover.
+     */
+    dataDir: string;
     /** Logger for WARN on I/O errors */
     logger: {
         warn: (obj: Record<string, unknown>, msg: string) => void;

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

@@ -9,9 +9,10 @@
  *
  * @module
  */
-import { writeFileSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { readdirSync, unlinkSync } from "node:fs";
 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. */
 const MAX_SNAPSHOT_CHARS = 50_000;
@@ -44,7 +45,24 @@ export function createCacheBreakDiffWriter(config) {
     return (event) => {
         try {
             if (!dirEnsured) {
-                mkdirSync(config.outputDir, { recursive: true });
+                // Route through the shared fs-safe substrate so
+                // `~/.comis/cache-breaks/` honors the §1.4 `0o700` invariant.
+                // 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).
+                const dirResult = ensureContainedDir({
+                    dir: config.outputDir,
+                    mode: 0o700,
+                    confinedBaseDir: config.dataDir,
+                });
+                if (!dirResult.ok) {
+                    config.logger.warn({
+                        err: dirResult.error,
+                        hint: "Cache-break dir creation rejected by fs-safe substrate; detection flow unaffected, future diffs will retry",
+                        errorKind: "resource",
+                    }, "Cache break diff dir creation failed");
+                    return;
+                }
                 dirEnsured = true;
             }
             pruneOldestFiles(config.outputDir, MAX_DIFF_FILES);
@@ -104,6 +122,14 @@ export function createCacheBreakDiffWriter(config) {
                 effortValue: event.effortValue,
                 // Breakpoint budget context
                 ...(event.breakpointBudget && { breakpointBudget: event.breakpointBudget }),
+                // Breakpoint pressure ratio: fraction of the SDK's
+                // 4-breakpoint ceiling consumed at the time of the cache break.
+                // Clamped to [0, 1] — values > 1 indicate accounting drift, < 0
+                // is impossible but locked in for defense in depth. Emitted only
+                // when breakpointBudget is present so the field stays meaningful.
+                ...(event.breakpointBudget && {
+                    breakpointPressureRatio: Math.max(0, Math.min(1, event.breakpointBudget.total / 4)),
+                }),
                 // Cost attribution
                 estimatedCostUsd: estimatedCostUsd === null
                     ? null
@@ -121,7 +147,23 @@ export function createCacheBreakDiffWriter(config) {
                     pricingKnown,
                 },
             };
-            writeFileSync(filePath, JSON.stringify(diff, null, 2) + "\n");
+            // Route the JSON write through the fs-safe substrate
+            // so each cache-break diff file lands at mode `0o600` per §1.4.
+            // 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.
+            const jsonResult = writeRegularFile({
+                path: filePath,
+                content: JSON.stringify(diff, null, 2) + "\n",
+                confinedBaseDir: config.dataDir,
+            });
+            if (!jsonResult.ok) {
+                config.logger.warn({
+                    err: jsonResult.error,
+                    hint: "Cache break diff JSON write rejected by fs-safe substrate; detection flow unaffected",
+                    errorKind: "resource",
+                }, "Cache break diff JSON write failed");
+            }
             // DIFF-CONTENT: Generate unified diff file alongside JSON
             const diffSections = [];
             // Generate diffs for ANY break event that has serialized content available
@@ -157,7 +199,20 @@ export function createCacheBreakDiffWriter(config) {
             if (diffSections.length > 0) {
                 const diffFilename = filename.replace(".json", ".diff");
                 const diffFilePath = safePath(config.outputDir, diffFilename);
-                writeFileSync(diffFilePath, diffSections.join("\n\n") + "\n");
+                // Route the .diff write through the fs-safe
+                // substrate so the sibling artifact also lands at mode `0o600`.
+                const diffResult = writeRegularFile({
+                    path: diffFilePath,
+                    content: diffSections.join("\n\n") + "\n",
+                    confinedBaseDir: config.dataDir,
+                });
+                if (!diffResult.ok) {
+                    config.logger.warn({
+                        err: diffResult.error,
+                        hint: "Cache break .diff write rejected by fs-safe substrate; JSON record persisted, .diff sibling missing",
+                        errorKind: "resource",
+                    }, "Cache break .diff write failed");
+                }
             }
         }
         catch (err) {

package/node_modules/@comis/agent/dist/executor/cache-detection/cache-state-types.d.ts

@@ -154,6 +154,17 @@ export interface CacheBreakDetector {
     aliasSession(compactionKey: string, parentKey: string): void;
     cleanupSession(sessionKey: string): void;
     reset(): void;
+    /**
+     * Read the current call count for a session (1-indexed turn number
+     * within the current agent session — turn 1 = first model call after
+     * session start). Returns undefined when the session has no detector
+     * state yet (cold start before the first recordPromptState).
+     *
+     * Used by the request-body factory to gate first-turn-only optimizations
+     * (e.g., 5m → 1h marker promotion) on real evidence the session will
+     * see a follow-up turn.
+     */
+    getCallCount(sessionKey: string): number | undefined;
 }
 /** Options for createCacheBreakDetector. */
 export interface CacheBreakDetectorOptions {

package/node_modules/@comis/agent/dist/executor/cache-detection/cache-state.js

@@ -225,6 +225,11 @@ export function createCacheBreakDetector(logger, options) {
         reset() {
             sessionDetectorState.clear();
         },
+        getCallCount(sessionKey) {
+            // Direct map read — no upsert. Returns undefined when no state exists
+            // (cold start before the first recordPromptState call).
+            return sessionDetectorState.get(sessionKey)?.currentSnapshot?.callCount;
+        },
     };
 }
 // ---------------------------------------------------------------------------

package/node_modules/@comis/agent/dist/executor/capability-index-context.js

@@ -41,7 +41,7 @@ const EMPTY = Object.freeze({
 /**
  * Active-tool count threshold above which all per-cluster name lists are
  * dropped (cluster headers + `(N tools)` counts remain).
- * Constant in v1.1; revisit only if telemetry shows fleets clustering near it.
+ * Currently a fixed constant; revisit only if telemetry shows fleets clustering near it.
  */
 const ELISION_THRESHOLD = 32;
 /**
@@ -193,6 +193,7 @@ export function buildCapabilityIndexContext(deferralResult, port) {
     const clusterCount = orderedClusters.length;
     return Object.freeze({
         text,
+        // flat-by-design: machine-rendered Latin capability index — factor would be 1.0 by construction (TOK-01)
         capabilityIndexTokens: Math.ceil(text.length / CHARS_PER_TOKEN_RATIO),
         clusterCount,
         activeToolCount,