@kici-dev/orchestrator 0.4.0 → 0.6.0

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

@@ -1,4 +1,5 @@
 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 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 JoinRequest, type JoinResponse, type DeploymentIdentity, 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';
 /**
@@ -36,6 +37,20 @@ export type ReplaySendResult = {
  */
 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.
+ *
+ * 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.
+ */
+export declare const ADMITTED_PIPELINE_LIFETIME_MS: number;
 export interface PlatformClientOptions {
     /** WebSocket URL of the Platform relay. */
     url: string;
@@ -100,6 +115,27 @@ export interface PlatformClientOptions {
     }) => void;
     /** Optional callback invoked after successful authentication and source registration. */
     onAuthenticated?: () => 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.
+     */
+    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.
+     */
+    planHeadroomStore?: PlanHeadroomStore;
+    /**
+     * Reconcile this coordinator's workers against a pushed ceiling. Invoked on
+     * EVERY `plan.headroom` frame with the frame's `evictExcess` flag, so a raised
+     * ceiling (or a cleared `evictExcess`) can cancel an in-flight drain, not only
+     * start one. Undefined → no eviction reconciliation.
+     */
+    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
@@ -181,16 +217,12 @@ export interface PlatformClientOptions {
     /** Custom orchestrator capabilities to merge with ORCH_CAPABILITIES in auth.request. */
     orchCapabilities?: Partial<OrchCapabilities>;
     /**
-     * Test-only. Whether the orchestrator runs in test mode (config
-     * `KICI_TEST_MODE=1`). Gates `testOmitDashboardRequestTypes`.
+     * 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.
      */
-    testMode?: boolean;
-    /**
-     * Test-only. Comma-separated `dashboard.*` request types to drop from the
-     * advertised capability manifest (config `KICI_TEST_OMIT_DASHBOARD_REQUEST_TYPES`).
-     * Only honored when `testMode` is true; production leaves both unset.
-     */
-    testOmitDashboardRequestTypes?: string;
+    capabilitiesTransform?: (c: OrchCapabilities) => OrchCapabilities;
     /**
      * Verify a reassembled inbound webhook from the chunked relay path.
      *
@@ -255,6 +287,7 @@ export declare class PlatformClient {
     private _state;
     private readonly eventBuffer;
     private heartbeatTimer;
+    private membershipTimer;
     private reconnectTimer;
     private reconnectAttempts;
     /** Armed on auth; resets the backoff only if the connection survives it. */
@@ -307,6 +340,9 @@ export declare class PlatformClient {
     private readonly onLogPullRequest?;
     private readonly onPeerDiscover?;
     private readonly onAuthenticated?;
+    private readonly getWorkerPeers?;
+    private readonly planHeadroomStore?;
+    private readonly onPlanCeiling?;
     private readonly onOrgIdentified?;
     private readonly onProvenanceIssuer?;
     private readonly onDashboardRunDetail?;
@@ -518,6 +554,29 @@ export declare class PlatformClient {
     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.
+     */
+    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.
+     */
+    private onPlanHeadroom;
+    /**
+     * The ceiling this coordinator enforces, or `null` when none was ever
+     * received — in which case worker joins are admitted freely.
+     */
+    getWorkerCeiling(): Promise<number | null>;
     private scheduleReconnect;
     private clearStabilityTimer;
     private cancelReconnect;

package/dist/ws/test-relay-handlers.d.ts

@@ -24,15 +24,6 @@ export interface TestRelayHandlerDeps extends ProcessingDeps {
     agentRegistry: NonNullable<ProcessingDeps['agentRegistry']>;
     cacheStorage?: CacheStorage;
     logStorage?: LogStorage;
-    /**
-     * Log writer that owns the in-flight append tracking. The logs cursor
-     * handler drains its pending appends for a terminal run before computing the
-     * `done` flag, so the final (fire-and-forget) log chunk can't be lost to a
-     * race with the run-status transition.
-     */
-    logWriter?: {
-        drain(runId: string): Promise<void>;
-    };
     accessLog?: AccessLogWriter;
     /** Canonical org id this orchestrator is bound to (for access_log attribution). */
     orgId?: string | null;
@@ -79,7 +70,41 @@ export interface TestRunStatusPayload {
     }>;
     done: boolean;
 }
-/** Snapshot a run's status + per-job status. `done` is true at a terminal run state. */
+/**
+ * Snapshot a run's status + per-job status. `done` is true at a terminal run state.
+ *
+ * ## Why this does not check ownership, even though the run now records an owner
+ *
+ * `handleTestTrigger` records the initiator on `execution_runs.triggered_by`,
+ * so comparing `msg.actor` against it here looks like free defence in depth. It
+ * is not, for three reasons that are worth writing down because the idea
+ * recurs.
+ *
+ * **The orchestrator cannot authenticate the actor.** It is asserted by the
+ * Platform over the authenticated control-plane connection; nothing here can
+ * verify it. A Platform that is lying can name any principal and pass the
+ * check, so enforcing would defend only against a Platform that reports the
+ * actor faithfully and forgets to check ownership — not against a hostile one.
+ *
+ * **The two gates would disagree.** The Platform deliberately admits a caller
+ * with unrestricted repository scope alongside the creator, because such a
+ * caller can already read these runs through the dashboard run plane. Repo
+ * patterns do not exist on this tier — only the actor arrives — so an
+ * organization owner reading a developer's run would be allowed there and
+ * refused here. Closing that would mean the Platform asserting "this caller is
+ * unrestricted", which is the first problem again with extra steps.
+ *
+ * **The version skew runs the wrong way.** This component is customer-deployed
+ * and versions independently of the Platform, so an orchestrator upgraded to
+ * enforce would start refusing legitimate reads against a Platform that has not
+ * changed — a break the customer triggers and we cannot roll back. Fail-closed
+ * is right for a security control and wrong for a compatibility surface, and
+ * this is both.
+ *
+ * So the actor is recorded, not enforced. Enforcing here needs the caller's
+ * effective authorization scope on the wire (so one policy is evaluated rather
+ * than two), and an actor this tier can establish independently.
+ */
 export declare function handleTestRunStatus(msg: TestRelayRunStatusRequest, deps: TestRelayHandlerDeps): Promise<TestRunStatusPayload | {
     error: string;
 }>;

package/installer-image-digests.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.4.0",
+  "version": "0.6.0",
   "images": {
-    "kici-agent": "sha256:60f463973e2fa02c4e1d9311c9214e679269fa6ead3135b4c826789ca0278cbf",
-    "kici-orchestrator": "sha256:75312fc8bee960384aa2c57ff72cf2fe65bcd52d222278632c79a5f14ccd3e27"
+    "kici-agent": "sha256:6a6dad749ae8a520774139588b6b83d194dcddc5fec58ed46207e0654eb9bc27",
+    "kici-orchestrator": "sha256:86cc2e5c316492bffce415ac55989681491de25085258f411928ed19ad7a36fb"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -30,6 +30,8 @@
   "files": [
     "dist",
     "!dist/**/*.map",
+    "!dist/server-test.d.ts",
+    "!dist/testing",
     "sbom.spdx.json",
     "installer-image-digests.json"
   ],
@@ -54,38 +56,41 @@
       "standalone.js": "src/standalone.ts",
       "cli.js": "src/cli/kici-admin.ts",
       "index.js": "src/index.ts"
+    },
+    "devEntries": {
+      "server-test.js": "src/server-test.ts"
     }
   },
   "dependencies": {
-    "@aws-sdk/client-kms": "^3.1089.0",
-    "@aws-sdk/client-s3": "^3.1089.0",
-    "@aws-sdk/lib-storage": "^3.1089.0",
-    "@aws-sdk/s3-request-presigner": "^3.1089.0",
-    "@hono/node-server": "^2.0.10",
-    "@inquirer/prompts": "^8.5.2",
-    "@octokit/auth-app": "^8.2.0",
+    "@aws-sdk/client-kms": "^3.1121.0",
+    "@aws-sdk/client-s3": "^3.1121.0",
+    "@aws-sdk/lib-storage": "^3.1121.0",
+    "@aws-sdk/s3-request-presigner": "^3.1121.0",
+    "@hono/node-server": "^2.1.1",
+    "@inquirer/prompts": "^8.7.0",
+    "@octokit/auth-app": "^8.3.0",
     "@octokit/rest": "^22.0.1",
     "archiver": "^8.0.0",
     "commander": "^15.0.0",
     "croner": "^10.0.1",
     "dockerode": "^5.0.1",
-    "hashi-vault-js": "^0.5.2",
-    "hono": "^4.12.32",
-    "jose": "^6.1.0",
+    "hashi-vault-js": "^0.5.3",
+    "hono": "^4.13.2",
+    "jose": "^6.2.10",
     "jsonpath-plus": "^10.4.0",
     "jszip": "^3.10.1",
     "kysely": "^0.29.4",
     "lru-cache": "^11.5.2",
-    "nanoid": "^6.0.0",
-    "pg": "^8.22.0",
-    "picomatch": "^4.0.5",
+    "nanoid": "^6.0.1",
+    "pg": "^8.23.0",
+    "picomatch": "^4.0.7",
     "strip-ansi": "^7.2.0",
-    "tar": "^7.5.20",
-    "ws": "^8.21.1",
+    "tar": "^7.5.22",
+    "ws": "^8.21.3",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@kici-dev/engine": "0.4.0",
-    "@kici-dev/shared": "0.4.0"
+    "@kici-dev/shared": "0.6.0",
+    "@kici-dev/engine": "0.6.0"
   },
   "kici": {
     "metrics": {
@@ -100,7 +105,7 @@
     "@types/dockerode": "^4.0.1",
     "@types/ws": "^8.18.1",
     "kysely-ctl": "^0.21.0",
-    "@kici-dev/agent": "0.4.0"
+    "@kici-dev/agent": "0.6.0"
   },
   "scripts": {
     "build": "node ../../scripts/build-service.mjs && tsgo --emitDeclarationOnly",