@cleocode/runtime 2026.10.4 → 2026.10.5-rc.ci.672

package/dist/gateway/http/index.js

@@ -27,8 +27,8 @@ import {
   statusForResponse,
   tickStreamSource,
   writeBundleAbsentError
-} from "../../chunk-U2ESNIJ5.js";
-import "../../chunk-L5BLVQDA.js";
+} from "../../chunk-NOPLC5WS.js";
+import "../../chunk-4PUSKGDO.js";
 export {
   NODE_PTY_INSTALL_HINT,
   SSE_HEADERS,

package/dist/gateway/index.d.ts

@@ -1,11 +1,556 @@
-import '@cleocode/contracts/gateway';
-export { a3 as BRAIN_DB_FILENAME, a4 as CLEO_DIR_NAME, DecodeResult, a5 as Dispatcher, a6 as DispatcherConfig, a7 as ErrorMeta, a8 as GatewayHandler, O as GatewayOperationKey, a9 as GatewayScope, a as GatewayStreamSource, aa as GatewaySubsystemContext, ab as GatewaySubsystemOptions, H as HttpServerHandle, b as HttpServerOptions, c as HttpUnaryRequest, d as HttpUnaryResult, LineBuffer, P as MCP_TOOL_PREFIX, Q as McpContent, R as McpInputProperty, T as McpServerOptions, V as McpTool, X as McpToolResult, ac as OPERATIONS, RpcServerHandle, RpcServerOptions, S as SSE_HEADERS, ad as STRING_TO_EXIT, e as STUDIO_PREFIX, ae as ServeGatewayHandle, af as ServeGatewayOptions, f as SseEmitter, g as SseFrame, h as SseSource, ag as StreamResolution, i as StreamSourceContext, j as StreamSourceTeardown, k as StudioStaticOptions, ah as WORKFLOWS_SUBDIR, buildErrorFrame, ai as buildNexusMetaExtensions, Y as buildToolsList, Z as callTool, aj as cleoErrorToEngineError, ak as compose, al as createDispatchMeta, am as createGatewayHandler, q as createSseStream, decodeLine, an as defineGatewaySubsystem, ao as deriveGatewayMatrix, encodeFrame, s as encodeSseFrame, t as encodeStreamEvent, ap as engineError, _ as exposedOperations, aq as formatSuggestedNext, ar as gatewaySubsystemName, as as generateTemplateConfig, at as getActiveDomains, au as getByDomain, av as getByGateway, aw as getByTier, ax as getCounts, ay as getGatewayDomains, az as getJobManager, aA as getTemplateForSubcommand, aB as inferGateway, v as isStudioPath, aC as mapNumericExitCodeToString, y as mimeType, $ as operationToMcpTool, a0 as operationToToolName, z as parseHttpRoute, aD as parseIssueTemplates, aE as pickDecoratorMetaExtensions, A as registerStreamSource, aF as resolve, aG as resolveStreamRoute, B as resolveStreamSource, C as resolveStudioAssetPath, D as resolveStudioStaticDir, routeFrame, E as routeUnary, aH as serveGateway, I as serveStudioStatic, aI as setJobManager, aJ as stampNexusMeta, J as startHttpServer, a1 as startMcpServer, startRpcServer, K as statusForResponse, L as tickStreamSource, a2 as toolNameToOperationKey, aK as validateLabels, aL as validateRequiredParams, aM as validateSuggestedNext, M as writeBundleAbsentError } from './rpc/index.js';
+import { BackgroundJobManager } from '@cleocode/core/store/background-jobs.js';
 export { BackgroundJob, BackgroundJobManager, BackgroundJobManagerConfig, BackgroundJobStatus, DurableJobStore } from '@cleocode/core/store/background-jobs.js';
+import { Subsystem, EngineResult, ProblemDetails } from '@cleocode/contracts';
 export { MinimalTaskRecord, OperationDef, Resolution, Session as SessionRecord, TaskRecord } from '@cleocode/contracts';
+import { HttpServerHandle, HttpServerOptions } from './http/index.js';
+export { GatewayStreamSource, HttpUnaryRequest, HttpUnaryResult, SSE_HEADERS, STUDIO_PREFIX, SseEmitter, SseFrame, SseSource, StreamSourceContext, StreamSourceTeardown, StudioStaticOptions, createSseStream, encodeSseFrame, encodeStreamEvent, isStudioPath, mimeType, parseHttpRoute, registerStreamSource, resolveStreamSource, resolveStudioAssetPath, resolveStudioStaticDir, routeUnary, serveStudioStatic, startHttpServer, statusForResponse, tickStreamSource, writeBundleAbsentError } from './http/index.js';
+import { RpcServerHandle, RpcServerOptions } from './rpc/index.js';
+export { DecodeResult, LineBuffer, buildErrorFrame, decodeLine, encodeFrame, routeFrame, startRpcServer } from './rpc/index.js';
+import { G as GatewayHandler } from '../gateway-handler-DCU6E0a2.js';
+export { D as Dispatcher, a as DispatcherConfig, c as createGatewayHandler } from '../gateway-handler-DCU6E0a2.js';
 export { OrchestratePlanResult } from '@cleocode/contracts/operations/orchestrate';
+import * as _cleocode_core_internal from '@cleocode/core/internal';
 export { ArchiveStatsResult as ArchiveStatsData, AuditResult as AuditData, BackupResult as BackupData, BackupEntry as BackupEntryData, CleanupResult as CleanupData, CompactTask, ComplianceData, ContextData, DashboardData, DecisionRecord, DiagnosticsResult as DiagnosticsData, FileRestoreResult, HealthResult as HealthData, HelpData, HookMatrixResult, InjectGenerateResult as InjectGenerateData, IssueTemplate, IvtrHistoryEntry, LabelsResult as LabelsData, LifecycleStageEntry, LogQueryData, SystemMetricsResult as MetricsData, MigrateResult as MigrateData, OrchestratePlanInput, PathsData, PlanWarning, PlanWave, PlanWorkerEntry, ProviderMatrixEntry, ManifestEntry as ResearchManifestEntry, RestoreResult as RestoreData, RuntimeDiagnostics as RuntimeData, SafestopResult as SafestopData, ScaffoldHubData, StatsData, SyncData, TemplateConfig, TemplateSection, UncancelResult as UncancelData, addTaskWithSessionScope, completeTaskStrict, configGet, configListPresets, configSet, configSetPreset, ensureInitialized, filterEntries as filterManifestEntries, getVersion, initProject, isAutoInitEnabled, lifecycleCheck, lifecycleGateFail, lifecycleGatePass, lifecycleGates, lifecycleHistory, lifecyclePrerequisites, lifecycleProgress, lifecycleReset, lifecycleSkip, lifecycleStatus, mapCodebase, memoryBrainStats, memoryContradictions, memoryDecisionFind, memoryDecisionStore, memoryFetch, memoryFind, memoryGraphAdd, memoryGraphContext, memoryGraphNeighbors, memoryGraphRelated, memoryGraphRemove, memoryGraphShow, memoryGraphStatsFull, memoryGraphTrace, memoryLearningFind, memoryLearningStats, memoryLearningStore, memoryLink, memoryObserve, memoryPatternFind, memoryPatternStats, memoryPatternStore, memoryQualityReport, memoryReasonSimilar, memoryReasonWhy, memorySearchHybrid, memoryShow, memorySuperseded, memoryTimeline, memoryUnlink, orchestrateAnalyze, orchestrateBootstrap, orchestrateCheck, orchestrateContext, orchestrateCriticalPath, orchestrateHandoff, orchestrateNext, orchestrateParallelEnd, orchestrateParallelStart, orchestratePlan, orchestrateReady, orchestrateReport, orchestrateSkillInject, orchestrateSpawn, orchestrateSpawnExecute, orchestrateStartup, orchestrateStatus, orchestrateUnblockOpportunities, orchestrateValidate, orchestrateWaves, phaseAdvance, phaseComplete, phaseDelete, phaseList, phaseRename, phaseSet, phaseShow, phaseStart, pipelineManifestAppend, pipelineManifestArchive, pipelineManifestFind, pipelineManifestList, pipelineManifestPending, pipelineManifestShow, pipelineManifestStats, queryCommonHooks, queryHookProviders, readManifestEntries, releaseCancel, releaseCommit, releaseGateCheck, releaseGatesRun, releaseIvtrAutoSuggest, releaseList, releaseOpen, releasePlan, releasePrStatus, releasePrepare, releasePush, releaseReconcileV2, releaseRollback, releaseRollbackFull, releaseShow, releaseTag, sessionAdopt, sessionArchive, sessionBriefing, sessionChainShow, sessionCleanup, sessionComputeDebrief, sessionComputeHandoff, sessionContextDrift, sessionContextInject, sessionDebriefShow, sessionDecisionLog, sessionEnd, sessionFind, sessionGc, sessionHandoff, sessionHistory, sessionList, sessionRecordAssumption, sessionRecordDecision, sessionResume, sessionShow, sessionStart, sessionStats, sessionStatus, sessionSuspend, sessionSwitch, systemHooksMatrix, taskAnalyze, taskArchive, taskAssignee, taskBatchValidate, taskBlockers, taskBulkMove, taskCancel, taskClaim, taskComplete, taskComplexityEstimate, taskCurrentGet, taskDecompose, taskDelete, taskDepends, taskDeps, taskDepsCycles, taskDepsOverview, taskDepsTree, taskDepsValidate, taskExists, taskExport, taskFind, taskHistory, taskImpact, taskImport, taskLabelList, taskLabelShow, taskLint, taskList, taskNext, taskPlan, taskPromote, taskRankingHistory, taskRankingRevert, taskReconcileScope, taskRelates, taskRelatesAdd, taskRelatesAddBatch, taskRelatesFind, taskRelatesRemove, taskReopen, taskReorder, taskReorderRank, taskReparent, taskRestore, taskShow, taskShowIvtrHistory, taskShowOperation, taskShowWithHistory, taskSlice, taskStart, taskStats, taskStop, taskSyncLinks, taskSyncLinksRemove, taskSyncReconcile, taskTree, taskUnarchive, taskUnclaim, taskUpdate, taskWorkHistory, tasksAddBatchOp, coreBatchValidate as validateBatchValidate, validateChangelog, coreCoherenceCheck as validateCoherenceCheck, coreComplianceRecord as validateComplianceRecord, coreComplianceSummary as validateComplianceSummary, coreComplianceViolations as validateComplianceViolations, validateGateVerify, coreValidateManifest as validateManifestOp, coreValidateOutput as validateOutput, coreValidateProtocol as validateProtocol, validateProtocolArchitectureDecision, validateProtocolArtifactPublish, validateProtocolConsensus, validateProtocolContribution, validateProtocolDecomposition, validateProtocolImplementation, validateProtocolProvenance, validateProtocolRelease, validateProtocolResearch, validateProtocolSpecification, validateProtocolTesting, validateProtocolValidation, coreValidateSchema as validateSchemaOp, coreValidateTask as validateTaskOp, coreTestCoverage as validateTestCoverage, coreTestRun as validateTestRun, coreTestStatus as validateTestStatus } from '@cleocode/core/internal';
-export { EngineResult, engineSuccess } from '@cleocode/core';
+import { EngineResult as EngineResult$1 } from '@cleocode/core';
+export { EngineResult } from '@cleocode/core';
+export { GatewayOperationKey, MCP_TOOL_PREFIX, McpContent, McpInputProperty, McpServerOptions, McpTool, McpToolResult, buildToolsList, callTool, exposedOperations, operationToMcpTool, operationToToolName, startMcpServer, toolNameToOperationKey } from './mcp/index.js';
+export { B as BRAIN_DB_FILENAME, C as CLEO_DIR_NAME, O as OPERATIONS, S as StreamResolution, W as WORKFLOWS_SUBDIR, b as buildNexusMetaExtensions, c as compose, a as createDispatchMeta, d as deriveGatewayMatrix, f as formatSuggestedNext, g as getActiveDomains, e as getByDomain, h as getByGateway, i as getByTier, j as getCounts, k as getGatewayDomains, l as inferGateway, p as pickDecoratorMetaExtensions, r as resolve, m as resolveStreamRoute, s as stampNexusMeta, v as validateRequiredParams, n as validateSuggestedNext } from '../dispatch-BWjVeeMg.js';
+export { engineSuccess } from '@cleocode/contracts/engine-result.js';
 import 'node:http';
+import '@cleocode/contracts/gateway';
+import 'node:stream';
 import '@cleocode/contracts/gateway/rpc';
 import 'node:net';
-import 'node:stream';
+
+/**
+ * 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$1<_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$1<_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$1<_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$1<{
+    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;
+
+/**
+ * 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 to expose, or null to unregister a stopped host.
+ * @remarks Hosts unregister before closing their store; absence is reported explicitly.
+ */
+declare function setJobManager(manager: BackgroundJobManager | null): 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;
+
+/**
+ * Daemon-side gateway server bootstrap — the call-site `cleo daemon serve`
+ * drives (T11919).
+ *
+ * The HTTP gateway adapter (`./http/listen.ts`, T11254) and the supervised
+ * `defineGatewaySubsystem` unit (`./daemon-subsystem.ts`, T11451) both already
+ * exist, but nothing started them: the daemon had no `serve` call-site. This
+ * module is that thin bootstrap — it assembles a {@link SubsystemRegistry} with
+ * one scoped gateway subsystem hosting the HTTP transport (loopback by default)
+ * over an INJECTED {@link GatewayHandler}, starts it, and returns a live handle
+ * with the bound port + an idempotent `close()`.
+ *
+ * It carries NO `@cleocode/cleo` dependency and NO drizzle (the runtime
+ * invariant): the caller (`cleo daemon serve`) injects the assembled CLI gateway
+ * handler and the resolved bind coordinates. Secrets never touch the wire —
+ * sealed-handle resolution happens server-side inside the dispatched handler,
+ * exactly as it does for an in-process CLI call. The HTTP listener binds
+ * `127.0.0.1` by default (loopback only); exposing it on a public interface is
+ * an explicit caller decision.
+ *
+ * The streaming transports (SSE — T11921, WS — T11922) extend the SAME
+ * subsystem: when their listeners land they bind alongside the unary HTTP server
+ * here, so this bootstrap deliberately owns only transport assembly + lifecycle,
+ * leaving the per-route seam to the adapter (`parseHttpRoute`).
+ *
+ * @packageDocumentation
+ * @module @cleocode/runtime/gateway
+ *
+ * @task T11919
+ * @epic T11769
+ * @saga T10400
+ */
+
+/**
+ * Options for {@link serveGateway}.
+ *
+ * The caller injects the assembled {@link GatewayHandler} and resolves the bind
+ * coordinates so the runtime stays free of `@cleocode/paths`/`@cleocode/cleo`.
+ */
+interface ServeGatewayOptions {
+    /** The transport-neutral gateway handler every hosted transport routes through. */
+    handler: GatewayHandler;
+    /** TCP port to bind. `0` selects an ephemeral port (readable from the handle). */
+    port: number;
+    /** Host/interface to bind. Defaults to `127.0.0.1` (loopback only). */
+    host?: string;
+    /** The scope this gateway process serves. Defaults to `'global'`. */
+    scope?: GatewayScope;
+    /**
+     * Absolute path to the Studio static asset directory (T11979).
+     *
+     * When set, the HTTP server serves the bundled CLEO Web Studio at `/studio`
+     * using the `build/client/` static assets from an `adapter-node` Studio build.
+     * When `undefined`, `/studio` routes return a clean 503 "bundle absent" JSON
+     * envelope. The caller resolves this path (typically via
+     * `resolveStudioStaticDir` from `@cleocode/cleo`) so the runtime stays free of
+     * any path-resolution policy.
+     */
+    studioStaticDir?: string;
+}
+/**
+ * A live gateway server handle returned by {@link serveGateway}.
+ *
+ * Exposes the actually-bound `port`/`host` (resolved even when `0` was
+ * requested) and an idempotent {@link close} for deterministic teardown
+ * (daemon shutdown, tests). Mirrors the lower-level
+ * {@link import('./http/listen.js').HttpServerHandle} so a test can boot, probe,
+ * and tear down on an ephemeral port.
+ */
+interface ServeGatewayHandle {
+    /** The actually-bound HTTP port (resolved when `0` was requested). */
+    port: number;
+    /** Host/interface the HTTP listener is bound to. */
+    host: string;
+    /** The scope the gateway process serves. */
+    scope: GatewayScope;
+    /** Stop every bound listener (best-effort, idempotent); resolves once closed. */
+    close(): Promise<void>;
+}
+/**
+ * Boot the HTTP gateway as a supervised subsystem and return a live handle.
+ *
+ * Declares one scoped gateway subsystem hosting the HTTP transport (loopback
+ * default) over the injected handler via {@link defineGatewaySubsystem}, starts
+ * it, and reads the actually-bound port from the start context (so the caller —
+ * and tests — learn the ephemeral port when `0` was requested). The returned
+ * `close()` drives the subsystem's `shutdown(context)` so teardown is the same
+ * lifecycle the daemon registry uses for every other supervised concern.
+ *
+ * Using `defineGatewaySubsystem` directly (rather than a full
+ * `SubsystemRegistry`) keeps the bound HTTP handle in reach for the port
+ * resolution while still routing through the canonical start→shutdown contract.
+ *
+ * @param opts - The injected handler + resolved bind coordinates.
+ * @returns A promise resolving to the live {@link ServeGatewayHandle}.
+ *
+ * @example
+ * ```ts
+ * const handle = await serveGateway({
+ *   handler: createCliGatewayHandler(),
+ *   port: 0, // ephemeral
+ * });
+ * // POST http://127.0.0.1:${handle.port}/v1/tasks/show
+ * await handle.close();
+ * ```
+ */
+declare function serveGateway(opts: ServeGatewayOptions): Promise<ServeGatewayHandle>;
+
+export { type ErrorMeta, GatewayHandler, type GatewayScope, type GatewaySubsystemContext, type GatewaySubsystemOptions, HttpServerHandle, HttpServerOptions, RpcServerHandle, RpcServerOptions, STRING_TO_EXIT, type ServeGatewayHandle, type ServeGatewayOptions, cleoErrorToEngineError, defineGatewaySubsystem, engineError, gatewaySubsystemName, generateTemplateConfig, getJobManager, getTemplateForSubcommand, mapNumericExitCodeToString, parseIssueTemplates, serveGateway, setJobManager, validateLabels };