@kici-dev/orchestrator 0.5.0 → 0.6.1

package/dist/worker/in-memory-job-queue.d.ts

@@ -35,7 +35,7 @@ export declare class InMemoryJobQueue {
      * label in the gate set. Empty (default) is a no-op for static / non-scaler
      * agents — the gate trivially passes.
      */
-    dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[]): Promise<QueuedJob | null>;
+    dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[], _agentId?: string, canServe?: (job: QueuedJob) => boolean): Promise<QueuedJob | null>;
     /**
      * Dequeue a specific pending job by id, validating that the agent's labels
      * still satisfy the job's runsOn / excludeLabels and the agent's

package/dist/ws/agent-handler.d.ts

@@ -13,7 +13,11 @@
  * 2. pendingRegistration (10s): After auth.success, agent must send agent.register.
  * 3. registered: Agent is fully connected and can exchange messages.
  *
- * When agentAuthMode === 'none', the auth phase is skipped (legacy behavior).
+ * When agentAuthMode === 'none', the auth phase is skipped and the connection
+ * starts in pendingRegistration. An agent that happens to carry a token still
+ * opens with auth.request — nothing on the wire tells it the mode — so that
+ * frame is accepted there and answered with auth.success without reading the
+ * token, and the agent then registers as normal.
  */
 import type { WSEvents } from 'hono/ws';
 import { LogStream } from '@kici-dev/engine';
@@ -124,12 +128,16 @@ export interface AgentWsHandlerDeps {
      *   AgentRegistry so subsequent label matches (queue drain + eager
      *   dispatch) apply the same gate the scaler-side selector applied.
      *
-     * Returns `null` for static agents not managed by any scaler.
+     * Resolves to `null` for static agents not managed by any scaler.
+     *
+     * Asynchronous because the agent may reach an instance that did not spawn
+     * it: that instance adopts the agent from the shared spawn record, which is
+     * a database round trip.
      */
-    onScalerAgentRegistered?: (agentId: string, labels: string[]) => {
+    onScalerAgentRegistered?: (agentId: string, labels: string[]) => Promise<{
         boundJobId?: string;
         mandatoryLabels: string[];
-    } | null;
+    } | null>;
     /** Optional callback when an agent disconnects (for scaler lifecycle). */
     onScalerAgentDisconnected?: (agentId: string) => void;
     /** Optional callback when an agent completes a job (for scaler lifecycle). */
@@ -170,6 +178,22 @@ export interface AgentWsHandlerDeps {
         deliveryId?: string;
         error?: string;
     }>;
+    /**
+     * Optional callback: a provisioning workflow's agent exchanges a single-use
+     * claim code (from a `kici.scaler.scale-up` event) for freshly minted
+     * ephemeral agent credentials. Delegates to the event scaler backend's claim
+     * store. Returns the credentials or an author-actionable error; the token is
+     * carried only in the response, never logged.
+     */
+    onClaimCredentials?: (agentId: string, claimCode: string) => Promise<{
+        credentials?: {
+            agentToken: string;
+            agentId: string;
+            orchestratorUrl: string;
+            labels: string[];
+        };
+        error?: string;
+    }>;
     /** Optional callback when agent sends a run.event for infrastructure lifecycle tracking. */
     onRunEvent?: (agentId: string, msg: {
         runId: string;

package/dist/ws/dashboard-context-handler.d.ts

@@ -13,11 +13,12 @@
 import { type Kysely } from 'kysely';
 import type { HeldRunStore, ReleaseSignal } from '../contexts/held-runs.js';
 import type { TeamMembershipLookup } from '../approvals/approval-resolver.js';
+import { type ApplyDecisionDeps } from '../approvals/apply-decision.js';
 import type { DashboardPlatformToOrchMessage } from '@kici-dev/engine';
 import type { ContextStore } from '../contexts/context-store.js';
 import type { VariableStore } from '../contexts/variable-store.js';
 import type { BindingStore } from '../contexts/binding-store.js';
-import type { Database } from '../db/types.js';
+import type { Database, HeldRun } from '../db/types.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 import { type ScopedSecretStore } from '../secrets/scope-routing.js';
 import type { ResolvedDashboardEncryptionKey } from '../secrets/dashboard-encryption-key.js';
@@ -74,10 +75,22 @@ export interface ApprovalHandlerDeps {
     resumeStep?: (signal: ReleaseSignal) => Promise<void>;
     /** Notify a waiting agent that a step hold was rejected (step scope). */
     rejectStep?: (heldRunId: string, reason?: string) => Promise<void> | void;
-    /** Resume a released workflow install-gate hold (workflow scope). */
+    /** Resume a released workflow-scoped hold (install gate or trust policy). */
     resumeWorkflow?: (signal: ReleaseSignal) => Promise<void>;
-    /** Cancel a rejected workflow install-gate hold (workflow scope). */
-    rejectWorkflow?: (runId: string) => Promise<void>;
+    /**
+     * Cancel a rejected workflow-scoped hold (install gate, trust policy, or an
+     * SDK workflow-level `requireApproval`), recording the rejecter's own reason
+     * as the run's cancellation reason. The hold row tells those apart, and the
+     * resolved boolean says whether a terminal `KiCI Security` check was written
+     * — see `onWorkflowReject` on `ApplyDecisionDeps`.
+     */
+    rejectWorkflow?: (hold: HeldRun, reason?: string) => Promise<boolean>;
+    /**
+     * Terminalize the `KiCI Security` check of any hold this handler ends that
+     * `rejectWorkflow` did not report on — see `settleSecurityCheck` on
+     * `ApplyDecisionDeps`.
+     */
+    settleSecurityCheck?: ApplyDecisionDeps['settleSecurityCheck'];
 }
 /**
  * Handler for all dashboard context and held run WS messages.
@@ -162,6 +175,12 @@ export declare class DashboardContextHandler {
     /**
      * Resolve the actor's Keycloak sub for approval attribution. Only `user` and
      * `platform_operator` actors carry a `sub`; others fall back to a stable id.
+     *
+     * The `service:` namespace comes from {@link adminActorSub} rather than a
+     * literal here: `applyDecision`'s self-approval gate compares this value
+     * against {@link triggererSubjectFor}'s output, so the two renderings of one
+     * principal have to be produced by the same code or the gate compares strings
+     * that can never be equal.
      */
     private actorSub;
     /** Read org_settings.allow_self_approval (default true). */
@@ -170,6 +189,11 @@ export declare class DashboardContextHandler {
      * Route an approve/reject through the shared `applyDecision` applier:
      * eligibility check, real attribution, multi-clause accumulation, and the
      * resume-after-approval re-dispatch. Sends the matching response message.
+     *
+     * The response goes out as soon as the decision is durable, not when its
+     * consequence finishes — see `ApplyDecisionResult.consequence`. The audit
+     * entry is attached to that consequence instead, so there is still exactly one
+     * per decision and it still carries the real outcome.
      */
     private applyApprovalDecision;
     private handleHeldRunApprove;

package/dist/ws/dashboard-global-workflows-handler.d.ts

@@ -75,6 +75,12 @@ export declare class DashboardGlobalWorkflowsHandler {
      */
     private effectiveEnabled;
     private upsertRow;
+    /**
+     * Same envelope as `sendError`, for a request the client got wrong. Logged at
+     * warn level: bad input is not a server fault, and error-level rows here would
+     * pollute the error dashboards an operator watches.
+     */
+    private sendClientError;
     private sendError;
 }
 interface NormalizedPatch {

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

@@ -25,5 +25,7 @@ export declare const AgentWsInternalFailure: Readonly<{
     readonly eventEmitFailed: 'the orchestrator hit an internal error while emitting this event';
     /** An agent private-API handler threw for a reason other than its two deliberate rejections. */
     readonly agentApiFailed: 'the orchestrator hit an internal error while handling this API request';
+    /** The event-scaler claim store threw while minting ephemeral credentials. */
+    readonly scalerClaimFailed: 'the orchestrator hit an internal error while claiming scaler credentials';
 }>;
 //# sourceMappingURL=failure-messages.d.ts.map

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

@@ -0,0 +1,39 @@
+/**
+ * `agent.api` handler for GIT_CREDENTIAL_REQUEST_METHOD.
+ *
+ * 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 has two layers. Job ownership comes first — an agent may only
+ * request credentials for a job it was dispatched, resolved from server truth
+ * via the dispatcher, never from the params. Then the repository fence, which
+ * applies to WRITE only: a read with the source credential may reach any
+ * repository inside the App installation's own selection (GitHub enforces that
+ * selection when the mint names the 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.
+ *
+ * A workflow-supplied credential needs no fence of its own: it names secrets
+ * the job can already read with `ctx.secrets.get()`, so brokering it grants no
+ * capability the workflow did not already have — the secret ACL is the
+ * authorization.
+ */
+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 this job was dispatched for. */
+    sourceRepo: string;
+}
+export interface GitCredentialHandlerDeps {
+    broker: GitCredentialBroker;
+    /** The dispatcher's job-ownership resolver — the same one the OIDC relay uses. */
+    dispatcher: {
+        resolveOwnedJob(agentId: string, jobId: string): {
+            runId: string;
+        } | undefined;
+    };
+    jobContext: (runId: string, jobId: string) => Promise<JobCredentialContext | null>;
+}
+export declare function buildGitCredentialHandler(deps: GitCredentialHandlerDeps): (agentId: string, rawParams: Record<string, unknown>) => Promise<unknown>;
+//# sourceMappingURL=git-credential-relay.d.ts.map

package/dist/ws/oidc-token-relay.d.ts

@@ -60,19 +60,14 @@ export interface OidcTokenHandlerDeps {
     };
     platformClient: MintPlatformClient;
     orchestratorId: string;
-    /** Test-only fault-injection master switch (config.testMode). */
-    testMode: boolean;
     /**
-     * Test-only: force-defer the *initial* agent mint for any job requesting this
-     * OIDC audience (config.testMintDeferAudience). Ignored unless `testMode`.
+     * Test-only fault-injection predicate over the requested OIDC `audience`,
+     * supplied only by the build-time test double. Returning `true` short-circuits
+     * the *initial* mint to a transient defer BEFORE the real Platform relay is
+     * contacted — it can only defer/reject, never forge or weaken a signature.
+     * Undefined (the shipped default) means no fault injection.
      */
-    testMintDeferAudience?: string;
-    /**
-     * Test-only: force the *initial* agent mint to defer for this OIDC audience
-     * (config.testMintRejectAudience) so a pending row is created, which the
-     * retrier then terminally rejects. Ignored unless `testMode`.
-     */
-    testMintRejectAudience?: string;
+    initialMintFault?: (audience: string) => boolean;
 }
 /**
  * Build the agent.api handler for `OIDC_TOKEN_REQUEST_METHOD`. Validates the

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';
 /**
@@ -114,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
@@ -195,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`.
-     */
-    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.
+     * 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.
      */
-    testOmitDashboardRequestTypes?: string;
+    capabilitiesTransform?: (c: OrchCapabilities) => OrchCapabilities;
     /**
      * Verify a reassembled inbound webhook from the chunked relay path.
      *
@@ -269,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. */
@@ -321,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?;
@@ -532,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/installer-image-digests.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.5.0",
+  "version": "0.6.1",
   "images": {
-    "kici-agent": "sha256:f5c3557be41a50900a5f7045ac769079e219766f01ef290d33b11c479d4dcb9c",
-    "kici-orchestrator": "sha256:596989e4804e6111f4263168e7fd41e0be9dc50d796c8ad0952af3e6e6d8e930"
+    "kici-agent": "sha256:bc64f67d749520b7424de6fc1bd614791064eadde3cb2d007074605aa30496c2",
+    "kici-orchestrator": "sha256:80079e870c3755f9467164fa7189c2a7dc6ddc44028e9c0932778839d56e0778"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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.5.0",
-    "@kici-dev/shared": "0.5.0"
+    "@kici-dev/shared": "0.6.1",
+    "@kici-dev/engine": "0.6.1"
   },
   "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.5.0"
+    "@kici-dev/agent": "0.6.1"
   },
   "scripts": {
     "build": "node ../../scripts/build-service.mjs && tsgo --emitDeclarationOnly",