@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/ws/dashboard-run-state-handler.d.ts

@@ -1,19 +1,16 @@
 /**
- * Orchestrator-side handler for the `dashboard.run.state` system reconciliation
- * read.
+ * Handler for the `dashboard.run.state` system reconciliation read.
  *
- * The Platform's `RunMirrorReconciler` issues this request for a run that is
- * stuck non-terminal in the Platform mirror to recover a terminal frame that was
- * dropped on a live Platform↔orchestrator connection. It projects the current
- * `execution_runs` + `execution_jobs` state for one run into the same
- * `StateReplayRun` shape the reconnect `state.replay` push carries, so the
- * Platform can drive it through the shared `upsertRunMirror` helper.
+ * The Platform's `RunMirrorReconciler` sends it for a run stuck non-terminal in
+ * the Platform mirror, to recover a terminal frame dropped on a live
+ * connection. It projects `execution_runs` + `execution_jobs` for one run into
+ * the `StateReplayRun` shape of the reconnect `state.replay` push, so the
+ * Platform drives it through the shared `upsertRunMirror` helper. Pure (deps
+ * passed as arguments), so the `server.ts` wiring stays a thin adapter and the
+ * logic is unit-testable without a live Platform connection.
  *
- * Unlike the user-plane `dashboard.run.detail` read, this handler does NOT write
- * an `access_log` row: it is a system reconciliation read (a `system` actor),
- * not a user data access. The handler is pure (deps passed as arguments) so the
- * WS wiring in `server.ts` stays a thin adapter and the logic is unit-testable
- * without a live Platform connection.
+ * Unlike `dashboard.run.detail`, it writes NO `access_log` row: it is a
+ * `system`-actor reconciliation read, not a user data access.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';

package/dist/ws/event-buffer.d.ts

@@ -1,12 +1,9 @@
 import type { OrchestratorToPlatformMessage } from '@kici-dev/engine';
 import { RingBuffer } from '@kici-dev/shared';
 /**
- * In-memory buffer for orchestrator-to-Platform messages during disconnection.
- *
- * Wraps the generic RingBuffer from @kici-dev/shared with the orchestrator's
- * message type. Default maxSize is 10,000 (inherited from RingBuffer). When
- * the orchestrator loses its WebSocket connection to Platform, outgoing messages
- * are buffered here and flushed in order on reconnection.
+ * In-memory buffer for orchestrator-to-Platform messages while the Platform
+ * WebSocket is down; flushed in order on reconnection. Default maxSize is
+ * 10,000 (inherited from RingBuffer).
  */
 export declare class EventBuffer extends RingBuffer<OrchestratorToPlatformMessage> {
     constructor(options?: {

package/dist/ws/execution-status-frame.d.ts

@@ -1,19 +1,17 @@
 /**
  * Build the `execution.status` frame the orchestrator forwards to the Platform.
+ * A pure function with its own tests: `server.ts`'s `onExecutionStatusChange`
+ * hook supplies the message id and the clock and hands the result to the
+ * Platform client.
  *
- * Extracted from `server.ts`'s `onExecutionStatusChange` hook so the projection
- * from an {@link ExecutionContext} onto the wire message is a pure function with
- * its own tests. The hook itself stays a thin adapter: it supplies the message
- * id and the clock and hands the result to the Platform client.
- *
- * Every field here is conditional on the context actually carrying it. That is
- * load-bearing for `workflowRepoIdentifier` in particular: the tracker records
- * it only when the repository that DEFINES the workflow differs from the
- * repository the run acted on, so the frame must stay silent for a per-repository
- * run or "present" stops marking a cross-repository global run downstream.
+ * Every field is conditional on the context carrying it. For
+ * `workflowRepoIdentifier` that is load-bearing: the tracker records it only
+ * when the repository that defines the workflow differs from the one the run
+ * acted on, so its presence marks a cross-repository global run downstream.
+ * Free text is clamped to the wire bound here, at the source.
  */
 import type { ExecutionContext } from '../reporting/execution-tracker.js';
-import type { ExecutionRunStatus, ExecutionStatus, InitFailure } from '@kici-dev/engine';
+import { type ExecutionRunStatus, type ExecutionStatus, type InitFailure } from '@kici-dev/engine';
 export interface ExecutionStatusFrameArgs {
     messageId: string;
     runId: string;

package/dist/ws/failure-messages.d.ts

@@ -2,21 +2,16 @@
  * Safe, fixed messages the orchestrator sends to the agent (and through it to
  * the workflow author) when an agent-WS request fails for an internal reason.
  *
- * These are presentation strings, not a wire vocabulary: the protocol carries
- * them in the free-text `reason` field of `step.approval-resolved` and in the
- * free-text `error` field of `event.emit.response` / `agent.api.response`, so an
- * orchestrator is free to reword them without any agent-side change. They live
- * in one module — rather than inline at each send site — so the handler, its
- * tests and the `onEventEmit` callback in `app.ts` cannot drift apart.
+ * They are presentation strings, not a wire vocabulary: they ride the free-text
+ * `reason` of `step.approval-resolved` and `error` of `event.emit.response` /
+ * `agent.api.response`, so rewording needs no agent change. One module keeps the
+ * handler, its tests and the `onEventEmit` callback in `app.ts` from drifting.
  *
- * Raw exception text is never one of these. Exceptions stay in the
- * orchestrator's own logs; the author sees only "this is an orchestrator
- * problem", never a database endpoint, a constraint name or a stack frame.
- *
- * Author-actionable failures do not come through here at all — they ride the
- * callback's return value with its own safe wording (an unknown job context, an
- * approval bridge's timeout reason), which stays specific enough to debug a bad
- * workflow without operator log access.
+ * Raw exception text is never sent: it stays in the orchestrator logs, so the
+ * author never sees a database endpoint, a constraint name or a stack frame.
+ * Author-actionable failures (an unknown job context, an approval bridge's
+ * timeout reason) ride the callback's return value with their own safe wording,
+ * specific enough to debug a bad workflow without operator log access.
  */
 export declare const AgentWsInternalFailure: Readonly<{
     /** The step-approval bridge rejected instead of resolving the hold. */

package/dist/ws/fleet-agent-collector.d.ts

@@ -4,27 +4,21 @@ export interface FleetAgentCollectorOptions {
 export declare class FleetAgentCollector {
     private readonly opts;
     private readonly waiter;
-    /** requestId -> owning agentId, so a disconnect rejects only that agent's requests. */
     private readonly requestAgent;
     constructor(opts: FleetAgentCollectorOptions);
-    /**
-     * Register the pending request `requestId` (owned by `agentId`), invoke
-     * `send` to dispatch the fleet.logs.request envelope, and await the
-     * reassembled bundle Buffer.
-     */
+    /** Registers `requestId` before `send` dispatches the envelope; resolves to the bundle. */
     request(requestId: string, agentId: string, send: () => void): Promise<Buffer>;
     onChunk(requestId: string, seq: number, dataB64: string, isLast: boolean): void;
     /**
-     * Whether `requestId` is a collection this orchestrator asked `agentId` for
-     * and is still waiting on. The agent handler consults this before rate
-     * limiting a `fleet.bundle.chunk`: a solicited transfer is exempt, an
-     * unsolicited one is not.
+     * Whether this orchestrator still awaits `requestId` from `agentId`. The agent handler
+     * checks it before rate limiting a `fleet.bundle.chunk`: a solicited transfer is exempt,
+     * an unsolicited one is not.
      */
     isPendingFor(requestId: string, agentId: string): boolean;
     onError(requestId: string, message: string): void;
-    /** Reject every pending request owned by `agentId` (called on its disconnect). */
+    /** Called on the agent's disconnect. */
     rejectAgent(agentId: string, reason: string): void;
-    /** Reject every pending request regardless of owner (orchestrator shutdown). */
+    /** Orchestrator shutdown: rejects regardless of owner. */
     rejectAll(reason: string): void;
 }
 //# sourceMappingURL=fleet-agent-collector.d.ts.map

package/dist/ws/fleet-runs-on-all.d.ts

@@ -1,12 +1,7 @@
 /**
  * Resolve a workflow's `runsOnAll` host-fan-out predicate from the orchestrator's
  * persisted registrations, for the fleet runsOnAll-preview read path.
- *
- * The orchestrator stores each registered workflow's full lock entry in
- * `workflow_registrations.lock_entry` (JSON). This reader parses that entry,
- * finds the first static job carrying a `runsOnAll` predicate, and returns its
- * `{ include, exclude, onUnreachable }` — or null when no registered workflow of
- * that name declares a host fan-out.
+ * Reads the lock entry stored as JSON in `workflow_registrations.lock_entry`.
  */
 import type { Kysely } from 'kysely';
 import { type LockWorkflow } from '@kici-dev/engine';

package/dist/ws/git-credential-relay.d.ts

@@ -4,8 +4,7 @@
  * The agent's credential helper calls this on every git network operation, so
  * this path is hot and must stay cheap: validate, authorize, delegate.
  *
- * Authorization is five layers, every one of them resolved from server truth
- * rather than from the request:
+ * Authorization is five layers, each resolved from server truth, never the request:
  *
  *   1. job ownership — an agent may only request credentials for a job it was
  *      dispatched, resolved through the dispatcher;
@@ -15,23 +14,20 @@
  *      repository), so cloning a sibling repo needs no credential in workflow
  *      code. A write must additionally stay inside the organisation that owns
  *      the job's source repository;
- *   3. the LOCK DECLARATION — a workflow-supplied `ref` must equal one of the
- *      entries in the job's `gitCredentials` map, which the orchestrator itself
- *      wrote from the lock at dispatch (`git/job-context.ts` names the two rows
- *      that carry it and why it reads them in that order). This is the only
- *      check a ref faces, and it is deliberately the whole of it: a ref that
- *      carries inline `*Value` material is admitted exactly when the lock
- *      declared that material, and refused otherwise;
+ *   3. the LOCK DECLARATION — a workflow-supplied `ref` must equal an entry of the
+ *      job's `gitCredentials` map, which the orchestrator wrote from the lock at
+ *      dispatch (`git/job-context.ts` names the rows that carry it and their read
+ *      order). This is deliberately the only check a ref faces: a ref carrying inline
+ *      `*Value` material is admitted exactly when the lock declared that material;
  *   4. the named context's protection rules, run by
  *      `resolveJobQualifiedSecret` when the broker resolves a
  *      `<context>:<key>` reference;
  *   5. the trust tier — an untrusted contributor gets no workflow-supplied
  *      credential at all, mirroring the install-secrets strip.
  *
- * The step process is the same process as the IPC sender, so job code can forge
- * any request frame it likes. Layers 3 to 5 are what make that forgery
- * worthless: a forged `ref` names a credential the job's lock never declared,
- * and every check here reads what the orchestrator wrote rather than what the
+ * The step process is the IPC sender, so job code can forge any request frame.
+ * Layers 3 to 5 make that forgery worthless: a forged `ref` names a credential the
+ * lock never declared, and every check reads what the orchestrator wrote, not what the
  * agent claimed.
  */
 import type { TrustTier } from '@kici-dev/engine';
@@ -39,10 +35,7 @@ import type { GitCredentialBroker } from '../git/credential-broker.js';
 /** Per-job facts the handler needs. Resolved from server truth, never from params. */
 export interface JobCredentialContext {
     orgId: string;
-    /**
-     * The repository whose code the job checks out — the event's repository.
-     * The write-credential organisation fence is anchored here.
-     */
+    /** The event's repository, which the job checks out; anchors the write-credential fence. */
     sourceRepo: string;
     /**
      * The repository whose policy governs the job's credentials: the workflow
@@ -51,9 +44,8 @@ export interface JobCredentialContext {
      */
     policyRepo: string;
     /**
-     * The `gitCredentials` map this job's lock entry declared, verbatim — a
-     * request's ref must equal one of these entries. An empty map means the job
-     * declared none, so every workflow-supplied ref is refused.
+     * The lock entry's `gitCredentials` map, verbatim; a request's ref must equal one
+     * entry. An empty map refuses every workflow-supplied ref.
      */
     declaredCredentials: Readonly<Record<string, Readonly<Record<string, string>>>>;
     /** The run's resolved contributor trust tier, or undefined when unresolved. */

package/dist/ws/inventory-api.d.ts

@@ -1,17 +1,16 @@
 import { type HostInventoryEntry } from '@kici-dev/engine';
 import type { HostRosterStore } from '../agent/host-roster.js';
-/** Store surface the inventory handlers need (kept narrow for testability). */
+/** Kept narrow for testability. */
 export interface InventoryApiDeps {
     rosterStore: Pick<HostRosterStore, 'queryInventory' | 'getInventory'>;
     /** Roster grace window (ms) — the same value runsOnAll's `findMatching` uses. */
     graceMs: number;
 }
 /**
- * Build the `inventory.query` handler. Validates the optional label selector
- * (`include` OR-of-AND groups + `exclude`); an empty selector ⇒ all hosts.
- * Property filtering is done client-side in the workflow.
+ * Label selector: `include` OR-of-AND groups + `exclude`; an empty selector ⇒
+ * all hosts. The workflow filters properties client-side.
  */
 export declare function createInventoryQueryHandler(deps: InventoryApiDeps): (agentId: string, params: Record<string, unknown>) => Promise<HostInventoryEntry[]>;
-/** Build the `inventory.get` handler — single-host lookup, null when absent. */
+/** Single-host lookup, null when absent. */
 export declare function createInventoryGetHandler(deps: InventoryApiDeps): (agentId: string, params: Record<string, unknown>) => Promise<HostInventoryEntry | null>;
 //# sourceMappingURL=inventory-api.d.ts.map

package/dist/ws/job-status-forward-frame.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Build the `job.status.forward` frame the orchestrator forwards to the Platform.
+ *
+ * Every optional field is sent only when the tracker supplied it, so the
+ * Platform reads an absent field as "no value" and keeps what it stored. Free
+ * text is clamped to the wire bound here, at the source, so a long agent error
+ * never produces a frame the Platform has to shorten.
+ */
+import { type ExecutionJobStatus, type InitFailure, type JobStatusForward } from '@kici-dev/engine';
+export interface JobStatusForwardFrameArgs {
+    messageId: string;
+    runId: string;
+    jobId: string;
+    jobName: string;
+    status: ExecutionJobStatus;
+    timestamp: number;
+    orchestratorId: string;
+    startedAt?: number;
+    completedAt?: number;
+    durationMs?: number;
+    errorMessage?: string;
+    agentId?: string;
+    runsOnLabels?: string[];
+    logBytes?: number;
+    initFailure?: InitFailure;
+    /** Ordered bound context names for a multi-context job. */
+    contexts?: string[];
+}
+export declare function buildJobStatusForwardFrame(args: JobStatusForwardFrameArgs): JobStatusForward;
+//# sourceMappingURL=job-status-forward-frame.d.ts.map

package/dist/ws/observer-registry.d.ts

@@ -1,86 +1,41 @@
 /**
- * Registry tracking active WebSocket observers per execution run.
- *
- * Multiple CLI clients can subscribe to observe the same run.
- * The registry handles:
- * - Per-run observer sets with subscribe/unsubscribe
- * - Broadcast of messages (log, step, status, complete) to all observers
- * - Message buffering with monotonic sequence numbers for reconnection backfill
- * - Automatic cleanup of closed/errored connections during broadcast
- * - TTL-based buffer cleanup after run completion
+ * Per-run registry of WebSocket observers (several CLI clients may observe one
+ * run). Messages carry a monotonic per-run sequence and are buffered for
+ * reconnection backfill; closed connections are dropped on broadcast, and a
+ * completed run's buffer is reclaimed after a TTL.
  */
 import type { WsLike } from '@kici-dev/engine';
 export type ObserverWsLike = WsLike;
 export declare class ObserverRegistry {
-    /** Per-run observer sets. */
     private readonly observers;
-    /** Per-run message buffers for reconnection backfill. */
     private readonly buffers;
-    /** Monotonic sequence counter per run. */
     private readonly sequenceCounters;
-    /** Scheduled buffer cleanup timers (for cancellation on new subscribe). */
+    /** Pending buffer cleanups, cancelled when a new observer subscribes. */
     private readonly cleanupTimers;
-    /**
-     * Subscribe an observer to a run.
-     *
-     * If `lastSeenSequence` is provided, buffered messages with sequence > lastSeenSequence
-     * are replayed to the observer immediately.
-     */
+    /** Replays buffered messages with sequence > `lastSeenSequence` when it is given. */
     subscribe(runId: string, ws: ObserverWsLike, lastSeenSequence?: number): void;
-    /**
-     * Unsubscribe an observer from a run.
-     *
-     * If the observer set becomes empty, the buffer is kept alive
-     * for potential reconnection (TTL-based cleanup happens later).
-     */
+    /** The buffer outlives an empty observer set, for reconnection. */
     unsubscribe(runId: string, ws: ObserverWsLike): void;
     /**
-     * Broadcast a message object to all observers of a run.
-     *
-     * The message is serialized once, sent to all observers, and added to the
-     * run's buffer with a monotonic sequence number. Closed/errored connections
-     * are removed during broadcast.
+     * Serialize once, stamp a monotonic sequence, buffer, and send to every
+     * observer; closed or erroring connections are removed.
      */
     broadcast(runId: string, message: object): void;
-    /**
-     * Convenience: broadcast a log chunk message.
-     */
     broadcastLog(runId: string, jobId: string, jobName: string, stepIndex: number, stepName: string, lines: string[]): void;
-    /**
-     * Convenience: broadcast a step lifecycle event.
-     */
     broadcastStep(runId: string, jobId: string, jobName: string, stepName: string, state: string, durationMs?: number): void;
-    /**
-     * Convenience: broadcast a run status change.
-     */
     broadcastStatus(runId: string, status: string, jobName?: string): void;
-    /**
-     * Convenience: broadcast run completion with summary.
-     *
-     * After broadcasting, schedules buffer cleanup after COMPLETION_BUFFER_TTL_MS
-     * to allow brief reconnection windows.
-     */
+    /** Schedules buffer cleanup after COMPLETION_BUFFER_TTL_MS, a brief reconnection window. */
     broadcastComplete(runId: string, status: string, summary: object): void;
-    /**
-     * Get the number of active observers for a run.
-     */
     getObserverCount(runId: string): number;
-    /**
-     * Check if a run has any active observers.
-     */
     hasObservers(runId: string): boolean;
     /**
-     * Remove all buffers for completed runs.
-     * Call periodically or on shutdown to reclaim memory.
+     * Drop every run's buffer, sequence counter, pending cleanup timer and
+     * observer set, active runs included. Call on shutdown.
      */
     cleanup(): void;
-    /**
-     * Get the current sequence number for a run (for testing).
-     */
+    /** For tests. */
     getCurrentSequence(runId: string): number;
-    /**
-     * Get the buffer size for a run (for testing).
-     */
+    /** For tests. */
     getBufferSize(runId: string): number;
     private nextSequence;
     private addToBuffer;

package/dist/ws/outbound-frame-guard.d.ts

@@ -0,0 +1,4 @@
+import { type OrchestratorToPlatformMessage } from '@kici-dev/engine';
+/** The frame to send (clamped for a guarded type), or null when it must not be sent. */
+export declare function guardOutboundFrame(frame: OrchestratorToPlatformMessage): OrchestratorToPlatformMessage | null;
+//# sourceMappingURL=outbound-frame-guard.d.ts.map

package/dist/ws/ownership-gate.d.ts

@@ -2,7 +2,7 @@ import type { OwnershipTracker } from '../agent/ownership-tracker.js';
 /** Whether a job-scoped agent frame may be handled. */
 export type OwnershipDecision = 'accept' | 'reject';
 /**
- * Resolve whether `agentId` may act on `jobId`, in the two steps every
+ * Resolve whether `agentId` may act on `jobId`, in the steps every
  * job-scoped agent frame shares.
  *
  * 1. No tracker configured — ownership enforcement is off; accept.

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

@@ -18,10 +18,7 @@ export type ReplaySendResult = {
     chunks: number;
     skipped?: 'empty' | 'invalid' | 'disconnected' | 'breaker';
 };
-/**
- * A webhook source this orchestrator manages, registered with the Platform after
- * auth.success. Defined in `../entry-helpers.ts`; re-exported for existing importers.
- */
+/** Re-exported from `../entry-helpers.ts` for existing importers. */
 export type { ProviderSource } from '../entry-helpers.js';
 import type { ProviderSource } from '../entry-helpers.js';
 /**
@@ -54,13 +51,12 @@ export type DashboardFrameHandlers = {
 export interface PlatformClientOptions {
     /** WebSocket URL of the Platform relay. */
     url: string;
-    /** API key for authentication. */
+    /** API key. */
     token: string;
-    /** Callback invoked when a webhook relay is received from Platform. */
     onWebhookRelay: (relay: WebhookRelay) => Promise<void>;
-    /** Provider sources to register after authentication. */
+    /** Registered after authentication. */
     providerSources?: ProviderSource[];
-    /** Orchestrator cluster instance ID (sent in source.register for peer correlation). */
+    /** Sent in source.register for peer correlation. */
     instanceId?: string;
     /** `cluster_meta.cluster_name`; the Platform routes per-orch dashboard requests by it. */
     clusterName?: string;
@@ -69,29 +65,28 @@ export interface PlatformClientOptions {
      * 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. */
+    /** Peer-to-peer address (KICI_CLUSTER_ADDRESS); null if not configured. */
     address?: string | null;
-    /** Orchestrator version string (e.g. "0.0.1"). Sent in source.register for diagnostics. */
+    /** e.g. "0.0.1". Sent in source.register for diagnostics. */
     version?: string;
-    /** Orchestrator config mode. Sent in source.register for diagnostics. */
+    /** Sent in source.register for diagnostics. */
     mode?: string;
-    /** Scaler backends configured (e.g. ["container", "firecracker"]). Sent in source.register for diagnostics. */
+    /** e.g. ["container", "firecracker"]. Sent in source.register for diagnostics. */
     scalerBackends?: string[];
-    /** How the orchestrator process was deployed. Sent in source.register so the dashboard can build the correct kici-admin invocation. */
+    /** Sent in source.register so the dashboard builds the correct kici-admin invocation. */
     deployment?: DeploymentIdentity;
-    /** Where this orchestrator's own config files live on its host. Sent in source.register so the dashboard can point an operator at them. */
+    /** Host config file locations, sent in source.register for the dashboard to show. */
     configPaths?: ConfigPaths;
-    /** Whether this orchestrator has S3 log storage configured. Sent in source.register for pool validation. */
+    /** S3 log storage configured. Sent in source.register for pool validation. */
     s3LogAccess?: boolean;
-    /** Queue timeout in ms. Sent in source.register for Platform safety-net GC. */
+    /** Ms. Sent in source.register for Platform safety-net GC. */
     queueTimeoutMs?: number;
-    /** Heartbeat interval in ms. Default: 30000 (30s). */
+    /** Ms. Default: 30000 (30s). */
     heartbeatIntervalMs?: number;
-    /** Maximum reconnect delay in ms. Default: 60000 (60s). */
+    /** Ms. Default: 60000 (60s). */
     maxReconnectDelayMs?: number;
-    /** Maximum event buffer size. Default: 10000. */
+    /** Default: 10000. */
     maxBufferSize?: number;
-    /** Optional callback for log pull requests from Platform. */
     onLogPullRequest?: FrameHandler<{
         messageId: string;
         executionId: string;
@@ -100,7 +95,7 @@ export interface PlatformClientOptions {
         cursor?: number;
         limit?: number;
     }>;
-    /** Optional callback for peer discovery (from Platform matchmaker). */
+    /** Peer discovery from the Platform matchmaker. */
     onPeerDiscover?: (peer: {
         connectionId: string;
         instanceId?: string;
@@ -108,7 +103,7 @@ export interface PlatformClientOptions {
         routingKeys: string[];
         orchRole?: OrchRole;
     }) => void;
-    /** Optional callback invoked after successful authentication and source registration. */
+    /** Invoked after authentication and source registration. */
     onAuthenticated?: () => void | Promise<void>;
     /** Connected worker peers for `cluster.membership`; undefined off-coordinator → none reported. */
     getWorkerPeers?: () => Array<{
@@ -140,15 +135,14 @@ export interface PlatformClientOptions {
     onRunCancel?: FrameHandler<RunCancelRequest>;
     /** 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>;
     /** `kici run remote` control-plane relay requests; the handler replies keyed by `requestId`. */
     onTestRelay?: FrameHandler<TestRelayRequest>;
     onTrustPolicyUpdate?: FrameHandler<TrustPolicyUpdate>;
     onStaleCheckrunCleanup?: FrameHandler<StaleCheckrunCleanup>;
-    /** Optional handler for join.request frames relayed by the Platform. It answers every such frame. */
+    /** Answers every Platform-relayed join.request frame. */
     onJoinRequest?: (raw: unknown) => Promise<JoinResponse>;
-    /** Custom orchestrator capabilities to merge with ORCH_CAPABILITIES in auth.request. */
+    /** Merged with ORCH_CAPABILITIES in auth.request. */
     orchCapabilities?: Partial<OrchCapabilities>;
     /**
      * Verify a reassembled chunked-relay webhook. Without it every chunked relay
@@ -171,7 +165,6 @@ export interface PlatformClientOptions {
      */
     onShedCapture?: (meta: RelayStartMeta, body: Buffer, reason: string) => Promise<void>;
 }
-/** Error `*.response` frame shape for a dashboard request that failed validation. */
 export interface DashboardRequestErrorFrame {
     type: string;
     requestId: string;
@@ -181,10 +174,8 @@ export interface DashboardRequestErrorFrame {
     requestType: string;
 }
 /**
- * Build the error `*.response` frame for a dashboard request that failed schema
- * validation, distinguishing a request type this build has never heard of
- * (version mismatch → upgrade the orchestrator) from a known type with a
- * malformed body (genuine client error).
+ * Distinguishes a request type this build has never heard of (version mismatch →
+ * upgrade the orchestrator) from a known type with a malformed body.
  */
 export declare function classifyDashboardRequestError(raw: {
     type: string;
@@ -293,7 +284,11 @@ export declare class PlatformClient {
     connect(): void;
     /** Graceful disconnect; does not reconnect. */
     disconnect(): void;
-    /** Send now when authenticated, otherwise buffer for the next connection. */
+    /**
+     * Send now when authenticated, otherwise buffer for the next connection. A
+     * status frame the Platform would refuse is dropped here (see
+     * `guardOutboundFrame`), so the buffer only ever holds frames that can be sent.
+     */
     send(message: OrchestratorToPlatformMessage): void;
     /**
      * Send the reconnect state replay as paced frames, each within the wire
@@ -349,6 +344,12 @@ export declare class PlatformClient {
     private handlePeerUpdate;
     /** Unbuffered send, for ACKs that must go now or not at all. */
     private sendDirect;
+    /**
+     * Send the frames buffered while disconnected, in order. A frame that cannot
+     * be serialized is dropped alone and the rest still go out. When the socket
+     * stops being open part-way, the frames not yet written go back into the
+     * buffer for the next connection instead of being lost.
+     */
     private flushBuffer;
     private startHeartbeat;
     private stopHeartbeat;

package/dist/ws/replay-chunker.d.ts

@@ -5,12 +5,10 @@
  * Platform's WS limiter caps a single message at 4 MB with a 2 MB burst
  * refilling at 500 KB/s, so a replay must be split on BOTH axes: a frame that
  * breaches either one is dropped by the Platform, which closes the connection
- * with 4003. Since nothing about reconnecting reduces the run count, an
- * oversized frame is not a transient failure — the orchestrator rebuilds and
- * resends it forever.
+ * with 4003. Reconnecting does not reduce the run count, so an oversized frame
+ * is not transient: the orchestrator would rebuild and resend it forever.
  *
- * Pure and I/O-free so the bounds can be shrunk in tests without building 500
- * real runs.
+ * Pure and I/O-free so tests can shrink the bounds instead of building 500 runs.
  */
 /**
  * Runs per frame. Deliberately below the schema's hard cap of 500 so growth in
@@ -26,12 +24,11 @@ export interface ChunkBounds {
     maxBytes: number;
 }
 /**
- * Split `runs` into frames obeying both bounds, preserving order.
+ * Splits `runs` into frames obeying both bounds, preserving order.
  *
- * A single run larger than `maxBytes` cannot be split — it is emitted alone.
- * That is why the byte test is guarded on a non-empty current chunk: without
- * the guard an oversized run would either loop forever or emit an empty chunk,
- * and an empty `runs` array is not a frame worth sending.
+ * A run larger than `maxBytes` is emitted alone. The byte test is guarded on a
+ * non-empty current chunk; without the guard an oversized run would loop
+ * forever or emit an empty chunk.
  */
 export declare function chunkReplayRuns<T>(runs: readonly T[], bounds?: ChunkBounds): T[][];
 //# sourceMappingURL=replay-chunker.d.ts.map

package/dist/ws/server-options.d.ts

@@ -1,15 +1,11 @@
 import type { WebSocketServer } from 'ws';
 /**
- * Applies the security-relevant options to a `ws` `WebSocketServer` instance.
+ * Single source of truth for the orchestrator's agent-WS server security
+ * options, kept outside the `createApp` graph so it is unit-testable.
  *
- * Single source of truth for the orchestrator's agent-WS server config. Lives
- * here so it is unit-testable independently of the heavy `createApp` dependency
- * graph.
- *
- * The `permessage-deflate` compression-bomb invariant lives here: any
- * field added to defend against compression-bomb DoS — `maxPayload`,
- * `serverNoContextTakeover`, etc. — MUST be set inside this helper so the
- * neighbouring test file can assert it.
+ * Compression-bomb invariant: any field that defends against compression-bomb
+ * DoS (`maxPayload`, `serverNoContextTakeover`, …) MUST be set inside this
+ * helper so the neighbouring test file can assert it.
  */
 export declare function configureSecureWsServer(wss: WebSocketServer): void;
 //# sourceMappingURL=server-options.d.ts.map