comisai 1.0.36 → 1.0.37

package/node_modules/@comis/agent/dist/executor/pi-executor.js

@@ -67,7 +67,7 @@ import { randomUUID } from "node:crypto";
 /** Number of turns to restrict breakpoints after server eviction. */
 const EVICTION_COOLDOWN_TURNS = 2;
 // ---------------------------------------------------------------------------
-// R-12: Proactive tool-call safety guard
+// Proactive tool-call safety guard
 // ---------------------------------------------------------------------------
 /**
  * Create a beforeToolCall guard that proactively blocks tool execution when
@@ -124,10 +124,10 @@ export function createBeforeToolCallGuard(stepCounter, budgetGuard, circuitBreak
     };
 }
 // ---------------------------------------------------------------------------
-// R-13: Session stats delegation helper
+// Session stats delegation helper
 // ---------------------------------------------------------------------------
 /**
- * Merge SDK session stats into execution result for token totals (R-13).
+ * Merge SDK session stats into execution result for token totals.
  *
  * Token counts (input, output, cacheRead, cacheWrite, total) are sourced
  * from the SDK's cumulative session stats -- single source of truth.
@@ -400,7 +400,7 @@ export function createPiExecutor(config, deps) {
                 provider: resolvedModel.provider,
                 id: resolvedModel.id,
             }) : undefined;
-            // f. Execute within session adapter (R-11: use ephemeral adapter if provided)
+            // f. Execute within session adapter (use ephemeral adapter if provided)
             const sessionAdapter = overrides?.ephemeralSessionAdapter ?? deps.sessionAdapter;
             const lockResult = await sessionAdapter.withSession(sessionKey, async (sm) => {
                 // Repair orphaned messages
@@ -450,6 +450,7 @@ export function createPiExecutor(config, deps) {
                 const stableGetPromptSkillsXml = frozenPromptSkillsXml !== undefined
                     ? () => frozenPromptSkillsXml
                     : deps.getPromptSkillsXml;
+                // toolCapabilityPort flows through frozenDeps spread — no explicit re-assignment.
                 const frozenDeps = { ...deps, getPromptSkillsXml: stableGetPromptSkillsXml };
                 // Tool assembly pipeline: merge, settings, prompt, deferral, JIT, pruning, snapshot, normalization, serializer
                 // Extracted to executor-tool-assembly.ts
@@ -459,7 +460,7 @@ export function createPiExecutor(config, deps) {
                     resolvedModel, modelCompat, agentId, safetyReinforcement, _directives,
                 });
                 const { mergedCustomTools, } = toolAssembly;
-                const { deferralResult, deferredContext, modelTier, discoveryTracker, settingsManager, resourceLoaderOptions, promptResult, cachedSystemTokensEstimate, } = toolAssembly;
+                const { deferralResult, deferredContext, capabilityIndexResult, modelTier, discoveryTracker, settingsManager, resourceLoaderOptions, promptResult, cachedSystemTokensEstimate, } = toolAssembly;
                 const currentDiscoveryTracker = toolAssembly.currentDiscoveryTracker;
                 const { systemPrompt, systemPromptBlocks, dynamicPreamble, inlineMemory } = promptResult;
                 // DAG ingestion hook -- install BEFORE microcompaction
@@ -537,8 +538,8 @@ export function createPiExecutor(config, deps) {
                 const messageSendLimiter = createMessageSendLimiter({
                     maxSendsPerExecution: deps.maxSendsPerExecution ?? 3,
                 });
-                // R-12: Proactive safety -- block tool execution before it starts
-                // when safety limits are already reached. Existing reactive checks in
+                // Proactive safety -- block tool execution before it starts when
+                // safety limits are already reached. Existing reactive checks in
                 // pi-event-bridge remain as fallback for limits crossed during execution.
                 // NOTE: beforeToolCall replaces the extension runner's hook. Comis does
                 // not load pi-mono extensions, so this override is safe.
@@ -663,6 +664,18 @@ export function createPiExecutor(config, deps) {
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     session.agent.transformContext = ceSetup.contextEngine.transformContext;
                 }
+                // Align register/deregister key shape with
+                // BackgroundSessionResolver.formatComposite so production lookups via
+                // resolveActiveSession({agentId, channelType, channelId}) find the
+                // handle this execute() call registers. session-resolver.test.ts
+                // locks the formula — drift on either side breaks that test.
+                // NormalizedMessageSchema enforces channelType / channelId are
+                // non-empty (z.string().min(1)), so this composition is unconditional.
+                const resolverRegisterKey = formatSessionKey({
+                    tenantId: agentId ?? "default",
+                    channelId: `${msg.channelType}:${msg.channelId}`,
+                    userId: msg.channelId,
+                });
                 // Register active run for mid-execution steering
                 if (deps.activeRunRegistry) {
                     const handle = {
@@ -672,9 +685,9 @@ export function createPiExecutor(config, deps) {
                         isStreaming: () => session.isStreaming,
                         isCompacting: () => session.isCompacting,
                     };
-                    const registered = deps.activeRunRegistry.register(formattedKey, handle);
+                    const registered = deps.activeRunRegistry.register(resolverRegisterKey, handle);
                     if (!registered) {
-                        deps.logger.warn({ sessionKey: formattedKey, hint: "Session already has an active run; concurrent execution may cause issues", errorKind: "resource" }, "Active run already registered");
+                        deps.logger.warn({ sessionKey: resolverRegisterKey, hint: "Session already has an active run; concurrent execution may cause issues", errorKind: "resource" }, "Active run already registered");
                     }
                 }
                 // SDK tool management validation and introspection.
@@ -748,7 +761,7 @@ export function createPiExecutor(config, deps) {
                     deps.logger.debug({ err: sdkSkillError, hint: "SDK skill population failed, Comis discovery still active", errorKind: "dependency" }, "SDK skill population non-fatal error");
                 }
                 // session.sendCustomMessage() is available for operator annotations.
-                // REQUIREMENTS.md refers to appendCustomEntry() which is the SessionManager-level API;
+                // Note: appendCustomEntry() is the SessionManager-level API;
                 // the AgentSession wrapper exposes this as sendCustomMessage({ customType, content, display, details }).
                 // Future commands or hooks can call this to inject custom entries into the JSONL session.
                 // Apply command directives (thinking, compact, model, export, fork, branch)
@@ -1067,7 +1080,7 @@ export function createPiExecutor(config, deps) {
                     const promptRunResult = await runPrompt({
                         msg, session, config, sessionKey, formattedKey, agentId, result,
                         executionOverrides, executionStartMs, effectiveTimeout, executionId,
-                        bridge, dynamicPreamble, deferredContext, inlineMemory,
+                        bridge, dynamicPreamble, deferredContext, capabilityIndexResult, inlineMemory,
                         systemPrompt,
                         mergedCustomTools,
                         cmdResult, sepEnabled, executionPlanRef,
@@ -1144,7 +1157,7 @@ export function createPiExecutor(config, deps) {
                     // Post-execution cleanup: stats merge, cache metrics, memory persist, session cleanup
                     // Extracted to executor-post-execution.ts
                     await postExecution({
-                        result, session, sm, config, msg, sessionKey, formattedKey, agentId,
+                        result, session, sm, config, msg, sessionKey, formattedKey, resolverRegisterKey, agentId,
                         executionStartMs, executionId, executionOverrides,
                         bridge, unsubscribe,
                         contextEngineRef, ceSetup, streamSetup,

package/node_modules/@comis/agent/dist/executor/prompt-assembly.d.ts

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { SessionKey, NormalizedMessage, PerAgentConfig, MemoryPort, HookRunner, SecretManager, EnvelopeConfig, WrapExternalContentOptions, TypedEventBus, SenderTrustDisplayConfig, SpawnPacket, DeliveryMirrorPort, ModelOperationType } from "@comis/core";
+import type { SessionKey, NormalizedMessage, PerAgentConfig, MemoryPort, HookRunner, SecretManager, EnvelopeConfig, WrapExternalContentOptions, TypedEventBus, SenderTrustDisplayConfig, SpawnPacket, DeliveryMirrorPort, ModelOperationType, ToolCapabilityPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
 import type { BootstrapContextFile } from "../bootstrap/types.js";
@@ -130,6 +130,14 @@ export interface PromptAssemblyParams {
         }>;
         /** Platform message character limit for auto verbosity mode. Resolved by caller from channelRegistry. */
         channelMaxChars?: number;
+        /**
+         * Tool-capability port for the gate flag.
+         * Only `port.isCapabilityIndexEnabled()` is read from this file — live-runtime
+         * port accessors (skill catalog, connected MCP servers, deferred-tool state)
+         * are FORBIDDEN here per the cache-fence invariant. Architecture-grep tests
+         * statically enforce this restriction.
+         */
+        toolCapabilityPort: ToolCapabilityPort;
     };
     msg: NormalizedMessage;
     sessionKey: SessionKey;

package/node_modules/@comis/agent/dist/executor/prompt-assembly.js

@@ -331,7 +331,7 @@ export async function assembleExecutionPrompt(params) {
     // Consolidated lightContext flag: heartbeat implies light-context regardless
     // of the explicit msg.metadata.lightContext flag. Callers that only set the
     // metadata flag OR only set operationType="heartbeat" produce identical
-    // prompt output (design-doc §Risks: "Heartbeat lightContext and operationType drift").
+    // prompt output.
     const effectiveLightContext = msg.metadata?.lightContext === true || params.operationType === "heartbeat";
     // 2. Load workspace bootstrap files (skip for "none" mode)
     let bootstrapContextFiles = [];
@@ -522,6 +522,13 @@ export async function assembleExecutionPrompt(params) {
     const isOnboarding = await detectOnboardingState(deps.workspaceDir);
     // Shared params for both assembleRichSystemPrompt and assembleRichSystemPromptBlocks.
     // Using a single variable guarantees identity by construction.
+    //
+    // Hot-flip safety: the capability-index gate value is read once per
+    // assembleExecutionPrompt call via
+    // `deps.toolCapabilityPort.isCapabilityIndexEnabled()`. The flag is
+    // restart-required and stable across the session by config contract, so the
+    // cached system-prompt prefix is NOT retroactively rewritten when the
+    // underlying YAML changes mid-session.
     const assemblerParams = {
         agentName: config.name,
         promptMode,
@@ -554,6 +561,13 @@ export async function assembleExecutionPrompt(params) {
         subagentRole: undefined, // relocated to dynamic preamble for sub-agent cache sharing
         excludeBootstrapFromContext: true, // BOOTSTRAP.md is either elevated (onboarding) or dead weight (post-onboarding); never useful in Project Context
         workspaceProfile: config.workspace?.profile,
+        /**
+         * Read once per call. The value is config-derived / restart-required,
+         * so it's stable across all turns in this session. Reading it via the
+         * port (rather than from config directly) isolates this code from the
+         * config-schema shape and matches the live adapter contract.
+         */
+        capabilityIndexEnabled: deps.toolCapabilityPort.isCapabilityIndexEnabled(),
         sepEnabled: params.sepEnabled,
     };
     let systemPrompt = assembleRichSystemPrompt(assemblerParams);

package/node_modules/@comis/agent/dist/executor/tool-deferral.d.ts

@@ -101,13 +101,16 @@ export declare function resolveModelTier(contextWindow: number): ModelTier;
  */
 export declare function resolveToolCallingTemperature(modelTier: ModelTier): number;
 /**
- * Anthropic models that support server-side tool_search_tool_regex
- * (defer_loading). Sonnet 4.x+, Opus 4.x+; NOT Haiku.
+ * Anthropic models that support server-side tool-search via defer_loading.
+ * Sonnet 4.x+, Opus 4.x+; NOT Haiku.
  *
- * When this returns true, request-body-injector strips client-side
- * `discover_tools` from the API payload and appends `tool_search_tool_regex`
- * instead -- so any model-facing teaching string about `discover_tools`
- * contradicts the actual tool list and must be suppressed.
+ * **Surviving caller:** `request-body-injector.ts` (the
+ * `if (supportsToolSearch(model.id)) {...}` gate inside the Anthropic
+ * `onPayload` handler). Used to gate the API-payload reshape that strips
+ * the client-side discovery tool, appends the server-side tool-search
+ * regex tool, and marks deferred tools `defer_loading: true`. This is a
+ * runtime API-payload concern, distinct from the deferred-tool prompt
+ * teaching emitted by `buildDeferredToolsContext`.
  *
  * Lowercase-normalize so provider-prefixed model ids
  * (`anthropic/claude-sonnet-4`, `bedrock/anthropic.claude-opus-4`) resolve
@@ -135,31 +138,19 @@ export declare function resolveToolDescription(tool: ToolDefinition): string;
  * Lists deferred tool names and descriptions so the LLM knows what's
  * available behind a discovery mechanism.
  *
- * The third line (the instruction line) is conditional on `useToolSearch`:
- *
- * - `useToolSearch=false` (default, every non-Anthropic provider + Haiku):
- *   teaches the model to call the client-side `discover_tools` tool, which
- *   IS present in those payloads.
- *
- * - `useToolSearch=true` (Anthropic Sonnet/Opus 4.x): the API payload no
- *   longer contains a client-side `discover_tools` tool -- the
- *   request-body-injector replaces it with the server-side
- *   `tool_search_tool_regex` and marks deferred tools `defer_loading: true`,
- *   meaning Anthropic auto-loads them on first direct invocation. The
- *   teaching string therefore points at direct invocation + tool-search by
- *   regex, never at `discover_tools`. Without this conditional, the model
- *   reads its own preamble ("call discover_tools") against a tool list that
- *   doesn't contain that tool and gives up (production repro).
+ * The instruction line is mechanism-neutral: it tells the model these
+ * tools are available but not loaded, and points it at "the discovery
+ * mechanism available in your active toolspace" without naming a specific
+ * tool. Provider-specific payload reshaping (stripping the client-side
+ * discovery tool and appending the server-side tool-search regex tool for
+ * Anthropic Sonnet/Opus 4.x) lives entirely in `request-body-injector.ts`
+ * and is gated by `supportsToolSearch(modelId)`. This separation is
+ * enforced by architecture-grep tests.
  *
  * @param entries - Deferred tool entries (remaining after discovery re-inclusion)
- * @param options - Optional flags. `useToolSearch=true` switches the third
- *   line to the tool-search-aware variant. Defaults to false (backward-
- *   compatible with the discover_tools teaching).
  * @returns XML block string, or empty string when no entries
  */
-export declare function buildDeferredToolsContext(entries: DeferredToolEntry[], options?: {
-    useToolSearch?: boolean;
-}): string;
+export declare function buildDeferredToolsContext(entries: DeferredToolEntry[]): string;
 /**
  * Apply unified tool deferral: rule-based, budget-based, small-model,
  * lifecycle merge, and operator overrides.

package/node_modules/@comis/agent/dist/executor/tool-deferral.js

@@ -15,7 +15,7 @@
  * @module
  */
 import { getToolMetadata } from "@comis/core";
-import { extractMcpServerName } from "../bridge/bridge-event-handlers.js";
+import { extractMcpServerName } from "@comis/shared";
 import { PRIVILEGED_TOOL_NAMES } from "../bootstrap/sections/tooling-sections.js";
 import { LEAN_TOOL_DESCRIPTIONS } from "../bootstrap/sections/tool-descriptions.js";
 // ---------------------------------------------------------------------------
@@ -96,13 +96,16 @@ export function resolveToolCallingTemperature(modelTier) {
     return modelTier === "small" ? 0.0 : 0.1;
 }
 /**
- * Anthropic models that support server-side tool_search_tool_regex
- * (defer_loading). Sonnet 4.x+, Opus 4.x+; NOT Haiku.
+ * Anthropic models that support server-side tool-search via defer_loading.
+ * Sonnet 4.x+, Opus 4.x+; NOT Haiku.
  *
- * When this returns true, request-body-injector strips client-side
- * `discover_tools` from the API payload and appends `tool_search_tool_regex`
- * instead -- so any model-facing teaching string about `discover_tools`
- * contradicts the actual tool list and must be suppressed.
+ * **Surviving caller:** `request-body-injector.ts` (the
+ * `if (supportsToolSearch(model.id)) {...}` gate inside the Anthropic
+ * `onPayload` handler). Used to gate the API-payload reshape that strips
+ * the client-side discovery tool, appends the server-side tool-search
+ * regex tool, and marks deferred tools `defer_loading: true`. This is a
+ * runtime API-payload concern, distinct from the deferred-tool prompt
+ * teaching emitted by `buildDeferredToolsContext`.
  *
  * Lowercase-normalize so provider-prefixed model ids
  * (`anthropic/claude-sonnet-4`, `bedrock/anthropic.claude-opus-4`) resolve
@@ -169,32 +172,21 @@ export function resolveToolDescription(tool) {
  * Lists deferred tool names and descriptions so the LLM knows what's
  * available behind a discovery mechanism.
  *
- * The third line (the instruction line) is conditional on `useToolSearch`:
- *
- * - `useToolSearch=false` (default, every non-Anthropic provider + Haiku):
- *   teaches the model to call the client-side `discover_tools` tool, which
- *   IS present in those payloads.
- *
- * - `useToolSearch=true` (Anthropic Sonnet/Opus 4.x): the API payload no
- *   longer contains a client-side `discover_tools` tool -- the
- *   request-body-injector replaces it with the server-side
- *   `tool_search_tool_regex` and marks deferred tools `defer_loading: true`,
- *   meaning Anthropic auto-loads them on first direct invocation. The
- *   teaching string therefore points at direct invocation + tool-search by
- *   regex, never at `discover_tools`. Without this conditional, the model
- *   reads its own preamble ("call discover_tools") against a tool list that
- *   doesn't contain that tool and gives up (production repro).
+ * The instruction line is mechanism-neutral: it tells the model these
+ * tools are available but not loaded, and points it at "the discovery
+ * mechanism available in your active toolspace" without naming a specific
+ * tool. Provider-specific payload reshaping (stripping the client-side
+ * discovery tool and appending the server-side tool-search regex tool for
+ * Anthropic Sonnet/Opus 4.x) lives entirely in `request-body-injector.ts`
+ * and is gated by `supportsToolSearch(modelId)`. This separation is
+ * enforced by architecture-grep tests.
  *
  * @param entries - Deferred tool entries (remaining after discovery re-inclusion)
- * @param options - Optional flags. `useToolSearch=true` switches the third
- *   line to the tool-search-aware variant. Defaults to false (backward-
- *   compatible with the discover_tools teaching).
  * @returns XML block string, or empty string when no entries
  */
-export function buildDeferredToolsContext(entries, options) {
+export function buildDeferredToolsContext(entries) {
     if (entries.length === 0)
         return "";
-    const useToolSearch = options?.useToolSearch === true;
     // Separate MCP tools (group by server) from non-MCP tools (individual listing)
     const mcpByServer = new Map();
     const nonMcpEntries = [];
@@ -220,9 +212,9 @@ export function buildDeferredToolsContext(entries, options) {
         const shortNames = tools.map(t => t.name.startsWith(prefix) ? t.name.slice(prefix.length) : t.name);
         lines.push(`[${server}] (${tools.length} tools): ${shortNames.join(", ")}`);
     }
-    const instruction = useToolSearch
-        ? "These tools auto-load on first invocation -- call them directly by name with the right arguments. To preview a tool's schema before calling, use tool_search_tool_regex with a regex matching the tool name (e.g., tool_search_tool_regex(pattern: \"agents_manage\"))."
-        : "Call discover_tools to search by keyword or server name (e.g., discover_tools(\"yfinance\")).";
+    const instruction = "These tools are connected but not currently loaded into your active context. " +
+        "To use one, invoke the discovery mechanism available in your active toolspace, " +
+        "then call the loaded tool with the appropriate arguments.";
     return [
         "<deferred-tools>",
         "The following tools are available but not loaded.",
@@ -428,7 +420,7 @@ function structuredSearch(deferredTools, query, maxResults) {
         if (prefixMatches.length > 0)
             return prefixMatches;
     }
-    // Mode 4: Server name match (e.g., "yfinance" -> all mcp__yfinance--* tools)
+    // Mode 4: Server name match (e.g., bare server token -> all mcp__<server>--* tools)
     const serverPrefix = `mcp__${q}--`;
     const serverMatches = deferredTools.filter(t => t.name.toLowerCase().startsWith(serverPrefix));
     if (serverMatches.length > 0)
@@ -622,7 +614,7 @@ export function createDiscoverTool(deferredEntries, logger, embeddingPort, score
                 return {
                     content: [{
                             type: "text",
-                            text: "No matching tools found. Try an exact tool name, MCP server name (e.g. 'yfinance'), or select:tool1,tool2 syntax.",
+                            text: "No matching tools found. Try an exact tool name, MCP server name, or select:tool1,tool2 syntax.",
                         }],
                     isError: false,
                     details: undefined,
@@ -648,12 +640,11 @@ export function createDiscoverTool(deferredEntries, logger, embeddingPort, score
  * Match modes (checked in order, first non-empty wins):
  * 1. Exact name match (case-insensitive) against the full query.
  * 2. `mcp__` / `mcp:` prefix match against the full query.
- * 3. Bare server-name match on full query (`"yfinance"` -> all `mcp__yfinance--*`).
+ * 3. Bare server-name match on full query (e.g., bare server token -> all `mcp__<server>--*`).
  * 4. Per-token server-name fallback: for multi-word queries like
- *    `"yfinance get_stock"`, check each whitespace-separated token as a
- *    potential MCP server name. Catches the srv1593437 08:06:39Z scenario
- *    where the agent emits `{query: "yfinance get_stock"}` rather than just
- *    `{query: "yfinance"}`.
+ *    `"<server> <verb>"`, check each whitespace-separated token as a
+ *    potential MCP server name. Catches the case where the agent emits
+ *    `{query: "<server> <verb>"}` rather than just `{query: "<server>"}`.
  */
 function findActiveToolMatches(query, activeToolNames) {
     const q = query.toLowerCase().trim();
@@ -679,7 +670,7 @@ function findActiveToolMatches(query, activeToolNames) {
     // Mode 4: per-token server fallback for multi-word queries.
     // Each whitespace-separated token is probed as a server name. The first
     // token that resolves to >= 1 active tool wins. This handles the common
-    // "{server} {verb}" pattern like "yfinance get_stock".
+    // "<server> <verb>" pattern like "<bare-server-token> <verb>".
     const tokens = q.split(/\s+/).filter(t => /^[a-z0-9_-]+$/.test(t));
     for (const token of tokens) {
         const tokenServerPrefix = `mcp__${token}--`;

package/node_modules/@comis/agent/dist/model/model-registry-adapter.js

@@ -113,7 +113,7 @@ export function registerCustomProviders(registry, entries, secretManager, logger
         if (isBuiltInType && providerName !== entry.type) {
             providerAliases.set(providerName, entry.type);
         }
-        // Layer 1B (260430-vwt): catalog-aware model enrichment.
+        // Catalog-aware model enrichment.
         //
         // Before computing customModels, decide whether to inherit the full
         // pi-ai catalog or to enrich the user's sparse list with catalog

package/node_modules/@comis/agent/dist/model/model-scanner.js

@@ -14,7 +14,7 @@
  */
 import { getModels, getProviders } from "@mariozechner/pi-ai";
 // ---------------------------------------------------------------------------
-// Catalog-driven endpoint resolution (Layer 1E -- 260430-vwt)
+// Catalog-driven endpoint resolution
 // ---------------------------------------------------------------------------
 /**
  * Native pi-ai providers from the live catalog. Used to source baseUrls

package/node_modules/@comis/agent/dist/safety/tool-retry-breaker.d.ts

@@ -1,7 +1,7 @@
 /**
  * Tool retry circuit breaker: per-tool-signature consecutive failure tracking.
  *
- * Prevents infinite retry loops (like the 48-call yfinance incident) by blocking
+ * Prevents infinite retry loops (the original repro: 48-call MCP-server retry incident) by blocking
  * tool calls after repeated failures and providing actionable LLM guidance with
  * alternative tool suggestions.
  *
@@ -29,6 +29,16 @@ export interface ToolRetryBreakerConfig {
     /** Max consecutive same-error-class failures (any args) before blocking.
      *  Stricter than args-based because same error + different args = stronger stuck signal. */
     maxConsecutiveErrorPatterns?: number;
+    /**
+     * Operator-supplied tool-alternative map. Keys are tool-name prefixes
+     * (e.g., `"mcp__finance-data"`); values are arrays of suggested alternative
+     * tool names. Used in block reasons to guide the LLM toward working tools.
+     *
+     * Defaults to an empty map (no alternatives suggested). The codebase MUST
+     * NOT ship hardcoded MCP server names — operators opt in by populating
+     * this map in their breaker config.
+     */
+    toolAlternatives?: Record<string, readonly string[]>;
 }
 /** Tool retry breaker interface -- tracks per-tool-signature failures. */
 export interface ToolRetryBreaker {

package/node_modules/@comis/agent/dist/safety/tool-retry-breaker.js

@@ -2,7 +2,7 @@
 /**
  * Tool retry circuit breaker: per-tool-signature consecutive failure tracking.
  *
- * Prevents infinite retry loops (like the 48-call yfinance incident) by blocking
+ * Prevents infinite retry loops (the original repro: 48-call MCP-server retry incident) by blocking
  * tool calls after repeated failures and providing actionable LLM guidance with
  * alternative tool suggestions.
  *
@@ -17,16 +17,6 @@
  * @module
  */
 // ---------------------------------------------------------------------------
-// Alternative tool mapping (hardcoded v1)
-// ---------------------------------------------------------------------------
-/**
- * Maps tool name prefixes to alternative tools that can serve similar purposes.
- * Used in block reasons to guide the LLM toward working alternatives.
- */
-const TOOL_ALTERNATIVES = {
-    "mcp__yfinance": ["web_search", "mcp__tavily--tavily-search", "web_fetch"],
-};
-// ---------------------------------------------------------------------------
 // Error tag extraction
 // ---------------------------------------------------------------------------
 /**
@@ -154,17 +144,6 @@ function fingerprint(toolName, args) {
     const sortedArgs = JSON.stringify(Object.fromEntries(Object.entries(args).sort()));
     return `${toolName}::${sortedArgs}`;
 }
-/**
- * Find alternative tools for a given tool name by prefix matching.
- * @returns Array of alternative tool names, empty if none known.
- */
-function findAlternatives(toolName) {
-    for (const [prefix, alts] of Object.entries(TOOL_ALTERNATIVES)) {
-        if (toolName.startsWith(prefix))
-            return alts;
-    }
-    return [];
-}
 /**
  * When tool failures are caused by the macOS sandbox-exec profile denying writes
  * to protected paths (~/.comis/skills/, global node_modules, ~/.gitconfig,
@@ -246,6 +225,7 @@ function buildBlockReason(toolName, count, lastError, alternatives, isToolLevel)
 export function createToolRetryBreaker(config) {
     const { maxConsecutiveFailures, maxToolFailures, suggestAlternatives } = config;
     const maxErrorPatterns = config.maxConsecutiveErrorPatterns ?? 2;
+    const toolAlternatives = config.toolAlternatives ?? {};
     // Per-fingerprint (tool+args) consecutive failure tracking
     const signatureFailures = new Map();
     // Per-tool-name total failure count (across all args)
@@ -254,6 +234,23 @@ export function createToolRetryBreaker(config) {
     const blockedTools = new Set();
     // Per-error-pattern consecutive failure tracking (keyed by `${toolName}::err::${errorTag}`)
     const errorPatternFailures = new Map();
+    /**
+     * Find alternative tools for a given tool name by prefix matching against
+     * `config.toolAlternatives`. Closed-over the factory's `toolAlternatives`
+     * local; defaults to no alternatives when the config field is omitted.
+     * Spread to a fresh mutable array so the readonly-input / mutable-output
+     * contract documented in `ToolRetryVerdict.alternatives?: string[]` is
+     * preserved.
+     *
+     * @returns Array of alternative tool names, empty if no prefix match.
+     */
+    function findAlternatives(toolName) {
+        for (const [prefix, alts] of Object.entries(toolAlternatives)) {
+            if (toolName.startsWith(prefix))
+                return [...alts];
+        }
+        return [];
+    }
     return {
         beforeToolCall(toolName, args) {
             // Check tool-level block first (all args blocked)

package/node_modules/@comis/agent/dist/session/comis-session-manager.d.ts

@@ -30,11 +30,25 @@ export interface ComisSessionManagerDeps {
  * Session metadata written as a companion file alongside the JSONL.
  * The SDK controls the JSONL format, so enrichment data (traceId, runId, session_end)
  * is stored in `_session-metadata.json` next to the `.jsonl` file.
+ *
+ * `traceId` and `runId` are deliberately distinct identifiers:
+ * - `traceId` is the request-scope AsyncLocalStorage value set by
+ *   `runWithContext` at the channel boundary (channels/.../execution-execute.ts).
+ *   The Pino tracing mixin (infra/.../log-fields.ts) injects it into every
+ *   daemon log line, so an operator can grep daemon.log for this exact value
+ *   to find every log entry produced while handling this turn.
+ * - `runId` is the executor-scope UUID minted per `executor.execute()` call
+ *   in pi-executor.ts. It keys cost-tracker / token_usage rows in the
+ *   observability store.
+ *
+ * They are 1:1 in the steady-state interactive path (one inbound message →
+ * one execution), but heartbeat and sub-agent paths can fan out a single
+ * trace into multiple executions.
  */
 export interface SessionMetadata {
-    /** Trace ID for cross-correlating with daemon logs */
+    /** Request-scope trace ID from runWithContext; matches traceId in daemon.log. */
     traceId?: string;
-    /** Execution run ID */
+    /** Executor-scope run ID; keys cost-tracker / token_usage rows. */
     runId?: string;
     /** Session end marker with completion details */
     sessionEnd?: {

package/node_modules/@comis/agent/dist/spawn/pi-mono-adapters.d.ts

@@ -1,5 +1,5 @@
 /**
- * Pi-mono adapter wrappers for sub-agent ephemeral sessions (R-11).
+ * Pi-mono adapter wrappers for sub-agent ephemeral sessions.
  *
  * Provides `createEphemeralComisSessionManager()` — a zero-persistence
  * ComisSessionManager whose `withSession` uses `SessionManager.inMemory()`

package/node_modules/@comis/agent/dist/spawn/pi-mono-adapters.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Pi-mono adapter wrappers for sub-agent ephemeral sessions (R-11).
+ * Pi-mono adapter wrappers for sub-agent ephemeral sessions.
  *
  * Provides `createEphemeralComisSessionManager()` — a zero-persistence
  * ComisSessionManager whose `withSession` uses `SessionManager.inMemory()`
@@ -51,10 +51,10 @@ export function createEphemeralComisSessionManager(cwd) {
             // No-op: no companion file for in-memory sessions
         },
         getSessionPath() {
-            // 260428-iag wire-edge diagnostic: ephemeral sub-agent sessions never
-            // persist a JSONL file, so there is no path to return. Empty string
-            // signals "no persisted file"; the bridge's wire-diff hook short-circuits
-            // when jsonlPath.length === 0.
+            // Wire-edge diagnostic: ephemeral sub-agent sessions never persist a
+            // JSONL file, so there is no path to return. Empty string signals
+            // "no persisted file"; the bridge's wire-diff hook short-circuits when
+            // jsonlPath.length === 0.
             return "";
         },
     };

package/node_modules/@comis/agent/dist/workspace/data-env.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Workspace-internal data env resolver.
+ *
+ * Returns environment variables for python/matplotlib subprocesses that
+ * derive ALL paths from `workspaceDir`. Avoids slow pip installs in the
+ * chart hot path and matplotlib Fontconfig errors from a non-writable
+ * default cache dir.
+ *
+ * This file contains no host-env reads. Subprocesses inheriting the
+ * daemon's full environment can pick up host paths (e.g.
+ * `/root/.cache/matplotlib`) that fail under read-only systemd hardening
+ * (`ProtectSystem=strict`) and leak host PATH into the agent's tool
+ * execution.
+ *
+ * matplotlib + python deps install into the agent workspace's `venv/`.
+ * The Dockerfile pre-warms the default workspace's venv at image build
+ * time so first-chart latency drops; subsequent chart calls reuse the
+ * venv. Full Docker image size goes up (acceptable trade-off).
+ *
+ * Mirrors workspace-resolver.ts's safePath + workspaceDir precedent
+ * (no path.join, no host-env reads).
+ *
+ * @module
+ */
+/**
+ * Resolve workspace-internal env vars for python/matplotlib subprocesses.
+ *
+ * The returned record is intended to be MERGED over an existing subprocess
+ * env at the call site (e.g. exec-tool's `{ ...baseEnv, ...resolveDataEnv(...) }`),
+ * so the workspace-internal values win on collision and the host PATH /
+ * cache dirs are not surfaced inside the subprocess.
+ *
+ * @param opts.workspaceDir - Absolute path to the agent workspace.
+ * @returns env-var record suitable for `child_process.spawn(..., { env })`.
+ */
+export declare function resolveDataEnv(opts: {
+    workspaceDir: string;
+}): Record<string, string>;