@kici-dev/orchestrator 0.1.15 → 0.1.17

package/dist/storage/filesystem.d.ts

@@ -13,7 +13,7 @@
  * data file is byte-identical to what the agent receives over HTTP. TTL is
  * enforced lazily on access — same model as the S3 backend.
  */
-import type { CacheStorage } from './types.js';
+import type { CacheMetadata, CacheStorage } from './types.js';
 export interface FilesystemCacheStorageOptions {
     /** Absolute path to the cache root directory. Created on first write if missing. */
     basePath: string;
@@ -55,6 +55,7 @@ export declare class FilesystemCacheStorage implements CacheStorage {
     getInternalUploadUrl(key: string): Promise<string>;
     initMeta(key: string): Promise<void>;
     list(subPrefix: string): Promise<string[]>;
+    getMetadata(key: string): Promise<CacheMetadata | null>;
     copy(srcKey: string, destKey: string): Promise<void>;
     /**
      * Recursively collect data files under `dir`, returning each as a cache key

package/dist/storage/s3.d.ts

@@ -11,7 +11,7 @@
  * TTL is enforced lazily: expired items are deleted on access.
  * Pre-signed URLs are generated for getUrl() with 15-minute expiry.
  */
-import type { CacheStorage } from './types.js';
+import type { CacheMetadata, CacheStorage } from './types.js';
 export interface S3CacheStorageOptions {
     bucket: string;
     prefix: string;
@@ -74,6 +74,7 @@ export declare class S3CacheStorage implements CacheStorage {
     getInternalUploadUrl(key: string): Promise<string>;
     initMeta(key: string): Promise<void>;
     list(subPrefix: string): Promise<string[]>;
+    getMetadata(key: string): Promise<CacheMetadata | null>;
     copy(srcKey: string, destKey: string): Promise<void>;
     /** Delete an S3 object. Idempotent (doesn't error if missing). */
     private deleteObject;

package/dist/storage/types.d.ts

@@ -79,6 +79,13 @@ export interface CacheStorage {
     list(subPrefix: string): Promise<string[]>;
     /** Server-side copy from one cache key to another (used for atomic temp -> final commit). */
     copy(srcKey: string, destKey: string): Promise<void>;
+    /**
+     * Read the stored metadata (createdAt + lastAccessedAt) for a key WITHOUT
+     * refreshing lastAccessedAt. Returns null when the key is missing or carries
+     * no metadata. A pure read (no TTL-expiry side effect) — used by quota
+     * eviction to order candidates by access recency.
+     */
+    getMetadata(key: string): Promise<CacheMetadata | null>;
 }
 import type { SharedS3Config } from '@kici-dev/shared';
 /**

package/dist/webhook/generic-sources-listener.d.ts

@@ -51,6 +51,10 @@ export interface GenericSourcesChangeListenerOptions {
     /** Required for universal-git source rows; null is acceptable on
      *  peers that cannot serve them. */
     secretResolver: SecretResolver | null;
+    /** Active scaler backend on this peer. Threaded into the warm-path
+     *  registration so a local source added at runtime on a container /
+     *  firecracker scaler emits the same reachability warning as a cold-boot one. */
+    scalerBackendType?: string;
     /** Coalesce window for rapid NOTIFYs against the same row. Default 200 ms. */
     debounceMs?: number;
     /**

package/dist/webhook/generic-sources.d.ts

@@ -9,6 +9,7 @@ import { type Kysely } from 'kysely';
 import type { Database, GenericWebhookSource } from '../db/types.js';
 import type { VerificationMethod } from '../providers/generic/verification.js';
 import { type UniversalGitConfig } from '../providers/universal-git/config.js';
+import { type LocalSourceConfig } from '../providers/local/local-source-config.js';
 /**
  * Input for creating a new generic webhook source.
  */
@@ -26,22 +27,31 @@ interface CreateSourceInput {
     allowedEvents?: string[];
     stripHeaders?: string[];
     rateLimitRpm?: number;
-    /** Provider implementation: 'generic' (default) or 'internal' (E2E/staging
-     *  github-shaped payload routing through InternalWebhookNormalizer). */
-    providerType?: 'generic' | 'internal';
+    /** Provider implementation: 'generic' (default) or 'local' (a git repo on
+     *  the agent filesystem cloned via file://, routed through
+     *  LocalWebhookNormalizer). */
+    providerType?: 'generic' | 'local';
     /** Universal-git configuration — when set, promotes this source from a
      *  payload-only generic webhook to a full git-aware source that can register
      *  workflows, fetch lock files, and be cloned by agents. Validated against
      *  `UniversalGitConfigSchema`; stored as JSONB in `generic_webhook_sources.git_config`. */
     gitConfig?: UniversalGitConfig;
+    /** Local filesystem source config (`{ repoBasePath, cloneUrlBase? }`).
+     *  Mutually exclusive with `gitConfig`. Stored as JSONB in the same
+     *  `git_config` column, discriminated from universal-git by `providerType='local'`.
+     *  Validated against `LocalSourceConfigSchema`. */
+    localConfig?: LocalSourceConfig;
 }
 /**
  * Input for updating an existing generic webhook source. Use `gitConfig: null`
  * to explicitly demote a universal-git source back to a plain generic webhook
  * (omitting the field leaves the existing config untouched).
  */
-type UpdateSourceInput = Partial<Omit<CreateSourceInput, 'orgId' | 'gitConfig'>> & {
+type UpdateSourceInput = Partial<Omit<CreateSourceInput, 'orgId' | 'gitConfig' | 'localConfig'>> & {
     gitConfig?: UniversalGitConfig | null;
+    /** `null` clears the local config; a validated object re-serializes it to
+     *  `git_config`. Omit to leave the existing config untouched. */
+    localConfig?: LocalSourceConfig | null;
 };
 /**
  * Generic webhook source manager.
@@ -77,19 +87,32 @@ export declare class GenericSourceManager {
      * List all enabled, non-deleted sources matching a provider type.
      *
      * Used at orchestrator startup to register provider bundles per routing key
-     * (e.g. registering an InternalWebhookNormalizer bundle for every
-     * provider_type='internal' source so the staging stg-ha smoke test and
-     * other internal-bundle E2E harnesses can dispatch real runs through the
-     * generic endpoint without a real GitHub signature).
+     * (e.g. registering a LocalWebhookNormalizer bundle for every
+     * provider_type='local' source so local filesystem repos can dispatch real
+     * runs through the generic endpoint without a real GitHub signature).
      */
-    listByProviderType(providerType: 'generic' | 'internal'): Promise<GenericWebhookSource[]>;
+    listByProviderType(providerType: 'generic' | 'local'): Promise<GenericWebhookSource[]>;
     /**
      * List all enabled, non-deleted sources with a non-null `git_config`
      * (universal-git sources). Used at orchestrator startup + config reload
      * to register a universal-git `ProviderBundle` under each source's
      * routing key.
+     *
+     * Local sources ALSO carry `git_config` (they store `{ repoBasePath }` there),
+     * so this query MUST exclude `provider_type='local'` — otherwise a local
+     * source would be mis-registered as a universal-git bundle. The matching
+     * discrimination lives in `genericProviderTypeToSubtype` (local branch first)
+     * and `registerProviderBundleForSource` (local branch before the universal-git
+     * branch).
      */
     listUniversalGitSources(): Promise<GenericWebhookSource[]>;
+    /**
+     * List all enabled, non-deleted local filesystem sources
+     * (`provider_type='local'`). Used at orchestrator startup + config reload to
+     * register a `LocalWebhookNormalizer` bundle (built from each row's
+     * `git_config.repoBasePath`) under the source's routing key.
+     */
+    listLocalSources(): Promise<GenericWebhookSource[]>;
     /**
      * Update a source's configuration.
      */
@@ -151,8 +174,8 @@ export declare class GenericSourceManager {
  *
  * Returns `provider_type` alongside the routing key so callers can decide
  * whether the local orchestrator can actually serve each row. A peer that
- * cannot serve a provider_type (e.g. an `internal` source on a peer with no
- * `KICI_INTERNAL_PROVIDER_REPO_PATH`) MUST NOT advertise that routing key
+ * cannot serve a provider_type (e.g. a `local` source whose `repoBasePath`
+ * does not exist on that peer) MUST NOT advertise that routing key
  * to Platform — otherwise Platform's least-loaded relay may pick that peer
  * and the webhook is silently dropped on a pipeline that has no working
  * lock-file fetcher.
@@ -164,6 +187,9 @@ export declare function loadActiveGenericRoutingKeys(db: Kysely<Database>): Prom
     name: string;
     /** Whether the row has a non-null `git_config` (universal-git source). */
     has_git_config: boolean;
+    /** Raw `git_config` JSONB. Carried so the caller can check a local source's
+     *  per-row `repoBasePath` reachability via `canServeGenericProviderType`. */
+    git_config: string | Record<string, unknown> | null;
 }>>;
 export {};
 //# sourceMappingURL=generic-sources.d.ts.map

package/dist/webhook/register-source-bundle.d.ts

@@ -24,7 +24,7 @@
  * the orchestrator's already-instantiated registry / config /
  * secret-resolver and we do the right thing.
  *
- * Failure semantics match the startup behaviour: internal-only-but-
+ * Failure semantics match the startup behaviour: local-only-but-
  * unservable peers log + skip (no throw); universal-git config errors
  * bump the per-row metric + log but never propagate. The caller can
  * assume "returns normally" means "the right thing happened or we
@@ -40,13 +40,23 @@ export interface RegisterSourceBundleDeps {
     /** Required for universal-git source rows. Null is allowed; rows that
      *  carry `git_config` will be skipped with a metric bump. */
     secretResolver: SecretResolver | null;
+    /** Active scaler backend on this peer. When 'container' or 'firecracker', a
+     *  local source registration emits a one-time reachability warning (the repo
+     *  must exist inside the agent filesystem, not just on the orchestrator host). */
+    scalerBackendType?: string;
+    /** Sink for the scaler-coexistence warning. Defaults to the module logger;
+     *  overridable in tests so the warning can be asserted without logger spying. */
+    onScalerWarning?: (message: string, ctx: Record<string, unknown>) => void;
 }
 /**
  * Register the per-routing-key provider bundle a source row needs.
  *
- *   - `provider_type='internal'`: registers an `InternalWebhookNormalizer`
- *     bundle when the peer can serve it (gated on
- *     `internalProviderRepoPath` per `canServeGenericProviderType`).
+ *   - `provider_type='local'`: registers a `LocalWebhookNormalizer` bundle
+ *     built from the ROW's own `git_config.repoBasePath`, when that path
+ *     exists as a directory on THIS peer. A peer that doesn't host the repo
+ *     skips registration (and won't advertise the routing key — see
+ *     `canServeGenericProviderType`). Checked BEFORE the universal-git branch
+ *     because local sources also carry `git_config`.
  *   - `git_config IS NOT NULL`: registers a universal-git bundle.
  *   - everything else: no-op — the default `'generic'` bundle handles it.
  *

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

@@ -31,6 +31,7 @@ import type { PendingDynamicTracker } from '../cache/pending-dynamics.js';
 import type { CacheStorage } from '../storage/types.js';
 import type { AgentMetricsAggregator } from '../metrics/agent-metrics-aggregator.js';
 import type { AgentApiRegistry } from './agent-api-registry.js';
+import type { FleetAgentCollector } from './fleet-agent-collector.js';
 /**
  * Run the three token-bound authorization gates against a wire-supplied
  * `agent.register` payload. The gates are identical at first register
@@ -181,6 +182,23 @@ export interface AgentWsHandlerDeps {
     dispatchCacheRefs?: DispatchCacheRefTracker;
     /** Cache storage for setting metadata after upload completion. */
     cacheStorage?: CacheStorage;
+    /**
+     * Storage used to mint presigned PUT URLs for provenance bundles. Distinct
+     * dep so a deployment can decide whether attestations share the cache bucket.
+     */
+    provenanceStorage?: CacheStorage;
+    /**
+     * Record a completed provenance-bundle upload (writes an attestations row).
+     * `runId` is resolved server-side from the job's dispatch ref, never the wire.
+     */
+    onProvenanceUpload?: (record: {
+        runId: string;
+        jobId: string;
+        subjectName: string;
+        subjectDigest: string;
+        storageKey: string;
+        mediaType: string;
+    }) => Promise<void>;
     /** Optional rate limiter configuration. */
     rateLimiterConfig?: RateLimiterConfig;
     /** Optional ownership tracker for validating job-related messages. */
@@ -208,6 +226,30 @@ export interface AgentWsHandlerDeps {
         action: 'proceed' | 'wait' | 'cancel';
         reason?: string;
     }>;
+    /**
+     * Optional callback when an agent blocks a `requireApproval` step. The server
+     * creates a step-scoped hold from the carried clauses and returns a promise
+     * that resolves when the hold is approved, rejected, or expired. The handler
+     * relays the resolution back to the originating agent as a
+     * `step.approval-resolved` message. The `agentId` lets the server drop the
+     * pending resolver when the agent disconnects.
+     */
+    onStepApproval?: (agentId: string, msg: {
+        runId: string;
+        jobId: string;
+        stepIndex: number;
+        stepName: string;
+        clauses: Array<{
+            team: string;
+        } | {
+            user: string;
+        }>;
+        reason: string;
+        timeoutSeconds?: number;
+    }) => Promise<{
+        outcome: 'approved' | 'rejected' | 'expired';
+        reason?: string;
+    }>;
     /**
      * Optional callback fired when an agent's WS connection closes, after the
      * dispatcher's own cleanup has run. Used by the long-poll concurrency
@@ -217,6 +259,13 @@ export interface AgentWsHandlerDeps {
     onConcurrencyAgentDisconnect?: (agentId: string) => void | Promise<void>;
     /** Agent private API registry for handling agent.api.request messages. */
     agentApiRegistry?: AgentApiRegistry;
+    /**
+     * Orchestrator-scoped collector that correlates fleet.logs.request with the
+     * agent's chunked fleet.bundle.chunk / fleet.bundle.error response. Routed to
+     * from the incoming-message switch; pending requests for a given agent are
+     * rejected when that agent's WS closes.
+     */
+    fleetAgentCollector?: FleetAgentCollector;
 }
 export declare function createAgentWsHandler(deps: AgentWsHandlerDeps): WSEvents;
 //# sourceMappingURL=agent-handler.d.ts.map

package/dist/ws/dashboard-dispatch-guard.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Guarantees every forwarded dashboard request produces exactly one response
+ * frame keyed to its requestId. Wraps the per-type dispatch so a thrown handler
+ * or an unhandled message type returns a fast structured error instead of a
+ * silently dropped frame (which the Platform would surface as a 10s 504 at its
+ * forward window).
+ */
+export interface DashboardDispatchGuardDeps {
+    /** Sends a raw frame back over the Platform WS. */
+    sendRaw: (msg: unknown) => void;
+    /** Runs the real per-type dispatch; resolves true if a handler owned the type. */
+    dispatch: (msg: {
+        type: string;
+        requestId: string;
+    }) => Promise<boolean>;
+}
+export declare function guardedDashboardDispatch(deps: DashboardDispatchGuardDeps, msg: {
+    type: string;
+    requestId: string;
+}): Promise<void>;
+//# sourceMappingURL=dashboard-dispatch-guard.d.ts.map

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

@@ -11,6 +11,8 @@
  * 3. Returns a response message with requestId and data (or error)
  */
 import { type Kysely } from 'kysely';
+import type { HeldRunStore, ReleaseSignal } from '../environments/held-runs.js';
+import type { TeamMembershipLookup } from '../approvals/approval-resolver.js';
 import type { DashboardPlatformToOrchMessage } from '@kici-dev/engine';
 import type { EnvironmentStore } from '../environments/environment-store.js';
 import type { VariableStore } from '../environments/variable-store.js';
@@ -44,6 +46,30 @@ export interface DashboardEnvHandlerDeps {
     accessLog?: AccessLogWriter;
     /** Routing key for access_log rows (null when not run-scoped). */
     routingKey?: string | null;
+    /**
+     * Held-run store + resume hook for the approve/reject flow. When present, the
+     * approve/reject handlers route through the shared `applyDecision` applier
+     * (eligibility check, real attribution, multi-clause accumulation, and the
+     * resume-after-approval re-dispatch). When absent (legacy / tests), the
+     * handlers fall back to the direct status flip.
+     */
+    approvals?: ApprovalHandlerDeps;
+}
+/** Dependencies enabling the resolver-backed approve/reject + resume path. */
+export interface ApprovalHandlerDeps {
+    store: HeldRunStore;
+    /** Team name → member user ids (Plan-1 trust-policy cache). */
+    teamMembershipLookup: TeamMembershipLookup;
+    /** Re-dispatch a released job hold (consumes its pending context). */
+    resumeJob: (signal: ReleaseSignal) => Promise<void>;
+    /** Notify a waiting agent that a step hold released (step scope). */
+    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). */
+    resumeWorkflow?: (signal: ReleaseSignal) => Promise<void>;
+    /** Cancel a rejected workflow install-gate hold (workflow scope). */
+    rejectWorkflow?: (runId: string) => Promise<void>;
 }
 /**
  * Handler for all dashboard environment and held run WS messages.
@@ -78,6 +104,14 @@ export declare class DashboardEnvHandler {
      */
     handleMessage(msg: DashboardPlatformToOrchMessage): Promise<boolean>;
     private handleEnvList;
+    /**
+     * Map each environment id to the distinct secret key names reachable through
+     * its scope bindings. Joins `environment_bindings` → `scoped_secrets` on the
+     * scope pattern, excluding the `__empty__` sentinel. Returns key names only —
+     * never values. Scoped to the caller-resolved org (the request's target org,
+     * or the connection-level org on the legacy path).
+     */
+    private loadSecretKeysByEnv;
     private handleEnvGet;
     private handleEnvCreate;
     private handleEnvUpdate;
@@ -107,6 +141,19 @@ export declare class DashboardEnvHandler {
     private handleScopeDelete;
     private handleEnvHistory;
     private handleHeldRunsList;
+    /**
+     * 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.
+     */
+    private actorSub;
+    /** Read org_settings.allow_self_approval (default true). */
+    private readAllowSelfApproval;
+    /**
+     * 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.
+     */
+    private applyApprovalDecision;
     private handleHeldRunApprove;
     private handleHeldRunReject;
     private sendError;

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

@@ -0,0 +1,23 @@
+export interface FleetAgentCollectorOptions {
+    timeoutMs: number;
+}
+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.
+     */
+    request(requestId: string, agentId: string, send: () => void): Promise<Buffer>;
+    onChunk(requestId: string, seq: number, dataB64: string, isLast: boolean): void;
+    onError(requestId: string, message: string): void;
+    /** Reject every pending request owned by `agentId` (called on its disconnect). */
+    rejectAgent(agentId: string, reason: string): void;
+    /** Reject every pending request regardless of owner (orchestrator shutdown). */
+    rejectAll(reason: string): void;
+}
+//# sourceMappingURL=fleet-agent-collector.d.ts.map

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

@@ -0,0 +1,59 @@
+/**
+ * Provenance ID-token relay (orchestrator side).
+ *
+ * Backs the `oidc.token.request` agent.api method: an agent asks for a
+ * short-lived OIDC ID token for a job it is running; the orchestrator verifies
+ * the agent owns that job, resolves its runId from its own dispatch state, and
+ * relays a mint request to the Platform's token-mint endpoint over HTTPS using
+ * the orchestrator's own `KICI_PLATFORM_TOKEN`. The agent never holds Platform
+ * credentials and never asserts its own identity claims — the Platform derives
+ * every identity claim from its own run/job rows.
+ */
+import { type OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+/** 404 / 409: the run/job is missing on the Platform or the job is terminal. */
+export declare class MintRejectedError extends Error {
+}
+/** 503: provenance signing is not configured / the Platform is unavailable. */
+export declare class MintUnavailableError extends Error {
+}
+/** Any other non-2xx from the mint endpoint. */
+export declare class MintRelayError extends Error {
+}
+/**
+ * Turn the Platform WS URL (`wss://host[/base]/ws`) into its HTTP base
+ * (`https://host[/base]`). Maps the scheme and strips a trailing `/ws` while
+ * preserving the host and any basePath in front of it.
+ */
+export declare function deriveHttpBaseFromWsUrl(wsUrl: string): string;
+export interface RequestMintArgs {
+    httpBase: string;
+    token: string;
+    orchestratorId: string;
+    runId: string;
+    jobId: string;
+    audience: string;
+}
+/**
+ * Call the Platform token-mint endpoint over HTTPS using the orchestrator's
+ * Platform token. Maps non-2xx responses to typed errors so the agent always
+ * sees a clear message instead of a raw 5xx body.
+ */
+export declare function requestMint(args: RequestMintArgs): Promise<OidcTokenResult>;
+export interface OidcTokenHandlerDeps {
+    dispatcher: {
+        resolveOwnedJob(agentId: string, jobId: string): {
+            runId: string;
+        } | undefined;
+    };
+    platformToken: string;
+    platformHttpBase: string;
+    orchestratorId: string;
+}
+/**
+ * Build the agent.api handler for `OIDC_TOKEN_REQUEST_METHOD`. Validates the
+ * params, verifies the agent owns the named job (resolving its runId from the
+ * dispatcher), and relays a mint request to the Platform. A job the agent does
+ * not own is rejected without ever contacting the Platform.
+ */
+export declare function createOidcTokenHandler(deps: OidcTokenHandlerDeps): (agentId: string, params: Record<string, unknown>) => Promise<OidcTokenResult>;
+//# sourceMappingURL=oidc-token-relay.d.ts.map

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

@@ -1,4 +1,4 @@
-import { type OrchestratorToPlatformMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardRunDetailRequest, type DashboardRunsListRequest, type DashboardRunsFiltersRequest, type DashboardSourcesListRequest, type DashboardStepLogsRequest, type DashboardOrchLogsRequest, type RunRerunRequest, type ManualScheduleRequest, type RunCancelRequest, type DashboardPayloadRequest, type DashboardPlatformToOrchMessage, type DashboardDiagnosticsRequest, type DashboardScalerCapacityRequest, type DashboardScalerAgentsRequest, type JoinRequest, type JoinResponse, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
+import { type OrchestratorToPlatformMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardRunDetailRequest, type DashboardRunsListRequest, type DashboardRunsFiltersRequest, type DashboardSourcesListRequest, type DashboardStepLogsRequest, type DashboardAttestationsListRequest, type DashboardOrchLogsRequest, type RunRerunRequest, type ManualScheduleRequest, type RunCancelRequest, type DashboardPayloadRequest, type DashboardPlatformToOrchMessage, type TestRelayRequest, type DashboardDiagnosticsRequest, type DashboardScalerCapacityRequest, type DashboardScalerAgentsRequest, type JoinRequest, type JoinResponse, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
 import { RelayBufferRegistry, type RelayStartMeta } from '../webhook/relay-buffer.js';
 /**
  * Verification + processing outcome returned by the chunked relay path's
@@ -87,6 +87,17 @@ export interface PlatformClientOptions {
     }) => void;
     /** Optional callback invoked after successful authentication and source registration. */
     onAuthenticated?: () => 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.
+     */
+    onOrgIdentified?: (info: {
+        orgId: string;
+        clusterId: string | null;
+    }) => void;
     /** Optional callback for dashboard run detail requests from Platform. */
     onDashboardRunDetail?: (msg: DashboardRunDetailRequest) => void;
     /** Optional callback for dashboard runs.list (operator console) requests from Platform. */
@@ -97,6 +108,8 @@ export interface PlatformClientOptions {
     onDashboardSourcesList?: (msg: DashboardSourcesListRequest) => void;
     /** Optional callback for dashboard step logs requests from Platform. */
     onDashboardStepLogs?: (msg: DashboardStepLogsRequest) => void;
+    /** Optional callback for dashboard attestations-list requests from Platform. */
+    onDashboardAttestationsList?: (msg: DashboardAttestationsListRequest) => void;
     /** Optional callback for run re-run requests from Platform (dashboard action). */
     onRunRerun?: (msg: RunRerunRequest) => void;
     /** Optional callback for manual schedule trigger requests from Platform (dashboard action). */
@@ -109,6 +122,12 @@ export interface PlatformClientOptions {
     onDashboardOrchLogs?: (msg: DashboardOrchLogsRequest) => void;
     /** Optional callback for dashboard environment/held-run messages from Platform. */
     onDashboardEnvMessage?: (msg: DashboardPlatformToOrchMessage) => void;
+    /**
+     * 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`.
+     */
+    onTestRelay?: (msg: TestRelayRequest) => void;
     /** Optional callback for dashboard diagnostics requests from Platform. */
     onDashboardDiagnostics?: (msg: DashboardDiagnosticsRequest) => void;
     /** Optional callback for dashboard scaler capacity requests from Platform. */
@@ -180,17 +199,20 @@ export declare class PlatformClient {
     private readonly onLogPullRequest?;
     private readonly onPeerDiscover?;
     private readonly onAuthenticated?;
+    private readonly onOrgIdentified?;
     private readonly onDashboardRunDetail?;
     private readonly onDashboardRunsList?;
     private readonly onDashboardRunsFilters?;
     private readonly onDashboardSourcesList?;
     private readonly onDashboardStepLogs?;
+    private readonly onDashboardAttestationsList?;
     private readonly onRunRerun?;
     private readonly onManualSchedule?;
     private readonly onRunCancel?;
     private readonly onDashboardPayload?;
     private readonly onDashboardOrchLogs?;
     private readonly onDashboardEnvMessage?;
+    private readonly onTestRelay?;
     private readonly onDashboardDiagnostics?;
     private readonly onDashboardScalerCapacity?;
     private readonly onDashboardScalerAgents?;
@@ -306,6 +328,13 @@ export declare class PlatformClient {
      * back to a structured warning if neither schema matches.
      */
     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).
+     */
+    private respondToInvalidDashboardRequest;
     /**
      * Dispatch a parsed platform message to the appropriate per-area
      * handler. Each `case` either inlines a tiny dispatch (for one-line

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

@@ -0,0 +1,112 @@
+/**
+ * Orchestrator-side handlers for the Platform-relayed `kici run remote` control
+ * plane. The Platform relays five `test.relay.*` requests over the authenticated
+ * dashboard-proxy WS connection; each handler here performs the action by
+ * reusing the existing test pipeline / upload / cancel internals (no
+ * duplication) and returns the response payload the caller sends back keyed by
+ * `requestId`.
+ *
+ * The control plane carries only small JSON. The overlay tarball never reaches
+ * the Platform — `handleTestUploadsInit` returns an external presigned URL the
+ * developer PUTs to directly.
+ */
+import type { Kysely } from 'kysely';
+import type { TestRelayRequest, TestRelayUploadsInitRequest, TestRelayTriggerRequest, TestRelayRunStatusRequest, TestRelayRunLogsRequest, TestRelayCancelRequest } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+import type { CacheStorage } from '../storage/types.js';
+import type { LogStorage } from '../reporting/log-storage.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+import { type TestPipelineDeps } from '../pipeline/test-pipeline.js';
+/** Dependencies shared by all five test-relay handlers. */
+export interface TestRelayHandlerDeps extends TestPipelineDeps {
+    db: Kysely<Database>;
+    cacheStorage?: CacheStorage;
+    logStorage?: LogStorage;
+    accessLog?: AccessLogWriter;
+    /** Canonical org id this orchestrator is bound to (for access_log attribution). */
+    orgId?: string | null;
+    /** Routing key resolved for this orchestrator's bound org (for access_log attribution). */
+    routingKey?: string | null;
+}
+/** Response payload for `test.relay.uploads.init.response` (minus envelope fields). */
+export interface TestUploadsInitPayload {
+    uploadId: string;
+    signedUrl: string;
+    publicKey: string;
+    expiresIn: number;
+}
+/**
+ * Mint an upload record + external presigned PUT URL. The developer's PAT
+ * identity (`msg.actor`) is recorded as the upload owner so the upload is
+ * attributable.
+ */
+export declare function handleTestUploadsInit(msg: TestRelayUploadsInitRequest, deps: TestRelayHandlerDeps): Promise<TestUploadsInitPayload>;
+/** Response payload for `test.relay.trigger.response` (minus envelope fields). */
+export interface TestTriggerPayload {
+    runId: string;
+    status: 'accepted' | 'rejected';
+    reason?: string;
+    jobIds: string[];
+}
+/**
+ * Resolve the overlay tarball URL + decryption keys from the upload record, then
+ * run the existing `processTestTrigger` pipeline with `routingKey = remote:<orgId>`.
+ * The developer's PAT identity is written to `access_log` (`run.trigger`).
+ */
+export declare function handleTestTrigger(msg: TestRelayTriggerRequest, deps: TestRelayHandlerDeps): Promise<TestTriggerPayload>;
+/** Response payload for `test.relay.run.status.response` (minus envelope fields). */
+export interface TestRunStatusPayload {
+    runId: string;
+    status: string;
+    jobs: Array<{
+        jobId: string;
+        jobName: string;
+        status: string;
+        errorMessage?: string | null;
+    }>;
+    done: boolean;
+}
+/** Snapshot a run's status + per-job status. `done` is true at a terminal run state. */
+export declare function handleTestRunStatus(msg: TestRelayRunStatusRequest, deps: TestRelayHandlerDeps): Promise<TestRunStatusPayload | {
+    error: string;
+}>;
+/** Response payload for `test.relay.run.logs.response` (minus envelope fields). */
+export interface TestRunLogsPayload {
+    lines: string[];
+    nextCursor: number;
+    done: boolean;
+}
+/**
+ * Return the next chunk of a run's logs from a monotonic line-offset cursor
+ * (spec §13a). The orchestrator concatenates every log line in a deterministic
+ * `(jobName ASC, stepIndex ASC, lineIndex ASC)` order; `cursor` is the count of
+ * lines already delivered. `done` is true only when the run is terminal AND the
+ * cursor has reached the end (the final tail-draining poll). A poll mid-step
+ * returns the lines available so far with `done: false`, so no line is ever
+ * dropped or skipped on a live run.
+ */
+export declare function handleTestRunLogs(msg: TestRelayRunLogsRequest, deps: TestRelayHandlerDeps): Promise<TestRunLogsPayload | {
+    error: string;
+}>;
+/** Response payload for `test.relay.cancel.response` (minus envelope fields). */
+export interface TestCancelPayload {
+    cancelled: boolean;
+}
+/**
+ * Cancel a running test run: signal cancellation to every dispatched agent,
+ * mark still-pending dispatch queue entries cancelled, and mark the
+ * `execution_runs` row cancelled. Returns `{ cancelled }` — true when the run
+ * existed, was a test run, and was not already terminal.
+ */
+export declare function handleTestCancel(msg: TestRelayCancelRequest, deps: TestRelayHandlerDeps): Promise<TestCancelPayload | {
+    error: string;
+}>;
+/**
+ * Route a parsed `test.relay.*` request to its handler and build the full
+ * response envelope (`type` + `requestId` + payload) the caller relays back over
+ * the WS connection via `sendRaw`. Errors and `{ error }` results are surfaced
+ * on the response's `error` field; the wire stays a structured response so the
+ * Platform can map it to an HTTP status.
+ */
+export declare function dispatchTestRelay(msg: TestRelayRequest, deps: TestRelayHandlerDeps): Promise<Record<string, unknown>>;
+//# sourceMappingURL=test-relay-handlers.d.ts.map