comisai 1.0.33 → 1.0.36

package/node_modules/@comis/daemon/dist/rpc/credential-resolver.js

@@ -9,11 +9,24 @@
  * Resolution chain (matches pi-coding-agent runtime semantics):
  *   1. KEYLESS_PROVIDER_TYPES.has(entry.type) — ollama / lm-studio
  *   2. providers.entries.<provider>.apiKeyName → secretManager.has(...)
- *   3. pi-ai's getEnvApiKey(provider) — canonical env + OAuth + ADC + AWS
+ *   3. pi-ai's getEnvApiKey(provider) — canonical env vars (incl. ANTHROPIC_OAUTH_TOKEN
+ *      and AWS/ADC special-cases). Does NOT cover comis-managed OAuth profiles in
+ *      ~/.comis/auth-profiles.json (e.g. openai-codex).
+ *   4. Comis OAuth profiles — agent.oauthProfiles[provider] resolved against an
+ *      injected oauthProfileLoader (the OAuthCredentialStorePort handle held by
+ *      the daemon, adapted to a synchronous has-check at the call site).
+ *
+ * Note on synchronous loader facade (quick-260504-irq): `OAuthCredentialStorePort.has`
+ * is async (returns Promise<Result<boolean, Error>>). To avoid an async cascade
+ * through every call site, this resolver remains SYNCHRONOUS and accepts a
+ * sync facade (`oauthProfileLoader: { has(profileId: string): boolean }`).
+ * The async port `has()` call MUST be performed at the daemon edge
+ * (config-handlers / agent-handlers) and adapted into the closure. This keeps
+ * the port-side validator I/O-free (Hexagonal: validator does no I/O).
  *
  * @module
  */
-import { getEnvApiKey } from "@mariozechner/pi-ai";
+import { getEnvApiKey, getProviders, getModels } from "@mariozechner/pi-ai";
 /**
  * Provider types that don't need an API key. Mirrors agent's
  * KEYLESS_PROVIDER_TYPES at model-registry-adapter.ts:60 — extended here to
@@ -28,23 +41,73 @@ export function resolveProviderCredential(targetProvider, deps) {
             reason: `Invalid provider value: must be a non-empty string (got ${JSON.stringify(targetProvider)})`,
         };
     }
-    // eslint-disable-next-line security/detect-object-injection -- typed Record<string, ProviderEntry> read; targetProvider validated above
-    const entry = deps.providerEntries?.[targetProvider];
+    // Resolve `provider: "default"` to the operator's configured default,
+    // mirroring runtime resolution in `resolveAgentModel`:
+    //   1. If `providers.entries.default` is explicitly configured, treat that
+    //      as the operator's intent — the entry itself carries the credential
+    //      resolution path (keyless / apiKeyName).
+    //   2. Else, if `models.defaultProvider` is set, use that.
+    //   3. Otherwise, fall back to the most-populated native provider in the
+    //      pi-ai catalog (same heuristic the runtime applies).
+    // This keeps the credential check semantically aligned with the literal
+    // provider the runtime will select.
+    let effectiveProvider = targetProvider;
+    if (targetProvider.toLowerCase() === "default") {
+        const explicitDefault = deps.providerEntries?.default;
+        if (!explicitDefault) {
+            const dp = deps.modelsConfig?.defaultProvider;
+            if (dp && dp.length > 0) {
+                effectiveProvider = dp;
+            }
+            else {
+                const allProviders = getProviders();
+                if (allProviders.length > 0) {
+                    effectiveProvider = allProviders
+                        .map((p) => ({ p, n: getModels(p).length }))
+                        .sort((a, b) => b.n - a.n)[0].p;
+                }
+            }
+        }
+    }
+    // eslint-disable-next-line security/detect-object-injection -- typed Record<string, ProviderEntry> read; effectiveProvider validated above
+    const entry = deps.providerEntries?.[effectiveProvider];
     // 1. Keyless types
     if (entry && KEYLESS_PROVIDER_TYPES.has(entry.type)) {
-        return { ok: true, source: "keyless" };
+        return { ok: true, source: "keyless", resolvedProvider: effectiveProvider };
     }
     // 2. Source A: providers.entries with secret-manager-resolvable apiKeyName
     if (entry?.apiKeyName && deps.secretManager?.has(entry.apiKeyName)) {
-        return { ok: true, source: "providers_entry" };
+        return { ok: true, source: "providers_entry", resolvedProvider: effectiveProvider };
+    }
+    // 3. Source C: comis OAuth profile (per-agent agents.<id>.oauthProfiles).
+    //    Covers OAuth-only providers like openai-codex whose tokens live in
+    //    ~/.comis/auth-profiles.json — pi-ai's getEnvApiKey does NOT see them.
+    //    Inserted before Source B so OAuth profiles win over env-canonical when
+    //    both would resolve (the operator explicitly configured the profile).
+    // eslint-disable-next-line security/detect-object-injection -- typed Record<string, string> read; effectiveProvider validated above
+    const configuredProfileId = deps.oauthProfiles?.[effectiveProvider];
+    if (configuredProfileId && deps.oauthProfileLoader?.has(configuredProfileId)) {
+        return { ok: true, source: "oauth_profile", resolvedProvider: effectiveProvider };
     }
-    // 3. Source B: pi-ai canonical env / OAuth / ADC chain
-    if (getEnvApiKey(targetProvider)) {
-        return { ok: true, source: "env_canonical" };
+    // 4. Source B: pi-ai canonical env / OAuth / ADC chain
+    if (getEnvApiKey(effectiveProvider)) {
+        return { ok: true, source: "env_canonical", resolvedProvider: effectiveProvider };
     }
-    return { ok: false, reason: buildRejectionMessage(targetProvider, entry) };
+    return { ok: false, reason: buildRejectionMessage(effectiveProvider, entry, configuredProfileId) };
 }
-function buildRejectionMessage(targetProvider, entry) {
+function buildRejectionMessage(targetProvider, entry, configuredProfileId) {
+    // OAuth-aware rejection: when the agent has an oauthProfiles entry for this
+    // provider but the loader could not confirm the profile, the failure mode is
+    // a missing OAuth profile (not a missing API key). Point the operator at
+    // `comis auth login` rather than env_set / apiKeyName recovery.
+    if (configuredProfileId) {
+        const lines = [];
+        lines.push(`Cannot set agent provider to "${targetProvider}": OAuth profile "${configuredProfileId}" is configured but not found in the OAuth credential store (~/.comis/auth-profiles.json).`);
+        lines.push(`Recovery:`);
+        lines.push(`  Run \`comis auth login --provider ${targetProvider}\` to (re)authenticate and create the profile, then retry this patch.`);
+        lines.push(`  Run \`comis auth list\` to see currently stored profiles.`);
+        return lines.join("\n");
+    }
     const lines = [];
     lines.push(`Cannot set agent provider to "${targetProvider}": no API key found.`);
     if (entry?.apiKeyName) {

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

@@ -6,6 +6,7 @@
  */
 import type { McpClientManager } from "@comis/skills";
 import type { ComisLogger } from "@comis/infra";
+import type { SecretManager } from "@comis/core";
 import type { RpcHandler } from "./types.js";
 /** Dependencies required by MCP management RPC handlers. */
 export interface McpHandlerDeps {
@@ -17,6 +18,13 @@ export interface McpHandlerDeps {
     mcpClientManager: McpClientManager;
     /** Logger for MCP test connection (used by temporary manager). */
     logger: ComisLogger;
+    /**
+     * Optional SecretManager for env-ref validation on mcp.connect. When
+     * undefined (legacy/test wiring), the env-ref check is skipped — the
+     * existing connect behavior is preserved. In production it is always
+     * wired via `deps.container.secretManager` from rpc-dispatch.
+     */
+    secretManager?: SecretManager;
 }
 /**
  * Create a record of MCP management RPC handlers bound to the given deps.

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