@cleocode/runtime 2026.5.130 → 2026.5.132

package/dist/gateway/rpc/index.d.ts

@@ -0,0 +1,1545 @@
+import { DomainHandler, Middleware, DispatchRequest, DispatchResponse, Gateway, GatewayStreamEvent, Source, DispatchResponseMeta, CanonicalDomain, Tier } from '@cleocode/contracts/gateway';
+import { BackgroundJobManager } from '@cleocode/core/store/background-jobs.js';
+import { Subsystem, OperationDef, SuggestedNextOp, Resolution } from '@cleocode/contracts';
+import { Server } from 'node:http';
+import '@cleocode/contracts/operations/orchestrate';
+import * as _cleocode_core_internal from '@cleocode/core/internal';
+import { EngineResult, ProblemDetails } from '@cleocode/core';
+import { GatewayRpcRequestFrame, GatewayRpcErrorFrame, GatewayRpcErrorCode, GatewayRpcResponseFrame } from '@cleocode/contracts/gateway/rpc';
+import { Server as Server$1 } from 'node:net';
+
+/**
+ * Central Dispatcher -- Routes requests through middleware to domain handlers.
+ *
+ * The dispatcher is the single entry point for the CLI adapter.
+ * It resolves operations, validates parameters, runs the middleware pipeline,
+ * and delegates to the appropriate domain handler.
+ *
+ * Flow: DispatchRequest → resolve → param validation → middleware → handler
+ *
+ * ## T1088 — Dialectic Evaluator Hook (PSYCHE Wave 3)
+ *
+ * After each successful mutate operation, the dispatcher fires a background
+ * `evaluateDialectic` call via `setImmediate` if all of the following apply:
+ *
+ *   1. The response indicates `success: true`.
+ *   2. The request gateway is `"mutate"` (state-modifying user-facing commands).
+ *   3. A `sessionId` is present on the request (identifies conversation context).
+ *   4. The in-memory rate limiter allows the evaluation (1 per 10s per session).
+ *
+ * Errors from the background evaluation are caught and logged at `warn` level
+ * so they never affect the caller.
+ *
+ * @epic T4820
+ * @task T1088
+ */
+
+interface DispatcherConfig {
+    handlers: Map<string, DomainHandler>;
+    middlewares?: Middleware[];
+}
+declare class Dispatcher {
+    private handlers;
+    private pipeline;
+    constructor(config: DispatcherConfig);
+    dispatch(request: DispatchRequest): Promise<DispatchResponse>;
+}
+
+/**
+ * `node:http` server binding for the framework-agnostic HTTP gateway adapter.
+ *
+ * The HTTP adapter ({@link routeUnary} + the SSE primitives) is deliberately
+ * framework-agnostic — it owns NO port binding and NO `Request`/`Response`
+ * lifecycle, so an embedder (a SvelteKit route, a test harness) can drive it
+ * directly. The **daemon**, however, is itself the embedder: it must expose the
+ * gateway to external HTTP clients over a real listening socket. This module is
+ * that thin embedder — a minimal `node:http` server that parses the request URL
+ * into a `(gateway, domain, operation)` triple, reads the JSON body, and routes
+ * it through {@link routeUnary}. It deliberately stays in the runtime (no
+ * SvelteKit / no `@cleocode/cleo` / no drizzle dependency) so the daemon can
+ * host the gateway without reaching across a package boundary.
+ *
+ * Routing contract (intentionally minimal — the wire vocabulary is the same as
+ * every other transport, only the framing differs):
+ *
+ *   `POST /<gateway>/<domain>/<operation>`  with a JSON body → operation params
+ *
+ * where `<gateway>` is `query` | `mutate`. A non-POST method, an unparseable
+ * path, or a body that is not a JSON object is rejected at the wire edge with a
+ * LAFS-shaped error envelope — the injected {@link GatewayHandler} is never
+ * invoked with a malformed request.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway/http
+ *
+ * @task T11451
+ * @epic T11254
+ * @saga T11243 SG-RUNTIME-UNIFICATION
+ */
+
+/**
+ * Options for {@link startHttpServer}.
+ *
+ * Mirrors the connection-oriented {@link RpcServerOptions} shape: the caller
+ * resolves the bind coordinates so the runtime stays free of any
+ * `@cleocode/paths` dependency.
+ */
+interface HttpServerOptions {
+    /**
+     * TCP port to bind. `0` selects an ephemeral port (the bound port is then
+     * readable from {@link HttpServerHandle.port}).
+     */
+    port: number;
+    /**
+     * Host/interface to bind. Defaults to `127.0.0.1` (loopback only) — the
+     * gateway is local-process-facing; exposing it on a public interface is an
+     * explicit caller decision.
+     */
+    host?: string;
+}
+/**
+ * A live HTTP server handle returned by {@link startHttpServer}.
+ *
+ * Exposes the bound {@link Server}, the actually-bound `port` (resolved even
+ * when `0` was requested), and an idempotent {@link close}. The adapter never
+ * calls `process.exit` — lifecycle stays with the caller (R3 contract).
+ */
+interface HttpServerHandle {
+    /** The bound `node:http` server. */
+    server: Server;
+    /** The actually-bound TCP port (resolved when `0` was requested). */
+    port: number;
+    /** Host/interface the server is bound to. */
+    host: string;
+    /** Close the server + all live connections; resolves once fully closed. */
+    close(): Promise<void>;
+}
+/**
+ * The result of parsing a request line into routing coordinates: either a
+ * resolved unary triple or a rejection reason for the wire edge.
+ */
+type ParsedRoute = {
+    ok: true;
+    gateway: Gateway;
+    domain: string;
+    operation: string;
+} | {
+    ok: false;
+    status: number;
+    code: string;
+    message: string;
+};
+/**
+ * Parse `POST /<gateway>/<domain>/<operation>` into a routing triple.
+ *
+ * Rejects a non-POST method (`405`) and any path that does not resolve to a
+ * known `(gateway, domain, operation)` triple (`404`). The gateway segment is
+ * validated against the two CQRS gateways so a client cannot smuggle an
+ * arbitrary value into the dispatch request.
+ *
+ * @param method - The HTTP request method.
+ * @param url - The HTTP request URL (path + query).
+ * @returns The parsed route, or a typed rejection for the wire edge.
+ */
+declare function parseHttpRoute(method: string | undefined, url: string | undefined): ParsedRoute;
+/**
+ * Start a `node:http` server that hosts the gateway over HTTP for external
+ * clients.
+ *
+ * Binds {@link HttpServerOptions.port} on {@link HttpServerOptions.host}
+ * (default loopback), routes every `POST /<gateway>/<domain>/<operation>`
+ * through the injected {@link GatewayHandler} via {@link routeUnary}, and
+ * resolves once listening. The returned {@link HttpServerHandle} exposes an
+ * idempotent `close()` for deterministic teardown (daemon shutdown, tests). The
+ * adapter never calls `process.exit`.
+ *
+ * The caller assembles the handler (via `createGatewayHandler` with its domain
+ * handlers + middleware) and injects it here — this server never builds
+ * handlers itself, keeping the runtime free of any `@cleocode/cleo` dependency.
+ *
+ * @param handler - The transport-neutral gateway handler to route through.
+ * @param opts - Bind coordinates.
+ * @returns A promise resolving to the live {@link HttpServerHandle}.
+ */
+declare function startHttpServer(handler: GatewayHandler, opts: HttpServerOptions): Promise<HttpServerHandle>;
+
+/**
+ * NDJSON codec for the CLI-RPC transport.
+ *
+ * Implements the SAME framing discipline as the FROZEN `supervisor-ipc` v1.0
+ * contract — one zod-validated JSON envelope per newline-delimited line, with
+ * an explicit `protocol_version` negotiation step — but for the gateway-RPC
+ * frame set (`@cleocode/contracts/gateway/rpc`). The supervisor-ipc module is
+ * frozen and is NOT edited; this codec re-applies its pattern.
+ *
+ * The codec is intentionally socket-agnostic: it owns line buffering, JSON
+ * parse, zod decode, and version negotiation, returning typed results the
+ * server maps onto `node:net` reads/writes. This keeps the parse/validate logic
+ * unit-testable without binding a real socket.
+ *
+ * @task T11449
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * Encode any RPC frame to a single NDJSON line (JSON + trailing `\n`).
+ *
+ * @param frame - The response or error frame to serialize.
+ * @returns A newline-terminated JSON string ready to write to the socket.
+ */
+declare function encodeFrame(frame: GatewayRpcResponseFrame | GatewayRpcErrorFrame): string;
+/**
+ * Build a protocol-level error frame.
+ *
+ * @param id - Correlation id (`'0'` when the originating frame's id is unknown).
+ * @param code - One of the frozen {@link GatewayRpcErrorCode} values.
+ * @param message - Human-readable detail.
+ * @returns A fully-formed {@link GatewayRpcErrorFrame}.
+ */
+declare function buildErrorFrame(id: string, code: GatewayRpcErrorCode, message: string): GatewayRpcErrorFrame;
+/**
+ * The discriminated outcome of decoding a single inbound NDJSON line.
+ *
+ * - `request` — a valid, version-matched request frame ready to route.
+ * - `error`   — a protocol-level error frame the server should write straight
+ *               back (parse failure, version mismatch, or malformed frame). The
+ *               server never routes these to the gateway.
+ */
+type DecodeResult = {
+    kind: 'request';
+    frame: GatewayRpcRequestFrame;
+} | {
+    kind: 'error';
+    frame: GatewayRpcErrorFrame;
+};
+/**
+ * Decode + validate a single inbound NDJSON line into a routable request or a
+ * protocol-level error frame.
+ *
+ * Steps (the supervisor-ipc pattern, applied to gateway frames):
+ *  1. JSON parse — failure → `E_RPC_PARSE`.
+ *  2. zod decode against {@link GatewayRpcFrameSchema} — failure → `E_RPC_BAD_FRAME`.
+ *  3. version negotiation via {@link isFrozenGatewayRpcVersion} —
+ *     mismatch → `E_RPC_BAD_VERSION`.
+ *  4. direction must be `request` (a server never receives response/error
+ *     frames) — otherwise → `E_RPC_BAD_FRAME`.
+ *
+ * The best-effort correlation `id` is recovered from the raw JSON when possible
+ * so the client can match the error to its request even on a decode failure.
+ *
+ * @param line - One trimmed NDJSON line (no trailing newline).
+ * @returns A {@link DecodeResult}.
+ */
+declare function decodeLine(line: string): DecodeResult;
+/**
+ * A streaming line splitter for the NDJSON wire.
+ *
+ * `node:net` sockets deliver arbitrary chunk boundaries; a single `data` event
+ * may carry a partial line or several lines. This buffer accumulates bytes and
+ * yields only complete lines (split on `\n`), matching the supervisor-ipc
+ * client's `readline`-style framing without depending on `readline` (so it can
+ * be driven directly off socket chunks).
+ */
+declare class LineBuffer {
+    /** Pending bytes that have not yet completed a line. */
+    private buffer;
+    /**
+     * Push a decoded UTF-8 chunk; return every complete line it completes.
+     *
+     * @param chunk - A UTF-8 string chunk from the socket.
+     * @returns Zero or more complete lines (trailing newline stripped, blanks
+     *   skipped).
+     */
+    push(chunk: string): string[];
+}
+
+/**
+ * Wire + lifecycle types for the `@cleocode/runtime/gateway/rpc` adapter.
+ *
+ * The RPC wire frames themselves are defined (zod) in
+ * `@cleocode/contracts/gateway/rpc`; this module holds only the
+ * runtime-adapter-local option/handle shapes (no external dependency, mirroring
+ * the MCP adapter's `types.ts`).
+ *
+ * @task T11449
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * Options for {@link startRpcServer}.
+ *
+ * Mirrors the MCP adapter's `McpServerOptions` shape (a transport-local options
+ * bag), adapted for a connection-oriented unix-socket server rather than a
+ * single stdio stream.
+ */
+interface RpcServerOptions {
+    /**
+     * Absolute path to the unix-domain socket to bind. The caller resolves this
+     * (e.g. under the CLEO home using
+     * {@link GATEWAY_RPC_CHANNEL_BASENAME}) so the runtime stays free of any
+     * `@cleocode/paths` dependency.
+     */
+    socketPath: string;
+    /**
+     * Whether to `unlink` a stale socket file at {@link socketPath} before
+     * binding. Defaults to `true` (a crashed prior server leaves a stale node).
+     */
+    removeStaleSocket?: boolean;
+}
+/**
+ * A live RPC server handle returned by {@link startRpcServer}.
+ *
+ * Exposes the bound {@link Server} and an idempotent {@link close} so callers
+ * (daemon, tests) can tear down deterministically. The adapter never calls
+ * `process.exit` — lifecycle stays with the caller (R3 contract).
+ */
+interface RpcServerHandle {
+    /** The bound `node:net` server. */
+    server: Server$1;
+    /** Absolute path of the bound unix socket. */
+    socketPath: string;
+    /** Close the server + all live connections; resolves once fully closed. */
+    close(): Promise<void>;
+}
+
+/**
+ * CLI-RPC unix-socket transport adapter — routes NDJSON frames through the gateway.
+ *
+ * Serves the gateway over a long-lived unix-domain socket using newline-delimited
+ * JSON (NDJSON): one zod-validated {@link GatewayRpcFrame} per line. Any local
+ * client (the `cleo` CLI talking to a warm daemon, Studio's server process, a
+ * test harness) can open the socket, write `request` frames, and read back
+ * `response`/`error` frames — without paying the per-invocation cold-start of
+ * spawning a fresh `cleo` process.
+ *
+ * This is the THIRD transport adapter, mirroring the just-merged MCP stdio
+ * adapter (`packages/runtime/src/gateway/mcp/`):
+ *
+ *   RPC request frame { direction:'request', request:{…} }
+ *     → decode + validate (`@cleocode/contracts/gateway/rpc`)
+ *     → DispatchRequest { source: 'rpc', … }  (re-validated at the boundary)
+ *     → injected {@link GatewayHandler}.handle()
+ *     → DispatchResponse (LAFS envelope)  →  RPC response frame
+ *
+ * The adapter owns ONLY wire concerns: socket lifecycle, line framing, version
+ * negotiation, error rendering, and per-connection cleanup. All domain logic
+ * (resolution, validation, middleware, handler execution) lives behind the
+ * {@link GatewayHandler} — exactly mirroring the CLI and MCP adapters. There is
+ * NO `process.exit` and NO error-render inside the handlers (R3 contract); the
+ * adapter never calls `process.exit` at all (lifecycle is the caller's).
+ *
+ * The request `source` is forced to `'rpc'` regardless of what the client sent,
+ * so a client cannot impersonate another transport.
+ *
+ * @task T11449
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * Route a single decoded request frame through the gateway handler and build
+ * the correlated response frame.
+ *
+ * The request's `source` is forced to `'rpc'`; the frame `id` is reused as the
+ * response correlation id (and, when the client omitted a `requestId` shaped
+ * for tracing, the frame id flows through as the dispatch `requestId`). Thrown
+ * handler errors are caught and rendered as a protocol-level `E_RPC_INTERNAL`
+ * error frame — never propagated as an unhandled rejection or `process.exit`.
+ *
+ * @param handler - The injected transport-neutral gateway handler.
+ * @param frame - A validated, version-matched request frame.
+ * @returns The response or error frame to write back on the same connection.
+ */
+declare function routeFrame(handler: GatewayHandler, frame: GatewayRpcRequestFrame): Promise<GatewayRpcResponseFrame | ReturnType<typeof buildErrorFrame>>;
+/**
+ * Start the CLI-RPC unix-socket server over the gateway.
+ *
+ * Binds {@link RpcServerOptions.socketPath}, accepts connections, and routes
+ * each inbound NDJSON `request` frame through the injected {@link GatewayHandler}.
+ * The caller assembles the handler (via `createGatewayHandler` with its domain
+ * handlers + middleware) and injects it here — this adapter never builds
+ * handlers itself, keeping the runtime free of any `@cleocode/cleo` dependency.
+ *
+ * Returns once the socket is listening. The returned {@link RpcServerHandle}
+ * exposes an idempotent `close()` for deterministic teardown (daemon shutdown,
+ * tests). The adapter never calls `process.exit`.
+ *
+ * @param handler - The transport-neutral gateway handler to route through.
+ * @param opts - Socket path + lifecycle options.
+ * @returns A promise resolving to the live {@link RpcServerHandle}.
+ */
+declare function startRpcServer(handler: GatewayHandler, opts: RpcServerOptions): Promise<RpcServerHandle>;
+
+/**
+ * The gateway as a supervised **daemon subsystem**.
+ *
+ * R3-T7 (this task) closes the loop between the two R-track halves: the R3
+ * gateway (dispatcher + the four transport adapters) and the R2 daemon
+ * (`defineSubsystem` + the `SubsystemRegistry`). It expresses the
+ * external-facing gateway as a uniform {@link Subsystem} so the R2 daemon
+ * registry drives its `start → healthProbe → shutdown` lifecycle exactly like
+ * every other long-running concern (Studio supervision, the GC cron, …). One
+ * gateway subsystem is registered per scope (project / global) → one
+ * external-facing gateway process per scope.
+ *
+ * Which transports the daemon hosts:
+ *  - the **RPC unix socket** (`@cleocode/runtime/gateway/rpc`) — the canonical
+ *    local-client wire: the `cleo` CLI, Studio's server process, and test
+ *    harnesses open it to dispatch without paying a cold `cleo` spawn.
+ *  - the **HTTP server** (`@cleocode/runtime/gateway/http` via the daemon-local
+ *    `startHttpServer` embedder) — for external clients that speak HTTP rather
+ *    than the unix-socket NDJSON wire.
+ *
+ * The CLI and MCP adapters are intentionally NOT hosted by the daemon: the CLI
+ * adapter is in-process to the `cleo` binary, and the MCP adapter is a stdio
+ * server an MCP client spawns and owns — neither is a long-lived,
+ * daemon-supervised listener. The two external-facing listeners (RPC + HTTP)
+ * are the ones the daemon owns.
+ *
+ * This subsystem adds NO behavior to the adapters themselves — it only wires
+ * their existing `start*Server` / `close()` lifecycle (and their already-merged
+ * routing) into the daemon registry's uniform lifecycle. It carries NO
+ * `@cleocode/cleo` dependency and NO drizzle-orm (the runtime invariant): the
+ * caller injects the assembled {@link GatewayHandler} and the resolved bind
+ * coordinates; this module only orchestrates listeners.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway
+ *
+ * @task T11451 (R3-T7)
+ * @epic T11254
+ * @saga T11243 SG-RUNTIME-UNIFICATION
+ */
+
+/** The scope a single gateway process serves — one external-facing process per scope. */
+type GatewayScope = 'project' | 'global';
+/**
+ * Configuration for one scoped gateway subsystem.
+ *
+ * The caller injects the assembled, transport-neutral {@link GatewayHandler}
+ * (built with `createGatewayHandler` from its domain handlers + middleware) and
+ * the resolved bind coordinates for each hosted transport. The runtime never
+ * resolves paths/ports itself — that keeps it free of `@cleocode/paths` and of
+ * any policy decision about where a scope's socket/port lives.
+ */
+interface GatewaySubsystemOptions {
+    /** The scope this gateway process serves (`project` | `global`). */
+    scope: GatewayScope;
+    /** The transport-neutral gateway handler every hosted transport routes through. */
+    handler: GatewayHandler;
+    /**
+     * RPC unix-socket transport options. When omitted, the RPC transport is not
+     * hosted (a deployment that only wants HTTP). At least one transport MUST be
+     * configured.
+     */
+    rpc?: RpcServerOptions;
+    /**
+     * HTTP transport options. When omitted, the HTTP transport is not hosted (a
+     * deployment that only wants the local RPC socket). At least one transport
+     * MUST be configured.
+     */
+    http?: HttpServerOptions;
+}
+/**
+ * The live context a started gateway subsystem threads from `start` into
+ * `healthProbe`/`shutdown`: the bound transport handles plus the owning pid.
+ *
+ * `void`-typed contexts are common for subsystems, but the gateway needs to
+ * carry its bound handles so `shutdown` can close exactly what `start` opened
+ * (and `healthProbe` can report the bound coordinates).
+ */
+interface GatewaySubsystemContext {
+    /** The OS pid hosting the listeners (this daemon process). */
+    readonly pid: number;
+    /** The bound RPC server handle, when the RPC transport is hosted. */
+    readonly rpc?: RpcServerHandle;
+    /** The bound HTTP server handle, when the HTTP transport is hosted. */
+    readonly http?: HttpServerHandle;
+}
+/**
+ * The stable subsystem name (and supervised `child_id`) of a scoped gateway.
+ *
+ * Suffixed with the scope so a single daemon process supervising both scopes
+ * (project + global) registers two distinct, non-colliding subsystems. The
+ * `child_id` matches the id the Rust supervisor tracks the listener under.
+ *
+ * @param scope - The gateway scope.
+ * @returns The subsystem name, e.g. `gateway-project`.
+ */
+declare function gatewaySubsystemName(scope: GatewayScope): string;
+/**
+ * Declare the external-facing gateway as a supervised daemon {@link Subsystem}.
+ *
+ * The returned subsystem (frozen by {@link defineSubsystem}) is registered with
+ * a `SubsystemRegistry`, which then drives its lifecycle uniformly:
+ *
+ *  - `start()`       — binds the configured transports (RPC unix socket and/or
+ *    HTTP server) over the injected handler, in a fixed order (RPC then HTTP).
+ *    If the second listener fails to bind, the first is rolled back so a failed
+ *    start leaves no half-open listener — then the error is re-thrown for the
+ *    registry's `onError` sink.
+ *  - `healthProbe()` — reports a single {@link SubsystemHealth} row keyed on the
+ *    scoped `child_id`, `running` while the configured listeners are live, with
+ *    a `detail` summarizing the bound coordinates. Projects losslessly onto the
+ *    supervisor's `ChildStatus`.
+ *  - `shutdown()`    — closes every bound listener (best-effort, idempotent) in
+ *    reverse bind order (HTTP then RPC).
+ *
+ * One subsystem instance is declared per scope, so registering the project and
+ * global gateways yields two supervised listeners → one external-facing gateway
+ * process surface per scope (AC1).
+ *
+ * @param opts - The scoped gateway configuration (handler + per-transport bind
+ *   coordinates).
+ * @returns A frozen {@link Subsystem} ready to `register()` with a
+ *   `SubsystemRegistry`.
+ * @throws {TypeError} When neither the RPC nor the HTTP transport is configured
+ *   (a gateway with no hosted transport serves nothing).
+ *
+ * @example
+ * ```ts
+ * const registry = new SubsystemRegistry();
+ * registry.register(
+ *   defineGatewaySubsystem({
+ *     scope: 'project',
+ *     handler: createGatewayHandler(dispatcherConfig),
+ *     rpc: { socketPath: '/run/cleo/cleo-gateway-rpc-project.sock' },
+ *     http: { port: 7777 },
+ *   }),
+ * );
+ * await registry.startAll();        // binds the RPC socket + HTTP server
+ * const health = await registry.aggregateHealth();
+ * await registry.shutdownAll();     // closes both listeners
+ * ```
+ */
+declare function defineGatewaySubsystem(opts: GatewaySubsystemOptions): Subsystem<GatewaySubsystemContext>;
+
+/**
+ * Centralized engine error helper for the transport-agnostic gateway.
+ *
+ * Every domain handler (and the engine barrel) imports `engineError()` /
+ * `engineSuccess()` from this module to produce consistently typed error
+ * results with correct exit codes and pino logging.
+ *
+ * The STRING_TO_EXIT map is the canonical mapping from string error codes
+ * to numeric exit codes. It mirrors ERROR_CODE_TO_EXIT in cli.ts.
+ *
+ * @remarks
+ * Relocated from `packages/cleo/src/dispatch/engines/_error.ts` into
+ * `@cleocode/runtime/gateway` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION) so the
+ * runtime owns the shared handler dependencies and can assemble the handler map
+ * without importing `@cleocode/cleo`. A thin re-export shim remains at the old
+ * `engines/_error.ts` path so in-package import sites compile unchanged.
+ *
+ * Error codes are organized into numeric ranges:
+ * - 1-9: General errors (invalid input, file, dependency, validation)
+ * - 10-19: Hierarchy errors (parent, depth, siblings, circular deps)
+ * - 20-29: Concurrency errors (checksum, modification, collision)
+ * - 30-39: Session errors (scope, claims, active task)
+ * - 40-47: Verification errors (gates, agents, rounds)
+ * - 50-54: Context safeguard (warning through emergency)
+ * - 60-67: Orchestrator / protocol errors
+ * - 70-79: Nexus errors
+ * - 80-94: Lifecycle, artifact, provenance errors
+ * - 95-99: Adapter errors
+ * - 100+: Special informational codes (not errors)
+ */
+
+/**
+ * Canonical mapping from string error codes to numeric exit codes.
+ *
+ * Source of truth: src/types/exit-codes.ts (ExitCode enum).
+ * Must stay in sync with ERROR_CODE_TO_EXIT in src/dispatch/adapters/cli.ts.
+ */
+declare const STRING_TO_EXIT: Record<string, number>;
+/**
+ * Create a typed engine error result with pino logging and correct exit code.
+ *
+ * @remarks
+ * The exit code is derived from the {@link STRING_TO_EXIT} mapping. If the
+ * code is not found in the map, exit code 1 (general error) is used.
+ * Pino logging is automatically triggered at the appropriate level
+ * (error for internal issues, warn for user/domain errors, debug for
+ * informational codes). Logging is suppressed under Vitest to keep
+ * test output clean.
+ *
+ * @param code - String error code (e.g., 'E_NOT_FOUND')
+ * @param message - Human-readable error message
+ * @param options - Optional details, fix command, and alternatives
+ * @returns EngineResult with success=false and properly structured error
+ *
+ * @example
+ * ```typescript
+ * import { engineError } from './_error.js';
+ *
+ * return engineError('E_NOT_FOUND', `Task ${id} not found`, {
+ *   fix: `cleo show ${id}`,
+ *   details: { taskId: id },
+ * });
+ * ```
+ */
+declare function engineError<T>(code: string, message: string, options?: {
+    exitCode?: number;
+    details?: Record<string, unknown>;
+    fix?: string;
+    alternatives?: Array<{
+        action: string;
+        command: string;
+    }>;
+    problemDetails?: ProblemDetails;
+}): EngineResult<T>;
+
+/**
+ * Minimal meta shape carrying the request ID for RFC 7807 `instance` population.
+ *
+ * Callers may pass the dispatch-layer `DispatchRequest.requestId` (or any
+ * other correlation identifier) so that the resulting `problemDetails.instance`
+ * URI uniquely identifies the specific error occurrence.
+ */
+interface ErrorMeta {
+    /** Unique request identifier (used as the RFC 7807 `instance` field). */
+    requestId?: string;
+}
+/**
+ * Convert any caught value into an {@link EngineResult}, forwarding the rich
+ * `fix`, `details`, and `alternatives` fields when the caught value is a
+ * `CleoError` (or structurally compatible object).
+ *
+ * @remarks
+ * This is the canonical catch-block helper for all dispatch engines. It
+ * replaces the previous pattern of:
+ * ```typescript
+ * const code = (err as { code?: number })?.code;
+ * if (code === 4) return engineError('E_NOT_FOUND', …);
+ * …
+ * ```
+ * with a single call that preserves every field the core layer attached.
+ *
+ * The `fallbackCode` is used when the numeric `err.code` is not present in
+ * the {@link STRING_TO_EXIT} mapping (e.g. unknown exit codes, plain `Error`
+ * instances, or values thrown by non-CLEO code).
+ *
+ * RFC 7807 `problemDetails` is always populated from the resolved code, message,
+ * and exit code. The optional `meta.requestId` is forwarded to the `instance`
+ * field so every error occurrence is uniquely identifiable.
+ *
+ * @param err - The caught value (unknown type)
+ * @param fallbackCode - String error code to use when mapping fails
+ * @param fallbackMessage - Human-readable message when `err.message` is absent
+ * @param meta - Optional dispatch meta carrying `requestId` for RFC 7807 `instance`
+ * @returns EngineResult with all available rich fields propagated
+ *
+ * @example
+ * ```typescript
+ * import { cleoErrorToEngineError } from './_error.js';
+ *
+ * } catch (err: unknown) {
+ *   return cleoErrorToEngineError(err, 'E_NOT_INITIALIZED', 'Task database not initialized');
+ * }
+ * ```
+ *
+ * @example With requestId for RFC 7807 instance field:
+ * ```typescript
+ * } catch (err: unknown) {
+ *   return cleoErrorToEngineError(err, 'E_NOT_FOUND', 'Not found', { requestId });
+ * }
+ * ```
+ */
+declare function cleoErrorToEngineError<T>(err: unknown, fallbackCode: string, fallbackMessage: string, meta?: ErrorMeta): EngineResult<T>;
+
+/**
+ * Parse all templates from the repo's .github/ISSUE_TEMPLATE/ directory.
+ *
+ * @remarks
+ * Delegates to the core template parser and adapts the result to the
+ * dispatch EngineResult type.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns EngineResult containing the parsed template configuration
+ *
+ * @example
+ * ```typescript
+ * const result = parseIssueTemplates('/path/to/project');
+ * if (result.success) {
+ *   console.log(result.data.templates);
+ * }
+ * ```
+ */
+declare function parseIssueTemplates(projectRoot: string): EngineResult<_cleocode_core_internal.TemplateConfig>;
+/**
+ * Get template config for a specific subcommand (bug/feature/help).
+ *
+ * @remarks
+ * Looks up a specific template by subcommand name from the project's
+ * issue template directory.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param subcommand - Template subcommand identifier (e.g. "bug", "feature")
+ * @returns EngineResult containing the matched issue template
+ *
+ * @example
+ * ```typescript
+ * const result = getTemplateForSubcommand('/path/to/project', 'bug');
+ * ```
+ */
+declare function getTemplateForSubcommand(projectRoot: string, subcommand: string): EngineResult<_cleocode_core_internal.IssueTemplate>;
+/**
+ * Generate and cache the config as .cleo/issue-templates.json.
+ *
+ * @remarks
+ * Parses all templates and writes the resulting config to disk for caching.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns EngineResult containing the generated template configuration
+ *
+ * @example
+ * ```typescript
+ * const result = await generateTemplateConfig('/path/to/project');
+ * ```
+ */
+declare function generateTemplateConfig(projectRoot: string): Promise<EngineResult<_cleocode_core_internal.TemplateConfig>>;
+/**
+ * Validate that labels exist on a GitHub repo.
+ *
+ * @remarks
+ * Compares a set of required labels against the labels found on the repo.
+ *
+ * @param labels - Labels required by the template
+ * @param repoLabels - Labels that exist on the GitHub repo
+ * @returns EngineResult with existing and missing label lists
+ *
+ * @example
+ * ```typescript
+ * const result = validateLabels(['bug', 'enhancement'], repoLabels);
+ * ```
+ */
+declare function validateLabels(labels: string[], repoLabels: string[]): EngineResult<{
+    existing: string[];
+    missing: string[];
+}>;
+
+/**
+ * Shared exit-code mapping utilities for the transport-agnostic gateway.
+ *
+ * Provides a canonical reverse lookup from numeric exit code to string error code,
+ * shared between the gateway engine helpers and every transport adapter (CLI,
+ * MCP, RPC, HTTP).
+ *
+ * @remarks
+ * Relocated from `packages/cleo/src/dispatch/lib/exit-codes.ts` into
+ * `@cleocode/runtime/gateway` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION) so the
+ * runtime can host the shared handler dependencies without importing
+ * `@cleocode/cleo`. A thin re-export shim remains at the old path.
+ *
+ * The forward mapping (string → number) lives in `engine-error.ts` as
+ * `STRING_TO_EXIT`. This module derives the inverse on first call and memoises
+ * it so engines can resolve a caught `CleoError.code` (numeric) to the
+ * string code expected by `engineError()`.
+ *
+ * @task T374
+ * @task T11455
+ * @epic T335
+ */
+/**
+ * Map a numeric CleoError exit code to the canonical string engine error code.
+ *
+ * @remarks
+ * Returns `undefined` when the numeric code is not present in the
+ * `STRING_TO_EXIT` map, allowing callers to fall back to their own default.
+ *
+ * @param numericCode - Numeric exit code from a caught `CleoError.code`
+ * @returns Canonical string error code (e.g. `'E_NOT_FOUND'`), or `undefined`
+ *
+ * @example
+ * ```typescript
+ * import { mapNumericExitCodeToString } from '../lib/exit-codes.js';
+ *
+ * const code = mapNumericExitCodeToString(4) ?? 'E_NOT_INITIALIZED';
+ * // → 'E_NOT_FOUND'
+ * ```
+ */
+declare function mapNumericExitCodeToString(numericCode: number | undefined): string | undefined;
+
+/**
+ * Wire + lifecycle types for the `@cleocode/runtime/gateway/http` adapter.
+ *
+ * The HTTP transport carries the SAME gateway payloads as every other transport
+ * — request/response shapes are owned by `@cleocode/contracts/gateway` (R3-T2 ·
+ * T11446) and the streaming frame by `GatewayStreamEvent`. This module holds
+ * only the runtime-adapter-local option/handle shapes (mirroring the MCP and RPC
+ * adapters' `types.ts`), so the runtime stays framework-agnostic and free of any
+ * `@cleocode/cleo` / SvelteKit / drizzle dependency.
+ *
+ * @task T11450
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * Where on the wire the `(gateway, domain, operation)` triple of an HTTP unary
+ * request is sourced from. The adapter is framework-agnostic, so the embedder
+ * (SvelteKit route, daemon HTTP server, test harness) supplies the resolved
+ * coordinates explicitly rather than the adapter parsing a URL itself.
+ */
+interface HttpUnaryRequest {
+    /** CQRS gateway — `'mutate'` (write) or `'query'` (read). */
+    gateway: Gateway;
+    /** Target canonical domain (e.g. `'tasks'`). */
+    domain: string;
+    /** Domain operation name (e.g. `'show'`). */
+    operation: string;
+    /** Decoded JSON request body → operation params. */
+    params?: Record<string, unknown>;
+    /**
+     * Optional caller-supplied request id for tracing. When omitted the adapter
+     * mints a fresh UUID.
+     */
+    requestId?: string;
+    /** Bound session id, if any (forwarded into the dispatch request). */
+    sessionId?: string;
+}
+/**
+ * The result of routing one HTTP unary request through the gateway: the LAFS
+ * {@link DispatchResponse} JSON body plus the HTTP status the embedder should
+ * set (200 on success, 4xx/5xx mapped from the dispatch error).
+ *
+ * The adapter never writes the response itself (no framework coupling) — it
+ * returns this so the embedder serializes it onto its own `Response`.
+ */
+interface HttpUnaryResult {
+    /** HTTP status code derived from the dispatch outcome. */
+    status: number;
+    /** The LAFS envelope to serialize as the JSON response body. */
+    body: DispatchResponse;
+}
+
+/**
+ * HTTP transport adapter — serves gateway unary + SSE over HTTP.
+ *
+ * The fourth and final gateway transport (after CLI, MCP, RPC). Unlike the
+ * connection-oriented RPC/MCP adapters, the HTTP adapter is framework-agnostic
+ * by design: it does NOT bind a port or own a `Request`/`Response` lifecycle.
+ * Instead it exposes two pure routing primitives the embedder (a SvelteKit
+ * route handler, the daemon's HTTP server, a test harness) calls directly:
+ *
+ *   - {@link routeUnary} — one POST → `source: 'http'` {@link DispatchRequest}
+ *     → injected {@link GatewayHandler} → `{ status, body }` (LAFS envelope).
+ *   - the SSE primitives in `./sse.js` (`createSseStream`) for streaming ops.
+ *
+ * This keeps the runtime free of any HTTP-server / SvelteKit / `@cleocode/cleo`
+ * dependency: the embedder owns wire concerns (parsing the URL into a
+ * `(gateway, domain, operation)` triple, setting headers, `process.exit`,
+ * error-render at the edge), exactly mirroring how the CLI adapter wraps the
+ * same handler. There is NO `process.exit` and NO error-render in the handlers
+ * (R3 contract); the adapter never calls `process.exit` at all.
+ *
+ * The request `source` is forced to `'http'` regardless of what the embedder
+ * passes, so a client cannot impersonate another transport.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway/http
+ *
+ * @task T11450
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * Map a LAFS dispatch error code to an HTTP status code.
+ *
+ * The canonical machine-readable error code (`E_NOT_FOUND`, `E_VALIDATION_…`,
+ * `E_FORBIDDEN`, …) is the source of truth; the numeric LAFS exit code is a
+ * secondary hint. Unknown error codes fall back to `500`. A successful envelope
+ * is always `200`.
+ *
+ * @param response - The dispatch response.
+ * @returns The HTTP status the embedder should set.
+ */
+declare function statusForResponse(response: DispatchResponse): number;
+/**
+ * Route a single HTTP unary request through the gateway handler.
+ *
+ * Builds a `source: 'http'` {@link DispatchRequest} from the embedder-resolved
+ * `(gateway, domain, operation, params)` triple and delegates to the injected
+ * {@link GatewayHandler}. A thrown handler error is trapped and rendered as a
+ * `500` LAFS error envelope — never propagated as an unhandled rejection or
+ * `process.exit`. The `source` is always forced to `'http'`.
+ *
+ * @param handler - The injected transport-neutral gateway handler.
+ * @param req - The embedder-resolved unary request coordinates + body params.
+ * @returns The HTTP status + LAFS response body for the embedder to serialize.
+ */
+declare function routeUnary(handler: GatewayHandler, req: HttpUnaryRequest): Promise<HttpUnaryResult>;
+
+/**
+ * Server-Sent Events (SSE) wire primitives for the `@cleocode/runtime/gateway/http`
+ * adapter.
+ *
+ * The HTTP transport is the only gateway transport that streams: long-running
+ * and subscription operations emit a sequence of {@link GatewayStreamEvent}
+ * frames terminated by a `done` or `error` frame. This module owns ONLY the SSE
+ * wire encoding + the `ReadableStream` lifecycle plumbing; the actual frame
+ * production (polling a DB, tailing a job, etc.) lives in the caller's async
+ * source. Keeping the encode/stream concern here lets BOTH the gateway-routed
+ * streaming ops AND the existing Studio SSE endpoints (which carry their own
+ * domain event shapes) share one tested, leak-free stream builder.
+ *
+ * Two encoders are provided so an existing stream can adopt this plumbing
+ * WITHOUT changing its observed bytes:
+ *  - {@link encodeStreamEvent} — the canonical `data: <json>\n\n` form for
+ *    {@link GatewayStreamEvent} frames (gateway-routed streaming ops).
+ *  - {@link encodeSseFrame} — a generic `event:`/`id:`/`data:` writer for any
+ *    payload, so endpoints with a bespoke wire (a named `event:` field, a
+ *    `data:`-only frame) keep an IDENTICAL byte stream while still routing their
+ *    lifecycle through the shared, abort-safe builder.
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway/http/sse
+ *
+ * @task T11450
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * One generic SSE frame: an optional named `event`, an optional `id`, and a
+ * `data` payload that is JSON-serialized.
+ *
+ * This is intentionally NOT {@link GatewayStreamEvent} — it is the raw wire
+ * shape so a bespoke endpoint can reproduce its exact existing bytes (e.g. a
+ * named `event: task-updated` line, or a `data:`-only frame with no `event`).
+ */
+interface SseFrame {
+    /** Optional SSE `event:` field name (omitted → a `data:`-only frame). */
+    event?: string;
+    /** Optional SSE `id:` field for client-side last-event-id resumption. */
+    id?: string;
+    /** The frame payload; JSON-serialized into the `data:` field. */
+    data: unknown;
+}
+/**
+ * Encode a generic {@link SseFrame} to its SSE wire bytes.
+ *
+ * Field order is `event:` (if present) → `id:` (if present) → `data:`, matching
+ * the SSE spec record layout, then a blank line. When `event` is omitted the
+ * frame is a `data:`-only record — byte-identical to a handwritten
+ * `data: <json>\n\n`.
+ *
+ * @param frame - The frame to serialize.
+ * @returns The SSE record as a string (UTF-8 caller-encoded).
+ */
+declare function encodeSseFrame(frame: SseFrame): string;
+/**
+ * Encode a canonical {@link GatewayStreamEvent} as a `data:`-only SSE record.
+ *
+ * Gateway-routed streaming ops carry the discriminator + sequence inside the
+ * JSON payload (`{ kind, seq, data, error, requestId }`), so no named SSE
+ * `event:` field is used — the client demultiplexes on `kind`/`seq`. The
+ * monotonic `seq` is also surfaced as the SSE `id:` so a reconnecting client can
+ * send `Last-Event-ID`.
+ *
+ * @param frame - The gateway stream event to serialize.
+ * @returns The SSE record as a string.
+ */
+declare function encodeStreamEvent(frame: GatewayStreamEvent): string;
+/** The standard SSE response headers (no caching, no proxy buffering). */
+declare const SSE_HEADERS: Readonly<Record<string, string>>;
+/**
+ * A push-style SSE controller handed to an {@link SseSource} so it can emit
+ * frames and close the stream without touching the underlying
+ * `ReadableStreamDefaultController`.
+ */
+interface SseEmitter {
+    /** Emit one generic SSE frame; a no-op once the stream is closed. */
+    send(frame: SseFrame): void;
+    /** Emit one canonical {@link GatewayStreamEvent}; a no-op once closed. */
+    sendStreamEvent(frame: GatewayStreamEvent): void;
+    /**
+     * Emit a pre-encoded SSE record verbatim; a no-op once closed. For endpoints
+     * that own their own wire encoder (e.g. a bespoke `data: <json>\n\n`) and want
+     * to keep emitting byte-identical records while still routing lifecycle
+     * through this builder.
+     */
+    sendRaw(record: string): void;
+    /** Whether the stream has been closed (client disconnect or `close()`). */
+    readonly closed: boolean;
+    /** Close the stream; idempotent. */
+    close(): void;
+}
+/**
+ * A teardown callback returned by an {@link SseSource}, invoked exactly once when
+ * the stream ends (client disconnect, `emitter.close()`, or producer completion).
+ */
+type SseTeardown = () => void;
+/**
+ * A frame source for {@link createSseStream}. Receives an {@link SseEmitter} and
+ * MAY return an {@link SseTeardown} callback (return nothing to skip teardown).
+ *
+ * The source is started SYNCHRONOUSLY inside `ReadableStream.start`, mirroring
+ * the existing Studio endpoints (which schedule timers inside `start`). A source
+ * may push frames immediately and/or schedule async work.
+ */
+type SseSource = (emitter: SseEmitter) => SseTeardown | undefined;
+/**
+ * Build a `text/event-stream` {@link ReadableStream} driven by an
+ * {@link SseSource}.
+ *
+ * This is the shared, abort-safe stream builder every SSE endpoint routes
+ * through. It guarantees:
+ *  - frames are dropped (never throw) after the stream closes;
+ *  - the source's teardown callback runs exactly once;
+ *  - an optional {@link AbortSignal} (the request's) closes the stream on client
+ *    disconnect, with its listener removed on teardown.
+ *
+ * The byte output is fully controlled by what the source emits — so an endpoint
+ * adopting this builder reproduces its prior wire exactly by emitting the same
+ * frames in the same order.
+ *
+ * @param source - The frame producer.
+ * @param signal - Optional request abort signal that closes the stream on
+ *   client disconnect.
+ * @returns A ReadableStream of UTF-8 SSE bytes for a `Response` body.
+ */
+declare function createSseStream(source: SseSource, signal?: AbortSignal): ReadableStream<Uint8Array>;
+
+/**
+ * Singleton accessor for the gateway {@link BackgroundJobManager}.
+ *
+ * @remarks
+ * Relocated from `packages/cleo/src/dispatch/lib/job-manager-accessor.ts` into
+ * `@cleocode/runtime/gateway` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION) so the
+ * `admin` domain handler resolves the job-manager singleton from the runtime
+ * layer rather than a cleo-internal path. A thin re-export shim remains at the
+ * old path so any existing import site compiles unchanged.
+ *
+ * Long-lived hosts (e.g. the daemon) call {@link setJobManager} once at startup;
+ * short-lived CLI invocations leave the singleton `null`, and consumers handle
+ * the absence gracefully.
+ *
+ * @task T4820
+ * @task T11455
+ */
+
+/**
+ * Register the process-wide {@link BackgroundJobManager} singleton.
+ *
+ * @param manager - The manager instance to expose to gateway consumers.
+ */
+declare function setJobManager(manager: BackgroundJobManager): void;
+/**
+ * Retrieve the registered {@link BackgroundJobManager} singleton.
+ *
+ * @returns The registered manager, or `null` when running in a short-lived
+ * host (e.g. a one-shot CLI invocation) that never called {@link setJobManager}.
+ */
+declare function getJobManager(): BackgroundJobManager | null;
+
+/**
+ * MCP wire types for the `@cleocode/runtime/gateway/mcp` transport adapter.
+ *
+ * A deliberately-minimal subset of the Model Context Protocol shapes the
+ * adapter needs — no external MCP SDK dependency. Mirrors the legacy
+ * `@cleocode/mcp-adapter` `types.ts` so the wire surface is unchanged.
+ *
+ * @task T11448
+ * @epic T11254
+ * @saga T11243
+ */
+/** JSON Schema property descriptor surfaced for a single tool input field. */
+interface McpInputProperty {
+    /** JSON Schema primitive type (`'string'`, `'number'`, …). */
+    type: string;
+    /** Human-readable description shown in MCP clients. */
+    description: string;
+    /** Allowed values (JSON Schema `enum`) for finite-domain string params. */
+    enum?: readonly string[];
+}
+/**
+ * MCP tool definition shape (minimal — no external MCP SDK dependency).
+ * Structurally compatible with the legacy `@cleocode/mcp-adapter` `McpTool`.
+ */
+interface McpTool {
+    /** Stable tool name (snake_case, e.g. `cleo_sentient_status`). */
+    name: string;
+    /** Human-readable description shown in MCP clients. */
+    description: string;
+    /** JSON Schema for the tool's input parameters. */
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, McpInputProperty>;
+        required?: string[];
+    };
+}
+/** A single content block returned by a tool handler. */
+interface McpContent {
+    type: 'text';
+    text: string;
+}
+/** Result returned by a tool handler over the MCP wire. */
+interface McpToolResult {
+    content: McpContent[];
+    isError?: boolean;
+}
+
+/**
+ * MCP stdio transport adapter — routes `tools/call` through the gateway.
+ *
+ * Serves the Model Context Protocol over stdio (newline-delimited JSON-RPC 2.0)
+ * so any MCP-compatible client (Claude Code, LLM-agnostic tools) can discover
+ * and invoke CLEO operations. Unlike the legacy standalone `@cleocode/mcp-adapter`
+ * — which called the `@cleocode/core` SDK directly — this adapter is a thin
+ * TRANSPORT over the unified gateway:
+ *
+ *   MCP `tools/call` { name, arguments }
+ *     → {@link GatewayOperationKey} (via the `mcpExposed` registry subset)
+ *     → DispatchRequest { source: 'mcp', gateway, domain, operation, params }
+ *     → injected {@link GatewayHandler}.handle()
+ *     → DispatchResponse (LAFS envelope)  →  MCP tool result (JSON text content)
+ *
+ * The adapter owns ONLY wire concerns: JSON-RPC framing, the stdio read loop,
+ * `tools/list` generation, error rendering, and `process.exit` on stream close.
+ * All domain logic (resolution, validation, middleware, handler execution) lives
+ * behind the {@link GatewayHandler} — exactly mirroring how the CLI adapter
+ * wraps the same handler. `process.exit` and error-render stay HERE, never in
+ * the handlers (R3-T4 contract).
+ *
+ * `tools/list` is generated from the OPERATIONS registry behind the default-deny
+ * `mcpExposed` flag, so the external tool surface is identical to the historical
+ * standalone adapter (no behavior change).
+ *
+ * @task T11448
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * Route a single MCP `tools/call` through the gateway handler.
+ *
+ * Resolves the tool name to a `(domain, operation)` key against the exposed
+ * (`mcpExposed`) registry subset, builds a `source: 'mcp'` {@link DispatchRequest},
+ * and delegates to the injected {@link GatewayHandler}. Unknown tool names and
+ * thrown handler errors are rendered as MCP error results — never propagated as
+ * `process.exit` from this layer.
+ *
+ * @param handler - The injected transport-neutral gateway handler.
+ * @param toolName - The MCP `tools/call` tool name.
+ * @param args - The parsed tool arguments (already JSON-decoded by the client).
+ * @returns An MCP {@link McpToolResult}.
+ */
+declare function callTool(handler: GatewayHandler, toolName: string, args: Record<string, unknown>): Promise<McpToolResult>;
+/**
+ * Options for {@link startMcpServer}.
+ */
+interface McpServerOptions {
+    /** Inbound stream (defaults to `process.stdin`). */
+    input?: NodeJS.ReadableStream;
+    /** Outbound stream (defaults to `process.stdout`). */
+    output?: NodeJS.WritableStream;
+    /**
+     * Whether to call `process.exit(0)` when the input stream closes.
+     * Defaults to `true` (production stdio). Tests pass `false`.
+     */
+    exitOnClose?: boolean;
+}
+/**
+ * Start the MCP stdio server over the gateway.
+ *
+ * Reads newline-delimited JSON-RPC 2.0 requests from the input stream, routes
+ * `tools/call` through the injected {@link GatewayHandler}, and writes responses
+ * to the output stream. Each inbound line must be one complete JSON-RPC request.
+ *
+ * The caller assembles the {@link GatewayHandler} (via `createGatewayHandler`
+ * with its domain handlers + middleware) and injects it here — this adapter
+ * never builds handlers itself, keeping the runtime free of any
+ * `@cleocode/cleo` dependency.
+ *
+ * @param handler - The transport-neutral gateway handler to route through.
+ * @param opts - Optional stream + lifecycle overrides (defaults to stdio).
+ */
+declare function startMcpServer(handler: GatewayHandler, opts?: McpServerOptions): void;
+
+/**
+ * MCP tool-name <-> gateway-operation mapping.
+ *
+ * The MCP wire protocol identifies a tool by a single flat `name` string
+ * (snake_case, e.g. `cleo_sentient_propose_list`), whereas the gateway routes
+ * on a `(gateway, domain, operation)` triple (e.g.
+ * `query / sentient / propose.list`). This module is the bijective bridge
+ * between the two surfaces:
+ *
+ *   gateway op  →  MCP tool name   {@link operationToToolName}
+ *   MCP tool name  →  domain+operation   {@link toolNameToOperationKey}
+ *
+ * ## Naming convention (frozen — matches the legacy `@cleocode/mcp-adapter`)
+ *
+ * `cleo_<domain>_<operation>` where every `.` and `-` in the dotted operation
+ * name becomes `_`. The three historically-exposed tools therefore map as:
+ *
+ *   | gateway op                  | MCP tool name                  |
+ *   |-----------------------------|--------------------------------|
+ *   | `sentient` · `status`       | `cleo_sentient_status`         |
+ *   | `sentient` · `propose.list` | `cleo_sentient_propose_list`   |
+ *   | `sentient` · `propose.enable` | `cleo_sentient_propose_enable` |
+ *
+ * Preserving this exact mapping is what guarantees R3-T4's "no behavior change
+ * to the MCP tool surface" acceptance criterion.
+ *
+ * @task T11448
+ * @epic T11254
+ * @saga T11243
+ */
+
+/** Prefix every CLEO MCP tool name carries. */
+declare const MCP_TOOL_PREFIX = "cleo_";
+/**
+ * Identifies a gateway operation by its `(domain, operation)` pair. The CQRS
+ * gateway resolves which `Gateway` ('query' | 'mutate') the pair belongs to via
+ * the operation registry, so the MCP adapter does not need to carry it.
+ */
+interface GatewayOperationKey {
+    /** Canonical domain (e.g. `'sentient'`). */
+    readonly domain: string;
+    /** Dotted operation name (e.g. `'propose.list'`). */
+    readonly operation: string;
+}
+/**
+ * Derive the flat MCP tool name for a gateway operation.
+ *
+ * @param op - An {@link OperationDef} (or any object carrying `domain` +
+ *   `operation`) from the registry.
+ * @returns The MCP tool name, e.g. `'cleo_sentient_propose_list'`.
+ */
+declare function operationToToolName(op: Pick<OperationDef, 'domain' | 'operation'>): string;
+/**
+ * Resolve an MCP tool name back to its `(domain, operation)` gateway key.
+ *
+ * The reverse of {@link operationToToolName} cannot recover dots vs dashes from
+ * the snake_case wire form, so resolution is performed against the provided
+ * `exposed` set (the same `mcpExposed: true` subset used to build `tools/list`).
+ * This keeps the mapping exact and rejects unknown tool names.
+ *
+ * @param toolName - The MCP `tools/call` tool name.
+ * @param exposed - The exposed operation defs (the `mcpExposed` subset).
+ * @returns The matching {@link GatewayOperationKey}, or `undefined` when the
+ *   tool name does not correspond to any exposed operation.
+ */
+declare function toolNameToOperationKey(toolName: string, exposed: readonly OperationDef[]): GatewayOperationKey | undefined;
+
+/**
+ * MCP `tools/list` generation from the OPERATIONS registry.
+ *
+ * The MCP tool surface is **default-deny**: only {@link OperationDef} entries
+ * that explicitly set `mcpExposed: true` are surfaced. This replaces the legacy
+ * `@cleocode/mcp-adapter`'s hand-maintained `ALL_TOOLS` array with a single
+ * generation point driven by the canonical registry — promoting a new tool is
+ * now one `mcpExposed: true` edit in `@cleocode/contracts`, not a fork-and-copy
+ * into a standalone adapter.
+ *
+ * @task T11448
+ * @epic T11254
+ * @saga T11243
+ */
+
+/**
+ * The subset of OPERATIONS surfaced over MCP (default-deny `mcpExposed` filter).
+ *
+ * @returns Every {@link OperationDef} with `mcpExposed === true`, in registry
+ *   order. Empty when no operation opts in.
+ */
+declare function exposedOperations(): OperationDef[];
+/**
+ * Convert a single exposed {@link OperationDef} into its MCP tool definition.
+ *
+ * @param op - An operation with `mcpExposed === true`.
+ * @returns The MCP {@link McpTool} (name + description + inputSchema).
+ */
+declare function operationToMcpTool(op: OperationDef): McpTool;
+/**
+ * Generate the full MCP `tools/list` payload from the registry.
+ *
+ * @returns Every exposed operation rendered as an {@link McpTool}, in registry
+ *   order (stable across calls).
+ */
+declare function buildToolsList(): McpTool[];
+
+/**
+ * Dispatch-local metadata factory.
+ *
+ * Generates LAFS-conformant metadata for dispatch layer responses.
+ * Generates LAFS-conformant metadata for dispatch responses.
+ *
+ * @task T4772
+ */
+
+/**
+ * Create metadata for a dispatch response.
+ *
+ * @param gateway   - Gateway name (e.g., 'query', 'mutate')
+ * @param domain    - Domain name (e.g., 'tasks', 'session')
+ * @param operation - Operation name (e.g., 'show', 'list')
+ * @param startTime - Timestamp from Date.now() at start of request
+ * @param source    - Where the request originated
+ * @param requestId - Optional pre-generated request ID
+ * @param sessionId - Optional session ID to include in metadata
+ * @param originSessionId - Optional root workflow/saga session ID
+ * @param executionSessionId - Optional execution-attempt session ID
+ * @returns Metadata conforming to DispatchResponse['meta']
+ *
+ * @task T4772
+ * @task T4959
+ */
+declare function createDispatchMeta(gateway: string, domain: string, operation: string, startTime: number, source?: Source, requestId?: string, sessionId?: string | null, originSessionId?: string | null, executionSessionId?: string | null): DispatchResponse['meta'];
+
+/**
+ * nexus-decorator — stamps `meta._nexus` on every nexus-domain dispatch response.
+ *
+ * Wave 2 of the Nexus Restructure (T9146). Reads `getNexusDescriptor(opId)` from
+ * the W1 SSoT (`NEXUS_SCOPE_MAP`) and injects the namespaced `_nexus` block into
+ * `DispatchResponse['meta']`.
+ *
+ * Usage:
+ * ```ts
+ * const decorated = stampNexusMeta(response, operation, params);
+ * ```
+ *
+ * The `suggestedNext` field uses a structured form (not literal display strings).
+ * Display strings are derived by `formatSuggestedNext()` for human/markdown renderers.
+ *
+ * Typed-registry gate: `validateSuggestedNext()` fails the build (throws at import-time
+ * in test mode) if any `suggestedNext.op` is absent from `NEXUS_SCOPE_MAP`.
+ *
+ * @remarks
+ * Relocated from `packages/cleo/src/dispatch/nexus-decorator.ts` into
+ * `@cleocode/runtime/gateway` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION) so the
+ * nexus domain handler can import it from the runtime layer rather than a
+ * cleo-internal path. The module is pure (`@cleocode/contracts` only). A thin
+ * re-export shim remains at the old path for the renderer / CLI import sites.
+ *
+ * @task T9146
+ * @task T11455
+ * @module runtime/gateway/nexus-decorator
+ */
+
+/**
+ * Assert that every `suggestedNext.op` in a list resolves to a known
+ * NEXUS_SCOPE_MAP entry.
+ *
+ * Throws `TypeError` at runtime (caught by tests and CI) if an unknown op
+ * is referenced — acting as a build-time gate when imported in test suites.
+ *
+ * @throws {TypeError} if any `op` is absent from `NEXUS_SCOPE_MAP`
+ * @task T9146
+ */
+declare function validateSuggestedNext(suggestions: ReadonlyArray<SuggestedNextOp>): void;
+/**
+ * Derive a human-readable display string from a {@link SuggestedNextOp}.
+ *
+ * Example: `"cleo nexus context --project-id myproj (read-only, no confirmation needed)"`
+ */
+declare function formatSuggestedNext(s: SuggestedNextOp): string;
+/**
+ * Stamp `meta._nexus` onto a nexus-domain {@link DispatchResponse}.
+ *
+ * Call this after every nexus handler produces its `DispatchResponse`. The
+ * function is a pure transformer — it returns a new object with `meta._nexus`
+ * merged in.
+ *
+ * @param response  - The original dispatch response from the nexus handler.
+ * @param operation - The nexus operation key (must be a `keyof NexusOps`).
+ * @param params    - Raw params passed to the handler (used for binding-source resolution).
+ * @param isTopLevel - Whether this is a top-level CLI invocation (not a sub-call).
+ * @returns A new `DispatchResponse` with `meta._nexus` populated.
+ *
+ * @task T9146
+ */
+declare function stampNexusMeta(response: DispatchResponse, operation: string, params: Record<string, unknown>, isTopLevel?: boolean): DispatchResponse;
+/**
+ * Pick the decorator-stamped fields (`_nexus`, `deprecated`) from a dispatch
+ * response's `meta` so they can be forwarded via `cliOutput`'s `extensions`
+ * option into the emitted LAFS envelope.
+ *
+ * Without this, `cliOutput(response.data, ...)` discards `response.meta._nexus`
+ * + `response.meta.deprecated` (T9393 defect). Canonical CLI meta fields
+ * (`operation`, `requestId`, `timestamp`) are intentionally NOT forwarded —
+ * those are produced by {@link createCliMeta} on the CLI side.
+ *
+ * @task T9393
+ */
+declare function pickDecoratorMetaExtensions(responseMeta: DispatchResponseMeta | undefined): Record<string, unknown>;
+/**
+ * Build CLI envelope extensions for nexus commands that bypass the dispatcher
+ * (e.g. `cleo nexus status` SSoT-EXEMPT path). Runs the same {@link stampNexusMeta}
+ * logic against a synthetic response so the resulting envelope still carries
+ * `meta._nexus` (and `meta.deprecated` for alias shims).
+ *
+ * Use this only where the command does NOT call `dispatchRaw`. When you have a
+ * real dispatch response, use {@link pickDecoratorMetaExtensions} on
+ * `response.meta` instead — that path already ran the decorator.
+ *
+ * @task T9393
+ */
+declare function buildNexusMetaExtensions(operation: string, params?: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Gateway-level path constants shared by domain handlers.
+ *
+ * @remarks
+ * The `orchestrate` and `admin` (smoke-provider) domain handlers join a handful
+ * of well-known `.cleo/` path segments when locating workflow definitions and
+ * the BRAIN database. Those constants were previously defined in
+ * `packages/cleo/src/cli/paths.ts` (a CLI-internal leaf), which coupled the
+ * handler subgraph to `@cleocode/cleo`.
+ *
+ * To let `@cleocode/runtime` assemble the handler map WITHOUT importing
+ * `@cleocode/cleo` (R3-K1 · T11455 · SG-RUNTIME-UNIFICATION), the constants the
+ * handlers actually consume are hosted here as the canonical source. The
+ * CLI-side `cli/paths.ts` re-exports them so the rest of the CLI (backup /
+ * restore / doctor) keeps importing from its established surface — there is a
+ * single definition, no drift.
+ *
+ * @task T090
+ * @task T11455
+ */
+/** Name of the project-local CLEO data directory (`.cleo`). */
+declare const CLEO_DIR_NAME: ".cleo";
+/** Subdirectory under `.cleo/` that stores CANT workflow definitions. */
+declare const WORKFLOWS_SUBDIR: "workflows";
+/** Project-local SQLite database filename for cognitive memory (BRAIN). */
+declare const BRAIN_DB_FILENAME: "brain.db";
+
+/**
+ * Unified CQRS Dispatch Layer -- Middleware Pipeline
+ *
+ * Provides compose() to chain multiple Middleware functions together
+ * into a single executable pipeline.
+ *
+ * @epic T4820
+ * @task T4815
+ */
+
+/**
+ * Composes an array of Middleware functions into a single Middleware function.
+ * Execution flows through the array from first to last, and returns bubble
+ * back up from last to first.
+ *
+ * @remarks
+ * Uses an index-tracked dispatch function to prevent `next()` from being
+ * called multiple times within a single middleware. If the array is empty,
+ * a passthrough middleware that immediately calls `next()` is returned.
+ *
+ * @param middlewares - Array of middleware functions to chain
+ * @returns A single composed Middleware function
+ *
+ * @example
+ * ```typescript
+ * import { compose } from './pipeline.js';
+ *
+ * const pipeline = compose([sanitizer, rateLimiter, protocolEnforcement]);
+ * const response = await pipeline(request, handler);
+ * ```
+ */
+declare function compose(middlewares: Middleware[]): Middleware;
+
+/**
+ * Unified CQRS Dispatch Layer -- Operation Registry (shim)
+ *
+ * The `OPERATIONS` data array was relocated to
+ * `@cleocode/contracts/dispatch/operations-registry` in T10061 / T9833b
+ * (E-CLI-BOUNDARY · Saga T9831 SG-ARCH-SOLID). This file is now a thin
+ * re-export shim that:
+ *
+ *   1. Re-exports `OPERATIONS` from contracts so every downstream consumer
+ *      that already imports `{ OPERATIONS }` from this path continues to
+ *      compile unchanged.
+ *   2. Keeps the pure utility / derivation functions (`resolve`,
+ *      `validateRequiredParams`, `getByDomain`, etc.) that operate on
+ *      the data and are rightly colocated with the CLI package.
+ *
+ * @epic T4820
+ * @task T4814, T5241, T5615, T10061
+ */
+
+/** The single source of truth for all operations in CLEO (data lives in @cleocode/contracts). */
+declare const OPERATIONS: OperationDef[];
+/**
+ * Derive a gateway operation matrix from the registry.
+ *
+ * Returns `Record<string, string[]>` containing:
+ * - All canonical domains with their operations
+ *
+ * This is the SINGLE derivation point — gateways use this instead of
+ * maintaining independent operation lists.
+ */
+declare function deriveGatewayMatrix(gateway: Gateway): Record<string, string[]>;
+/**
+ * Get all accepted domain names for a gateway (canonical only).
+ */
+declare function getGatewayDomains(gateway: Gateway): string[];
+/**
+ * Resolves a domain + operation to its registered definition.
+ */
+declare function resolve(gateway: Gateway, domain: string, operation: string): Resolution | undefined;
+/**
+ * Validates that all required parameters are present in the request.
+ * Returns an array of missing parameter keys.
+ */
+declare function validateRequiredParams(def: OperationDef, params?: Record<string, unknown>): string[];
+/** Get all operations for a specific canonical domain. */
+declare function getByDomain(domain: CanonicalDomain): OperationDef[];
+/** Get all operations for a specific gateway. */
+declare function getByGateway(gateway: Gateway): OperationDef[];
+/** Get all operations available at or below a specific tier. */
+declare function getByTier(tier: Tier): OperationDef[];
+/** Get a list of canonical domains that actually have operations registered. */
+declare function getActiveDomains(): CanonicalDomain[];
+/**
+ * Returns summary counts of operations for module validation.
+ */
+declare function getCounts(): {
+    query: number;
+    mutate: number;
+    total: number;
+};
+
+/**
+ * `@cleocode/runtime/gateway` — the transport-agnostic CQRS dispatch core.
+ *
+ * Relocated from `packages/cleo/src/dispatch` (R3-T3 · T11447 ·
+ * SG-RUNTIME-UNIFICATION) so the dispatcher is owned by the runtime layer and
+ * can be driven by ANY transport adapter — CLI, MCP, RPC, HTTP — not just the
+ * CLI. Mirrors the `@cleocode/runtime/daemon` subpath (R2).
+ *
+ * The CLI adapter (`packages/cleo/src/dispatch/adapters/cli.ts`) and the
+ * domain handlers + transport-specific middleware stay in `packages/cleo`; they
+ * are INJECTED into the {@link Dispatcher} via {@link DispatcherConfig}. The
+ * gateway contract itself lives in `@cleocode/contracts/gateway` (R3-T2).
+ *
+ * `packages/cleo/src/dispatch/{dispatcher,registry,lib/meta,middleware/pipeline}.ts`
+ * remain as thin re-export shims pointing here, so the in-package import sites
+ * (cli adapter, ~18 registry consumers, getCliDispatcher) compile unchanged.
+ *
+ * @epic T4820
+ * @task T11447
+ * @saga T11243
+ */
+
+/**
+ * Transport-agnostic gateway entrypoint. Wraps a configured {@link Dispatcher}
+ * (`compose(middlewares) → DomainHandler`) behind a single `handle()` call that
+ * every transport adapter (CLI/MCP/RPC/HTTP) invokes uniformly. The adapter
+ * owns wire concerns (error-render, `process.exit`, serialization); the handler
+ * only resolves, validates, runs middleware, and returns a {@link DispatchResponse}.
+ */
+interface GatewayHandler {
+    /** Route one gateway request through the dispatch pipeline. */
+    handle(req: DispatchRequest): Promise<DispatchResponse>;
+}
+/**
+ * Build a {@link GatewayHandler} from a {@link DispatcherConfig} (injected
+ * domain handlers + middleware). The returned handler is transport-neutral.
+ */
+declare function createGatewayHandler(config: DispatcherConfig): GatewayHandler;
+
+export { getByDomain as $, type GatewayHandler as A, BRAIN_DB_FILENAME as B, CLEO_DIR_NAME as C, Dispatcher as D, type DecodeResult, type ErrorMeta as E, type GatewayScope as F, type GatewayOperationKey as G, type HttpServerHandle as H, type GatewaySubsystemContext as I, type GatewaySubsystemOptions as J, STRING_TO_EXIT as K, buildNexusMetaExtensions as L, LineBuffer, MCP_TOOL_PREFIX as M, cleoErrorToEngineError as N, OPERATIONS as O, compose as P, createDispatchMeta as Q, createGatewayHandler as R, type RpcServerHandle, type RpcServerOptions, SSE_HEADERS as S, defineGatewaySubsystem as T, deriveGatewayMatrix as U, engineError as V, WORKFLOWS_SUBDIR as W, formatSuggestedNext as X, gatewaySubsystemName as Y, generateTemplateConfig as Z, getActiveDomains as _, type HttpServerOptions as a, getByGateway as a0, getByTier as a1, getCounts as a2, getGatewayDomains as a3, getJobManager as a4, getTemplateForSubcommand as a5, mapNumericExitCodeToString as a6, parseIssueTemplates as a7, pickDecoratorMetaExtensions as a8, resolve as a9, setJobManager as aa, stampNexusMeta as ab, validateLabels as ac, validateRequiredParams as ad, validateSuggestedNext as ae, type HttpUnaryRequest as b, buildErrorFrame, type HttpUnaryResult as c, type SseEmitter as d, decodeLine, type SseFrame as e, encodeFrame, type SseSource as f, createSseStream as g, encodeSseFrame as h, encodeStreamEvent as i, statusForResponse as j, type McpContent as k, type McpInputProperty as l, type McpServerOptions as m, type McpTool as n, type McpToolResult as o, parseHttpRoute as p, buildToolsList as q, routeUnary as r, routeFrame, startHttpServer as s, startRpcServer, callTool as t, exposedOperations as u, operationToMcpTool as v, operationToToolName as w, startMcpServer as x, toolNameToOperationKey as y, type DispatcherConfig as z };