comisai 1.0.36 → 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,
@@ -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.js

@@ -78,11 +78,23 @@ export async function setupDeliveryQueue(deps) {
             suppressError(draining, "delivery queue recurring drain tick");
         }, queueConfig.drainIntervalMs);
         drainInterval.unref();
-        // --- Step 4: Prune timer (existing behavior, unchanged). ---
+        // --- 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();

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;

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

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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 { readdirSync, statSync, unlinkSync } from "node:fs";
+import { safePath } from "@comis/core";
+import { ok, err, suppressError } from "@comis/shared";
+// ---------------------------------------------------------------------------
+// Validator (test contract gate)
+// ---------------------------------------------------------------------------
+/**
+ * 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 function validateOutputRetentionConfig(config) {
+    if (typeof config !== "object" || config === null) {
+        return err(new Error("output retention config must be an object"));
+    }
+    const obj = config;
+    if (!Array.isArray(obj.classes)) {
+        return err(new Error("output retention config: 'classes' must be an array"));
+    }
+    const out = [];
+    for (let i = 0; i < obj.classes.length; i++) {
+        const entry = obj.classes[i];
+        if (typeof entry !== "object" || entry === null) {
+            return err(new Error(`output retention config: classes[${i}] must be an object`));
+        }
+        const e = entry;
+        if (typeof e.classId !== "string" || e.classId.length === 0) {
+            return err(new Error(`output retention config: classes[${i}].classId must be a non-empty string`));
+        }
+        if (typeof e.retentionMs !== "number" ||
+            !Number.isInteger(e.retentionMs) ||
+            e.retentionMs <= 0) {
+            return err(new Error(`output retention config: classes[${i}].retentionMs must be a positive integer (got ${String(e.retentionMs)})`));
+        }
+        out.push({ classId: e.classId, retentionMs: e.retentionMs });
+    }
+    return ok({ classes: out });
+}
+// ---------------------------------------------------------------------------
+// Housekeeper factory
+// ---------------------------------------------------------------------------
+/**
+ * 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 function setupOutputRetention(deps) {
+    const log = deps.logger.child({ submodule: "output-retention-housekeeper" });
+    // Defensive degradation: when config is undefined (legacy test mocks
+    // bypassing the AppConfig schema via `as unknown as`), behave as if
+    // disabled. Mirrors setupDeliveryMirror's optional-chain pattern.
+    // Production paths get a fully-defaulted config from
+    // AppConfigSchema.outputRetention, so this branch only triggers in
+    // tests with hand-constructed config objects.
+    if (!deps.config) {
+        log.debug({
+            hint: "Output retention config not present; housekeeper inactive (likely a hand-constructed test mock)",
+        }, "Output retention: no config");
+        return {
+            shutdown: () => { },
+            runOnePass: async () => ({ deleted: 0, bytesFreed: 0 }),
+        };
+    }
+    const config = deps.config;
+    let interval;
+    let running = null;
+    async function runOnePass() {
+        const outputDir = safePath(deps.workspaceDir, "output");
+        const now = Date.now();
+        let deleted = 0;
+        let bytesFreed = 0;
+        // Read class subdirectories under output/. Missing dir = nothing to do.
+        let classDirs;
+        try {
+            classDirs = readdirSync(outputDir);
+        }
+        catch {
+            log.debug({ outputDir, hint: "Output dir missing — nothing to retain yet" }, "Output retention: output dir not present");
+            return { deleted, bytesFreed };
+        }
+        for (const className of classDirs) {
+            // Resolve class config: explicit class, else fall back to "default".
+            const classConfig = config.classes[className] ?? config.classes.default;
+            if (!classConfig)
+                continue;
+            const classDir = safePath(outputDir, className);
+            let entries;
+            try {
+                entries = readdirSync(classDir);
+            }
+            catch (entryErr) {
+                log.debug({
+                    err: entryErr,
+                    classDir,
+                    hint: "Could not read class dir; will retry next pass",
+                    errorKind: "internal",
+                }, "Output retention: class dir read failed");
+                continue;
+            }
+            for (const entry of entries) {
+                const filePath = safePath(classDir, entry);
+                try {
+                    const stats = statSync(filePath);
+                    // Skip subdirectories — only retain leaf files. Per KISS, no
+                    // recursion: each retention class is a single flat directory.
+                    if (!stats.isFile())
+                        continue;
+                    const ageMs = now - stats.mtimeMs;
+                    if (ageMs > classConfig.retentionMs) {
+                        bytesFreed += stats.size;
+                        unlinkSync(filePath);
+                        deleted++;
+                    }
+                }
+                catch (fileErr) {
+                    log.debug({
+                        err: fileErr,
+                        filePath,
+                        hint: "Failed to inspect/delete file in housekeeper pass; will retry next pass",
+                        errorKind: "internal",
+                    }, "Output retention: file inspect/delete failed");
+                }
+            }
+        }
+        if (deleted > 0) {
+            log.info({
+                deleted,
+                bytesFreed,
+                class: "output_retention",
+                hint: "Per-class output retention completed; files older than configured retentionMs removed",
+            }, "Output retention: housekeeper pass completed");
+        }
+        else {
+            log.debug({ class: "output_retention", hint: "No files exceeded retentionMs this pass" }, "Output retention: nothing to delete");
+        }
+        return { deleted, bytesFreed };
+    }
+    function startInterval() {
+        if (!config.enabled) {
+            log.info({ hint: "Output retention disabled by config; not starting housekeeper" }, "Output retention: disabled");
+            return;
+        }
+        interval = setInterval(() => {
+            // Single-tick gate: in-flight Promise prevents overlapping ticks.
+            if (running)
+                return;
+            running = runOnePass()
+                .then(() => undefined)
+                .finally(() => {
+                running = null;
+            });
+            // Fire-and-forget: failures inside runOnePass are already logged
+            // and do not propagate (it never throws). suppressError satisfies
+            // the no-floating-promise lint without altering semantics.
+            suppressError(running, "output retention recurring tick");
+        }, config.intervalMs);
+        interval.unref();
+        log.info({
+            intervalMs: config.intervalMs,
+            classes: Object.keys(config.classes),
+            hint: "Output retention housekeeper started",
+        }, "Output retention: started");
+    }
+    function shutdown() {
+        if (interval) {
+            clearInterval(interval);
+            interval = undefined;
+        }
+    }
+    // Start immediately on construction (mirrors setup-delivery's startup pattern).
+    startInterval();
+    return { shutdown, runOnePass };
+}

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

@@ -1,11 +1,10 @@
 /**
  * Tool assembly setup: assembleToolsForAgent and preprocessMessageText.
- * Extracted from daemon.ts steps 6.6.8.5 (tool pipeline assembly) to isolate
- * per-agent tool creation and message preprocessing from the main wiring
- * sequence.
+ * Isolates per-agent tool creation and message preprocessing from the
+ * main wiring sequence.
  * @module
  */
-import type { AppContainer, ApprovalGate, CredentialMappingPort, WrapExternalContentOptions, SessionKey } from "@comis/core";
+import type { AppContainer, ApprovalGate, CredentialMappingPort, WrapExternalContentOptions, SessionKey, ToolCapabilityPort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { SessionTrackerRegistry } from "@comis/agent";
 import type { PerAgentConfig } from "@comis/core";
@@ -54,6 +53,21 @@ export interface ToolsDeps {
      * without requiring a daemon restart.
      */
     mcpClientManager: McpClientManager;
+    /**
+     * Per-agent ToolCapabilityPort resolver. Populated by daemon.ts from the
+     * AgentsResult.toolCapabilityPorts map (one adapter per agent constructed
+     * inside setupSingleAgent). Used by exec / process tools to consult the
+     * live install-detour mode + connected MCP servers + visible skills, and
+     * to read operator-supplied cluster hints. The closure may throw or fall
+     * back to the default agent's port for unknown agentIds -- daemon.ts
+     * decides the contract.
+     *
+     * Consumed via the single mandated form `deps.getCapabilityPortForAgent(agentId)`
+     * inside assembleToolsForAgent (mirrors the deps.<field> direct-access
+     * convention used for nearby fields like deps.eventBus, deps.skillsLogger,
+     * deps.linkRunner, deps.subprocessEnv).
+     */
+    getCapabilityPortForAgent: (agentId: string) => ToolCapabilityPort;
     /** Image generation provider (undefined when API key missing -- tool not registered). */
     imageGenProvider?: ImageGenerationPort;
     /** OS-level sandbox provider detected once at daemon startup. */