comisai 1.0.33 → 1.0.36

package/node_modules/@comis/core/dist/config/loader.js

@@ -74,11 +74,18 @@ export function loadConfigFile(filePath, options) {
         }
         // Step 3: Substitute ${VAR} references (if getSecret provided)
         if (options?.getSecret) {
+            // Stash disabled MCP server entries before substitution. A disabled
+            // server may legitimately reference env vars the user has not set yet
+            // (e.g., a placeholder finnhub entry awaiting an API key). Substitution
+            // must not fail bootstrap on those — they are filtered out at
+            // connect-time in setup-mcp.ts. Originals are restored verbatim after.
+            const stash = stashDisabledMcpServers(processed);
             const subResult = substituteEnvVars(processed, options.getSecret, resolved);
             if (!subResult.ok) {
                 return subResult;
             }
             processed = subResult.value;
+            restoreDisabledMcpServers(processed, stash);
         }
         return ok(processed);
     }
@@ -108,3 +115,57 @@ export function validateConfig(raw) {
         details: result.error.issues,
     });
 }
+/**
+ * Replace `enabled: false` MCP server entries in
+ * `integrations.mcp.servers[]` with neutral stubs and return the originals
+ * so `restoreDisabledMcpServers` can put them back after env substitution.
+ *
+ * Mutates `processed` in place. The stub keeps no env-substitutable fields,
+ * so substitution sees no `${VAR}` refs from disabled servers.
+ */
+function stashDisabledMcpServers(processed) {
+    const integrations = processed.integrations;
+    if (integrations === null || typeof integrations !== "object" || Array.isArray(integrations)) {
+        return [];
+    }
+    const mcp = integrations.mcp;
+    if (mcp === null || typeof mcp !== "object" || Array.isArray(mcp))
+        return [];
+    const servers = mcp.servers;
+    if (!Array.isArray(servers))
+        return [];
+    const stash = [];
+    for (let idx = 0; idx < servers.length; idx++) {
+        const srv = servers[idx];
+        if (srv === null || typeof srv !== "object" || Array.isArray(srv))
+            continue;
+        if (srv.enabled !== false)
+            continue;
+        stash.push({ idx, original: srv });
+        servers[idx] = { enabled: false };
+    }
+    return stash;
+}
+/**
+ * Restore originals previously saved by `stashDisabledMcpServers`. Operates
+ * on the substituted tree (a fresh object returned by `substituteEnvVars`),
+ * walking back to the same array index. No-op when stash is empty.
+ */
+function restoreDisabledMcpServers(processed, stash) {
+    if (stash.length === 0)
+        return;
+    const integrations = processed.integrations;
+    if (integrations === null || typeof integrations !== "object" || Array.isArray(integrations)) {
+        return;
+    }
+    const mcp = integrations.mcp;
+    if (mcp === null || typeof mcp !== "object" || Array.isArray(mcp))
+        return;
+    const servers = mcp.servers;
+    if (!Array.isArray(servers))
+        return;
+    for (const { idx, original } of stash) {
+        if (idx < servers.length)
+            servers[idx] = original;
+    }
+}

package/node_modules/@comis/core/dist/config/managed-sections.d.ts

@@ -41,7 +41,7 @@ export interface ManagedSectionRedirect {
      * fields fit in < 20 lines of hint text. Verified against the tool's
      * TypeBox parameter schema as of this commit.
      *
-     * Bug B (260428-gj6): production trace c7b91328 showed the agent burning
+     * Bug B: production trace c7b91328 showed the agent burning
      * ~30s × 4 LLM calls re-loading the agents_manage schema after an
      * immutable-path rejection. Surfacing the fragment inline closes that
      * round-trip tax.
@@ -91,8 +91,8 @@ export declare function getManagedSectionRedirect(section: string | undefined, k
  *   stub forwards to the real tool and registers it as discovered).
  *
  * Naming `discover_tools` in the hint actively misleads Anthropic
- * Sonnet/Opus 4.x because that tool is not in their payload (260428-oyc
- * production repro: agent saw "Recovery: (1) call discover_tools(...)" and
+ * Sonnet/Opus 4.x because that tool is not in their payload (production
+ * repro: agent saw "Recovery: (1) call discover_tools(...)" and
  * gave up, reporting "I don't have a discover_tools function"). The
  * single-step framing works on every provider.
  *

package/node_modules/@comis/core/dist/config/managed-sections.js

@@ -30,7 +30,7 @@ export const MANAGED_SECTIONS = [
         // Flat parameter shape -- verified against mcp-manage-tool.ts McpManageToolParams.
         exampleArgs: {
             action: "connect",
-            name: "<server-name>",
+            server_name: "<server-name>",
             transport: "stdio",
             command: "<command>",
             args: [],
@@ -44,7 +44,7 @@ export const MANAGED_SECTIONS = [
         schemaFragment: {
             actions: ["list", "status", "connect", "disconnect", "reconnect"],
             requiredByAction: {
-                connect: ["name", "transport", "command"],
+                connect: ["server_name", "transport", "command"],
             },
         },
     },
@@ -120,6 +120,11 @@ export const MANAGED_SECTIONS = [
                 model: "<model-id>",
                 provider: "<provider>",
                 maxSteps: 100,
+                // Advertise the per-agent OAuth profile preference to the LLM.
+                // Maps provider → "<provider>:<identity>" stored profile ID.
+                // Validated end-to-end by the Zod refine and daemon-side has()
+                // existence check.
+                oauthProfiles: { "openai-codex": "openai-codex:user@example.com" },
             },
         },
         fullyManaged: true,
@@ -173,8 +178,8 @@ export function getManagedSectionRedirect(section, key) {
  *   stub forwards to the real tool and registers it as discovered).
  *
  * Naming `discover_tools` in the hint actively misleads Anthropic
- * Sonnet/Opus 4.x because that tool is not in their payload (260428-oyc
- * production repro: agent saw "Recovery: (1) call discover_tools(...)" and
+ * Sonnet/Opus 4.x because that tool is not in their payload (production
+ * repro: agent saw "Recovery: (1) call discover_tools(...)" and
  * gave up, reporting "I don't have a discover_tools function"). The
  * single-step framing works on every provider.
  *
@@ -195,7 +200,7 @@ export function formatRedirectHint(redirect, mutablePaths) {
     else {
         parts.push(`Call ${redirect.tool} directly; it will auto-load on first invocation.`);
     }
-    // Bug B (260428-gj6): inline the dedicated tool's action enum + required
+    // Bug B: inline the dedicated tool's action enum + required
     // fields so the LLM can call it without a separate discover_tools round-
     // trip. Positioned AFTER the Recovery example (so the example is the first
     // thing the model sees) and BEFORE the mutablePaths block (which is the

package/node_modules/@comis/core/dist/config/schema-agent.d.ts

@@ -1783,6 +1783,7 @@ export declare const PerAgentConfigSchema: z.ZodObject<{
         maxTotal: z.ZodDefault<z.ZodNumber>;
         maxBackgroundDurationMs: z.ZodDefault<z.ZodNumber>;
         excludeTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        maxBackgroundHops: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
     memoryReview: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -1793,6 +1794,7 @@ export declare const PerAgentConfigSchema: z.ZodObject<{
         dedupThreshold: z.ZodDefault<z.ZodNumber>;
         autoTags: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    oauthProfiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strict>;
 /** Agents map: keyed by agent ID string to per-agent configuration. */
 export declare const AgentsMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -2480,6 +2482,7 @@ export declare const AgentsMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
         maxTotal: z.ZodDefault<z.ZodNumber>;
         maxBackgroundDurationMs: z.ZodDefault<z.ZodNumber>;
         excludeTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        maxBackgroundHops: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
     memoryReview: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -2490,6 +2493,7 @@ export declare const AgentsMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
         dedupThreshold: z.ZodDefault<z.ZodNumber>;
         autoTags: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    oauthProfiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strict>>;
 export type PerAgentConfig = z.infer<typeof PerAgentConfigSchema>;
 export type PerAgentSchedulerConfig = z.infer<typeof PerAgentSchedulerConfigSchema>;

package/node_modules/@comis/core/dist/config/schema-agent.js

@@ -8,6 +8,7 @@ import { NotificationConfigSchema } from "./schema-notification.js";
 import { VerbosityConfigSchema } from "./schema-verbosity.js";
 import { BackgroundTasksConfigSchema } from "./schema-background-tasks.js";
 import { MemoryReviewConfigSchema } from "./schema-memory-review.js";
+import { validateProfileId } from "../ports/oauth-credential-store.js";
 // ── Model Selection Schemas ─────────────────────────────────────────────
 /**
  * Model selection configuration schemas.
@@ -363,7 +364,7 @@ export const ContextEngineConfigSchema = z.strictObject({
     summaryModel: z.string().optional(),
     /** Optional provider override for DAG summary generation. */
     summaryProvider: z.string().optional(),
-    // --- Post-batch continuation (L4 — replaces SEP nudge enforcement) ---
+    // --- Post-batch continuation (replaces SEP nudge enforcement) ---
     /** Post-batch continuation handler: when the LLM emits an empty final
      *  turn after a successful tool batch, fire a directive followUp with
      *  multi-shot retry. Replaces the legacy SEP one-shot completeness nudge
@@ -770,6 +771,20 @@ export const PerAgentConfigSchema = AgentConfigSchema.extend({
     backgroundTasks: BackgroundTasksConfigSchema.optional(),
     /** Periodic memory review configuration (session history extraction) */
     memoryReview: MemoryReviewConfigSchema.optional(),
+    /**
+     * Per-provider OAuth profile preferences (provider -> profileId map).
+     * When set, the OAuthTokenManager resolves the named profile for that
+     * provider's LLM calls. Each value must match the `<provider>:<identity>`
+     * format enforced by `validateProfileId` from `@comis/core`.
+     */
+    oauthProfiles: z
+        .record(z.string().min(1), z
+        .string()
+        .min(1)
+        .refine((val) => validateProfileId(val).ok, {
+        message: 'Invalid profile ID: expected "<provider>:<identity>" format (use validateProfileId from @comis/core to verify).',
+    }))
+        .optional(),
 });
 /** Agents map: keyed by agent ID string to per-agent configuration. */
 export const AgentsMapSchema = z.record(z.string().min(1), PerAgentConfigSchema);

package/node_modules/@comis/core/dist/config/schema-background-tasks.d.ts

@@ -21,5 +21,12 @@ export declare const BackgroundTasksConfigSchema: z.ZodObject<{
     maxBackgroundDurationMs: z.ZodDefault<z.ZodNumber>;
     /** Tool names excluded from auto-background promotion. */
     excludeTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    /** Recursion bound for background-task completion re-trigger (maxBackgroundHops).
+     *  Each completion re-enters the originating session as a fresh turn;
+     *  the hop counter prevents a runaway chain when an announcement
+     *  triggers another background task. Default 3 — enough headroom for
+     *  normal "install then generate then send" sequences, low enough that
+     *  loops surface quickly. Runner reads config.backgroundTasks.maxBackgroundHops. */
+    maxBackgroundHops: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>;
 export type BackgroundTasksConfig = z.infer<typeof BackgroundTasksConfigSchema>;

package/node_modules/@comis/core/dist/config/schema-background-tasks.js

@@ -22,4 +22,11 @@ export const BackgroundTasksConfigSchema = z.strictObject({
     maxBackgroundDurationMs: z.number().int().positive().default(300_000),
     /** Tool names excluded from auto-background promotion. */
     excludeTools: z.array(z.string()).default([]),
+    /** Recursion bound for background-task completion re-trigger (maxBackgroundHops).
+     *  Each completion re-enters the originating session as a fresh turn;
+     *  the hop counter prevents a runaway chain when an announcement
+     *  triggers another background task. Default 3 — enough headroom for
+     *  normal "install then generate then send" sequences, low enough that
+     *  loops surface quickly. Runner reads config.backgroundTasks.maxBackgroundHops. */
+    maxBackgroundHops: z.number().int().positive().default(3),
 });

package/node_modules/@comis/core/dist/config/schema-delivery.d.ts

@@ -65,6 +65,8 @@ export declare const DeliveryQueueConfigSchema: z.ZodObject<{
     drainOnStartup: z.ZodDefault<z.ZodBoolean>;
     /** Maximum time in milliseconds allowed for startup drain before continuing. */
     drainBudgetMs: z.ZodDefault<z.ZodNumber>;
+    /** Interval in milliseconds between recurring drain ticks after startup. Set tick cadence for SPEC-R1 continuous drainer. */
+    drainIntervalMs: z.ZodDefault<z.ZodNumber>;
     /** Interval in milliseconds between automatic prune sweeps for expired entries. */
     pruneIntervalMs: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>;

package/node_modules/@comis/core/dist/config/schema-delivery.js

@@ -58,6 +58,8 @@ export const DeliveryQueueConfigSchema = z.strictObject({
     drainOnStartup: z.boolean().default(true),
     /** Maximum time in milliseconds allowed for startup drain before continuing. */
     drainBudgetMs: z.number().int().positive().default(60_000),
+    /** Interval in milliseconds between recurring drain ticks after startup. Set tick cadence for SPEC-R1 continuous drainer. */
+    drainIntervalMs: z.number().int().positive().default(1_000),
     /** Interval in milliseconds between automatic prune sweeps for expired entries. */
     pruneIntervalMs: z.number().int().positive().default(300_000),
 });

package/node_modules/@comis/core/dist/config/schema-gemini-cache.d.ts

@@ -5,8 +5,6 @@ import { z } from "zod";
  * Controls Gemini CachedContent lifecycle: whether explicit caching is
  * enabled and the maximum number of active cached contents per agent.
  *
- * Design reference: D-05 (Gemini cache config section).
- *
  * @module
  */
 /** Gemini cache configuration (per-agent, nested under AgentConfigSchema). */

package/node_modules/@comis/core/dist/config/schema-gemini-cache.js

@@ -6,8 +6,6 @@ import { z } from "zod";
  * Controls Gemini CachedContent lifecycle: whether explicit caching is
  * enabled and the maximum number of active cached contents per agent.
  *
- * Design reference: D-05 (Gemini cache config section).
- *
  * @module
  */
 /** Gemini cache configuration (per-agent, nested under AgentConfigSchema). */

package/node_modules/@comis/core/dist/config/schema-oauth.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+/**
+ * OAuth credential storage configuration.
+ *
+ * Forward-room for Phases 8-11 to add clientId, scopes, profileSelectors
+ * etc. without scattering OAuth config across the codebase. Today only
+ * the storage-backend selector is meaningful.
+ *
+ * @module
+ */
+export declare const OAuthConfigSchema: z.ZodObject<{
+    /**
+     * Storage backend for refreshed OAuth credentials.
+     * - "file" (default): plaintext JSON at ${dataDir}/auth-profiles.json with mode 0o600
+     * - "encrypted": AES-256-GCM SQLite (requires SECRETS_MASTER_KEY)
+     */
+    storage: z.ZodDefault<z.ZodEnum<{
+        file: "file";
+        encrypted: "encrypted";
+    }>>;
+}, z.core.$strict>;
+/** Inferred OAuth configuration type. */
+export type OAuthConfig = z.infer<typeof OAuthConfigSchema>;

package/node_modules/@comis/core/dist/config/schema-oauth.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from "zod";
+/**
+ * OAuth credential storage configuration.
+ *
+ * Forward-room for Phases 8-11 to add clientId, scopes, profileSelectors
+ * etc. without scattering OAuth config across the codebase. Today only
+ * the storage-backend selector is meaningful.
+ *
+ * @module
+ */
+export const OAuthConfigSchema = z.strictObject({
+    /**
+     * Storage backend for refreshed OAuth credentials.
+     * - "file" (default): plaintext JSON at ${dataDir}/auth-profiles.json with mode 0o600
+     * - "encrypted": AES-256-GCM SQLite (requires SECRETS_MASTER_KEY)
+     */
+    storage: z.enum(["file", "encrypted"]).default("file"),
+});

package/node_modules/@comis/core/dist/config/schema-skills.d.ts

@@ -24,13 +24,12 @@ export declare const PromptSkillsConfigSchema: z.ZodObject<{
  */
 declare const ToolDiscoverySchema: z.ZodObject<{
     /** Minimum BM25 score as FRACTION OF TOP MATCH (0..1). Default 0.8.
-     *  As of 2026-04-23, BM25 scores are normalized to [0, 1] before this floor
-     *  applies, matching the semantics of minHybridScore. A value of 0.8 means
+     *  BM25 scores are normalized to [0, 1] before this floor applies,
+     *  matching the semantics of minHybridScore. A value of 0.8 means
      *  "return only tools scoring >= 80% of the top match". Values > 1.0 fail
      *  validation at config load (stale raw-score overrides would produce zero
      *  matches under the new normalized semantics; fail-fast surfaces the
-     *  error immediately per AGENTS.md §3.4). See design §5.6:
-     *  .planning/design/discover-tools-bm25-fallback-fix.md */
+     *  error immediately per AGENTS.md §3.4). */
     minBm25Score: z.ZodDefault<z.ZodNumber>;
     /** Minimum combined score (0..1 normalized) for hybrid mode. Default 0.35. */
     minHybridScore: z.ZodDefault<z.ZodNumber>;
@@ -123,13 +122,12 @@ export declare const SkillsConfigSchema: z.ZodObject<{
     /** discover_tools score-floor thresholds (BM25 + hybrid). */
     toolDiscovery: z.ZodDefault<z.ZodObject<{
         /** Minimum BM25 score as FRACTION OF TOP MATCH (0..1). Default 0.8.
-         *  As of 2026-04-23, BM25 scores are normalized to [0, 1] before this floor
-         *  applies, matching the semantics of minHybridScore. A value of 0.8 means
+         *  BM25 scores are normalized to [0, 1] before this floor applies,
+         *  matching the semantics of minHybridScore. A value of 0.8 means
          *  "return only tools scoring >= 80% of the top match". Values > 1.0 fail
          *  validation at config load (stale raw-score overrides would produce zero
          *  matches under the new normalized semantics; fail-fast surfaces the
-         *  error immediately per AGENTS.md §3.4). See design §5.6:
-         *  .planning/design/discover-tools-bm25-fallback-fix.md */
+         *  error immediately per AGENTS.md §3.4). */
         minBm25Score: z.ZodDefault<z.ZodNumber>;
         /** Minimum combined score (0..1 normalized) for hybrid mode. Default 0.35. */
         minHybridScore: z.ZodDefault<z.ZodNumber>;

package/node_modules/@comis/core/dist/config/schema-skills.js

@@ -94,13 +94,12 @@ const ExecSandboxSchema = z.strictObject({
  */
 const ToolDiscoverySchema = z.strictObject({
     /** Minimum BM25 score as FRACTION OF TOP MATCH (0..1). Default 0.8.
-     *  As of 2026-04-23, BM25 scores are normalized to [0, 1] before this floor
-     *  applies, matching the semantics of minHybridScore. A value of 0.8 means
+     *  BM25 scores are normalized to [0, 1] before this floor applies,
+     *  matching the semantics of minHybridScore. A value of 0.8 means
      *  "return only tools scoring >= 80% of the top match". Values > 1.0 fail
      *  validation at config load (stale raw-score overrides would produce zero
      *  matches under the new normalized semantics; fail-fast surfaces the
-     *  error immediately per AGENTS.md §3.4). See design §5.6:
-     *  .planning/design/discover-tools-bm25-fallback-fix.md */
+     *  error immediately per AGENTS.md §3.4). */
     minBm25Score: z.number().min(0).max(1).default(0.8),
     /** Minimum combined score (0..1 normalized) for hybrid mode. Default 0.35. */
     minHybridScore: z.number().min(0).max(1).default(0.35),

package/node_modules/@comis/core/dist/config/schema.d.ts

@@ -497,6 +497,7 @@ export declare const AppConfigSchema: z.ZodObject<{
             maxTotal: z.ZodDefault<z.ZodNumber>;
             maxBackgroundDurationMs: z.ZodDefault<z.ZodNumber>;
             excludeTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            maxBackgroundHops: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
         memoryReview: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
@@ -507,6 +508,7 @@ export declare const AppConfigSchema: z.ZodObject<{
             dedupThreshold: z.ZodDefault<z.ZodNumber>;
             autoTags: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
+        oauthProfiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>>>;
     /** Channel adapter configuration */
     channels: z.ZodDefault<z.ZodObject<{
@@ -1509,6 +1511,13 @@ export declare const AppConfigSchema: z.ZodObject<{
             snapshotIntervalMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
+    /** OAuth credential storage configuration (storage backend selector) */
+    oauth: z.ZodDefault<z.ZodObject<{
+        storage: z.ZodDefault<z.ZodEnum<{
+            file: "file";
+            encrypted: "encrypted";
+        }>>;
+    }, z.core.$strict>>;
     /** Plugin system configuration */
     plugins: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -1987,6 +1996,7 @@ export declare const AppConfigSchema: z.ZodObject<{
         defaultExpireMs: z.ZodDefault<z.ZodNumber>;
         drainOnStartup: z.ZodDefault<z.ZodBoolean>;
         drainBudgetMs: z.ZodDefault<z.ZodNumber>;
+        drainIntervalMs: z.ZodDefault<z.ZodNumber>;
         pruneIntervalMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
     /** Session mirroring persistence configuration */

package/node_modules/@comis/core/dist/config/schema.js

@@ -19,6 +19,7 @@ import { MessagesConfigSchema } from "./schema-messages.js";
 import { ModelsConfigSchema } from "./schema-models.js";
 import { MonitoringConfigSchema } from "./schema-observability.js";
 import { ObservabilityConfigSchema } from "./schema-observability.js";
+import { OAuthConfigSchema } from "./schema-oauth.js";
 import { PluginsConfigSchema } from "./schema-plugins.js";
 import { ProvidersConfigSchema } from "./schema-providers.js";
 import { QueueConfigSchema } from "./schema-queue.js";
@@ -68,6 +69,8 @@ export const AppConfigSchema = z.strictObject({
     monitoring: MonitoringConfigSchema.default(() => MonitoringConfigSchema.parse({})),
     /** Observability persistence configuration */
     observability: ObservabilityConfigSchema.default(() => ObservabilityConfigSchema.parse({})),
+    /** OAuth credential storage configuration (storage backend selector) */
+    oauth: OAuthConfigSchema.default(() => OAuthConfigSchema.parse({})),
     /** Plugin system configuration */
     plugins: PluginsConfigSchema.default(() => PluginsConfigSchema.parse({})),
     /** Command queue configuration for session serialization and concurrency control */

package/node_modules/@comis/core/dist/domain/background-task-origin.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Background task origin: captures the originating session attribution
+ * (agent + session + channel + trace + hop count) at the moment a tool
+ * execution is promoted to a background task. Persisted on the task so
+ * completion can route a re-entry announcement back to the right session
+ * even after a daemon restart.
+ *
+ * Lives in @comis/core (not @comis/agent) so the event-bus payload type
+ * in core/src/event-bus/events-infra.ts can carry it without violating
+ * the inward-only dependency direction (AGENTS.md §1).
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * Origin context captured at promote() time. All string fields are
+ * non-empty so the runner can reconstruct a valid SessionKey via
+ * parseFormattedSessionKey() and dispatch executor.execute() to the
+ * correct session.
+ */
+export declare const BackgroundTaskOriginSchema: z.ZodObject<{
+    /** The agent that owned the tool call. */
+    agentId: z.ZodString;
+    /** Formatted session key string (parseFormattedSessionKey-compatible). */
+    sessionKey: z.ZodString;
+    /** Channel type the originating message arrived on (e.g., "telegram"). */
+    channelType: z.ZodString;
+    /** Channel-specific identifier for the originating user/group. */
+    channelId: z.ZodString;
+    /** Per-execution trace identifier; null when no trace was active. */
+    traceId: z.ZodNullable<z.ZodString>;
+    /** Recursion-bound counter. Captured at promote-time from the inbound
+     *  NormalizedMessage's metadata.backgroundHopCount (defaults to 0 for
+     *  top-level user messages). The completion runner increments this
+     *  when constructing the outgoing synthetic message, and falls back to
+     *  fallbackNotifyFn when (incomingHopCount + 1) >= maxBackgroundHops. */
+    backgroundHopCount: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type BackgroundTaskOrigin = z.infer<typeof BackgroundTaskOriginSchema>;

package/node_modules/@comis/core/dist/domain/background-task-origin.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Background task origin: captures the originating session attribution
+ * (agent + session + channel + trace + hop count) at the moment a tool
+ * execution is promoted to a background task. Persisted on the task so
+ * completion can route a re-entry announcement back to the right session
+ * even after a daemon restart.
+ *
+ * Lives in @comis/core (not @comis/agent) so the event-bus payload type
+ * in core/src/event-bus/events-infra.ts can carry it without violating
+ * the inward-only dependency direction (AGENTS.md §1).
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * Origin context captured at promote() time. All string fields are
+ * non-empty so the runner can reconstruct a valid SessionKey via
+ * parseFormattedSessionKey() and dispatch executor.execute() to the
+ * correct session.
+ */
+export const BackgroundTaskOriginSchema = z.strictObject({
+    /** The agent that owned the tool call. */
+    agentId: z.string().min(1),
+    /** Formatted session key string (parseFormattedSessionKey-compatible). */
+    sessionKey: z.string().min(1),
+    /** Channel type the originating message arrived on (e.g., "telegram"). */
+    channelType: z.string().min(1),
+    /** Channel-specific identifier for the originating user/group. */
+    channelId: z.string().min(1),
+    /** Per-execution trace identifier; null when no trace was active. */
+    traceId: z.string().nullable(),
+    /** Recursion-bound counter. Captured at promote-time from the inbound
+     *  NormalizedMessage's metadata.backgroundHopCount (defaults to 0 for
+     *  top-level user messages). The completion runner increments this
+     *  when constructing the outgoing synthetic message, and falls back to
+     *  fallbackNotifyFn when (incomingHopCount + 1) >= maxBackgroundHops. */
+    backgroundHopCount: z.number().int().nonnegative().default(0),
+});

package/node_modules/@comis/core/dist/event-bus/events-infra.d.ts

@@ -1,3 +1,4 @@
+import type { BackgroundTaskOrigin } from "../domain/background-task-origin.js";
 /**
  * InfraEvents: Config, plugin, hook, auth, diagnostic,
  * media, scheduler, system, and metrics events.
@@ -61,9 +62,53 @@ export interface InfraEvents {
     "auth:token_rotated": {
         provider: string;
         profileName: string;
+        /** Canonical "<provider>:<identity>" form. Coexists with profileName for backward compat. */
+        profileId: string;
         expiresAtMs: number;
         timestamp: number;
     };
+    /**
+     * OAuth profile bootstrapped from environment variable on first
+     * store-empty access. Fires once per process per provider.
+     */
+    "auth:profile_bootstrapped": {
+        provider: string;
+        profileId: string;
+        /** Semi-redacted email (e.g. "mo…e@gmail.com") or "id-<base64url>" fallback. */
+        identity: string;
+        timestamp: number;
+    };
+    /**
+     * OAuth profile added to the credential store by an external writer
+     * (CLI `auth login` or wizard step 04). Emitted by OAuthTokenManager's
+     * file watcher after a chokidar `change`/`add` event invalidates the
+     * cache and the store list reveals a new profile.
+     *
+     * `source: "external"` indicates the writer is outside this manager
+     * instance.
+     */
+    "auth:profile_added": {
+        provider: string;
+        profileId: string;
+        /** Semi-redacted email (e.g. "mo…e@gmail.com") or "id-<base64url>" fallback. */
+        identity: string;
+        source: "external";
+        timestamp: number;
+    };
+    /**
+     * OAuth refresh failed terminally (e.g. refresh_token_reused, network
+     * error after retries, timeout). Emitted with coarse errorKind because
+     * pi-ai swallows the original cause.
+     */
+    "auth:refresh_failed": {
+        provider: string;
+        profileId: string;
+        /** Coarse classification: refresh_token_reused | network | timeout | refresh_failed. */
+        errorKind: string;
+        /** Operator action recommendation. */
+        hint: string;
+        timestamp: number;
+    };
     /** Full message lifecycle diagnostic with timing and cost */
     "diagnostic:message_processed": {
         messageId: string;
@@ -185,6 +230,12 @@ export interface InfraEvents {
         sessionStrategy?: "fresh" | "rolling" | "accumulate";
         /** Number of recent turns to keep for rolling strategy. */
         maxHistoryTurns?: number;
+        /** Schedule cadence in ms when known. Populated only for schedule.kind === "every"
+         *  (where everyMs is a literal). Undefined for cron-expression and one-shot ("at")
+         *  schedules — deriving cadence from a cron expression would require parsing and is
+         *  intentionally out of scope for this field. Used by the cron handler to warn when
+         *  long-cadence jobs run with a cache-wasting sessionStrategy. */
+        cadenceMs?: number;
         /** Per-cron-job model override from CronPayload.agent_turn.model. */
         cronJobModel?: string;
         /** Per-cron-job cache retention override from CronJob config. */
@@ -349,21 +400,39 @@ export interface InfraEvents {
         toolName: string;
         timestamp: number;
     };
-    /** Background task completed successfully */
+    /** Background task completed successfully. `origin` carries originating
+     *  session attribution so subscribers (the completion runner) can
+     *  re-enter the right session without a synchronous round-trip through
+     *  the manager. */
     "background_task:completed": {
         agentId: string;
         taskId: string;
         toolName: string;
         durationMs: number;
+        origin: BackgroundTaskOrigin;
         timestamp: number;
     };
-    /** Background task failed (timeout, error, or daemon restart) */
+    /** Background task failed (timeout, error, or daemon restart).
+     *  `origin` is populated for in-process failures and for restart-recovery
+     *  failures (recoverOnStartup re-emits with origin from the persisted JSON). */
     "background_task:failed": {
         agentId: string;
         taskId: string;
         toolName: string;
         error: string;
         durationMs: number;
+        origin: BackgroundTaskOrigin;
+        timestamp: number;
+    };
+    /** Background completion runner is about to invoke executor.execute() on
+     *  the originating session (latency-instrumentation hook). Subscribers
+     *  may compute the delta from background_task:completed.timestamp to
+     *  this event for SLO tracking (target: p95 ≤ 1000ms over 50 trials). */
+    "background_task:reentered": {
+        taskId: string;
+        agentId: string;
+        sessionKey: string;
+        hopCount: number;
         timestamp: number;
     };
     /** Background task cancelled by user or system */