comisai 1.0.34 → 1.0.37

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

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * Cross-session messaging setup: cross-session sender and sub-agent runner.
- * Extracted from daemon.ts step 6.6.9 to isolate cross-session service
- * creation from the main wiring sequence. The three callback closures
- * (executeInSession, sendToChannel, executeSubAgent) are built internally
- * from injected dependencies (assembleToolsForAgent, getExecutor, adaptersByType).
+ * Isolates cross-session service creation from the main wiring sequence.
+ * The three callback closures (executeInSession, sendToChannel,
+ * executeSubAgent) are built internally from injected dependencies
+ * (assembleToolsForAgent, getExecutor, adaptersByType).
  * @module
  */
 import { tryGetContext, runWithContext, formatSessionKey, safePath } from "@comis/core";
@@ -15,7 +15,6 @@ import { createSubAgentRunner } from "../sub-agent-runner.js";
 import { createAnnouncementBatcher } from "../announcement-batcher.js";
 import { createAnnouncementDeadLetterQueue } from "../announcement-dead-letter.js";
 import { randomUUID } from "node:crypto";
-import { resolve } from "node:path";
 // ---------------------------------------------------------------------------
 // Depth-aware graph cache retention
 // ---------------------------------------------------------------------------
@@ -348,7 +347,7 @@ export function setupCrossSession(deps) {
                     deps.logger?.warn({
                         err,
                         hint: "Parent summary generation failed; proceeding without summary",
-                        errorKind: "upstream",
+                        errorKind: "dependency",
                     }, "generateParentSummary failed for parent context");
                 }
             }
@@ -426,13 +425,13 @@ export function setupCrossSession(deps) {
         const GRAPH_PROMPT_TIMEOUT_MS = 600_000;
         // Base subagent retention is "short" (5m TTL).
         // Graph sub-agents with graphSharedDir get depth-aware retention:
-        //   - Root nodes (depth=0): "short" -- complete in <3min, consumed by Wave 2 within 3-4min
-        //   - Downstream nodes (depth >= 1): "long" -- may be consumed by further waves
+        //   - Root nodes (depth=0): "short" -- complete fast, consumed by downstream nodes within 5m
+        //   - Downstream nodes (depth >= 1): "long" -- may be consumed by further descendants
         // Non-graph sub-agents always get "short".
         const subAgentCacheRetention = graphSharedDir
             ? resolveGraphCacheRetention(graphNodeDepth, isLeafNode)
             : "short";
-        // R-11: Session adapter for sub-agents.
+        // Session adapter for sub-agents.
         // When subAgentSessionPersistence is true, sub-agents get disk-backed JSONL sessions
         // for debugging/auditing. Default (false): ephemeral in-memory, garbage-collected.
         const subAgentPersistence = container.config.security?.agentToAgent?.subAgentSessionPersistence ?? false;
@@ -472,8 +471,8 @@ export function setupCrossSession(deps) {
             // Reuse sessions need their own cache entries (skipCacheWrite will be false
             // because spawnPacket is undefined). Force "long" retention for multi-round persistence.
             // Graph sub-agents use depth-aware retention:
-            // Root nodes (depth=0): "short" -- complete fast, consumed within 5m by Wave 2.
-            // Downstream nodes (depth>=1): "long" -- may be consumed by later waves beyond 5m.
+            // Root nodes (depth=0): "short" -- complete fast, consumed within 5m by downstream nodes.
+            // Downstream nodes (depth>=1): "long" -- may be consumed beyond 5m.
             // Model resolution's cacheRetention must NOT override graph-aware default.
             cacheRetention: isReuseSession
                 ? "long"
@@ -508,7 +507,7 @@ export function setupCrossSession(deps) {
             toolCallHistory: result.toolCallHistory,
         };
     };
-    // 6.6.9a. Cross-session sender — fire-and-forget, wait, or ping-pong messaging
+    // Cross-session sender — fire-and-forget, wait, or ping-pong messaging
     const crossSessionSender = createCrossSessionSender({
         sessionStore: {
             loadByFormattedKey: (key) => sessionStore.loadByFormattedKey(key),
@@ -572,8 +571,13 @@ export function setupCrossSession(deps) {
         }
     };
     // Create dead-letter queue for failed announcement persistence (before batcher, so batcher can reference it)
-    const dlqBaseDir = resolve(container.config.dataDir || ".");
-    const deadLetterFilePath = safePath(dlqBaseDir, "dead-letters.jsonl");
+    // Direct safePath composition. AGENTS §2.2: all paths via safePath. safePath
+    // requires an absolute base (see PathTraversalError contract in
+    // packages/core/src/security/safe-path.ts), so when container.config.dataDir
+    // is unset we fall back to process.cwd(). process.cwd() is not banned by
+    // AGENTS §2.2 (only process.env and node:path's path.join/path.resolve are
+    // restricted).
+    const deadLetterFilePath = safePath(container.config.dataDir || process.cwd(), "dead-letters.jsonl");
     const deadLetterQueue = createAnnouncementDeadLetterQueue({
         filePath: deadLetterFilePath,
         maxRetries: 5,
@@ -581,7 +585,7 @@ export function setupCrossSession(deps) {
         maxAgeMs: 3_600_000,
         maxEntries: 100,
         eventBus: container.eventBus,
-        logger: deps.logger?.child({ module: "dead-letter-queue" }),
+        logger: deps.logger?.child({ submodule: "dead-letter-queue" }),
     });
     // Create announcement batcher for coalescing near-simultaneous sub-agent completions
     const announcementBatcher = createAnnouncementBatcher({
@@ -628,7 +632,7 @@ export function setupCrossSession(deps) {
             : { info: () => { }, warn: () => { }, debug: () => { } },
         eventBus: container.eventBus,
     });
-    // 6.6.9b. Sub-agent runner — async sub-agent spawning with allowlist + auto-archive
+    // Sub-agent runner — async sub-agent spawning with allowlist + auto-archive
     const subAgentRunner = createSubAgentRunner({
         sessionStore: {
             save: (key, messages, metadata) => sessionStore.save(key, messages, metadata),
@@ -645,6 +649,7 @@ export function setupCrossSession(deps) {
         memoryAdapter: deps.memoryAdapter,
         batcher: announcementBatcher,
         activeRunRegistry: deps.activeRunRegistry,
+        sessionResolver: deps.sessionResolver,
         resultCondenser,
         condenserModel: condenserApiKey ? { id: condensationResolution.modelId, provider: condensationResolution.provider } : undefined,
         condenserApiKey: condenserApiKey || undefined,

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

@@ -5,8 +5,9 @@
  * Queue two-phase lifecycle resolves the circular dependency between the
  * queue and channel adapters:
  *   1. setupDeliveryQueue() creates the adapter immediately (before setupChannels).
- *   2. drainAndStartPrune() runs drain + starts prune timer AFTER setupChannels
- *      populates channelAdapters.
+ *   2. drainAndStart() recovers in_flight rows, runs startup drain, then starts
+ *      both the recurring drain timer and the prune timer AFTER
+ *      setupChannels populates channelAdapters.
  * Crash-Safe Delivery Queue.
  * Session Mirroring.
  * @module setup-delivery — Delivery subsystem wiring (queue + mirror)
@@ -18,9 +19,9 @@ import type { PluginRegistry } from "@comis/core";
 export interface DeliveryQueueResult {
     /** The delivery queue adapter (real or no-op), available immediately. */
     deliveryQueue: DeliveryQueuePort;
-    /** Runs startup drain then starts periodic prune timer. Call AFTER setupChannels. */
-    drainAndStartPrune: () => Promise<void>;
-    /** Clears the prune interval timer (call on shutdown). */
+    /** Recovers in_flight rows, runs startup drain, then starts the recurring drain + prune timers. Call AFTER setupChannels. */
+    drainAndStart: () => Promise<void>;
+    /** Clears the recurring drain interval AND the prune interval (call on shutdown). */
     shutdown: () => void;
 }
 export declare function setupDeliveryQueue(deps: {
@@ -31,6 +32,14 @@ export declare function setupDeliveryQueue(deps: {
     logger: ComisLogger;
     channelAdapters: Map<string, DeliveryAdapter>;
 }): Promise<DeliveryQueueResult>;
+export declare function drainDeliveryQueue(deps: {
+    deliveryQueue: DeliveryQueuePort;
+    channelAdapters: Map<string, DeliveryAdapter>;
+    eventBus: TypedEventBus;
+    logger: ComisLogger;
+    drainBudgetMs: number;
+    defaultMaxAttempts: number;
+}): Promise<void>;
 export interface DeliveryMirrorResult {
     /** The delivery mirror adapter (real or no-op), available immediately. */
     deliveryMirror: DeliveryMirrorPort;

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

@@ -6,8 +6,9 @@
  * Queue two-phase lifecycle resolves the circular dependency between the
  * queue and channel adapters:
  *   1. setupDeliveryQueue() creates the adapter immediately (before setupChannels).
- *   2. drainAndStartPrune() runs drain + starts prune timer AFTER setupChannels
- *      populates channelAdapters.
+ *   2. drainAndStart() recovers in_flight rows, runs startup drain, then starts
+ *      both the recurring drain timer and the prune timer AFTER
+ *      setupChannels populates channelAdapters.
  * Crash-Safe Delivery Queue.
  * Session Mirroring.
  * @module setup-delivery — Delivery subsystem wiring (queue + mirror)
@@ -15,7 +16,7 @@
 import { createNoOpDeliveryQueue, createNoOpDeliveryMirror } from "@comis/core";
 import { createSqliteDeliveryQueue, createSqliteDeliveryMirror } from "@comis/memory";
 import { isPermanentError, computeQueueBackoff } from "@comis/channels";
-import { ok } from "@comis/shared";
+import { ok, suppressError } from "@comis/shared";
 import { createHash } from "node:crypto";
 // ---------------------------------------------------------------------------
 // Setup function
@@ -28,48 +29,92 @@ export async function setupDeliveryQueue(deps) {
         logger.debug("Delivery queue disabled by config");
         return {
             deliveryQueue: createNoOpDeliveryQueue(),
-            drainAndStartPrune: async () => { },
+            drainAndStart: async () => { },
             shutdown: () => { },
         };
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- db is better-sqlite3 Database; typed as unknown to avoid cross-package type dependency
-    const deliveryQueue = createSqliteDeliveryQueue(db);
+    const deliveryQueue = createSqliteDeliveryQueue(db, eventBus);
     logger.info({ maxQueueDepth: queueConfig.maxQueueDepth, defaultMaxAttempts: queueConfig.defaultMaxAttempts }, "Delivery queue enabled");
     let pruneInterval;
-    // 2. Startup drain + 3. Periodic prune (deferred until channelAdapters populated)
-    const drainAndStartPrune = async () => {
-        // --- Drain ---
+    let drainInterval;
+    // Single-tick gate: in-flight Promise prevents overlapping ticks.
+    let draining = null;
+    // Inner helper: one drain pass. Reused by startup drain AND each recurring tick.
+    const runOneDrainPass = async () => {
+        await drainDeliveryQueue({
+            deliveryQueue,
+            channelAdapters,
+            eventBus,
+            logger,
+            drainBudgetMs: queueConfig.drainBudgetMs,
+            defaultMaxAttempts: queueConfig.defaultMaxAttempts,
+        });
+    };
+    // 2. Startup drain + recurring drain timer + prune timer (deferred until channelAdapters populated)
+    const drainAndStart = async () => {
+        // --- Step 1: Recover in_flight rows. ---
+        // Runs UNCONDITIONALLY -- independent of drainOnStartup policy. An 'in_flight'
+        // row from a prior crash is a correctness bug regardless of the drain policy.
+        const recoverResult = await deliveryQueue.recoverInFlight();
+        if (!recoverResult.ok) {
+            logger.warn({ err: recoverResult.error, hint: "Could not recover in_flight rows on startup; messages may stall until next restart", errorKind: "internal" }, "Delivery queue: recoverInFlight failed");
+        }
+        else if (recoverResult.value > 0) {
+            logger.info({ recovered: recoverResult.value }, "Delivery queue: recovered in_flight rows to pending");
+        }
+        // --- Step 2: Startup drain (existing behavior, unchanged). ---
         if (queueConfig.drainOnStartup) {
-            await drainDeliveryQueue({
-                deliveryQueue,
-                channelAdapters,
-                eventBus,
-                logger,
-                drainBudgetMs: queueConfig.drainBudgetMs,
-                defaultMaxAttempts: queueConfig.defaultMaxAttempts,
-            });
+            await runOneDrainPass();
         }
-        // --- Prune timer ---
+        // --- Step 3: Recurring drain timer. ---
+        drainInterval = setInterval(() => {
+            if (draining)
+                return; // single-tick gate
+            draining = runOneDrainPass().finally(() => { draining = null; });
+            // Fire-and-forget: failures inside drainDeliveryQueue are already logged
+            // and do not propagate (it never throws). suppressError satisfies the
+            // no-floating-promise lint without altering semantics.
+            suppressError(draining, "delivery queue recurring drain tick");
+        }, queueConfig.drainIntervalMs);
+        drainInterval.unref();
+        // --- Step 4: Prune timer. ---
+        // Emit a per-class drain log line with structured fields
+        // (`pruned`, `class`, `durationMs`) so operators can correlate prune
+        // activity by retention class across subsystems (delivery_queue,
+        // delivery_mirror, output retention housekeeper, etc.). The `class`
+        // field is a placeholder until the underlying pruneExpired() is
+        // extended with per-class breakdown. Canonical Pino object-first;
+        // durationMs is the canonical name (CLAUDE.md logging conventions).
         pruneInterval = setInterval(async () => {
+            const startMs = Date.now();
             const result = await deliveryQueue.pruneExpired();
             if (result.ok && result.value > 0) {
-                logger.debug({ pruned: result.value }, "Delivery queue pruned");
+                logger.debug({
+                    pruned: result.value,
+                    class: "delivery_queue",
+                    durationMs: Date.now() - startMs,
+                }, "Delivery queue pruned");
             }
         }, queueConfig.pruneIntervalMs);
         pruneInterval.unref();
     };
     const shutdown = () => {
+        if (drainInterval) {
+            clearInterval(drainInterval);
+            drainInterval = undefined;
+        }
         if (pruneInterval) {
             clearInterval(pruneInterval);
             pruneInterval = undefined;
         }
     };
-    return { deliveryQueue, drainAndStartPrune, shutdown };
+    return { deliveryQueue, drainAndStart, shutdown };
 }
 // ---------------------------------------------------------------------------
 // Drain implementation
 // ---------------------------------------------------------------------------
-async function drainDeliveryQueue(deps) {
+export async function drainDeliveryQueue(deps) {
     const { deliveryQueue, channelAdapters, eventBus, logger, drainBudgetMs, defaultMaxAttempts } = deps;
     const drainStart = Date.now();
     const deadline = drainStart + drainBudgetMs;

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

@@ -1,10 +1,8 @@
 /**
  * Gateway setup: RPC bridge (deferred dispatch), RPC adapter wiring, dynamic
  * method registration, webhook mounting, OpenAI-compatible route mounting,
- * and gateway server creation/start.
- * Extracted from daemon.ts to isolate the single
- * largest inline block from the main wiring sequence. Covers the full
- * gateway lifecycle from RPC bridge creation through server start.
+ * and gateway server creation/start. Covers the full gateway lifecycle from
+ * RPC bridge creation through server start.
  * @module
  */
 import type { SessionKey, AppContainer, AppConfig } from "@comis/core";
@@ -36,7 +34,7 @@ export declare function buildExecutionRequestedLogFields(input: {
     messageHash?: string;
     connectionId?: string;
 };
-/** All services produced by the RPC bridge setup phase. */
+/** All services produced by the RPC bridge setup. */
 export interface RpcBridgeResult {
     /** The rpcCall function usable immediately (delegates to inner dispatch once wired). */
     rpcCall: RpcCall;
@@ -145,7 +143,7 @@ export interface GatewayDeps {
     /** Set of suspended agent IDs for REST API status reporting. */
     suspendedAgents?: ReadonlySet<string>;
 }
-/** All services produced by the gateway setup phase. */
+/** All services produced by the gateway setup. */
 export interface GatewayResult {
     /** Gateway server handle (undefined when gateway is disabled). */
     gatewayHandle?: GatewayServerHandle;

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

@@ -2,10 +2,8 @@
 /**
  * Gateway setup: RPC bridge (deferred dispatch), RPC adapter wiring, dynamic
  * method registration, webhook mounting, OpenAI-compatible route mounting,
- * and gateway server creation/start.
- * Extracted from daemon.ts to isolate the single
- * largest inline block from the main wiring sequence. Covers the full
- * gateway lifecycle from RPC bridge creation through server start.
+ * and gateway server creation/start. Covers the full gateway lifecycle from
+ * RPC bridge creation through server start.
  * @module
  */
 import { registerRpcMethods } from "./setup-gateway-rpc.js";
@@ -417,7 +415,7 @@ export async function setupGateway(deps) {
                 catch {
                     // Session history bridging is non-fatal
                 }
-                // Token usage now captured by tokenTracker's bus subscription (quick-138):
+                // Token usage captured by tokenTracker's bus subscription:
                 // PiEventBridge emits observability:token_usage at turn_end -> tokenTracker
                 // bus handler stores it. No direct record() call needed here.
                 // Conversation memory persistence now handled by PiExecutor

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

@@ -9,9 +9,19 @@
 import type { AppContainer, ChannelPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import { type PerAgentHeartbeatRunner, type DuplicateDetector, type SystemEventQueue } from "@comis/scheduler";
-/** Minimal ActiveRunRegistry -- only needs has() for queue-busy check. */
-interface HeartbeatActiveRunRegistry {
-    has(sessionKey: string): boolean;
+/**
+ * Minimal BackgroundSessionResolver shape -- only needs hasActiveSession()
+ * for the queue-busy check. Locally re-declared to avoid the
+ * cycle from importing @comis/agent here; the daemon constructs the
+ * resolver as `createBackgroundSessionResolver({activeRunRegistry})` and
+ * the resulting object is structurally assignable to this shape.
+ */
+interface HeartbeatSessionResolver {
+    hasActiveSession(key: {
+        agentId: string;
+        channelType: string;
+        channelId: string;
+    }): boolean;
 }
 /** 8-param executor interface matching AgentExecutor.execute (used in deps map). */
 interface InnerExecutor {
@@ -29,8 +39,13 @@ export interface HeartbeatSetupDeps {
     assembleToolsForAgent: (agentId: string) => Promise<unknown[]>;
     /** Per-agent workspace directories. */
     workspaceDirs: Map<string, string>;
-    /** Active run registry for queue-busy detection (optional). */
-    activeRunRegistry?: HeartbeatActiveRunRegistry;
+    /**
+     * Composite-key resolver for queue-busy detection (optional).
+     * The daemon wires this via `createBackgroundSessionResolver`; it
+     * supersedes the previous `.has(sessionKey)` lookup so multi-agent /
+     * multi-channel collisions are distinguishable.
+     */
+    sessionResolver?: HeartbeatSessionResolver;
     /** Duplicate detector shared between global and per-agent heartbeat delivery. */
     duplicateDetector?: DuplicateDetector;
     /** Channel adapters for heartbeat delivery (optional). */

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

@@ -23,7 +23,7 @@ import { applyToolPolicy } from "@comis/skills";
  * @param deps - Per-agent heartbeat dependencies
  */
 export function setupHeartbeat(deps) {
-    const { container, executors, assembleToolsForAgent, workspaceDirs, activeRunRegistry, duplicateDetector, adaptersByType, systemEventQueue, memoryApi, schedulerLogger, } = deps;
+    const { container, executors, assembleToolsForAgent, workspaceDirs, sessionResolver, duplicateDetector, adaptersByType, systemEventQueue, memoryApi, schedulerLogger, } = deps;
     const agents = container.config.agents;
     const globalHeartbeat = container.config.scheduler.heartbeat;
     // 1. Build per-agent state map (only heartbeat-enabled agents)
@@ -76,7 +76,16 @@ export function setupHeartbeat(deps) {
     // 4. Build AgentHeartbeatSource dependencies
     const source = createAgentHeartbeatSource({
         getExecutor: (agentId) => {
+            // Explicit boundary throw replaces a non-null-assertion lookup. The
+            // assertion was unsafe — if executor wiring missed an agent that's
+            // still in the heartbeat config, `inner.execute(...)` would surface
+            // as a runtime TypeError inside a timer callback (uncaught). The
+            // explicit Error gives operators a clean stack at the wiring
+            // boundary instead.
             const inner = executors.get(agentId);
+            if (!inner) {
+                throw new Error(`No executor found for heartbeat agent ${agentId}`);
+            }
             return {
                 execute: (msg, sessionKey, tools, hbAgentId, overrides) => inner.execute(msg, sessionKey, tools, undefined, hbAgentId, undefined, undefined, overrides),
             };
@@ -96,7 +105,7 @@ export function setupHeartbeat(deps) {
             eventBus: container.eventBus,
             logger: schedulerLogger,
         },
-        activeRunRegistry,
+        sessionResolver,
         getMemoryStats,
         // Inject applyToolPolicy so scheduler can filter without taking a direct
         // dependency on @comis/skills. Type-erased `unknown[]` at the boundary is

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

@@ -0,0 +1,89 @@
+/**
+ * Output retention housekeeper: scans the agent's output/ directory,
+ * deletes files whose age exceeds the per-class retentionMs.
+ *
+ * Mirrors setup-delivery.ts drain+prune timer pattern (single-tick gate +
+ * unref() + structured DEBUG log per pass).
+ *
+ * Consumes JSONL details.visibleDelivery for offline analysis (the
+ * housekeeper does NOT delete JSONL itself; it only manages output/
+ * files referenced by it).
+ *
+ * Per AGENTS §2.2: NO `path.join`, NO `process.env`. All paths via
+ *   `safePath(workspaceDir, ...)`. Per AGENTS §2.4: factory + Deps with
+ *   ComisLogger injected. Per AGENTS §2.1: error paths log WARN/DEBUG with
+ *   hint+errorKind; never throws. Per AGENTS §2.3 KISS: in-place file
+ *   deletion. No "trash dir", no "soft delete". Per AGENTS §6.6
+ *   (security/daemon): file deletion is destructive — operator can
+ *   disable via `enabled: false` config.
+ *
+ * Test contract: `validateOutputRetentionConfig({ classes:
+ * [{classId, retentionMs}] })` returns `{ ok, value | error }`.
+ *
+ * @module setup-output-retention
+ */
+import type { OutputRetentionConfig } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+import { type Result } from "@comis/shared";
+export interface SetupOutputRetentionDeps {
+    /**
+     * Validated config (from AppConfig.outputRetention). May be undefined
+     * in legacy test mocks where AppConfig is hand-constructed via
+     * `as unknown as`; the factory degrades to no-op in that case (mirrors
+     * `setupDeliveryMirror`'s `if (!mirrorConfig?.enabled)` pattern).
+     */
+    config: OutputRetentionConfig | undefined;
+    /** Absolute path to the workspace dir. The housekeeper scans `<workspaceDir>/output/`. */
+    workspaceDir: string;
+    /** Injected logger (per AGENTS §2.4 — never import @comis/infra at runtime). */
+    logger: ComisLogger;
+}
+export interface SetupOutputRetentionHandle {
+    /** Stop the recurring housekeeper interval. Idempotent. */
+    shutdown(): void;
+    /** Manual trigger for tests; runs one full pass synchronously. */
+    runOnePass(): Promise<{
+        deleted: number;
+        bytesFreed: number;
+    }>;
+}
+/**
+ * Legacy array-of-objects shape preserved as the input to
+ * `validateOutputRetentionConfig`. The housekeeper itself uses the
+ * schema-derived `OutputRetentionConfig` (Record-of-classes shape); this
+ * validator acts as the test's binding gate that retentionMs <= 0 is
+ * rejected.
+ */
+export interface RetentionClassConfigInput {
+    classId: string;
+    retentionMs: number;
+}
+export interface ValidatedRetentionConfig {
+    classes: RetentionClassConfigInput[];
+}
+/**
+ * Validate an output-retention config supplied as the legacy
+ * `{ classes: [{classId, retentionMs}] }` shape. Returns a Result-shaped
+ * `{ ok: true, value }` on success, `{ ok: false, error }` on failure.
+ *
+ * Validator contract:
+ *   - retentionMs = -1   → rejected
+ *   - retentionMs = 0    → rejected
+ *   - retentionMs = 1    → accepted
+ *
+ * Production wiring uses the Zod schema in
+ * @comis/core/config/schema-output-retention.ts directly; this
+ * validator is a thin compatibility surface for the test contract.
+ */
+export declare function validateOutputRetentionConfig(config: unknown): Result<ValidatedRetentionConfig, Error>;
+/**
+ * Wire the per-class output-retention housekeeper.
+ *
+ * Mirrors setup-delivery.ts (drain + prune timer): single-tick gate, .unref(),
+ * structured per-pass log. The factory starts the recurring interval
+ * immediately on construction; call shutdown() on system:shutdown.
+ *
+ * Returns a handle exposing `shutdown()` (idempotent) and `runOnePass()`
+ * (manual trigger for tests).
+ */
+export declare function setupOutputRetention(deps: SetupOutputRetentionDeps): SetupOutputRetentionHandle;