@kici-dev/orchestrator 0.15.0 → 0.16.0

package/dist/ws/platform-client.d.ts

@@ -1,13 +1,8 @@
-import { type StateReplayRun, type OrchestratorToPlatformMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardRunDetailRequest, type DashboardRunStructuredRequest, type DashboardRunStateRequest, type DashboardRunsListRequest, type DashboardRunsFiltersRequest, type DashboardSourcesListRequest, type DashboardAdminTokensListRequest, type DashboardStepLogsRequest, type DashboardAttestationsListRequest, type DashboardAttestationsListAllRequest, type DashboardAttestationGetRequest, type DashboardAttestationRetryRequest, type DashboardArtifactsListRequest, type DashboardOrchLogsRequest, type RunRerunRequest, type ManualScheduleRequest, type RunCancelRequest, type DashboardPayloadRequest, type DashboardPlatformToOrchMessage, type TestRelayRequest, type DashboardDiagnosticsRequest, type DashboardScalerCapacityRequest, type DashboardScalerAgentsRequest, type DashboardFleetHostsRequest, type DashboardFleetHostRequest, type DashboardFleetPreviewRequest, type DashboardFleetWorkflowsForHostRequest, type JoinResponse, type DeploymentIdentity, type ConfigPaths, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
+import { type StateReplayRun, type OrchestratorToPlatformMessage, type PlatformToOrchestratorMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardAttestationRetryRequest, type RunRerunRequest, type ManualScheduleRequest, type RunCancelRequest, type DashboardPlatformToOrchMessage, type TestRelayRequest, type JoinResponse, type DeploymentIdentity, type ConfigPaths, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
 import type { PlanHeadroomStore } from '../cluster/plan-headroom-store.js';
 import { RelayBufferRegistry, type RelayStartMeta } from '../webhook/relay-buffer.js';
 import type { AdmitResult } from '../webhook/ingest-admission.js';
-/**
- * Verification + processing outcome returned by the chunked relay path's
- * `onVerifyInbound` callback. Mirrors the shape exported by
- * `webhook/verify-inbound.ts` so wiring is a single hand-off without an
- * adapter layer.
- */
+/** Outcome of the chunked relay path's `onVerifyInbound`; mirrors `webhook/verify-inbound.ts`. */
 export interface InboundVerifyOutcome {
     result: WebhookRelayResult;
     reason?: string;
@@ -24,31 +19,18 @@ export type ReplaySendResult = {
     skipped?: 'empty' | 'invalid' | 'disconnected' | 'breaker';
 };
 /**
- * A webhook source that this orchestrator manages.
- * Sent to Platform after auth.success so the Platform knows which
- * routing keys this orchestrator handles.
- *
- * Note: webhookSecret is no longer included. Secrets are pushed separately
- * via source.secrets after loading from PgSecretStore.
- *
- * Single source of truth lives in `../entry-helpers.ts`. Re-exported here
- * so existing imports of `ProviderSource` from `./platform-client.js` keep
- * working without churn.
+ * A webhook source this orchestrator manages, registered with the Platform after
+ * auth.success. Defined in `../entry-helpers.ts`; re-exported for existing importers.
  */
 export type { ProviderSource } from '../entry-helpers.js';
 import type { ProviderSource } from '../entry-helpers.js';
 /**
  * Hard ceiling on how long an admitted fire-and-forget relay pipeline may hold
- * its admission slot before it is force-released. A pipeline running longer than
- * this is treated as hung; releasing its slot (idempotently) prevents a
- * permanent slot leak that would otherwise shrink capacity for every future
- * webhook. Well above any legitimate ingest-pipeline duration.
+ * its admission slot. Past it the pipeline counts as hung and its slot is
+ * force-released, so a hang cannot permanently shrink ingest capacity.
  *
- * Exported because it is also the hard bound on anything a webhook waits for
- * inline: the global eval round caps its raised wait ceiling at this value,
- * since a ceiling past the point the relay force-releases the pipeline buys
- * latency and no verdict. Two copies of "5 minutes" with nothing coupling them
- * is exactly the pair that drifts.
+ * Exported because the global eval round caps its inline wait ceiling at this
+ * value: waiting past the force-release buys latency and no verdict.
  */
 export declare const ADMITTED_PIPELINE_LIFETIME_MS: number;
 /**
@@ -57,6 +39,18 @@ export declare const ADMITTED_PIPELINE_LIFETIME_MS: number;
  * keeps the connection.
  */
 export type FrameHandler<M> = (msg: M) => void | Promise<void>;
+/**
+ * Platform → orchestrator frame types answered by exactly one dashboard / fleet
+ * read handler, looked up in {@link PlatformClientOptions.dashboardHandlers}.
+ */
+export declare const DASHBOARD_FRAME_TYPES: readonly ["dashboard.run.detail", "dashboard.run.structured", "dashboard.run.state", "dashboard.runs.list", "dashboard.runs.filters", "dashboard.sources.list", "dashboard.admin-tokens.list", "dashboard.step.logs", "dashboard.attestations.list", "dashboard.attestations.list.all", "dashboard.attestation.get", "dashboard.artifacts.list", "dashboard.payload", "dashboard.orch.logs", "dashboard.diagnostics", "dashboard.scaler.capacity", "dashboard.scaler.agents", "dashboard.fleet.hosts", "dashboard.fleet.host", "dashboard.fleet.preview", "dashboard.fleet.workflows-for-host"];
+export type DashboardFrameType = (typeof DASHBOARD_FRAME_TYPES)[number];
+/** One optional handler per {@link DASHBOARD_FRAME_TYPES} entry, typed by its frame. */
+export type DashboardFrameHandlers = {
+    [K in DashboardFrameType]?: FrameHandler<Extract<PlatformToOrchestratorMessage, {
+        type: K;
+    }>>;
+};
 export interface PlatformClientOptions {
     /** WebSocket URL of the Platform relay. */
     url: string;
@@ -68,18 +62,11 @@ export interface PlatformClientOptions {
     providerSources?: ProviderSource[];
     /** Orchestrator cluster instance ID (sent in source.register for peer correlation). */
     instanceId?: string;
-    /**
-     * Human-friendly cluster name resolved on orch boot
-     * (`cluster_meta.cluster_name`). Sent in source.register so Platform
-     * can route per-orch dashboard requests by this identifier.
-     */
+    /** `cluster_meta.cluster_name`; the Platform routes per-orch dashboard requests by it. */
     clusterName?: string;
     /**
-     * Orchestrator DB identifier (UUID, seeded by migration 001 in
-     * `cluster_meta` key `'cluster_id'`). Sent in source.register so
-     * Platform can warn when two unrelated clusters in the same org
-     * accidentally share a `clusterName`. HA siblings share the same orch
-     * DB and therefore the same `clusterId`.
+     * `cluster_meta.cluster_id` (UUID). Lets the Platform warn when two unrelated
+     * clusters in one org share a `clusterName`; HA siblings share one DB and so one id.
      */
     clusterId?: string;
     /** Reachable address for peer-to-peer connections (from KICI_CLUSTER_ADDRESS env var). Null if not configured. */
@@ -123,18 +110,13 @@ export interface PlatformClientOptions {
     }) => void;
     /** Optional callback invoked after successful authentication and source registration. */
     onAuthenticated?: () => void | Promise<void>;
-    /**
-     * Returns this coordinator's currently-connected worker peers for the
-     * `cluster.membership` snapshot. Undefined on a non-coordinator (or when
-     * clustering is off) → no membership is reported.
-     */
+    /** Connected worker peers for `cluster.membership`; undefined off-coordinator → none reported. */
     getWorkerPeers?: () => Array<{
         instanceId: string;
     }>;
     /**
-     * Persisted cache of the Platform-pushed worker ceiling. Written on every
-     * `plan.headroom`, read by `getWorkerCeiling`. Undefined → the coordinator
-     * receives no ceiling and admits worker joins freely.
+     * Persisted Platform-pushed worker ceiling, written on every `plan.headroom`.
+     * Undefined → no ceiling, worker joins are admitted freely.
      */
     planHeadroomStore?: PlanHeadroomStore;
     /**
@@ -145,126 +127,47 @@ export interface PlatformClientOptions {
      */
     onPlanCeiling?: (ceiling: number, evictExcess: boolean) => void;
     /**
-     * Optional callback invoked when the Platform surfaces the orchestrator's
-     * canonical org id on `auth.success`. Used to auto-provision the
-     * `remote_sources` anchor (`remote:<orgId>`) so Platform-relayed
-     * `kici run remote` resolves the real tenant. Fires on every (re)connect;
-     * provisioning is idempotent.
+     * Fires with the canonical org id from `auth.success` on every (re)connect, to
+     * idempotently provision the `remote:<orgId>` anchor `kici run remote` resolves.
      */
     onOrgIdentified?: (info: {
         orgId: string;
         clusterId: string | null;
     }) => void;
-    /**
-     * Optional callback fired with the provenance trust root (OIDC issuer) the
-     * Platform supplies on `auth.success`. The orchestrator uses it to verify
-     * provenance bundles at ingest. `null` means provenance is not configured.
-     */
-    onProvenanceIssuer?: (issuer: string | null) => void;
-    /** Optional callback for dashboard run detail requests from Platform. */
-    onDashboardRunDetail?: FrameHandler<DashboardRunDetailRequest>;
-    /** Optional callback for dashboard structured run-result requests from Platform. */
-    onDashboardRunStructured?: FrameHandler<DashboardRunStructuredRequest>;
-    /** Optional callback for the run-state system reconciliation read from Platform. */
-    onDashboardRunState?: FrameHandler<DashboardRunStateRequest>;
-    /** Optional callback for dashboard runs.list (operator console) requests from Platform. */
-    onDashboardRunsList?: FrameHandler<DashboardRunsListRequest>;
-    /** Optional callback for dashboard runs.filters (operator console) requests from Platform. */
-    onDashboardRunsFilters?: FrameHandler<DashboardRunsFiltersRequest>;
-    /** Optional callback for dashboard sources.list (operator console) requests from Platform. */
-    onDashboardSourcesList?: FrameHandler<DashboardSourcesListRequest>;
-    /** Optional callback for dashboard admin-tokens.list (RBAC drift report) requests from Platform. */
-    onDashboardAdminTokensList?: FrameHandler<DashboardAdminTokensListRequest>;
-    /** Optional callback for dashboard step logs requests from Platform. */
-    onDashboardStepLogs?: FrameHandler<DashboardStepLogsRequest>;
-    /** Optional callback for dashboard attestations-list requests from Platform. */
-    onDashboardAttestationsList?: FrameHandler<DashboardAttestationsListRequest>;
-    /** Optional callback for org-wide attestations list (browser) requests from Platform. */
-    onDashboardAttestationsListAll?: FrameHandler<DashboardAttestationsListAllRequest>;
-    /** Optional callback for single-attestation detail requests from Platform. */
-    onDashboardAttestationGet?: FrameHandler<DashboardAttestationGetRequest>;
     onDashboardAttestationRetry?: FrameHandler<DashboardAttestationRetryRequest>;
-    /** Optional callback for dashboard artifacts-list requests from Platform. */
-    onDashboardArtifactsList?: FrameHandler<DashboardArtifactsListRequest>;
-    /** Optional callback for run re-run requests from Platform (dashboard action). */
     onRunRerun?: FrameHandler<RunRerunRequest>;
-    /** Optional callback for manual schedule trigger requests from Platform (dashboard action). */
     onManualSchedule?: FrameHandler<ManualScheduleRequest>;
-    /** Optional callback for run cancel requests from Platform (dashboard action). */
     onRunCancel?: FrameHandler<RunCancelRequest>;
-    /** Optional callback for dashboard payload requests from Platform. */
-    onDashboardPayload?: FrameHandler<DashboardPayloadRequest>;
-    /** Optional callback for dashboard orchestration logs requests from Platform. */
-    onDashboardOrchLogs?: FrameHandler<DashboardOrchLogsRequest>;
-    /** Optional callback for dashboard environment/held-run messages from Platform. */
+    /** Handlers for the {@link DASHBOARD_FRAME_TYPES} read frames; a type with none is dropped. */
+    dashboardHandlers?: DashboardFrameHandlers;
+    /** Dashboard environment / held-run messages. */
     onDashboardEnvMessage?: FrameHandler<DashboardPlatformToOrchMessage>;
-    /**
-     * Optional callback for Platform-first `kici run remote` control-plane relay
-     * requests (upload-init, trigger, status, logs, cancel). The handler performs
-     * the action and replies over the WS keyed by `requestId`.
-     */
+    /** `kici run remote` control-plane relay requests; the handler replies keyed by `requestId`. */
     onTestRelay?: FrameHandler<TestRelayRequest>;
-    /** Optional callback for dashboard diagnostics requests from Platform. */
-    onDashboardDiagnostics?: FrameHandler<DashboardDiagnosticsRequest>;
-    /** Optional callback for dashboard scaler capacity requests from Platform. */
-    onDashboardScalerCapacity?: FrameHandler<DashboardScalerCapacityRequest>;
-    /** Optional callback for dashboard scaler agents requests from Platform. */
-    onDashboardScalerAgents?: FrameHandler<DashboardScalerAgentsRequest>;
-    /** Optional callback for fleet roster requests from Platform. */
-    onFleetHosts?: FrameHandler<DashboardFleetHostsRequest>;
-    /** Optional callback for fleet host-detail requests from Platform. */
-    onFleetHost?: FrameHandler<DashboardFleetHostRequest>;
-    /** Optional callback for fleet runsOnAll-preview requests from Platform. */
-    onFleetPreview?: FrameHandler<DashboardFleetPreviewRequest>;
-    /** Optional callback for fleet workflows-for-host requests from Platform. */
-    onFleetWorkflowsForHost?: FrameHandler<DashboardFleetWorkflowsForHostRequest>;
-    /** Optional callback for trust policy updates pushed from Platform. */
     onTrustPolicyUpdate?: FrameHandler<TrustPolicyUpdate>;
-    /** Optional callback for stale check run cleanup requests from Platform. */
     onStaleCheckrunCleanup?: FrameHandler<StaleCheckrunCleanup>;
-    /**
-     * Optional handler for join.request frames relayed by the Platform. It answers
-     * every such frame. Wiring it advertises the clusterJoinV2 capability.
-     */
+    /** Optional handler for join.request frames relayed by the Platform. It answers every such frame. */
     onJoinRequest?: (raw: unknown) => Promise<JoinResponse>;
     /** Custom orchestrator capabilities to merge with ORCH_CAPABILITIES in auth.request. */
     orchCapabilities?: Partial<OrchCapabilities>;
     /**
-     * Test-only fault-injection transform over the advertised capability manifest,
-     * supplied only by the build-time test double to reproduce an older /
-     * sourceless orchestrator that predates a given dashboard capability. Undefined
-     * (the shipped default) means identity — the full capability set is advertised.
-     */
-    capabilitiesTransform?: (c: OrchCapabilities) => OrchCapabilities;
-    /**
-     * Verify a reassembled inbound webhook from the chunked relay path.
-     *
-     * Wired to `verifyInboundWebhook(deps, ...)` in production. Required when
-     * Platform sends `webhook.relay.start`/`webhook.relay.chunk` (chunked path);
-     * if absent, the orchestrator ACKs `rejected_misconfigured` because it
-     * cannot perform the trust check the new design requires.
+     * Verify a reassembled chunked-relay webhook. Without it every chunked relay
+     * is ACKed `rejected_misconfigured`, since the trust check cannot run.
      */
     onVerifyInbound?: (meta: RelayStartMeta, body: Buffer) => Promise<InboundVerifyOutcome> | InboundVerifyOutcome;
-    /**
-     * Optional injected reassembly registry. Tests pass a registry with a short
-     * TTL; production constructs a default one per PlatformClient.
-     */
+    /** Reassembly registry override (tests use a short TTL). */
     relayBuffer?: RelayBufferRegistry;
     /**
-     * Webhook-ingest admission hook. Called with the relay's routing key BEFORE
-     * signature verification (so an unverified flood is throttled too — a verify
-     * does a DB read). When it sheds, the relay acks `shed_retry_later` (429) and
-     * no pipeline work runs. When it admits, the returned slot is held for the
-     * fire-and-forget pipeline's lifetime and released on completion / error /
-     * timeout. Absent → no admission gate (tests, minimal wirings).
+     * Webhook-ingest admission, called BEFORE signature verification so an
+     * unverified flood is throttled too (verify reads the DB). A shed acks
+     * `shed_retry_later` (429); an admitted slot is held for the pipeline's
+     * lifetime. Absent → no admission gate.
      */
     onAdmit?: (routingKey: string) => Promise<AdmitResult>;
     /**
-     * Optional shed-recording seam. Invoked with the pre-verify relay meta +
-     * assembled body + the admission controller's shed reason, before the
-     * shed_retry_later ack. The wiring records the delivery durably — an
-     * `event_log` breadcrumb, and the overflow-buffer row when that queue is
-     * enabled. Best-effort — the client wraps it so a failure never blocks the ack.
+     * Records a shed delivery durably (an `event_log` breadcrumb, plus an
+     * overflow-buffer row when enabled) before the shed ack. Best-effort: a
+     * failure never blocks the ack.
      */
     onShedCapture?: (meta: RelayStartMeta, body: Buffer, reason: string) => Promise<void>;
 }
@@ -288,14 +191,9 @@ export declare function classifyDashboardRequestError(raw: {
     requestId: string;
 }, knownTypes: ReadonlySet<string>, orchVersion: string | undefined): DashboardRequestErrorFrame;
 /**
- * WebSocket client that connects the orchestrator to the Platform relay.
- *
- * Handles:
- * - Authentication handshake (auth.request -> auth.success/failure)
- * - Periodic heartbeat messages to keep the connection alive
- * - Auto-reconnect with exponential backoff (1s initial, 1.5x, jitter, 60s max)
- * - Webhook relay reception and ACK responses
- * - Event buffering during disconnection with flush on reconnect
+ * The orchestrator's WebSocket link to the Platform relay: auth handshake,
+ * heartbeat, jittered exponential reconnect, webhook relay + ACK, and event
+ * buffering while disconnected.
  */
 export declare class PlatformClient {
     private ws;
@@ -318,22 +216,8 @@ export declare class PlatformClient {
     private readonly token;
     private readonly onWebhookRelay;
     private providerSources;
-    /**
-     * Pending `registerSourceAndAwait()` callers, keyed by routing key. Resolved
-     * with the Platform-computed webhook URL when the matching
-     * `source.register.ack` arrives, or rejected on timeout / disconnect.
-     */
+    /** `registerSourceAndAwait()` waiters by routing key, settled by ack, timeout or disconnect. */
     private readonly pendingSourceRegistrations;
-    /**
-     * Platform capabilities advertised on this connection (Platform → orchestrator
-     * `platform.capabilities` frame). `undefined` means nothing advertised yet —
-     * either a pre-capability Platform (which never advertises) or the frame has
-     * not arrived. Feature-gated sends treat "undefined" as optimistic (send
-     * anyway, backward-safe); only an advertised-but-absent flag suppresses a send.
-     * Reset to `undefined` on every (re)connect so a stale advertisement can't
-     * leak across connections.
-     */
-    private platformCapabilities;
     private readonly instanceId?;
     private readonly clusterName?;
     private readonly clusterId?;
@@ -354,34 +238,13 @@ export declare class PlatformClient {
     private readonly planHeadroomStore?;
     private readonly onPlanCeiling?;
     private readonly onOrgIdentified?;
-    private readonly onProvenanceIssuer?;
-    private readonly onDashboardRunDetail?;
-    private readonly onDashboardRunStructured?;
-    private readonly onDashboardRunState?;
-    private readonly onDashboardRunsList?;
-    private readonly onDashboardRunsFilters?;
-    private readonly onDashboardSourcesList?;
-    private readonly onDashboardAdminTokensList?;
-    private readonly onDashboardStepLogs?;
-    private readonly onDashboardAttestationsList?;
-    private readonly onDashboardAttestationsListAll?;
-    private readonly onDashboardAttestationGet?;
     private readonly onDashboardAttestationRetry?;
-    private readonly onDashboardArtifactsList?;
     private readonly onRunRerun?;
     private readonly onManualSchedule?;
     private readonly onRunCancel?;
-    private readonly onDashboardPayload?;
-    private readonly onDashboardOrchLogs?;
+    private readonly dashboardHandlers;
     private readonly onDashboardEnvMessage?;
     private readonly onTestRelay?;
-    private readonly onDashboardDiagnostics?;
-    private readonly onDashboardScalerCapacity?;
-    private readonly onDashboardScalerAgents?;
-    private readonly onFleetHosts?;
-    private readonly onFleetHost?;
-    private readonly onFleetPreview?;
-    private readonly onFleetWorkflowsForHost?;
     private readonly onTrustPolicyUpdate?;
     private readonly onStaleCheckrunCleanup?;
     private readonly onJoinRequest?;
@@ -391,34 +254,18 @@ export declare class PlatformClient {
     private readonly onShedCapture?;
     private readonly relayBuffer;
     /**
-     * Public alias of the orchestrator's owning org as supplied by
-     * Platform on `auth.success`. Used by the check-run emitter to build
-     * outbound `details_url`s that hide the canonical `org_<12-char>` id.
-     * `undefined` when the orchestrator runs against a Platform that
-     * predates the alias plumbing, or before the first successful auth.
+     * Owning org's public alias from `auth.success`, used for outbound check-run
+     * `details_url`s so they hide the canonical `org_<12-char>` id.
      */
     private _orgPublicAlias?;
-    /** Canonical Platform org id from `auth.success`; see {@link getOrgId}. */
     private _orgId?;
-    /** The Platform's org-scoped GitHub webhook URL from the last `auth.success`. */
     private _githubWebhookUrl?;
-    /**
-     * Returns the cached public alias of the orchestrator's owning org,
-     * or `undefined` if Platform has not supplied one yet. Read by
-     * `check-run-reporter.ts` when building `details_url`.
-     */
     getOrgPublicAlias(): string | undefined;
     /**
-     * The canonical Platform organization id this orchestrator authenticated
-     * as, from `auth.success`. `undefined` before the first successful auth, or
-     * against a Platform that does not supply it.
-     *
-     * A generic source's routing key embeds the organization
-     * (`generic:<orgId>:<id>`), and the Platform now refuses to register a key
-     * naming a different one. So the source-create path reads this to refuse a
-     * mismatched `--org` up front, naming the correct value, instead of letting
-     * the operator create a source that registers, is rejected, and never
-     * delivers.
+     * Canonical org id from `auth.success` (`undefined` before it). The Platform
+     * refuses a generic routing key (`generic:<orgId>:<id>`) naming another org,
+     * so source-create reads this to refuse a mismatched `--org` up front rather
+     * than create a source that never delivers.
      */
     getOrgId(): string | undefined;
     /**
@@ -430,133 +277,59 @@ export declare class PlatformClient {
     getGithubWebhookUrl(): string | null | undefined;
     constructor(options: PlatformClientOptions);
     /**
-     * Merge `updates` into the stored orch capabilities and broadcast the
-     * full set to Platform via `orch.capabilities.update`. Buffers via
-     * `send()` when not yet authenticated. The next `auth.request` will
-     * also carry the merged capabilities, so a reconnect-followed-by-
-     * runtime-broadcast still ends Platform in the correct cache state.
+     * Merge `updates` and broadcast the full set (buffered while unauthenticated).
+     * The next `auth.request` carries the merged set too, so a reconnect cannot
+     * leave the Platform's cache stale.
      */
     broadcastCapabilities(updates: Partial<OrchCapabilities>): void;
-    /**
-     * Current merged orchestrator capabilities. Read-only view used by
-     * tests and diagnostics; mutate via `broadcastCapabilities`.
-     */
     getCapabilities(): OrchCapabilities;
-    /** Current connection state. */
     get state(): ConnectionState;
-    /** Number of messages currently buffered. */
     getBufferedCount(): number;
     /**
-     * Complete a chunked webhook relay: verify, process if accepted, ACK.
-     *
-     * Called from the `webhook.relay.chunk` handler once `relayBuffer.chunk(...)`
-     * returns `{ status: 'completed' }`. This sequence is intentionally single-pass
-     * and inside `requestContext.run` so trace propagation works end-to-end.
+     * Verify, process if accepted, and ACK a fully reassembled chunked relay.
+     * Runs single-pass inside `requestContext.run` so trace propagation holds.
      */
     private completeChunkedRelay;
-    /**
-     * Initiate connection to the Platform relay.
-     * Starts the connect -> authenticate -> ready lifecycle.
-     */
     connect(): void;
-    /**
-     * Gracefully disconnect from Platform. Does not trigger reconnection.
-     */
+    /** Graceful disconnect; does not reconnect. */
     disconnect(): void;
-    /**
-     * Send a message to Platform. If authenticated, sends immediately.
-     * If not authenticated, buffers the message for later delivery.
-     */
+    /** Send now when authenticated, otherwise buffer for the next connection. */
     send(message: OrchestratorToPlatformMessage): void;
     /**
-     * Send the reconnect state replay as N paced frames.
-     *
-     * The payload is bounded by BOTH the wire schema's run cap and the Platform
-     * limiter's byte budget, and paced under its refill rate, because a frame
-     * breaching either one is rejected with a 4003 close — and since reconnecting
-     * does not reduce the run count, an oversized frame is resent forever rather
-     * than failing once.
+     * Send the reconnect state replay as paced frames, each within the wire
+     * schema's run cap and the Platform limiter's byte budget: a breaching frame
+     * gets a 4003 close and, since reconnecting does not shrink it, is resent forever.
      *
-     * Uses `this.ws.send` directly rather than `this.send()` on purpose: `send()`
-     * falls back to `this.eventBuffer` when the socket is not open, which for a
-     * multi-frame replay would queue the remaining frames for the NEXT connection
-     * instead of abandoning a replay whose connection has already gone. The
-     * Platform's replay handler upserts per run, so abandoning is safe — the next
-     * reconnect replays from scratch.
+     * Uses `this.ws.send`, not `send()`, so a dropped connection abandons the
+     * replay instead of buffering its tail for the next one. The Platform upserts
+     * per run, so the next reconnect replays from scratch.
      */
     sendStateReplay(runs: StateReplayRun[]): Promise<ReplaySendResult>;
-    /**
-     * Send a feature-gated message only if the Platform is known to support the
-     * named capability — the orchestrator-side pre-flight for a self-hosted
-     * orchestrator running ahead of the hosted Platform.
-     *
-     * Backward-safe: a Platform that never advertised capabilities (a
-     * pre-capability build, or the advertisement hasn't arrived yet) is treated as
-     * "unknown → send optimistically", exactly like the Platform's dashboard
-     * pre-flight treats an absent `supportedDashboardRequests` as "unknown", never
-     * "supports nothing". Only an *advertised* capability set that explicitly lacks
-     * the flag suppresses the send — surfacing a diagnosable capability gap instead
-     * of firing a frame the Platform would silently drop.
-     */
-    sendIfPlatformSupports(capability: string, message: OrchestratorToPlatformMessage): void;
-    /**
-     * Send a raw message directly on the WebSocket, bypassing typed validation.
-     * Used for log pull response messages (log.response) which are
-     * NOT in the OrchestratorToPlatformMessage union (they are in the separate log pull schema).
-     */
+    /** Unbuffered, untyped send for frames outside the union (e.g. `log.response`). */
     sendRaw(data: unknown): void;
-    /**
-     * Register a new source at runtime (e.g., after config reload adds a new GitHub app).
-     * Separate from the post-auth registration which sends all sources at once.
-     */
+    /** Register one source at runtime (the post-auth registration sends them all). */
     sendSourceRegister(source: ProviderSource): void;
-    /**
-     * Deregister sources at runtime (e.g., after config reload removes a GitHub app).
-     * Tells Platform to stop routing webhooks for these routing keys to this orchestrator.
-     */
     sendSourceDeregister(source: {
         routingKey: string;
     }): void;
-    /**
-     * Diff current provider sources with new ones and send register/deregister as needed.
-     * Convenience method for config reload that atomically updates routing.
-     */
+    /** Diff against the current sources and send the register / deregister frames. */
     updateSources(newSources: ProviderSource[]): void;
     /**
-     * Push the full source list to the Platform and resolve with the webhook URL
-     * the Platform computed for `routingKey` (from the `source.register.ack`), or
-     * `null` if the Platform has no public webhook base configured.
-     *
-     * Used by `kici-admin source add` (platform/hybrid mode) to print the URL
-     * synchronously. Passing the **full** source list keeps this on the single
-     * `updateSources` push path — the routing key being newly added means
-     * `updateSources` emits a `source.register` whose ack carries the URL; the
-     * later NOTIFY-driven republish then diffs to a no-op.
-     *
-     * Rejects on timeout or disconnect; the caller degrades to a "(unavailable)"
-     * note rather than fabricating a URL.
+     * Push the full source list and resolve with the webhook URL the Platform's
+     * `source.register.ack` carries for `routingKey` (`null`: no public webhook
+     * base). `kici-admin source add` prints it. Taking the FULL list keeps this
+     * on the one `updateSources` path, so the later NOTIFY republish diffs to a
+     * no-op. Rejects on timeout or disconnect.
      */
     registerSourceAndAwait(fullSources: ProviderSource[], routingKey: string, timeoutMs?: number): Promise<string | null>;
-    /**
-     * Reject every pending `registerSourceAndAwait()` — called on disconnect so a
-     * `source add` issued while the link drops fails fast instead of hanging.
-     */
+    /** On disconnect, so a `source add` in flight fails fast instead of hanging. */
     private rejectPendingSourceRegistrations;
     getReconnectDelay(): number;
     private doConnect;
     private handleMessage;
-    /**
-     * Try the non-mainline frames (log-pull, cluster join.request) when the
-     * primary `platformToOrchestratorMessageSchema` failed to parse. Falls back to
-     * a structured warning if none matches.
-     */
+    /** Recognition chain for frames the primary schema rejected. */
     private handleNonStandardMessage;
-    /**
-     * If `raw` looks like a dashboard request (a `dashboard.*` type with a
-     * requestId) that failed schema validation, send a structured error response
-     * keyed to its requestId and return true. Returns false when the message is
-     * not a recognisable dashboard request (let the caller log a warning).
-     */
+    /** Answer an invalid `dashboard.*` request carrying a requestId; false when `raw` is not one. */
     private respondToInvalidDashboardRequest;
     /**
      * Run the handler for one Platform frame. Nothing awaits a frame, so a throw
@@ -564,13 +337,9 @@ export declare class PlatformClient {
      * connection carries on; left unhandled it would stop the orchestrator.
      */
     private runFrameHandler;
-    /**
-     * Dispatch a parsed platform message to the appropriate per-area
-     * handler. Each `case` either inlines a tiny dispatch (for one-line
-     * forwards to a callback) or delegates to a private method when the
-     * branch carries non-trivial logic.
-     */
     private dispatchPlatformMessage;
+    /** Log a dashboard read frame and hand it to its registered handler. */
+    private dispatchDashboardFrame;
     private handleAuthSuccess;
     private handleAuthFailure;
     private handleWebhookRelayStart;
@@ -578,36 +347,22 @@ export declare class PlatformClient {
     private handleSourceRegisterAck;
     private handlePeerDiscover;
     private handlePeerUpdate;
-    /**
-     * Send a message directly on the WebSocket without buffering.
-     * Used for ACK responses that must go immediately.
-     */
+    /** Unbuffered send, for ACKs that must go now or not at all. */
     private sendDirect;
     private flushBuffer;
     private startHeartbeat;
     private stopHeartbeat;
-    /** How often a coordinator re-sends its membership snapshot. */
     private static readonly CLUSTER_MEMBERSHIP_INTERVAL_MS;
-    /**
-     * Send the current worker-peer snapshot to the Platform.
-     *
-     * A snapshot, not a delta: a dropped frame self-heals on the next send. A
-     * no-op when the client is not authenticated or has no worker-peer source.
-     */
+    /** Worker-peer snapshot (not a delta, so a dropped frame self-heals on the next send). */
     sendClusterMembership(): void;
     private startClusterMembership;
     private stopClusterMembership;
     /**
-     * Store the Platform's worker ceiling and act on an eviction directive.
-     *
-     * The stored value survives a Platform disconnect and a coordinator restart,
-     * which is what makes the fail-open stance bounded rather than unlimited.
+     * Store the worker ceiling; it survives disconnects and restarts, which keeps
+     * the fail-open stance bounded.
      */
     private onPlanHeadroom;
-    /**
-     * The ceiling this coordinator enforces, or `null` when none was ever
-     * received — in which case worker joins are admitted freely.
-     */
+    /** Enforced ceiling; `null` (never received) admits worker joins freely. */
     getWorkerCeiling(): Promise<number | null>;
     private scheduleReconnect;
     private clearStabilityTimer;

package/installer-image-digests.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.15.0",
+  "version": "0.16.0",
   "images": {
-    "kici-agent": "sha256:753e878b220babd497fbbab484748f122028014a2468e5dc48d45560dc4cf80e",
-    "kici-orchestrator": "sha256:bd6655f1485e7401ab6c696090a1927d551e7d937d9f5b66c7cfa2a13c8f7d2d"
+    "kici-agent": "sha256:d685cb8756dd86e6bb5a160fb2190ae2728de7db06a2d3183a4f60c641418034",
+    "kici-orchestrator": "sha256:34f613d76f78b77966680ac2c7f326b949723b959d46cae32767075cd524577d"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Customer-deployable orchestrator for the KiCI CI/CD stack. Receives webhook events (direct or via Platform relay), matches triggers against the lock file, and dispatches jobs to connected agents.",
   "keywords": [
     "ci",
@@ -90,8 +90,8 @@
     "ws": "^8.21.3",
     "yaml": "^2.9.1",
     "zod": "^4.6.5",
-    "@kici-dev/engine": "0.15.0",
-    "@kici-dev/shared": "0.15.0"
+    "@kici-dev/engine": "0.16.0",
+    "@kici-dev/shared": "0.16.0"
   },
   "kici": {
     "metrics": {
@@ -106,7 +106,7 @@
     "@types/dockerode": "^4.0.1",
     "@types/ws": "^8.18.1",
     "kysely-ctl": "^0.21.0",
-    "@kici-dev/agent": "0.15.0"
+    "@kici-dev/agent": "0.16.0"
   },
   "scripts": {
     "build": "node ../../scripts/build-service.mjs && tsc --emitDeclarationOnly",