comisai 1.0.34 → 1.0.36

package/node_modules/@comis/daemon/dist/rpc/mcp-handlers.js

@@ -6,6 +6,7 @@
  * @module
  */
 import { createMcpClientManager } from "@comis/skills";
+import { findUnresolvedEnvRefs, formatMissingEnvRefError } from "@comis/core";
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -30,9 +31,9 @@ export function createMcpHandlers(deps) {
             return { servers, total: servers.length };
         },
         "mcp.status": async (params) => {
-            const name = params.name;
+            const name = params.server_name;
             if (!name)
-                throw new Error("Missing required parameter: name");
+                throw new Error("Missing required parameter: server_name");
             const manager = deps.mcpClientManager;
             const conn = manager.getConnection(name);
             if (!conn) {
@@ -59,10 +60,10 @@ export function createMcpHandlers(deps) {
             };
         },
         "mcp.connect": async (params) => {
-            const name = params.name;
+            const name = params.server_name;
             const transport = params.transport;
             if (!name)
-                throw new Error("Missing required parameter: name");
+                throw new Error("Missing required parameter: server_name");
             if (!transport)
                 throw new Error("Missing required parameter: transport");
             const manager = deps.mcpClientManager;
@@ -76,6 +77,19 @@ export function createMcpHandlers(deps) {
                 headers: params.headers,
                 enabled: true,
             };
+            // Reject connects that reference env vars not in the secrets store.
+            // mcp.connect is unconditionally enabled (config.enabled = true
+            // above), so the check always applies when both env and secretManager
+            // are present. Skipped only when secretManager is unwired (test
+            // setups) — production always wires it via rpc-dispatch.
+            if (config.env && deps.secretManager) {
+                const sm = deps.secretManager;
+                const unresolved = findUnresolvedEnvRefs(config.env, (key) => sm.get(key));
+                if (unresolved.length > 0) {
+                    const missingNames = unresolved.map((u) => u.varName);
+                    throw new Error(formatMissingEnvRefError(name, missingNames));
+                }
+            }
             const result = await manager.connect(config);
             if (!result.ok) {
                 throw new Error(`Failed to connect MCP server "${name}": ${result.error.message}`);
@@ -88,9 +102,9 @@ export function createMcpHandlers(deps) {
             };
         },
         "mcp.disconnect": async (params) => {
-            const name = params.name;
+            const name = params.server_name;
             if (!name)
-                throw new Error("Missing required parameter: name");
+                throw new Error("Missing required parameter: server_name");
             const manager = deps.mcpClientManager;
             const conn = manager.getConnection(name);
             if (!conn) {
@@ -148,9 +162,9 @@ export function createMcpHandlers(deps) {
             }
         },
         "mcp.reconnect": async (params) => {
-            const name = params.name;
+            const name = params.server_name;
             if (!name)
-                throw new Error("Missing required parameter: name");
+                throw new Error("Missing required parameter: server_name");
             const manager = deps.mcpClientManager;
             // Use manager's reconnect (preserves generation counter, uses stored config)
             const result = await manager.reconnect(name);

package/node_modules/@comis/daemon/dist/rpc/provider-handlers.js

@@ -196,20 +196,17 @@ export function createProviderHandlers(deps) {
                 throw new Error(`Provider already exists: ${providerId}`);
             }
             const config = params.config ?? {};
-            // 260501-gyy: reject redundant catalog-shadowing entries before
-            // promotion / probe / persist. A built-in provider with a catalog
-            // (or absent) baseUrl is structurally redundant -- pi-ai's dynamic
-            // catalog already provides its model list. Production trace
-            // 2026-05-01 08:53 showed an LLM agent creating
-            // providers.entries.openrouter with an invented model id, leading
-            // to a downstream 404.
+            // Reject redundant catalog-shadowing entries before promotion / probe
+            // / persist. A built-in provider with a catalog (or absent) baseUrl is
+            // structurally redundant -- pi-ai's dynamic catalog already provides
+            // its model list.
             const guardResult = checkBuiltInProviderRedundancy(providerId, config);
             if (!guardResult.ok) {
                 throw new Error(guardResult.reason);
             }
-            // Layer 1C (260430-vwt): auto-promote type to native catalog name
-            // when the providerId matches a pi-ai catalog entry AND the user has
-            // not opted out via a custom baseUrl.
+            // Auto-promote type to native catalog name when the providerId
+            // matches a pi-ai catalog entry AND the user has not opted out via a
+            // custom baseUrl.
             const normalizedConfig = normalizeProviderEntry(providerId, config, deps.persistDeps?.logger);
             const parsedConfig = ProviderEntrySchema.parse(normalizedConfig);
             // Probe provider API key before committing config
@@ -260,8 +257,8 @@ export function createProviderHandlers(deps) {
             // Capture user-provided fields BEFORE merge -- persistToConfig does deepMerge internally,
             // so we only persist the user's partial patch (not the fully merged config).
             const userPatch = params.config ? structuredClone(params.config) : {};
-            // Layer 1C (260430-vwt): on update, only auto-promote when the user
-            // is actively changing the `type` field. If `type` is absent from
+            // On update, only auto-promote when the user is actively changing
+            // the `type` field. If `type` is absent from
             // the patch, the user is editing other fields and we must not
             // rewrite their existing type silently.
             let normalizedPatch = config;

package/node_modules/@comis/daemon/dist/rpc/rpc-dispatch.d.ts

@@ -185,6 +185,7 @@ export interface RpcDispatchDeps {
     globalHeartbeatConfig?: Record<string, unknown>;
     notificationService?: import("../notification/notification-service.js").NotificationService;
     imageHandlerDeps?: ImageHandlerDeps;
+    oauthCredentialStore?: import("@comis/core").OAuthCredentialStorePort;
 }
 /**
  * Classify an RPC error message for structured logging.

package/node_modules/@comis/daemon/dist/rpc/rpc-dispatch.js

@@ -71,7 +71,17 @@ export function createRpcDispatch(deps) {
         ...createSessionHandlers(deps),
         ...createMessageHandlers(deps),
         ...createMediaHandlers(deps),
-        ...createConfigHandlers(deps),
+        // Thread the daemon-level OAuth credential store into config.patch's
+        // credential guard so model/provider patches on OAuth-only providers
+        // (e.g. openai-codex) can resolve via Source C
+        // (agents.<id>.oauthProfiles -> ~/.comis/auth-profiles.json). Explicit
+        // pass-through mirrors the createAgentHandlers wiring below; do not
+        // simplify back to `...createConfigHandlers(deps)` (the structural-typing
+        // inheritance is fragile to future deps-shape narrowing).
+        ...createConfigHandlers({
+            ...deps,
+            oauthCredentialStore: deps.oauthCredentialStore,
+        }),
         ...createEnvHandlers(deps),
         ...createBrowserHandlers(deps),
         ...createSubagentHandlers(deps),
@@ -90,6 +100,14 @@ export function createRpcDispatch(deps) {
             ...deps,
             secretManager: deps.container?.secretManager,
             providerEntries: deps.container.config.providers.entries,
+            // Thread the daemon-level OAuth credential store into agents.update
+            // so the oauthProfiles existence check can run via has(). When unset
+            // (e.g. unwired test setups) the validation block in agent-handlers
+            // becomes a no-op.
+            oauthCredentialStore: deps.oauthCredentialStore,
+            // Resolves `provider: "default"` to `models.defaultProvider` in the
+            // credential check, mirroring `resolveAgentModel` runtime resolution.
+            modelsConfig: deps.container.config.models,
             persistDeps: {
                 container: deps.container,
                 configPaths: deps.configPaths,
@@ -135,7 +153,14 @@ export function createRpcDispatch(deps) {
                 logger: deps.logger,
             },
         }),
-        ...createMcpHandlers({ mcpClientManager: deps.mcpClientManager, logger: deps.logger }),
+        ...createMcpHandlers({
+            mcpClientManager: deps.mcpClientManager,
+            logger: deps.logger,
+            // Threaded for env-ref validation on mcp.connect. Same pattern as
+            // agent/provider handlers above. When undefined the validator becomes
+            // a no-op.
+            secretManager: deps.container?.secretManager,
+        }),
         ...createDaemonHandlers({ logLevelManager: deps.logLevelManager }),
         // Workspace file management handlers
         ...createWorkspaceHandlers({

package/node_modules/@comis/daemon/dist/setup-docker-restart-warn.js

@@ -25,6 +25,5 @@ export function emitDockerRestartPolicyWarn(logger, opts = {}) {
     logger.warn({
         hint: "Wizard 'Restart' actions, gateway.restart, gateway.env_set, and gateway.patch on restart-triggering paths all require the container to have --restart unless-stopped (or compose restart: unless-stopped). Verify from your host with: docker inspect <name> --format '{{.HostConfig.RestartPolicy.Name}}'",
         errorKind: "config",
-        module: "daemon",
     }, "Running in Docker — restart policy required for config-reload operations");
 }

package/node_modules/@comis/daemon/dist/wiring/index.d.ts

@@ -17,3 +17,5 @@ export { setupGateway, type GatewayDeps, type GatewayResult, setupRpcBridge, typ
 export { setupDeliveryQueue, type DeliveryQueueResult, setupDeliveryMirror, type DeliveryMirrorResult } from "./setup-delivery.js";
 export { setupNotifications, type NotificationContext } from "./setup-notifications.js";
 export { setupBackgroundTasks, type BackgroundTasksContext } from "./setup-background-tasks.js";
+export { setupBackgroundCompletionRunner } from "./setup-background-completion-runner.js";
+export type { BackgroundCompletionRunnerContext, SetupBackgroundCompletionRunnerDeps, } from "./setup-background-completion-runner.js";

package/node_modules/@comis/daemon/dist/wiring/index.js

@@ -16,3 +16,4 @@ export { setupGateway, setupRpcBridge } from "./setup-gateway.js";
 export { setupDeliveryQueue, setupDeliveryMirror } from "./setup-delivery.js";
 export { setupNotifications } from "./setup-notifications.js";
 export { setupBackgroundTasks } from "./setup-background-tasks.js";
+export { setupBackgroundCompletionRunner } from "./setup-background-completion-runner.js";

package/node_modules/@comis/daemon/dist/wiring/oauth-preflight.d.ts

@@ -0,0 +1,21 @@
+import type { ComisLogger } from "@comis/infra";
+import type { PerAgentConfig } from "@comis/core";
+/**
+ * Returns `true` iff at least one agent's `provider` is recognised by pi-ai's
+ * `getOAuthProvider` as an OAuth-using provider.
+ *
+ * Single-source-of-truth check — avoids drift with pi-ai's provider catalogue.
+ * When this returns `false`, the daemon skips the preflight entirely (zero
+ * outbound probes during boot for OAuth-less deployments).
+ */
+export declare function hasAnyOAuthAgent(agents: Record<string, PerAgentConfig>): boolean;
+/**
+ * Run the OAuth TLS preflight and emit a single structured log line if it
+ * fails. Never throws — `runOAuthTlsPreflight` returns a discriminated union
+ * and this function only reads-and-logs.
+ *
+ * Caller is expected to invoke this fire-and-forget (`void`) AFTER the
+ * `"Comis daemon started"` banner so the daemon already counts as healthy
+ * to PM2/systemd by the time the probe resolves.
+ */
+export declare function emitOAuthTlsPreflightWarn(logger: ComisLogger): Promise<void>;

package/node_modules/@comis/daemon/dist/wiring/oauth-preflight.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Boot-time OAuth TLS preflight wiring.
+ *
+ * Two helpers exposed for the daemon entry point:
+ *
+ *   1. `hasAnyOAuthAgent(agents)` — runtime gate. Returns `true` iff at least
+ *      one entry in the per-agent map declares a `provider` value that
+ *      pi-ai's `getOAuthProvider` recognises as an OAuth provider. Used to
+ *      skip the entire preflight (and any outbound network probe) when no
+ *      OAuth-using agent is configured.
+ *
+ *   2. `emitOAuthTlsPreflightWarn(logger)` — fire-and-forget. Calls
+ *      `runOAuthTlsPreflight({ timeoutMs: 4000 })` from `@comis/agent`
+ *      and surfaces the result via Pino:
+ *        - `kind: "tls-cert"` → exactly one WARN with module + errorKind +
+ *          distro-aware install hint + OpenSSL `code` + raw `message`.
+ *        - `kind: "network"` → a single DEBUG (no WARN — transient failures
+ *          should not pollute the boot path).
+ *        - `{ ok: true }` → silent (operators do not want noise on boot).
+ *
+ * The 4000 ms timeout is intentionally tighter than the CLI doctor variant's
+ * 5000 ms — boot must stay under PM2 / systemd watchdog windows even on the
+ * worst case.
+ *
+ * Distro detection (`/etc/os-release` parser + 5-distro install-hint switch)
+ * is duplicated inline from `packages/cli/src/doctor/checks/oauth-health.ts`.
+ * Per AGENTS.md §2.3 rule of three, two callers do not yet justify a shared
+ * helper. If a third caller appears, extract the pair to
+ * `packages/agent/src/model/oauth-os-release.ts`.
+ *
+ * Per AGENTS.md §2.4 the logger is injected — no `@comis/infra` import.
+ *
+ * @module
+ */
+import { readFile } from "node:fs/promises";
+import { runOAuthTlsPreflight } from "@comis/agent";
+import { getOAuthProvider } from "@mariozechner/pi-ai/oauth";
+/** Boot-tighter timeout — keeps the preflight inside PM2/systemd watchdog windows. */
+const PREFLIGHT_TIMEOUT_MS = 4000;
+/** Pino `module` field — operators grep on this to isolate preflight logs. */
+const MODULE_NAME = "oauth-tls-preflight";
+/**
+ * Returns `true` iff at least one agent's `provider` is recognised by pi-ai's
+ * `getOAuthProvider` as an OAuth-using provider.
+ *
+ * Single-source-of-truth check — avoids drift with pi-ai's provider catalogue.
+ * When this returns `false`, the daemon skips the preflight entirely (zero
+ * outbound probes during boot for OAuth-less deployments).
+ */
+export function hasAnyOAuthAgent(agents) {
+    return Object.values(agents).some((agent) => Boolean(getOAuthProvider(agent.provider)));
+}
+/**
+ * Parses `/etc/os-release` into `{ id, idLike }`. Returns `null` on read
+ * error (missing file, permission denied, malformed contents).
+ *
+ * Verbatim duplication from `oauth-health.ts` — see module JSDoc for the
+ * AGENTS.md §2.3 deferral rationale.
+ */
+async function readOsRelease(path = "/etc/os-release") {
+    try {
+        const text = await readFile(path, "utf-8");
+        const map = new Map();
+        for (const line of text.split("\n")) {
+            const m = line.match(/^([A-Z_]+)=(.*)$/);
+            if (m)
+                map.set(m[1], m[2].replace(/^"|"$/g, ""));
+        }
+        const id = map.get("ID") ?? "";
+        const idLike = (map.get("ID_LIKE") ?? "").split(/\s+/).filter(Boolean);
+        return { id, idLike };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Produces a distro-aware install command for the system CA bundle.
+ *
+ * Verbatim duplication from `oauth-health.ts` — see module JSDoc for the
+ * AGENTS.md §2.3 deferral rationale.
+ */
+function caCertificatesInstallHint(os) {
+    if (!os)
+        return "Install ca-certificates via your distro's package manager and retry";
+    const idChain = [os.id, ...os.idLike];
+    if (idChain.includes("alpine"))
+        return "apk add ca-certificates && update-ca-certificates";
+    if (idChain.includes("debian") || idChain.includes("ubuntu")) {
+        return "sudo apt-get install -y ca-certificates && sudo update-ca-certificates";
+    }
+    if (idChain.includes("fedora") || idChain.includes("rhel") || idChain.includes("centos")) {
+        return "sudo dnf install -y ca-certificates && sudo update-ca-trust";
+    }
+    if (idChain.includes("arch"))
+        return "sudo pacman -S ca-certificates && sudo trust extract-compat";
+    if (idChain.includes("suse") || idChain.includes("opensuse")) {
+        return "sudo zypper install ca-certificates && sudo update-ca-certificates";
+    }
+    return "Install ca-certificates via your distro's package manager and retry";
+}
+/**
+ * Run the OAuth TLS preflight and emit a single structured log line if it
+ * fails. Never throws — `runOAuthTlsPreflight` returns a discriminated union
+ * and this function only reads-and-logs.
+ *
+ * Caller is expected to invoke this fire-and-forget (`void`) AFTER the
+ * `"Comis daemon started"` banner so the daemon already counts as healthy
+ * to PM2/systemd by the time the probe resolves.
+ */
+export async function emitOAuthTlsPreflightWarn(logger) {
+    const result = await runOAuthTlsPreflight({ timeoutMs: PREFLIGHT_TIMEOUT_MS });
+    if (result.ok)
+        return;
+    if (result.kind === "tls-cert") {
+        const os = await readOsRelease();
+        const hint = caCertificatesInstallHint(os);
+        logger.warn({
+            submodule: MODULE_NAME,
+            errorKind: "oauth_tls_cert",
+            hint,
+            code: result.code,
+            message: result.message,
+        }, "OAuth TLS preflight failed: system CA bundle cannot validate auth.openai.com");
+        return;
+    }
+    // kind === "network" — transient outage / DNS / firewall. DEBUG only.
+    logger.debug({
+        submodule: MODULE_NAME,
+        errorKind: "oauth_tls_network",
+        message: result.message,
+    }, "OAuth TLS preflight network failure (skipping WARN — likely transient)");
+}

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

@@ -5,8 +5,9 @@
  * All agents use PiExecutor (pi-coding-agent AgentSession wrapper).
  * @module
  */
-import { type AppContainer, type InjectionRateLimiter, type PerAgentConfig } from "@comis/core";
+import { type AppContainer, type InjectionRateLimiter, type OAuthCredentialStorePort, type SecretsCrypto, type PerAgentConfig } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
+import type Database from "better-sqlite3";
 import type { SqliteMemoryAdapter, createSessionStore } from "@comis/memory";
 import { createBudgetGuard, createCostTracker, createStepCounter, createSessionLifecycle, createComisSessionManager, type AgentExecutor, type ActiveRunRegistry, type ProviderHealthMonitor, type LastKnownModelTracker } from "@comis/agent";
 import { type SkillRegistry, type SkillWatcherHandle } from "@comis/skills";
@@ -59,6 +60,32 @@ export interface SingleAgentDeps {
     backgroundTaskManager?: import("@comis/agent").BackgroundTaskManager;
     /** Callback to send completion notifications for background tasks. */
     backgroundNotifyFn?: import("@comis/agent").NotifyFn;
+    /**
+     * SecretsCrypto engine bound to SECRETS_MASTER_KEY. Defined when the daemon
+     * was started with a valid master key (encrypted-secrets mode). Required
+     * when `appConfig.oauth.storage === "encrypted"` — selectOAuthCredentialStore
+     * fails fast with an operator hint when missing.
+     */
+    secretsCrypto?: SecretsCrypto;
+    /**
+     * Shared better-sqlite3 handle to secrets.db (the SqliteSecretStoreHandle.db
+     * field, plumbed through from daemon.ts after createSqliteSecretStore).
+     * Required when `appConfig.oauth.storage === "encrypted"` so the OAuth
+     * profile adapter can share the existing connection rather than opening a
+     * second handle to the same DB file — eliminates the dual-handle lifecycle
+     * hazards: close-order, schema-init double-execution, prepared-statement
+     * cache fragmentation.
+     */
+    secretsDb?: Database.Database;
+    /**
+     * The daemon-level OAuthCredentialStore handle. Constructed ONCE in
+     * setupAgents() and passed down to every per-agent setupSingleAgent call
+     * AND surfaced on AgentsResult so daemon.ts can thread it into
+     * RpcDispatchDeps for `agents.update` existence checks. Single shared
+     * handle (file backend is stateless on a shared path; encrypted backend
+     * shares the secretsDb connection).
+     */
+    oauthCredentialStore: OAuthCredentialStorePort;
 }
 /** Per-agent outputs from setupSingleAgent(), matching the Maps in AgentsResult. */
 export interface SingleAgentResult {
@@ -103,6 +130,12 @@ export interface AgentsResult {
     singleAgentDeps: SingleAgentDeps;
     /** Global provider health monitor for daemon-level health metrics */
     providerHealth: ProviderHealthMonitor;
+    /**
+     * Daemon-level OAuthCredentialStore handle. Threaded into
+     * RpcDispatchDeps so agents.update can validate oauthProfiles patches
+     * via has().
+     */
+    oauthCredentialStore: OAuthCredentialStorePort;
 }
 /**
  * Set up a single agent's executor and all supporting services.
@@ -162,6 +195,18 @@ export declare function setupAgents(deps: {
     backgroundTaskManager?: import("@comis/agent").BackgroundTaskManager;
     /** Callback to send completion notifications for background tasks. */
     backgroundNotifyFn?: import("@comis/agent").NotifyFn;
+    /**
+     * SecretsCrypto engine bound to SECRETS_MASTER_KEY. Defined when daemon
+     * was started with a valid master key. Required for
+     * `appConfig.oauth.storage === "encrypted"` mode.
+     */
+    secretsCrypto?: SecretsCrypto;
+    /**
+     * Shared better-sqlite3 handle to secrets.db. Plumbed from daemon.ts where
+     * createSqliteSecretStore now exposes its db field. Required for
+     * `appConfig.oauth.storage === "encrypted"` mode.
+     */
+    secretsDb?: Database.Database;
 }): Promise<AgentsResult>;
 /**
  * Resolve "default" model/provider placeholders to concrete values from the

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

@@ -13,8 +13,15 @@ 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 +111,75 @@ 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. Line ~222 above writes effectiveConfig (a NEW object built
+            //      from { ...agentConfig, model, provider }) into
+            //      container.config.agents[agentId]. The local `agentConfig`
+            //      parameter diverges from the daemon's 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:594, 634 confirm `deps.agents` and
+            //      `container.config.agents` are THE SAME map object — the
+            //      daemon's 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) {
@@ -235,6 +311,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,
@@ -312,9 +393,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
@@ -368,6 +463,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 +503,12 @@ 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,
     };
     for (const [agentId, agentConfig] of Object.entries(agents)) {
         const result = await setupSingleAgent(agentId, agentConfig, singleAgentDeps);
@@ -451,6 +565,10 @@ export async function setupAgents(deps) {
         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 +661,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,39 @@
+/**
+ * Background completion runner wiring for daemon startup.
+ *
+ * Subscribes the runner to background_task:{completed,failed} events after
+ * the notification service has been wired (so fallbackNotifyFn is live),
+ * and returns a shutdown handle for the daemon's system:shutdown sequence
+ * to await before tearing down the executor.
+ *
+ * Per AGENTS §2.4: composition root + factories. This wiring lives in
+ * @comis/daemon (composition root); the actual factory body is in
+ * @comis/agent.
+ *
+ * @module
+ */
+import { type BackgroundCompletionRunner, type BackgroundTaskManager, 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;
+}
+export interface SetupBackgroundCompletionRunnerDeps {
+    eventBus: TypedEventBus;
+    getExecutor: (agentId: string) => AgentExecutor;
+    sessionStore: RunnerSessionStore;
+    taskManager: Pick<BackgroundTaskManager, "getTask">;
+    /** 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 background completion runner from daemon-level dependencies.
+ * Call this AFTER setupNotifications so fallbackNotifyFn is wired.
+ */
+export declare function setupBackgroundCompletionRunner(deps: SetupBackgroundCompletionRunnerDeps): BackgroundCompletionRunnerContext;