comisai 1.0.34 → 1.0.37

package/node_modules/@comis/daemon/dist/wiring/setup-agents.js

@@ -4,17 +4,34 @@
  * dependencies (circuit breaker, budget guard, cost tracker, step counter),
  * and PiExecutor creation.
  * All agents use PiExecutor (pi-coding-agent AgentSession wrapper).
+ *
+ * The live ToolCapabilityPort adapter is constructed inside setupSingleAgent
+ * (this function), NOT at a higher composition site (daemon.ts). Rationale:
+ * skillRegistry is per-agent and the skill-allow/deny precedence chain is
+ * per-agent; a daemon-global adapter cannot satisfy this without breaking
+ * the port interface (would require adding agentId to every method). The
+ * per-agent port is exposed via AgentsResult.toolCapabilityPorts and threaded
+ * into setupTools via the getCapabilityPortForAgent closure on ToolsDeps.
+ *
  * @module
  */
 import { safePath, SkillsConfigSchema, createScopedSecretManager, createOutputGuard, generateCanaryToken, createInputSecurityGuard, validateInput, PerAgentConfigSchema } from "@comis/core";
+import { createToolCapabilityAdapter } from "./tool-capability-adapter.js";
 import { suppressError } from "@comis/shared";
 import { createHmac } from "node:crypto";
 import { homedir } from "node:os";
 import { existsSync, mkdirSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import { getModels, getProviders } from "@mariozechner/pi-ai";
-import { createCircuitBreaker, createBudgetGuard, createCostTracker, createStepCounter, createSessionLifecycle, ensureWorkspace, resolveWorkspaceDir, createPiExecutor, createComisSessionManager, cleanupStaleLocks, createAuthStorageAdapter, createModelRegistryAdapter, registerCustomProviders, createProviderHealthMonitor, createLastKnownModelTracker, createAuthProfileManager, createAuthRotationAdapter, setSanitizeLogger, setToolNormalizationLogger, resolveOperationDefaults, resolveCompactionModel, LEAN_TOOL_DESCRIPTIONS, resolveDescription, } from "@comis/agent";
+import { createCircuitBreaker, createBudgetGuard, createCostTracker, createStepCounter, createSessionLifecycle, ensureWorkspace, resolveWorkspaceDir, createPiExecutor, createComisSessionManager, cleanupStaleLocks, createAuthStorageAdapter, createAuthProvider, selectOAuthCredentialStore, createModelRegistryAdapter, registerCustomProviders, createProviderHealthMonitor, createLastKnownModelTracker, createAuthProfileManager, createAuthRotationAdapter, setSanitizeLogger, setToolNormalizationLogger, resolveOperationDefaults, resolveCompactionModel, LEAN_TOOL_DESCRIPTIONS, resolveDescription, } from "@comis/agent";
 import { agentToolsToToolDefinitions, createSkillRegistry, createRuntimeEligibilityContext, TOOL_PROFILES, } from "@comis/skills";
+// Once-per-daemon-process WARN flag for the encrypted-store hot-reload
+// limitation. Lifted to module scope so the flag survives across per-agent
+// setupSingleAgent calls AND any future re-invocations of setupAgents within
+// the same process. Operator-friendly notice — fires exactly once per daemon
+// process so the operator sees it in startup logs without N-times-per-agent
+// noise.
+let encryptedModeWarnFired = false;
 // ---------------------------------------------------------------------------
 // Single-agent setup (extracted for hot-add reuse)
 // ---------------------------------------------------------------------------
@@ -104,6 +121,79 @@ export async function setupSingleAgent(agentId, rawAgentConfig, deps) {
         secretManager: scopedManager,
         customProviderEntries,
     });
+    // -------------------------------------------------------------------------
+    // FIRST daemon-side OAuth wiring.
+    //
+    // Closes the unwired-OAuth gap — the createAuthProvider symbol was exported
+    // by @comis/agent but never called by the daemon, so refreshed OAuth tokens
+    // lived only in the in-memory cache and silently disappeared on restart.
+    // AuthProviderConfig.oauth credentialStore + logger + dataDir are REQUIRED
+    // so this wiring is type-checked at compile time — future regressions
+    // surface as TS errors, not silent runtime failures.
+    //
+    // All path constructions in this block use safePath from @comis/core (NOT
+    // path.join — AGENTS.md §2.2 ESLint security rule).
+    // When storage === "encrypted", the OAuth profile adapter SHARES the
+    // existing secretsDb handle from createSqliteSecretStore (no dual-handle).
+    // -------------------------------------------------------------------------
+    const oauthStorageMode = container.config.oauth.storage;
+    const dataDirAbs = container.config.dataDir && container.config.dataDir.length > 0
+        ? container.config.dataDir
+        : safePath(homedir(), ".comis");
+    // Use the daemon-level OAuthCredentialStore handle that setupAgents()
+    // constructed once and threaded through SingleAgentDeps. Same store
+    // reference is also exposed on AgentsResult so daemon.ts can plumb it into
+    // RpcDispatchDeps for the agents.update oauthProfiles existence check.
+    const oauthCredentialStore = deps.oauthCredentialStore;
+    const authProvider = createAuthProvider({
+        secretManager: scopedManager,
+        additionalProviderKeys: undefined,
+        oauth: {
+            eventBus: container.eventBus,
+            credentialStore: oauthCredentialStore,
+            logger: agentLogger.child({ submodule: "oauth-token-manager" }),
+            dataDir: dataDirAbs,
+            keyPrefix: "OAUTH_",
+            // Pass auth-profiles.json path when file adapter active so
+            // OAuthTokenManager can register the chokidar watcher and pick up
+            // CLI-written profiles within ~250ms without a daemon restart.
+            // Encrypted-mode: undefined -> no watcher; documented limitation.
+            watchPath: oauthStorageMode === "file"
+                ? safePath(dataDirAbs, "auth-profiles.json")
+                : undefined,
+            // Closure-stability: the closure dereferences
+            // container.config.agents[agentId]?.oauthProfiles on every call.
+            // This is the only correct shape because:
+            //   1. The `container.config.agents[agentId] = effectiveConfig`
+            //      writeback above (search for that assignment in this file)
+            //      stores a NEW object built from
+            //      { ...agentConfig, model, provider } into the daemon's map.
+            //      The local `agentConfig` parameter diverges from the map
+            //      immediately at startup — capturing it would observe the
+            //      wrong value.
+            //   2. agents.update at agent-handlers.ts:341 executes
+            //      `deps.agents[agentId] = parsedConfig`, REPLACING the
+            //      reference at that key with a new validated object. Capturing
+            //      the local agentConfig parameter would miss this hot-update.
+            //   3. daemon.ts confirms `deps.agents` and `container.config.agents`
+            //      are THE SAME map object — search for
+            //      `agents: container.config.agents` in the RpcDispatchDeps
+            //      construction. The daemon holds a single per-process
+            //      Container.config instance.
+            // The map identity is stable; only the value at the agent key
+            // changes. The closure-evaluated dereference observes (1) at
+            // startup AND (2) on every agents.update without an event-bus
+            // invalidation or daemon restart, allowing the agents_manage tool to
+            // update without a daemon restart.
+            getAgentOauthProfiles: () => container.config.agents?.[agentId]?.oauthProfiles,
+        },
+    });
+    agentLogger.debug({
+        agentId,
+        oauthStorage: oauthStorageMode,
+        dataDir: dataDirAbs,
+        submodule: "setup-agents",
+    }, "OAuth credential store + auth provider + per-LLM-call dispatch wired");
     const piModelRegistry = createModelRegistryAdapter(piAuthStorage);
     const { registered: customProviderCount, providerAliases } = registerCustomProviders(piModelRegistry, customProviderEntries, scopedManager, agentLogger);
     if (customProviderCount > 0) {
@@ -146,6 +236,16 @@ export async function setupSingleAgent(agentId, rawAgentConfig, deps) {
     };
     const skillRegistry = createSkillRegistry(resolvedSkillsConfig, container.eventBus, { agentId, tenantId: container.config.tenantId, userId: "system" }, perAgentLogger, eligibilityContext);
     skillRegistry.init();
+    // Per-agent ToolCapabilityPort adapter. Construction sits here so the
+    // adapter can close over this agent's skillRegistry; the adapter is
+    // reused by pi-executor (capability-index renderer) AND by exec/process
+    // tools (install-detour parser via setupTools.getCapabilityPortForAgent).
+    const toolCapabilityPort = createToolCapabilityAdapter({
+        toolingConfig: container.config.tooling,
+        skillRegistry,
+        mcpClientManager: deps.mcpClientManager,
+        logger: perAgentLogger,
+    });
     // Opt-in file watching for automatic skill reload
     let skillWatcherHandle;
     if (skillsConfig.watchEnabled) {
@@ -235,6 +335,11 @@ export async function setupSingleAgent(agentId, rawAgentConfig, deps) {
         eventBus: container.eventBus,
         logger: perAgentLogger,
         authStorage: piAuthStorage,
+        // Thread OAuthTokenManager into the executor so the per-LLM-call
+        // dispatch hook (PiExecutor.execute pre-hook + the two compaction
+        // getApiKey callbacks in executor-context-engine-setup.ts) can resolve
+        // OAuth tokens via resolveProviderApiKey.
+        oauthManager: authProvider.oauth,
         modelRegistry: piModelRegistry,
         providerAliases,
         fallbackModels: fallbackModelStrings.length > 0 ? fallbackModelStrings : undefined,
@@ -268,6 +373,7 @@ export async function setupSingleAgent(agentId, rawAgentConfig, deps) {
             : undefined,
         embeddingEnqueue: deps.embeddingQueue?.enqueue.bind(deps.embeddingQueue),
         embeddingPort: deps.embeddingPort, // Semantic search in discover_tools
+        toolCapabilityPort, // Live adapter constructed above from container.config.tooling + skillRegistry + mcpClientManager.
         // DAG context engine deps (optional -- only when context engine version is dag)
         contextStore: deps.contextStore,
         db: deps.db,
@@ -295,6 +401,7 @@ export async function setupSingleAgent(agentId, rawAgentConfig, deps) {
         piSessionAdapter: sessionAdapter,
         skillWatcherHandle,
         skillRegistry,
+        toolCapabilityPort, // Exposed for AgentsResult.toolCapabilityPorts map
     };
 }
 // ---------------------------------------------------------------------------
@@ -312,9 +419,23 @@ export async function setupSingleAgent(agentId, rawAgentConfig, deps) {
 export async function setupAgents(deps) {
     const { container, memoryAdapter, sessionStore, agentLogger } = deps;
     // Inject module-level logger for response sanitization pipeline
-    setSanitizeLogger(agentLogger.child({ module: "response-sanitize" }));
+    setSanitizeLogger(agentLogger.child({ submodule: "response-sanitize" }));
     // Inject module-level logger for tool schema normalization pipeline
-    setToolNormalizationLogger(agentLogger.child({ module: "tool-normalize" }));
+    setToolNormalizationLogger(agentLogger.child({ submodule: "tool-normalize" }));
+    // Once-per-daemon WARN for the encrypted-store hot-reload limitation.
+    // Placed in setupAgents() body (NOT setupSingleAgent) so the notice fires
+    // exactly once per daemon process — not N times for N agents. Operator
+    // sees this in startup logs without surprise; daemon restart is required
+    // to pick up CLI-written OAuth profiles in encrypted-store mode.
+    const overallStorageMode = container.config.oauth.storage;
+    if (overallStorageMode === "encrypted" && !encryptedModeWarnFired) {
+        encryptedModeWarnFired = true;
+        agentLogger.warn({
+            hint: "CLI auth login changes require daemon restart in encrypted mode (file-watch unsupported on encrypted SQLite WAL)",
+            errorKind: "limitation_known",
+            submodule: "setup-agents",
+        }, "OAuth hot-reload disabled in encrypted-store mode");
+    }
     const agents = container.config.agents; // Always populated after schema transform
     const routingConfig = container.config.routing;
     // Daemon-level tracing defaults
@@ -351,6 +472,9 @@ export async function setupAgents(deps) {
     const piSessionAdapters = new Map();
     const skillWatcherHandles = new Map();
     const skillRegistries = new Map();
+    // Per-agent live ToolCapabilityPort adapters, parallel to skillRegistries;
+    // mutated in lockstep by hot-add/hot-remove.
+    const toolCapabilityPorts = new Map();
     // Resolve sub-agent tool names from config for delegation awareness
     const subAgentToolGroups = container.config.security?.agentToAgent?.subAgentToolGroups ?? [];
     const subAgentToolNames = subAgentToolGroups.length === 0 || subAgentToolGroups.includes("full")
@@ -368,6 +492,19 @@ export async function setupAgents(deps) {
     });
     // Global last-known-working model tracker (shared across all agents)
     const lastKnownModel = createLastKnownModelTracker();
+    // Construct the daemon-level OAuthCredentialStore handle ONCE (instead of
+    // per-agent inside setupSingleAgent). Same handle is reused across every
+    // agent setup AND surfaced on AgentsResult so daemon.ts can plumb it into
+    // RpcDispatchDeps for the agents.update oauthProfiles existence check.
+    const dataDirAbsForOauth = container.config.dataDir && container.config.dataDir.length > 0
+        ? container.config.dataDir
+        : safePath(homedir(), ".comis");
+    const oauthCredentialStore = selectOAuthCredentialStore({
+        storage: container.config.oauth.storage,
+        dataDir: dataDirAbsForOauth,
+        secretsCrypto: deps.secretsCrypto,
+        secretsDb: deps.secretsDb,
+    });
     // Construct shared deps struct once before the loop (for hot-add reuse)
     const singleAgentDeps = {
         container,
@@ -395,6 +532,16 @@ export async function setupAgents(deps) {
         getChannelMaxChars: deps.getChannelMaxChars,
         backgroundTaskManager: deps.backgroundTaskManager,
         backgroundNotifyFn: deps.backgroundNotifyFn,
+        // Secrets bootstrap output for OAuth wiring.
+        secretsCrypto: deps.secretsCrypto,
+        secretsDb: deps.secretsDb,
+        // Daemon-level OAuth credential store handle (constructed once above,
+        // reused per-agent + threaded into RPC deps).
+        oauthCredentialStore,
+        // Daemon-global MCP client manager. Threaded through so each
+        // setupSingleAgent invocation can construct a per-agent
+        // ToolCapabilityPort adapter that closes over the live MCP state.
+        mcpClientManager: deps.mcpClientManager,
     };
     for (const [agentId, agentConfig] of Object.entries(agents)) {
         const result = await setupSingleAgent(agentId, agentConfig, singleAgentDeps);
@@ -407,6 +554,7 @@ export async function setupAgents(deps) {
         if (result.skillWatcherHandle)
             skillWatcherHandles.set(agentId, result.skillWatcherHandle);
         skillRegistries.set(agentId, result.skillRegistry);
+        toolCapabilityPorts.set(agentId, result.toolCapabilityPort);
     }
     const defaultAgentId = routingConfig.defaultAgentId;
     const defaultWorkspaceDir = workspaceDirs.get(defaultAgentId);
@@ -448,9 +596,16 @@ export async function setupAgents(deps) {
         piSessionAdapters,
         skillWatcherHandles,
         skillRegistries,
+        // daemon.ts threads this Map into setupTools via
+        // getCapabilityPortForAgent and mutates it on hot-add/hot-remove.
+        toolCapabilityPorts,
         lockCleanupTimer,
         singleAgentDeps,
         providerHealth,
+        // Daemon-level OAuth credential store, plumbed by daemon.ts into
+        // RpcDispatchDeps.oauthCredentialStore so agents.update can validate
+        // oauthProfiles patches via has().
+        oauthCredentialStore,
     };
 }
 // ---------------------------------------------------------------------------
@@ -543,3 +698,9 @@ function deriveCanaryFallback(baseSecret, agentId) {
         .update(`canary-fallback:${agentId}`)
         .digest("hex");
 }
+// ---------------------------------------------------------------------------
+// OAuth credential store selection lives in @comis/agent (CLI cannot import
+// from @comis/daemon, so the helper must live where both daemon and CLI
+// consume it).
+// See: packages/agent/src/model/oauth-credential-store-selector.ts
+// ---------------------------------------------------------------------------

package/node_modules/@comis/daemon/dist/wiring/setup-background-completion-runner.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Background completion dispatcher + runner wiring for daemon startup.
+ *
+ * Subscribes the dispatcher BEFORE the runner so its synchronous
+ * `transitionDispatchState` runs first; the runner's handler then reads
+ * the updated `task.dispatchState` and skips when state is "notified"
+ * (the dispatcher already fired fallback). Subscription order matters
+ * because the event bus fires handlers in registration order; the
+ * dispatcher MUST come first.
+ *
+ * Per AGENTS §2.4: composition root + factories. This wiring lives in
+ * @comis/daemon (composition root); the actual factory bodies live in
+ * @comis/agent.
+ *
+ * @module
+ */
+import { type BackgroundCompletionRunner, type BackgroundTaskManager, type CompletionDispatcher, type NotifyFn } from "@comis/agent";
+import type { TypedEventBus } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+import type { AgentExecutor } from "@comis/agent";
+import type { RunnerSessionStore } from "@comis/agent";
+/** Result of setupBackgroundCompletionRunner -- exposed to the daemon for shutdown. */
+export interface BackgroundCompletionRunnerContext {
+    runner: BackgroundCompletionRunner;
+    dispatcher: CompletionDispatcher;
+}
+/**
+ * The taskManager arg widened to require `transitionDispatchState` so the
+ * dispatcher can persist state-machine transitions.
+ *
+ * The runner only consumes `getTask` (existing contract); the dispatcher
+ * consumes both `getTask` and `transitionDispatchState`. Daemon callers
+ * pass the full BackgroundTaskManager so structural subtyping covers both.
+ */
+export interface SetupBackgroundCompletionRunnerDeps {
+    eventBus: TypedEventBus;
+    getExecutor: (agentId: string) => AgentExecutor;
+    sessionStore: RunnerSessionStore;
+    /**
+     * Must support `transitionDispatchState`; the dispatcher persists state
+     * machine transitions through it. The runner only needs `getTask`.
+     */
+    taskManager: Pick<BackgroundTaskManager, "getTask" | "transitionDispatchState">;
+    /** bgNotifyFn closure used when the originating session is gone. */
+    fallbackNotifyFn: NotifyFn;
+    /** From config.backgroundTasks.maxBackgroundHops (default 3). NOT config.workflow.*. */
+    maxBackgroundHops: number;
+    logger: ComisLogger;
+}
+/**
+ * Wire the dispatcher + completion runner from daemon-level dependencies.
+ * Call this AFTER setupNotifications so fallbackNotifyFn is wired.
+ *
+ * Subscription order: dispatcher first (synchronous transition), runner
+ * second (reads updated state). Reverse-order shutdown so the runner
+ * stops accepting events before the dispatcher tears down.
+ */
+export declare function setupBackgroundCompletionRunner(deps: SetupBackgroundCompletionRunnerDeps): BackgroundCompletionRunnerContext;

package/node_modules/@comis/daemon/dist/wiring/setup-background-completion-runner.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Background completion dispatcher + runner wiring for daemon startup.
+ *
+ * Subscribes the dispatcher BEFORE the runner so its synchronous
+ * `transitionDispatchState` runs first; the runner's handler then reads
+ * the updated `task.dispatchState` and skips when state is "notified"
+ * (the dispatcher already fired fallback). Subscription order matters
+ * because the event bus fires handlers in registration order; the
+ * dispatcher MUST come first.
+ *
+ * Per AGENTS §2.4: composition root + factories. This wiring lives in
+ * @comis/daemon (composition root); the actual factory bodies live in
+ * @comis/agent.
+ *
+ * @module
+ */
+import { createBackgroundCompletionRunner, createCompletionDispatcher, } from "@comis/agent";
+/**
+ * Wire the dispatcher + completion runner from daemon-level dependencies.
+ * Call this AFTER setupNotifications so fallbackNotifyFn is wired.
+ *
+ * Subscription order: dispatcher first (synchronous transition), runner
+ * second (reads updated state). Reverse-order shutdown so the runner
+ * stops accepting events before the dispatcher tears down.
+ */
+export function setupBackgroundCompletionRunner(deps) {
+    // Dispatcher subscribes FIRST so its synchronous transitionDispatchState
+    // runs before the runner's handler reads task.dispatchState within the
+    // same event-bus tick.
+    const dispatcher = createCompletionDispatcher({
+        eventBus: deps.eventBus,
+        sessionStore: deps.sessionStore,
+        taskManager: deps.taskManager,
+        fallbackNotifyFn: deps.fallbackNotifyFn,
+        maxBackgroundHops: deps.maxBackgroundHops,
+        logger: deps.logger,
+    });
+    const runner = createBackgroundCompletionRunner({
+        eventBus: deps.eventBus,
+        getExecutor: deps.getExecutor,
+        sessionStore: deps.sessionStore,
+        taskManager: deps.taskManager,
+        fallbackNotifyFn: deps.fallbackNotifyFn,
+        maxBackgroundHops: deps.maxBackgroundHops,
+        logger: deps.logger,
+    });
+    return {
+        runner: {
+            // Reverse-order shutdown: runner first (stops accepting events), then
+            // dispatcher (ensures the at-most-once gate is the last to tear down).
+            async shutdown() {
+                await runner.shutdown();
+                await dispatcher.shutdown();
+            },
+        },
+        dispatcher,
+    };
+}

package/node_modules/@comis/daemon/dist/wiring/setup-background-tasks.d.ts

@@ -19,9 +19,16 @@ export interface SetupBackgroundTasksDeps {
 }
 /**
  * Wire the background task subsystem from daemon-level dependencies.
- * Creates BackgroundTaskManager with file-based persistence, recovers
- * incomplete tasks from the previous daemon run (marking them failed),
- * and starts an hourly cleanup timer for stale completed/failed tasks.
+ * Creates BackgroundTaskManager with file-based persistence and starts
+ * an hourly cleanup timer for stale completed/failed tasks.
+ *
+ * Note: startup recovery (marking interrupted tasks as failed) is
+ * INTENTIONALLY deferred to daemon.ts. The daemon calls it AFTER
+ * `setupBackgroundCompletionRunner` has subscribed to
+ * background_task:{completed,failed}. If recovery fires before the runner
+ * subscribes, the synthesized failure events for restart-interrupted tasks
+ * land in an empty handler set and the user never sees the recovery
+ * announcement.
  * @param deps - Daemon-level dependencies
  * @returns BackgroundTasksContext with manager instance
  */

package/node_modules/@comis/daemon/dist/wiring/setup-background-tasks.js

@@ -5,24 +5,30 @@
  * daemon runs, and starts periodic cleanup of stale completed/failed tasks.
  * @module
  */
-import { createBackgroundTaskManager } from "@comis/agent";
+import { createBackgroundTaskManager, TASK_DIR_NAME } from "@comis/agent";
 import { safePath } from "@comis/core";
 /**
  * Wire the background task subsystem from daemon-level dependencies.
- * Creates BackgroundTaskManager with file-based persistence, recovers
- * incomplete tasks from the previous daemon run (marking them failed),
- * and starts an hourly cleanup timer for stale completed/failed tasks.
+ * Creates BackgroundTaskManager with file-based persistence and starts
+ * an hourly cleanup timer for stale completed/failed tasks.
+ *
+ * Note: startup recovery (marking interrupted tasks as failed) is
+ * INTENTIONALLY deferred to daemon.ts. The daemon calls it AFTER
+ * `setupBackgroundCompletionRunner` has subscribed to
+ * background_task:{completed,failed}. If recovery fires before the runner
+ * subscribes, the synthesized failure events for restart-interrupted tasks
+ * land in an empty handler set and the user never sees the recovery
+ * announcement.
  * @param deps - Daemon-level dependencies
  * @returns BackgroundTasksContext with manager instance
  */
 export function setupBackgroundTasks(deps) {
     const manager = createBackgroundTaskManager({
-        dataDir: safePath(deps.dataDir, "background-tasks"),
+        dataDir: safePath(deps.dataDir, TASK_DIR_NAME),
         eventBus: deps.eventBus,
         logger: deps.logger,
     });
-    // Mark incomplete tasks from previous daemon run as failed
-    manager.recoverOnStartup();
+    // Startup recovery is deferred to daemon.ts (after the completion runner subscribes).
     // Periodic cleanup of stale completed/failed tasks (24h TTL)
     const cleanupInterval = setInterval(() => manager.cleanup(), 3_600_000); // every hour
     cleanupInterval.unref(); // don't keep daemon alive for cleanup

package/node_modules/@comis/daemon/dist/wiring/setup-channels.d.ts

@@ -10,7 +10,7 @@
  */
 import type { AppContainer, ChannelPort, ChannelPluginPort, NormalizedMessage, SessionKey, TranscriptionPort, TTSPort, ImageAnalysisPort, FileExtractionPort, FileExtractionConfig, MemoryPort, QueueConfig } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
-import type { AgentExecutor, createSessionLifecycle, ActiveRunRegistry } from "@comis/agent";
+import type { AgentExecutor, createSessionLifecycle, ActiveRunRegistry, BackgroundSessionResolver } from "@comis/agent";
 import type { createSessionStore } from "@comis/memory";
 import { type CommandQueue } from "@comis/agent";
 import { type ChannelManager, type ApprovalNotifier } from "@comis/channels";
@@ -107,6 +107,13 @@ export interface ChannelsDeps {
     deliveryQueue?: import("@comis/core").DeliveryQueuePort;
     /** Optional active run registry for SDK-native steer+followup inbound routing */
     activeRunRegistry?: ActiveRunRegistry;
+    /**
+     * Optional composite-key resolver. Wired by the daemon as
+     * `createBackgroundSessionResolver({ activeRunRegistry })`; supersedes
+     * `activeRunRegistry.has/.get` for production lookups in the inbound
+     * pipeline.
+     */
+    sessionResolver?: BackgroundSessionResolver;
     /** RPC call dispatcher for /config chat commands (deferred dispatch -- safe to pass before wireDispatch). */
     rpcCall?: RpcCall;
     /** Optional callback for task extraction after successful agent execution (gated by config.scheduler.tasks.enabled). */
@@ -120,7 +127,7 @@ export interface ChannelsDeps {
     onMessageReceived?: (msg: NormalizedMessage, channelType: string) => void;
     /** Optional callback fired AFTER each successful inbound message processing. Used by post-processing state (e.g. notification session activity recording). */
     onMessageProcessed?: (msg: NormalizedMessage, channelType: string) => void;
-    /** Optional approval gate for /approve and /deny chat commands in inbound pipeline (APPR-CHAT). */
+    /** Optional approval gate for /approve and /deny chat commands in inbound pipeline. */
     approvalGate?: import("@comis/core").ApprovalGate;
     /** Per-agent PI session adapters for session stats/destroy in slash commands (CMD-WIRE). */
     piSessionAdapters?: Map<string, {

package/node_modules/@comis/daemon/dist/wiring/setup-channels.js

@@ -11,9 +11,8 @@
  */
 import { readdir, readFile, stat } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { join } from "node:path";
 import { formatSessionKey, runWithContext, createDeliveryOrigin, safePath } from "@comis/core";
-import { createMessageRouter, createCommandQueue, createCommandHandler, parseSlashCommand, sanitizeAssistantResponse, resolveOperationModel, resolveProviderFamily, runMemoryReview } from "@comis/agent";
+import { createMessageRouter, createCommandQueue, createCommandHandler, parseSlashCommand, sanitizeAssistantResponse, resolveOperationModel, resolveProviderFamily, runMemoryReview, classifyError } from "@comis/agent";
 import { createChannelManager, createRetryEngine, createApprovalNotifier, deliverToChannel, filterResponse, } from "@comis/channels";
 import { RetryConfigSchema } from "@comis/core";
 import { shouldAutoTts, resolveOutputFormat, parseOutboundMedia, applyToolPolicy, } from "@comis/skills";
@@ -96,7 +95,7 @@ export async function setupChannels(deps) {
                 return;
             }
             const workspacePath = deps.workspaceDirs?.get(agentId) ?? "";
-            const reviewLogger = logger.child({ agentId, module: "memory-review" });
+            const reviewLogger = logger.child({ agentId, submodule: "memory-review" });
             const reviewResult = await runMemoryReview({
                 agentId,
                 tenantId: deps.tenantId ?? container.config.tenantId ?? "default",
@@ -142,6 +141,25 @@ export async function setupChannels(deps) {
             // Extract session strategy from event payload (defaults: fresh, 3 turns)
             const sessionStrategy = payload.sessionStrategy ?? "fresh";
             const maxHistoryTurns = payload.maxHistoryTurns ?? 3;
+            // Cadence-aware cache-waste guard: rolling/accumulate strategies on long cadences
+            // guarantee cache-write waste because the prompt cache TTL is short (5 min for "cron"
+            // operations — see OPERATION_CACHE_DEFAULTS.cron in @comis/agent). Threshold = 2x TTL
+            // so we don't warn on borderline-useful 6-9 min cadences. Operator intent is preserved
+            // (no auto-downgrade) — this is informational only. Scoped to schedule.kind === "every"
+            // because cron-expression cadence is not threaded through the event payload.
+            const CRON_CACHE_TTL_2X_MS = 600_000;
+            if (sessionStrategy !== "fresh" &&
+                payload.cadenceMs !== undefined &&
+                payload.cadenceMs > CRON_CACHE_TTL_2X_MS) {
+                logger.warn({
+                    jobName,
+                    agentId: payload.agentId,
+                    sessionStrategy,
+                    cadenceMs: payload.cadenceMs,
+                    hint: "Cadence exceeds cache TTL by 2x; rolling/accumulate guarantees per-tick cache-write waste. Set sessionStrategy:'fresh' unless cross-tick session memory is essential.",
+                    errorKind: "config",
+                }, "Cron sessionStrategy may waste cache writes at this cadence");
+            }
             // Resolve cron operation model via 5-level priority chain
             const agentConfig = agents[payload.agentId];
             let cronOverrides;
@@ -353,9 +371,10 @@ export async function setupChannels(deps) {
             logger.warn({ channelType: deliveryTarget.channelType, jobName, hint: "Ensure the target channel adapter is started", errorKind: "config" }, "No adapter found for job suspension notification");
             return;
         }
+        const classified = classifyError(lastError);
         const message = [
             `Scheduled task "${jobName}" was suspended after ${consecutiveErrors} consecutive failures.`,
-            `Last error: ${lastError.slice(0, 200)}`,
+            `Reason: ${classified.userMessage}`,
             `Re-enable with /cron enable ${jobId}`,
         ].join("\n");
         try {
@@ -445,6 +464,7 @@ export async function setupChannels(deps) {
             voiceResponsePipeline,
             parseOutboundMedia,
             activeRunRegistry: deps.activeRunRegistry,
+            sessionResolver: deps.sessionResolver,
             queueConfig: deps.queueConfig,
             getElevatedReplyConfig: (agentId) => {
                 const agentConfig = agents[agentId];
@@ -498,8 +518,13 @@ export async function setupChannels(deps) {
                         return;
                     }
                     let graphDir;
+                    // Two-step safePath composition matches the canonical daemon-wiring
+                    // pattern in setup-output-retention.ts. Both safePath calls throw on
+                    // traversal; the surrounding catch handles either failure with a
+                    // single operator-facing WARN.
                     try {
-                        graphDir = safePath(join(dataDir, "graph-runs"), graphId);
+                        const graphRunsDir = safePath(dataDir, "graph-runs");
+                        graphDir = safePath(graphRunsDir, graphId);
                     }
                     catch {
                         channelsLogger.warn({ graphId, hint: "Path traversal attempt in graphId", errorKind: "validation" }, "Graph report request rejected");
@@ -510,7 +535,7 @@ export async function setupChannels(deps) {
                         await stat(graphDir);
                     }
                     catch {
-                        channelsLogger.warn({ graphId, graphDir, hint: "Graph run directory not found", errorKind: "not_found" }, "Graph report directory missing");
+                        channelsLogger.warn({ graphId, graphDir, hint: "Graph run directory not found", errorKind: "validation" }, "Graph report directory missing");
                         await adapter.sendMessage(channelId, "Report not available \u2014 graph run data not found.", threadId ? { extra: { threadId } } : undefined);
                         return;
                     }
@@ -524,7 +549,7 @@ export async function setupChannels(deps) {
                     // Try to identify leaf nodes from metadata
                     let leafOutputFile;
                     try {
-                        const metadataRaw = await readFile(join(graphDir, "_run-metadata.json"), "utf8");
+                        const metadataRaw = await readFile(safePath(graphDir, "_run-metadata.json"), "utf8");
                         const metadata = JSON.parse(metadataRaw);
                         const completedNodes = Object.entries(metadata.nodes)
                             .filter(([, v]) => v.status === "completed")
@@ -534,7 +559,7 @@ export async function setupChannels(deps) {
                         for (const f of outputFiles) {
                             const nodeId = f.replace(/-output\.md$/, "");
                             if (completedNodes.includes(nodeId)) {
-                                const fileStat = await stat(join(graphDir, f));
+                                const fileStat = await stat(safePath(graphDir, f));
                                 if (fileStat.size > maxSize) {
                                     maxSize = fileStat.size;
                                     leafOutputFile = f;
@@ -549,7 +574,7 @@ export async function setupChannels(deps) {
                         // Fallback: pick largest output file
                         let maxSize = 0;
                         for (const f of outputFiles) {
-                            const fileStat = await stat(join(graphDir, f));
+                            const fileStat = await stat(safePath(graphDir, f));
                             if (fileStat.size > maxSize) {
                                 maxSize = fileStat.size;
                                 leafOutputFile = f;
@@ -560,7 +585,7 @@ export async function setupChannels(deps) {
                         await adapter.sendMessage(channelId, "Report not available \u2014 could not identify output file.", threadId ? { extra: { threadId } } : undefined);
                         return;
                     }
-                    const filePath = join(graphDir, leafOutputFile);
+                    const filePath = safePath(graphDir, leafOutputFile);
                     const nodeId = leafOutputFile.replace(/-output\.md$/, "");
                     const caption = `Full report \u2014 ${nodeId} (graph ${graphId.slice(0, 8)})`;
                     await adapter.sendAttachment(channelId, {

package/node_modules/@comis/daemon/dist/wiring/setup-cross-session.d.ts

@@ -1,9 +1,9 @@
 /**
  * Cross-session messaging setup: cross-session sender and sub-agent runner.
- * Extracted from daemon.ts step 6.6.9 to isolate cross-session service
- * creation from the main wiring sequence. The three callback closures
- * (executeInSession, sendToChannel, executeSubAgent) are built internally
- * from injected dependencies (assembleToolsForAgent, getExecutor, adaptersByType).
+ * Isolates cross-session service creation from the main wiring sequence.
+ * The three callback closures (executeInSession, sendToChannel,
+ * executeSubAgent) are built internally from injected dependencies
+ * (assembleToolsForAgent, getExecutor, adaptersByType).
  * @module
  */
 import type { SessionKey } from "@comis/core";
@@ -14,7 +14,7 @@ import { createCrossSessionSender } from "../cross-session-sender.js";
 import { createSubAgentRunner } from "../sub-agent-runner.js";
 import { createAnnouncementBatcher } from "../announcement-batcher.js";
 import { createAnnouncementDeadLetterQueue } from "../announcement-dead-letter.js";
-/** All services produced by the cross-session messaging setup phase. */
+/** All services produced by the cross-session messaging setup. */
 export interface CrossSessionResult {
     /** Cross-session message sender for agent-to-agent communication. */
     crossSessionSender: ReturnType<typeof createCrossSessionSender>;
@@ -103,6 +103,21 @@ export declare function setupCrossSession(deps: {
             abort(): Promise<void>;
         } | undefined;
     };
+    /**
+     * Optional composite-key resolver. Threaded into sub-agent-runner so abort
+     * paths use `(agentId, channelType, channelId)` instead of a single-arg
+     * formatted-key lookup. Daemon builds it via
+     * `createBackgroundSessionResolver({activeRunRegistry})`.
+     */
+    sessionResolver?: {
+        resolveActiveSession(key: {
+            agentId: string;
+            channelType: string;
+            channelId: string;
+        }): {
+            abort(): Promise<void>;
+        } | undefined;
+    };
     /** Delivery queue for crash-safe persistence */
     deliveryQueue?: import("@comis/core").DeliveryQueuePort;
 }): CrossSessionResult;