@cleocode/cleo 2026.4.161 → 2026.5.1

package/dist/dispatch/middleware/protocol-enforcement.js

@@ -0,0 +1,56 @@
+import { ProtocolEnforcer } from '@cleocode/core/internal';
+/**
+ * Creates a middleware that enforces protocol compliance.
+ *
+ * Delegates to ProtocolEnforcer.enforceProtocol() which:
+ * - Passes through query operations untouched
+ * - Passes through mutate operations that don't require validation
+ * - Validates protocol compliance on validated mutate operations after execution
+ * - In strict mode, blocks operations with protocol violations (exit codes 60-70)
+ *
+ * @remarks
+ * ProtocolEnforcer.enforceProtocol uses the core's proto-shape (`_meta`) while
+ * the dispatch layer uses the canonical CLI envelope shape (`meta`). This
+ * middleware bridges between the two shapes:
+ * - Wraps `next` to map `DispatchResponse.meta` → proto-shape `_meta` for the enforcer
+ * - Maps the enforcer's proto-shape result back to `DispatchResponse` (with `meta`)
+ * - Ensures `source` and `requestId` are always populated on the returned `meta`
+ *
+ * @param strictMode - When true, blocks operations that violate protocol rules
+ * @returns Middleware function that enforces protocol compliance
+ *
+ * @example
+ * ```typescript
+ * import { createProtocolEnforcement } from './protocol-enforcement.js';
+ *
+ * const enforcement = createProtocolEnforcement(true);
+ * ```
+ */
+export function createProtocolEnforcement(strictMode = true) {
+    const enforcer = new ProtocolEnforcer(strictMode);
+    return async (req, next) => {
+        // Bridge DispatchNext (returns DispatchResponse with `meta`) to the proto-shape
+        // expected by ProtocolEnforcer (ProtocolResponse with `_meta`).
+        const protoNext = async () => {
+            const dispatchResult = await next();
+            // Map canonical `meta` → proto-shape `_meta` for the enforcer
+            const { meta, ...rest } = dispatchResult;
+            return { ...rest, _meta: meta };
+        };
+        const protoResult = await enforcer.enforceProtocol(req, protoNext);
+        // Map proto-shape result back to canonical DispatchResponse shape.
+        // enforceProtocol may return a minimal proto-response (missing source/requestId)
+        // when it constructs an error response — fill those in from the request.
+        const { _meta, ...protoRest } = protoResult;
+        const responseMeta = {
+            ..._meta,
+            source: _meta.source ?? req.source,
+            requestId: _meta.requestId ?? req.requestId,
+        };
+        return {
+            ...protoRest,
+            meta: responseMeta,
+        };
+    };
+}
+//# sourceMappingURL=protocol-enforcement.js.map

package/dist/dispatch/middleware/protocol-enforcement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-enforcement.js","sourceRoot":"","sources":["../../../src/dispatch/middleware/protocol-enforcement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,yBAAyB,CAAC,aAAsB,IAAI;IAClE,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAElD,OAAO,KAAK,EAAE,GAAoB,EAAE,IAAkB,EAA6B,EAAE;QACnF,gFAAgF;QAChF,gEAAgE;QAChE,MAAM,SAAS,GAAG,KAAK,IAAI,EAAE;YAC3B,MAAM,cAAc,GAAG,MAAM,IAAI,EAAE,CAAC;YACpC,8DAA8D;YAC9D,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,cAAc,CAAC;YACzC,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAClC,CAAC,CAAC;QAEF,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,eAAe,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAEnE,mEAAmE;QACnE,iFAAiF;QACjF,yEAAyE;QACzE,MAAM,EAAE,KAAK,EAAE,GAAG,SAAS,EAAE,GAAG,WAAW,CAAC;QAC5C,MAAM,YAAY,GAAG;YACnB,GAAG,KAAK;YACR,MAAM,EAAG,KAAK,CAAC,MAA6C,IAAI,GAAG,CAAC,MAAM;YAC1E,SAAS,EAAG,KAAK,CAAC,SAAoB,IAAI,GAAG,CAAC,SAAS;SACxD,CAAC;QAEF,OAAO;YACL,GAAG,SAAS;YACZ,IAAI,EAAE,YAAY;SACC,CAAC;IACxB,CAAC,CAAC;AACJ,CAAC"}

package/dist/dispatch/middleware/rate-limiter.d.ts

@@ -0,0 +1,72 @@
+import type { DispatchRequest, Middleware, RateLimitMeta } from '../types.js';
+/**
+ * Per-category rate limit thresholds.
+ *
+ * @remarks
+ * Each category (query, mutate, spawn) uses a sliding window algorithm.
+ * Requests older than `windowMs` are pruned before checking the count.
+ */
+export interface RateLimitConfig {
+    /** Maximum number of requests allowed within the window. */
+    maxRequests: number;
+    /** Sliding window duration in milliseconds. */
+    windowMs: number;
+}
+/**
+ * Full rate limiting configuration across all categories.
+ *
+ * @remarks
+ * When `enabled` is false, all requests pass through without limit checks.
+ */
+export interface RateLimitingConfig {
+    /** Whether rate limiting is active. */
+    enabled: boolean;
+    /** Limits for read-only query operations. */
+    query: RateLimitConfig;
+    /** Limits for mutate (write) operations. */
+    mutate: RateLimitConfig;
+    /** Limits for spawn (subagent launch) operations. */
+    spawn: RateLimitConfig;
+}
+export declare const DEFAULT_RATE_LIMITING: RateLimitingConfig;
+/**
+ * Sliding-window rate limiter for the dispatch pipeline.
+ *
+ * @remarks
+ * Tracks request timestamps per category (query, mutate, spawn) using
+ * in-memory sliding window buckets. The `check` method prunes stale
+ * timestamps, evaluates the current count, and returns whether the
+ * request is allowed along with limit metadata.
+ */
+export declare class RateLimiter {
+    /** Per-category sliding window buckets. */
+    private buckets;
+    /** Merged configuration with defaults. */
+    private config;
+    constructor(config?: Partial<RateLimitingConfig>);
+    check(req: DispatchRequest): RateLimitMeta & {
+        allowed: boolean;
+    };
+    private resolveCategory;
+    private getLimitConfig;
+}
+/**
+ * Creates a rate limiting middleware for the dispatch pipeline.
+ *
+ * @remarks
+ * Attaches rate limit metadata to every response `_meta.rateLimit` field.
+ * When the limit is exceeded, returns an error response with code
+ * `E_RATE_LIMIT_EXCEEDED` and HTTP-style exit code 429.
+ *
+ * @param config - Optional partial config to override defaults
+ * @returns Middleware function that enforces rate limits
+ *
+ * @example
+ * ```typescript
+ * import { createRateLimiter } from './rate-limiter.js';
+ *
+ * const limiter = createRateLimiter({ query: { maxRequests: 50, windowMs: 30_000 } });
+ * ```
+ */
+export declare function createRateLimiter(config?: Partial<RateLimitingConfig>): Middleware;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/dispatch/middleware/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../../src/dispatch/middleware/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,eAAe,EAEf,UAAU,EACV,aAAa,EACd,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,KAAK,EAAE,eAAe,CAAC;IACvB,4CAA4C;IAC5C,MAAM,EAAE,eAAe,CAAC;IACxB,qDAAqD;IACrD,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,eAAO,MAAM,qBAAqB,EAAE,kBAKnC,CAAC;AASF;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,2CAA2C;IAC3C,OAAO,CAAC,OAAO,CAA+C;IAC9D,0CAA0C;IAC1C,OAAO,CAAC,MAAM,CAAqB;gBAEvB,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC;IAUhD,KAAK,CAAC,GAAG,EAAE,eAAe,GAAG,aAAa,GAAG;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE;IA2CjE,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,cAAc;CAGvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,UAAU,CAqClF"}

package/dist/dispatch/middleware/rate-limiter.js

@@ -0,0 +1,127 @@
+export const DEFAULT_RATE_LIMITING = {
+    enabled: true,
+    query: { maxRequests: 100, windowMs: 60_000 },
+    mutate: { maxRequests: 30, windowMs: 60_000 },
+    spawn: { maxRequests: 10, windowMs: 60_000 },
+};
+/**
+ * Sliding-window rate limiter for the dispatch pipeline.
+ *
+ * @remarks
+ * Tracks request timestamps per category (query, mutate, spawn) using
+ * in-memory sliding window buckets. The `check` method prunes stale
+ * timestamps, evaluates the current count, and returns whether the
+ * request is allowed along with limit metadata.
+ */
+export class RateLimiter {
+    /** Per-category sliding window buckets. */
+    buckets = new Map();
+    /** Merged configuration with defaults. */
+    config;
+    constructor(config) {
+        this.config = {
+            ...DEFAULT_RATE_LIMITING,
+            ...config,
+            query: { ...DEFAULT_RATE_LIMITING.query, ...config?.query },
+            mutate: { ...DEFAULT_RATE_LIMITING.mutate, ...config?.mutate },
+            spawn: { ...DEFAULT_RATE_LIMITING.spawn, ...config?.spawn },
+        };
+    }
+    check(req) {
+        if (!this.config.enabled) {
+            return {
+                allowed: true,
+                remaining: Infinity,
+                limit: Infinity,
+                resetMs: 0,
+                category: 'disabled',
+            };
+        }
+        const category = this.resolveCategory(req.gateway, req.domain, req.operation);
+        const limitConfig = this.getLimitConfig(category);
+        const now = Date.now();
+        const windowStart = now - limitConfig.windowMs;
+        let bucket = this.buckets.get(category);
+        if (!bucket) {
+            bucket = { timestamps: [] };
+            this.buckets.set(category, bucket);
+        }
+        // Clean up old timestamps
+        bucket.timestamps = bucket.timestamps.filter((t) => t > windowStart);
+        const allowed = bucket.timestamps.length < limitConfig.maxRequests;
+        if (allowed) {
+            bucket.timestamps.push(now);
+        }
+        const oldest = bucket.timestamps[0] || now;
+        const resetMs = Math.max(0, oldest + limitConfig.windowMs - now);
+        return {
+            allowed,
+            remaining: Math.max(0, limitConfig.maxRequests - bucket.timestamps.length),
+            limit: limitConfig.maxRequests,
+            resetMs,
+            category,
+        };
+    }
+    resolveCategory(gateway, domain, operation) {
+        if (domain === 'orchestrate' && operation === 'spawn') {
+            return 'spawn';
+        }
+        return gateway === 'query' ? 'query' : 'mutate';
+    }
+    getLimitConfig(category) {
+        return this.config[category];
+    }
+}
+/**
+ * Creates a rate limiting middleware for the dispatch pipeline.
+ *
+ * @remarks
+ * Attaches rate limit metadata to every response `_meta.rateLimit` field.
+ * When the limit is exceeded, returns an error response with code
+ * `E_RATE_LIMIT_EXCEEDED` and HTTP-style exit code 429.
+ *
+ * @param config - Optional partial config to override defaults
+ * @returns Middleware function that enforces rate limits
+ *
+ * @example
+ * ```typescript
+ * import { createRateLimiter } from './rate-limiter.js';
+ *
+ * const limiter = createRateLimiter({ query: { maxRequests: 50, windowMs: 30_000 } });
+ * ```
+ */
+export function createRateLimiter(config) {
+    const limiter = new RateLimiter(config);
+    return async (req, next) => {
+        const check = limiter.check(req);
+        if (!check.allowed) {
+            return {
+                meta: {
+                    gateway: req.gateway,
+                    domain: req.domain,
+                    operation: req.operation,
+                    timestamp: new Date().toISOString(),
+                    duration_ms: 0,
+                    source: req.source,
+                    requestId: req.requestId,
+                    rateLimit: check,
+                },
+                success: false,
+                error: {
+                    code: 'E_RATE_LIMIT_EXCEEDED',
+                    exitCode: 429, // Too Many Requests
+                    message: `Rate limit exceeded for category: ${check.category}. Please wait ${Math.ceil(check.resetMs / 1000)} seconds.`,
+                },
+            };
+        }
+        const response = await next();
+        response.meta.rateLimit = {
+            limit: check.limit,
+            remaining: check.remaining,
+            resetMs: check.resetMs,
+            category: check.category,
+        };
+        return response;
+    };
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/dispatch/middleware/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../../src/dispatch/middleware/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/dispatch/middleware/sanitizer.d.ts

@@ -0,0 +1,24 @@
+import type { Middleware } from '../types.js';
+/**
+ * Creates a middleware that sanitizes incoming request parameters.
+ * Uses the canonical sanitization logic from security.ts to handle
+ * Task IDs, paths, string lengths, and enum validation.
+ *
+ * @remarks
+ * If sanitization fails (e.g. path traversal detected, invalid task ID format),
+ * the middleware short-circuits the pipeline and returns an error response with
+ * code `E_VALIDATION_FAILED` (exit code 6). Otherwise, the sanitized params
+ * replace the originals on the request object before calling `next()`.
+ *
+ * @param getProjectRoot - Optional function to resolve the current project root for path sanitization
+ * @returns Middleware function that sanitizes request params
+ *
+ * @example
+ * ```typescript
+ * import { createSanitizer } from './sanitizer.js';
+ *
+ * const sanitizer = createSanitizer(() => process.cwd());
+ * ```
+ */
+export declare function createSanitizer(getProjectRoot?: () => string): Middleware;
+//# sourceMappingURL=sanitizer.d.ts.map

package/dist/dispatch/middleware/sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.d.ts","sourceRoot":"","sources":["../../../src/dispatch/middleware/sanitizer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmD,UAAU,EAAE,MAAM,aAAa,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,UAAU,CAgCzE"}

package/dist/dispatch/middleware/sanitizer.js

@@ -0,0 +1,56 @@
+import { sanitizeParams as legacySanitizeParams } from '../lib/security.js';
+/**
+ * Creates a middleware that sanitizes incoming request parameters.
+ * Uses the canonical sanitization logic from security.ts to handle
+ * Task IDs, paths, string lengths, and enum validation.
+ *
+ * @remarks
+ * If sanitization fails (e.g. path traversal detected, invalid task ID format),
+ * the middleware short-circuits the pipeline and returns an error response with
+ * code `E_VALIDATION_FAILED` (exit code 6). Otherwise, the sanitized params
+ * replace the originals on the request object before calling `next()`.
+ *
+ * @param getProjectRoot - Optional function to resolve the current project root for path sanitization
+ * @returns Middleware function that sanitizes request params
+ *
+ * @example
+ * ```typescript
+ * import { createSanitizer } from './sanitizer.js';
+ *
+ * const sanitizer = createSanitizer(() => process.cwd());
+ * ```
+ */
+export function createSanitizer(getProjectRoot) {
+    return async (req, next) => {
+        if (req.params) {
+            try {
+                const root = getProjectRoot ? getProjectRoot() : undefined;
+                req.params = legacySanitizeParams(req.params, root, {
+                    domain: req.domain,
+                    operation: req.operation,
+                });
+            }
+            catch (error) {
+                return {
+                    meta: {
+                        gateway: req.gateway,
+                        domain: req.domain,
+                        operation: req.operation,
+                        timestamp: new Date().toISOString(),
+                        duration_ms: 0,
+                        source: req.source,
+                        requestId: req.requestId,
+                    },
+                    success: false,
+                    error: {
+                        code: 'E_VALIDATION_FAILED',
+                        exitCode: 6, // VALIDATION_ERROR
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                };
+            }
+        }
+        return next();
+    };
+}
+//# sourceMappingURL=sanitizer.js.map

package/dist/dispatch/middleware/sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.js","sourceRoot":"","sources":["../../../src/dispatch/middleware/sanitizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,cAA6B;IAC3D,OAAO,KAAK,EAAE,GAAoB,EAAE,IAAkB,EAA6B,EAAE;QACnF,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,cAAc,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC3D,GAAG,CAAC,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE;oBAClD,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,SAAS,EAAE,GAAG,CAAC,SAAS;iBACzB,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO;oBACL,IAAI,EAAE;wBACJ,OAAO,EAAE,GAAG,CAAC,OAAO;wBACpB,MAAM,EAAE,GAAG,CAAC,MAAM;wBAClB,SAAS,EAAE,GAAG,CAAC,SAAS;wBACxB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;wBACnC,WAAW,EAAE,CAAC;wBACd,MAAM,EAAE,GAAG,CAAC,MAAM;wBAClB,SAAS,EAAE,GAAG,CAAC,SAAS;qBACzB;oBACD,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE;wBACL,IAAI,EAAE,qBAAqB;wBAC3B,QAAQ,EAAE,CAAC,EAAE,mBAAmB;wBAChC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;qBAChE;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/dispatch/middleware/session-resolver.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Session Resolver Middleware for CQRS Dispatch Layer.
+ *
+ * Runs FIRST in the CLI middleware pipeline.
+ * Populates request.sessionId from the best available source:
+ *
+ *   1. request.sessionId already set (explicit)  -> use it
+ *   2. getBoundSession() has context              -> stamp it
+ *   3. process.env.CLEO_SESSION_ID (legacy/transitional) -> use it
+ *   4. No session found -> leave undefined (OK for many operations)
+ *
+ * All downstream middleware (audit, enforcement) reads request.sessionId
+ * directly instead of doing their own multi-tier fallback.
+ *
+ * @epic T4959
+ */
+import type { Middleware } from '../types.js';
+/**
+ * Creates the session resolver middleware.
+ *
+ * @param cliSessionLookup Optional async function that resolves the active
+ *   session ID from SQLite for CLI commands. If not provided, the resolver
+ *   falls through to env var / null.
+ */
+export declare function createSessionResolver(cliSessionLookup?: () => Promise<string | null>): Middleware;
+//# sourceMappingURL=session-resolver.d.ts.map

package/dist/dispatch/middleware/session-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-resolver.d.ts","sourceRoot":"","sources":["../../../src/dispatch/middleware/session-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAmD,UAAU,EAAE,MAAM,aAAa,CAAC;AAE/F;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,UAAU,CA0CjG"}

package/dist/dispatch/middleware/session-resolver.js

@@ -0,0 +1,65 @@
+/**
+ * Session Resolver Middleware for CQRS Dispatch Layer.
+ *
+ * Runs FIRST in the CLI middleware pipeline.
+ * Populates request.sessionId from the best available source:
+ *
+ *   1. request.sessionId already set (explicit)  -> use it
+ *   2. getBoundSession() has context              -> stamp it
+ *   3. process.env.CLEO_SESSION_ID (legacy/transitional) -> use it
+ *   4. No session found -> leave undefined (OK for many operations)
+ *
+ * All downstream middleware (audit, enforcement) reads request.sessionId
+ * directly instead of doing their own multi-tier fallback.
+ *
+ * @epic T4959
+ */
+import { getBoundSession } from '../context/session-context.js';
+/**
+ * Creates the session resolver middleware.
+ *
+ * @param cliSessionLookup Optional async function that resolves the active
+ *   session ID from SQLite for CLI commands. If not provided, the resolver
+ *   falls through to env var / null.
+ */
+export function createSessionResolver(cliSessionLookup) {
+    return async (req, next) => {
+        // Tier 1: Explicit — already populated by adapter
+        if (req.sessionId) {
+            return next();
+        }
+        // Tier 2: Process-scoped session context
+        const bound = getBoundSession();
+        if (bound) {
+            req.sessionId = bound.sessionId;
+            return next();
+        }
+        // Tier 3: CLI active session lookup (best-effort SQLite query)
+        if (cliSessionLookup && req.source === 'cli') {
+            try {
+                const activeId = await cliSessionLookup();
+                if (activeId) {
+                    req.sessionId = activeId;
+                    return next();
+                }
+            }
+            catch {
+                // Silent failure — many CLI commands don't need a session
+            }
+        }
+        // Tier 4: Legacy env var (transitional — will be removed)
+        const envGradeId = process.env.CLEO_SESSION_GRADE_ID;
+        if (envGradeId && process.env.CLEO_SESSION_GRADE === 'true') {
+            req.sessionId = envGradeId;
+            return next();
+        }
+        const envId = process.env.CLEO_SESSION_ID;
+        if (envId) {
+            req.sessionId = envId;
+            return next();
+        }
+        // Tier 5: No session — leave undefined
+        return next();
+    };
+}
+//# sourceMappingURL=session-resolver.js.map

package/dist/dispatch/middleware/session-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-resolver.js","sourceRoot":"","sources":["../../../src/dispatch/middleware/session-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGhE;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,gBAA+C;IACnF,OAAO,KAAK,EAAE,GAAoB,EAAE,IAAkB,EAA6B,EAAE;QACnF,kDAAkD;QAClD,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAClB,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QAED,yCAAyC;QACzC,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;QAChC,IAAI,KAAK,EAAE,CAAC;YACV,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;YAChC,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QAED,+DAA+D;QAC/D,IAAI,gBAAgB,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,gBAAgB,EAAE,CAAC;gBAC1C,IAAI,QAAQ,EAAE,CAAC;oBACb,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC;oBACzB,OAAO,IAAI,EAAE,CAAC;gBAChB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,0DAA0D;YAC5D,CAAC;QACH,CAAC;QAED,0DAA0D;QAC1D,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;QACrD,IAAI,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,MAAM,EAAE,CAAC;YAC5D,GAAG,CAAC,SAAS,GAAG,UAAU,CAAC;YAC3B,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QAC1C,IAAI,KAAK,EAAE,CAAC;YACV,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC;YACtB,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QAED,uCAAuC;QACvC,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/dispatch/middleware/telemetry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Telemetry Middleware for CQRS Dispatch Layer.
+ *
+ * After every operation completes (success or failure), emits a telemetry
+ * event to telemetry.db if the user has opted in via `cleo diagnostics enable`.
+ *
+ * Behaviour:
+ *   - Fire-and-forget: errors are swallowed, never blocks the response.
+ *   - Opt-out is the DEFAULT: nothing is recorded unless explicitly enabled.
+ *   - No params, no output, no user data — only shape/timing/exit-code.
+ *
+ * @task T624
+ */
+import type { Middleware } from '../types.js';
+/**
+ * Creates the telemetry middleware.
+ * Insert into the middleware pipeline AFTER the terminal handler so it
+ * always sees the final response (including duration_ms stamp).
+ */
+export declare function createTelemetry(): Middleware;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/dispatch/middleware/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../../src/dispatch/middleware/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAmD,UAAU,EAAE,MAAM,aAAa,CAAC;AAE/F;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,UAAU,CA+B5C"}

package/dist/dispatch/middleware/telemetry.js

@@ -0,0 +1,50 @@
+/**
+ * Telemetry Middleware for CQRS Dispatch Layer.
+ *
+ * After every operation completes (success or failure), emits a telemetry
+ * event to telemetry.db if the user has opted in via `cleo diagnostics enable`.
+ *
+ * Behaviour:
+ *   - Fire-and-forget: errors are swallowed, never blocks the response.
+ *   - Opt-out is the DEFAULT: nothing is recorded unless explicitly enabled.
+ *   - No params, no output, no user data — only shape/timing/exit-code.
+ *
+ * @task T624
+ */
+import { isTelemetryEnabled, recordTelemetryEvent } from '@cleocode/core/internal';
+/**
+ * Creates the telemetry middleware.
+ * Insert into the middleware pipeline AFTER the terminal handler so it
+ * always sees the final response (including duration_ms stamp).
+ */
+export function createTelemetry() {
+    return async (req, next) => {
+        const startTime = Date.now();
+        const response = await next();
+        // Fire-and-forget — never awaited, never throws to caller.
+        // Wrapping isTelemetryEnabled in try/catch guards against mocked environments
+        // where the underlying getPlatformPaths / getCleoHome may not be available.
+        try {
+            if (isTelemetryEnabled()) {
+                const durationMs = response.meta.duration_ms ?? Date.now() - startTime;
+                const exitCode = response.success ? 0 : (response.error?.exitCode ?? 1);
+                const errorCode = response.error?.code ?? null;
+                recordTelemetryEvent({
+                    domain: req.domain,
+                    gateway: req.gateway,
+                    operation: req.operation,
+                    durationMs,
+                    exitCode,
+                    errorCode,
+                }).catch(() => {
+                    // Non-fatal — telemetry failure must never surface to the user
+                });
+            }
+        }
+        catch {
+            // Non-fatal: telemetry check must never crash the dispatch pipeline
+        }
+        return response;
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/dispatch/middleware/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../../src/dispatch/middleware/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAGnF;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,EAAE,GAAoB,EAAE,IAAkB,EAA6B,EAAE;QACnF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAC;QAE9B,2DAA2D;QAC3D,8EAA8E;QAC9E,4EAA4E;QAC5E,IAAI,CAAC;YACH,IAAI,kBAAkB,EAAE,EAAE,CAAC;gBACzB,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;gBACvE,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAC;gBACxE,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,EAAE,IAAI,IAAI,IAAI,CAAC;gBAE/C,oBAAoB,CAAC;oBACnB,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,SAAS,EAAE,GAAG,CAAC,SAAS;oBACxB,UAAU;oBACV,QAAQ;oBACR,SAAS;iBACV,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;oBACZ,+DAA+D;gBACjE,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;QACtE,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC"}

package/dist/dispatch/middleware/verification-gates.d.ts

@@ -0,0 +1,22 @@
+import type { Middleware } from '../types.js';
+/**
+ * Creates a middleware that enforces verification gates on task operations.
+ *
+ * @remarks
+ * Maps the dispatch request into a legacy OperationContext and delegates
+ * to the core VerificationGate. When verification fails, returns an error
+ * response with code `E_VALIDATION_FAILED` (exit code 80, LIFECYCLE_GATE_FAILED).
+ * On success, attaches the verification result to the response `_meta.verification`.
+ *
+ * @param strictMode - When true, blocks operations that fail verification gates
+ * @returns Middleware function that enforces verification gates
+ *
+ * @example
+ * ```typescript
+ * import { createVerificationGates } from './verification-gates.js';
+ *
+ * const gates = createVerificationGates(true);
+ * ```
+ */
+export declare function createVerificationGates(strictMode?: boolean): Middleware;
+//# sourceMappingURL=verification-gates.d.ts.map

package/dist/dispatch/middleware/verification-gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-gates.d.ts","sourceRoot":"","sources":["../../../src/dispatch/middleware/verification-gates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmD,UAAU,EAAE,MAAM,aAAa,CAAC;AAE/F;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,GAAE,OAAc,GAAG,UAAU,CAyC9E"}

package/dist/dispatch/middleware/verification-gates.js

@@ -0,0 +1,59 @@
+import { createVerificationGate as legacyCreateGate } from '@cleocode/core/internal';
+/**
+ * Creates a middleware that enforces verification gates on task operations.
+ *
+ * @remarks
+ * Maps the dispatch request into a legacy OperationContext and delegates
+ * to the core VerificationGate. When verification fails, returns an error
+ * response with code `E_VALIDATION_FAILED` (exit code 80, LIFECYCLE_GATE_FAILED).
+ * On success, attaches the verification result to the response `_meta.verification`.
+ *
+ * @param strictMode - When true, blocks operations that fail verification gates
+ * @returns Middleware function that enforces verification gates
+ *
+ * @example
+ * ```typescript
+ * import { createVerificationGates } from './verification-gates.js';
+ *
+ * const gates = createVerificationGates(true);
+ * ```
+ */
+export function createVerificationGates(strictMode = true) {
+    const gate = legacyCreateGate(strictMode);
+    return async (req, next) => {
+        // Map DispatchRequest to legacy OperationContext
+        const context = {
+            domain: req.domain,
+            operation: req.operation,
+            gateway: req.gateway === 'query' ? 'query' : 'mutate',
+            params: req.params,
+            taskId: req.params?.taskId || req.params?.parent,
+        };
+        const result = await gate.verifyOperation(context);
+        if (!result.passed) {
+            return {
+                meta: {
+                    gateway: req.gateway,
+                    domain: req.domain,
+                    operation: req.operation,
+                    timestamp: new Date().toISOString(),
+                    duration_ms: 0,
+                    source: req.source,
+                    requestId: req.requestId,
+                    verification: result,
+                },
+                success: false,
+                error: {
+                    code: 'E_VALIDATION_FAILED',
+                    exitCode: 80, // LIFECYCLE_GATE_FAILED
+                    message: `Verification gate failed at layer ${result.blockedAt}: ${result.summary}`,
+                    details: { verification: result },
+                },
+            };
+        }
+        const response = await next();
+        response.meta.verification = result;
+        return response;
+    };
+}
+//# sourceMappingURL=verification-gates.js.map

package/dist/dispatch/middleware/verification-gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-gates.js","sourceRoot":"","sources":["../../../src/dispatch/middleware/verification-gates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,IAAI,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGrF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CAAC,aAAsB,IAAI;IAChE,MAAM,IAAI,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAE1C,OAAO,KAAK,EAAE,GAAoB,EAAE,IAAkB,EAA6B,EAAE;QACnF,iDAAiD;QACjD,MAAM,OAAO,GAAG;YACd,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAE,OAAiB,CAAC,CAAC,CAAE,QAAkB;YAC3E,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM,EAAG,GAAG,CAAC,MAAM,EAAE,MAAiB,IAAK,GAAG,CAAC,MAAM,EAAE,MAAiB;SACzE,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAEnD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,OAAO;gBACL,IAAI,EAAE;oBACJ,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,SAAS,EAAE,GAAG,CAAC,SAAS;oBACxB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;oBACnC,WAAW,EAAE,CAAC;oBACd,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,SAAS,EAAE,GAAG,CAAC,SAAS;oBACxB,YAAY,EAAE,MAAM;iBACrB;gBACD,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,qBAAqB;oBAC3B,QAAQ,EAAE,EAAE,EAAE,wBAAwB;oBACtC,OAAO,EAAE,qCAAqC,MAAM,CAAC,SAAS,KAAK,MAAM,CAAC,OAAO,EAAE;oBACnF,OAAO,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE;iBAClC;aACF,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAC;QAC9B,QAAQ,CAAC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC;QACpC,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC"}