@kici-dev/orchestrator 0.6.0 → 0.7.0

package/dist/storage/loopback-guard.d.ts

@@ -9,14 +9,33 @@ import { ScalerBackendType } from '@kici-dev/engine';
 import type { AppConfig } from '../config.js';
 import type { ScalerConfig } from '../scaler/types.js';
 /**
- * Every current scaler backend places the agent outside the orchestrator's
- * loopback (separate netns, microVM, or host). Only a future co-located/"local"
- * backend would be absent from this set. `kubernetes` is included defensively
- * even though `ScalerEntry.type` excludes it today.
+ * Backends that place the agent outside the orchestrator's loopback (separate
+ * netns, microVM, or host) whenever the entry does not say otherwise.
+ * `kubernetes` is included defensively even though `ScalerEntry.type` excludes
+ * it today.
+ *
+ * Backend type alone is an imprecise signal — a `bare-metal` scaler may spawn
+ * on this very machine or on a rack of remote hosts — so it is only the
+ * fallback. When an entry declares its own `orchestratorUrl`, that URL says
+ * where the agent will be, and `scalerIsColocated` reads it instead.
  */
 export declare const NON_COLOCATED_BACKENDS: ReadonlySet<ScalerBackendType>;
-/** True for any host an agent in another netns/VM/host cannot reach. */
+/**
+ * Answers "could an agent in another netns/VM/host reach this address?" — the
+ * question a DESTINATION URL asks. A wildcard (`0.0.0.0`, `::`) is not a
+ * destination at all, so it is reported as loopback here.
+ *
+ * For a listener's bind address the question is the opposite one; use
+ * `isLoopbackBind`.
+ */
 export declare function isLoopbackHost(hostname: string): boolean;
+/**
+ * Answers "does a listener on this address stay on this machine?" — the
+ * question a BIND address asks. A wildcard (`0.0.0.0`, `::`) accepts every
+ * interface, so it is NOT loopback here, which is the one case where this
+ * predicate and `isLoopbackHost` disagree.
+ */
+export declare function isLoopbackBind(hostname: string): boolean;
 /**
  * Decide whether an agent-facing storage URL is a loopback address that a
  * non-co-located agent could not reach. Returns a remediation message, or null
@@ -26,7 +45,10 @@ export declare function checkLoopbackAgentEndpoint(input: {
     agentFacingUrl: string | null;
     endpointSource: string;
     fixEnvVar: string;
-    scalerBackends: ScalerBackendType[];
+    scalers: {
+        type: ScalerBackendType;
+        orchestratorUrl?: string;
+    }[];
 }): {
     message: string;
 } | null;
@@ -46,4 +68,29 @@ export declare function resolveAgentFacingStorage(config: AppConfig): {
  * remediation (so it reaches `kici-admin orchestrator logs`) then throws.
  */
 export declare function assertAgentReachableStorage(config: AppConfig, scalerConfig: ScalerConfig | null): void;
+/**
+ * Refuse to start when agent authentication is disabled and the listener is
+ * bound to something other than a loopback address.
+ *
+ * `KICI_AGENT_AUTH=none` answers `auth.success` to any `auth.request`
+ * (`ws/agent-handler.ts`), so a listener on a routable address hands anyone who
+ * can reach the port a registered agent: it receives dispatched jobs — with the
+ * org's resolved secrets in hybrid mode — and streams results back as the
+ * operator's own agent. No credential is involved anywhere in that sequence.
+ *
+ * `none` is a local-development affordance, and any bind other hosts can reach
+ * is never an intended pairing with it. The one-shot startup warning that used
+ * to be the only signal was demonstrably not enough — the local dev plane
+ * shipped in exactly this state — so this refuses, following the sibling guard
+ * above: an orchestrator misconfiguration that produces a confusing failure
+ * later must refuse to start with an actionable message.
+ *
+ * The bind question is `isLoopbackBind`, not `isLoopbackHost`. The default
+ * `KICI_HOST` is the wildcard `0.0.0.0`, which `isLoopbackHost` reports as
+ * loopback because a wildcard is not a reachable destination — true of a
+ * storage URL, and the opposite of what a listener on it does. So the guard
+ * covers the default bind, which is the configuration an operator reaches
+ * without setting `KICI_HOST` at all.
+ */
+export declare function assertAgentAuthBindSafe(config: AppConfig): void;
 //# sourceMappingURL=loopback-guard.d.ts.map

package/dist/webhook/event-log.d.ts

@@ -53,6 +53,19 @@ export interface PayloadBytes {
     /** UTF-8 encoded raw body bytes (what Platform hashed). */
     raw: Buffer;
 }
+/** Per-call write mode for {@link EventLogWriter.record}. */
+export interface RecordOptions {
+    /**
+     * Insert only when `(org_id, delivery_id)` has no row yet, leaving an
+     * existing row untouched instead of updating its outcome fields.
+     *
+     * Used by breadcrumb writers that record a delivery was SEEN rather than how
+     * it ended — a shed under load, say. Those run before the pipeline, so with
+     * the default upsert a re-shed of an already-processed delivery would
+     * downgrade a terminal `processed` row back to `shed`.
+     */
+    onlyIfAbsent?: boolean;
+}
 /**
  * Build a `PayloadBytes` from the parsed webhook payload object. Uses
  * `JSON.stringify` with no formatting — same shape Platform uses to compute
@@ -89,6 +102,6 @@ export declare class EventLogWriter {
      * payload_key / hash / size fields are NOT overwritten on update — those
      * come from the original delivery's body.
      */
-    record(info: WebhookInfo, payload: PayloadBytes, outcome: EventLogOutcome): Promise<void>;
+    record(info: WebhookInfo, payload: PayloadBytes, outcome: EventLogOutcome, opts?: RecordOptions): Promise<void>;
 }
 //# sourceMappingURL=event-log.d.ts.map

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

@@ -72,7 +72,7 @@ export interface GenericSourcesChangeListenerOptions {
 }
 export declare class GenericSourcesChangeListener {
     private readonly opts;
-    private client;
+    private listener;
     private readonly pending;
     private debounceTimer;
     private readonly debounceMs;

package/dist/webhook/ingest-admission.d.ts

@@ -101,6 +101,30 @@ export declare class IngestAdmissionController {
     private incKey;
     private decKey;
     isShedding(): boolean;
+    /**
+     * Take an admission slot on behalf of the durable-overflow replayer, BEFORE
+     * it claims a row. The replayer holds the grant across the whole re-injection
+     * and releases it afterwards, so a capacity refusal leaves the buffered row
+     * untouched instead of costing it a replay attempt.
+     *
+     * This is NOT an exempt lane. It evaluates the same layer-1 loop-lag gate and
+     * the same layer-2 global + per-key caps {@link admit} does, in the same
+     * order, through the same {@link canAdmit} predicate — so a reservation can
+     * always be refused, and a granted one occupies a slot indistinguishable from
+     * a sender's. The two differences are deliberate and both narrow the grant
+     * rather than widening it:
+     *
+     * - It never queues (there is no caller waiting on an ack; the next pass
+     *   retries in `intervalMs`), so it cannot occupy a CoDel queue slot a real
+     *   sender needs.
+     * - A refusal does not fire the shed seam or the shed metric.
+     *   `kici_orch_ingest_shed_total` means "a sender was refused"; a background
+     *   drain deciding not to start is not that, and counting it there would make
+     *   the shed rate unreadable during exactly the overload it measures. The
+     *   replayer counts its own refusals on
+     *   `kici_orch_ingest_overflow_replay_refused_total` instead.
+     */
+    reserve(key: string, orgCap: number): AdmitResult;
     snapshot(): IngestAdmissionSnapshot;
     private emit;
     /**

package/dist/webhook/ingest-overflow-replayer.d.ts

@@ -3,15 +3,50 @@ import type { Database } from '../db/types.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import { WebhookIngestOutcome } from '../pipeline/process-webhook.js';
 import { type OverflowDelivery } from './ingest-overflow-types.js';
+import type { AdmitResult } from './ingest-admission.js';
+/**
+ * Re-inject one buffered delivery through the ingest pipeline.
+ *
+ * The caller (this replayer) already holds the admission grant, so an
+ * implementation MUST NOT admit again — that second admission is what used to
+ * charge a per-org capacity refusal against the delivery's failure budget.
+ */
 export type ReinjectFn = (d: OverflowDelivery) => Promise<WebhookIngestOutcome>;
+/**
+ * The admission-controller surface the replayer needs: the pass-level
+ * short-circuit and the per-row reservation.
+ */
+export interface ReplayAdmissionController {
+    isShedding(): boolean;
+    reserve(key: string, orgCap: number): AdmitResult;
+}
+/** Resolve a routing key to its fairness key + per-org concurrency cap. */
+export type ResolveAdmissionKeyFn = (routingKey: string) => Promise<{
+    key: string;
+    orgCap: number;
+}>;
 export interface IngestOverflowReplayerDeps {
     db: Kysely<Database>;
-    controller: {
-        isShedding(): boolean;
-    };
+    controller: ReplayAdmissionController;
+    /**
+     * Resolve a buffered row's routing key to the same fairness key + per-org cap
+     * the live ingest paths admit on, so a reservation competes on exactly the
+     * terms a fresh delivery would.
+     */
+    resolveAdmissionKey: ResolveAdmissionKeyFn;
     intervalMs: number;
     batchSize: number;
     maxAttempts: number;
+    /**
+     * Wall-clock retention bound. A row that has sat `buffered` this long without
+     * ever winning a capacity grant is marked `failed` (`max_age`) rather than
+     * held forever. This is what keeps the buffer bounded now that a capacity
+     * refusal no longer consumes an attempt: without it, a permanently saturated
+     * org's rows would fill `ingestOverflowMax` and capture would start dropping
+     * FRESH deliveries instead — trading a bounded per-delivery loss for an
+     * unbounded new-delivery one.
+     */
+    maxAgeMs: number;
     /**
      * How long a `replaying` claim may stand before it is reclaimed. Resolved per
      * pass so a fleet-wide `cluster_settings` override takes effect without a
@@ -20,30 +55,45 @@ export interface IngestOverflowReplayerDeps {
     claimTimeoutMs: number;
     /** Fleet-wide override reader for {@link IngestOverflowReplayerDeps.claimTimeoutMs}. */
     clusterSettings?: ClusterSettingsReader;
+    /** Injectable clock (default `Date.now`); the retention bound reads it. */
+    now?: () => number;
 }
 /**
  * Background drain for the durable ingest queue. Each pass first reclaims rows
  * whose `replaying` claim went stale — a worker killed mid-pipeline releases
  * nothing, so without this its delivery would sit claimed forever and the
- * durable row it acknowledged would never be worth anything. It then claims the
- * oldest `buffered` rows FIFO up to a bounded batch and re-injects each through
- * the admission-gated ingest path. A re-shed or error reverts the row to
- * `buffered` (never lost); past the max-attempts ceiling it goes `failed`.
- * Successful rows are swept.
+ * durable row it acknowledged would never be worth anything. It then expires
+ * rows past the wall-clock retention bound, and finally drains the oldest
+ * `buffered` rows FIFO up to a bounded batch.
+ *
+ * **Reserve, then claim.** The drain takes an admission slot from the same
+ * controller the live ingest paths use BEFORE it claims a row, and holds that
+ * grant across the whole re-injection. A refusal therefore leaves the row
+ * untouched in `buffered` with its attempt counter unmoved — the delivery never
+ * entered the pipeline, so there was no delivery failure to charge. Ordering it
+ * the other way round is what used to spend a per-delivery failure budget on a
+ * transient per-org capacity refusal, killing a whole FIFO cohort in seconds.
+ *
+ * `replay_attempts` therefore counts genuine failures only: a verify throw, a
+ * pipeline throw, a stale claim. Retention is bounded by `maxAgeMs` instead.
  *
- * Re-injection runs only while the admission controller is NOT shedding
- * (replaying into a still-overloaded orchestrator just re-sheds). Reclaiming is
- * not gated that way: a stranded claim is stranded regardless of load, and the
- * row it frees simply waits in `buffered` until capacity returns.
+ * Refusal is per fairness key: a saturated org's rows are skipped for the rest
+ * of the pass while other orgs' rows keep draining, mirroring the fair skip the
+ * controller's own queue does. Reclaiming is not gated on load at all: a
+ * stranded claim is stranded regardless, and the row it frees simply waits in
+ * `buffered` until a reservation succeeds.
  */
 export declare class IngestOverflowReplayer {
     private readonly db;
     private readonly controller;
+    private readonly resolveAdmissionKey;
     private readonly intervalMs;
     private readonly batchSize;
     private readonly maxAttempts;
+    private readonly maxAgeMs;
     private readonly claimTimeoutMs;
     private readonly clusterSettings;
+    private readonly now;
     private reinjectDirect;
     private reinjectRelay;
     private timer;
@@ -76,8 +126,22 @@ export declare class IngestOverflowReplayer {
      * take through {@link claimBatch} and must release it the same way on failure.
      */
     releaseClaim(id: number, reason: string): Promise<boolean>;
-    /** Select the oldest buffered rows and claim each via a conditional update. */
-    private claimBatch;
+    /**
+     * Mark every `buffered` row past the retention bound `failed`. Only
+     * `buffered` rows are eligible, so a row a worker is actively holding is
+     * never expired out from under it — the stale-claim reclaim above hands that
+     * row back to `buffered` first, and the next pass expires it there. That is
+     * why the two bounds compose rather than race even when `maxAgeMs` equals
+     * `claimTimeoutMs`.
+     */
+    private expireAgedRows;
+    /**
+     * Reserve-then-claim drain. For each candidate, oldest first: resolve its
+     * fairness key, take an admission slot, and only then claim the row. A
+     * refusal skips that key for the rest of the pass and leaves the row exactly
+     * as it was — `buffered`, same attempt count, no `last_error`.
+     */
+    private drain;
     private toDelivery;
     private replayOne;
     /**

package/dist/webhook/ingest-overflow-types.d.ts

@@ -32,9 +32,21 @@ export declare const OverflowSourceKind: z.ZodEnum<{
     relay: "relay";
 }>;
 export type OverflowSourceKind = z.infer<typeof OverflowSourceKind>;
-/** Reasons a delivery is permanently dropped from the overflow buffer. */
+/**
+ * Reasons a delivery is permanently dropped from the overflow buffer.
+ *
+ * - `cap_full`     — the buffer was at `ingestOverflowMax` when capture ran.
+ * - `max_attempts` — replay failed `ingestOverflowMaxAttempts` times. Only a
+ *   genuine failure counts (a verify throw, a pipeline throw, a stale claim);
+ *   a capacity refusal never reaches a claim, so it cannot consume an attempt.
+ * - `max_age`      — the row sat in `buffered` past `ingestOverflowMaxAgeMs`.
+ *   This is the retention bound: without an attempt ceiling on the capacity
+ *   path, age is the only thing that stops a permanently-saturated org's rows
+ *   from filling the cap and dropping fresh captures instead.
+ */
 export declare const OverflowDropReason: z.ZodEnum<{
     cap_full: "cap_full";
+    max_age: "max_age";
     max_attempts: "max_attempts";
 }>;
 export type OverflowDropReason = z.infer<typeof OverflowDropReason>;

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

@@ -67,4 +67,27 @@ export interface RegisterSourceBundleDeps {
  * second call with the same routing key replaces the prior bundle.
  */
 export declare function registerProviderBundleForSource(row: GenericWebhookSource, deps: RegisterSourceBundleDeps): void;
+/** What {@link registerAllGenericSourceBundles} needs beyond the per-row deps. */
+export interface RegisterAllGenericSourceBundlesDeps extends RegisterSourceBundleDeps {
+    sourceManager: {
+        listLocalSources(): Promise<GenericWebhookSource[]>;
+        listUniversalGitSources(): Promise<GenericWebhookSource[]>;
+    };
+}
+/**
+ * Register a provider bundle for every generic source currently in the
+ * database.
+ *
+ * Two call sites share this: cold boot, and a `generic_sources_change`
+ * listener that has just reconnected. A reconnect missed an unknown number of
+ * NOTIFYs and Postgres keeps no durable log of them, so re-deriving the whole
+ * set from the database is the only correct catch-up — and it is exactly what
+ * boot already does.
+ *
+ * `ProviderRegistry.registerByRoutingKey` replaces a bundle at the same key,
+ * so re-running this is idempotent. Each list is fetched inside its own
+ * try/catch: one failing query must not cost the other its registrations.
+ * Per-row failures are handled inside `registerProviderBundleForSource`.
+ */
+export declare function registerAllGenericSourceBundles(deps: RegisterAllGenericSourceBundlesDeps): Promise<void>;
 //# sourceMappingURL=register-source-bundle.d.ts.map

package/dist/webhook/relay-reinject.d.ts

@@ -1,4 +1,3 @@
-import type { AdmitResult } from './ingest-admission.js';
 import type { WebhookInfo } from './handler.js';
 import { WebhookIngestOutcome } from '../pipeline/process-webhook.js';
 import type { OverflowDelivery } from './ingest-overflow-types.js';
@@ -13,12 +12,6 @@ export interface RelayVerifyResult {
  * store / provider registry. server.ts wires these to the real subsystems.
  */
 export interface RelayReinjectSeams {
-    /**
-     * Re-admit on the routing key (allowQueue:false — same non-queueing gate the
-     * live relay path uses). A re-shed maps the reinject to `shed` so the replayer
-     * reverts the row to `buffered`.
-     */
-    admit: (routingKey: string) => Promise<AdmitResult>;
     /** Re-verify the raw body against the stored headers. */
     verify: (d: OverflowDelivery, body: Buffer) => Promise<RelayVerifyResult>;
     /** Resolve the provider string for a routing key (bundle → prefix fallback). */
@@ -33,11 +26,17 @@ export interface RelayReinjectSeams {
  */
 export declare function parseRelayPayload(body: Buffer, headers: Record<string, string>): Record<string, unknown>;
 /**
- * Build the relay-origin overflow re-injector. Re-admits on the routing key,
- * re-verifies the stored raw body (relay deliveries are captured pre-verify),
- * normalizes it, and processes it through the admission-gated relay pipeline.
- * A re-shed maps to `shed` (revert); a verify miss maps to `skipped` (terminal
- * — the delivery is no longer routable, so it is not retried forever).
+ * Build the relay-origin overflow re-injector. Re-verifies the stored raw body
+ * (relay deliveries are captured pre-verify), normalizes it, and processes it
+ * through the relay pipeline. A verify miss maps to `skipped` (terminal — the
+ * delivery is no longer routable, so it is not retried forever).
+ *
+ * It does NOT admit. The replayer reserves an admission slot before it claims
+ * the row and holds that grant for the whole call, so admitting again here
+ * would be a second, redundant gate — and a refusal from it would be charged to
+ * the delivery as a failed replay attempt, which is the defect this ordering
+ * exists to remove. The slot is genuinely held: nothing here bypasses the
+ * controller, the decision was simply made one step earlier.
  */
 export declare function buildRelayReinject(seams: RelayReinjectSeams): ReinjectFn;
 //# sourceMappingURL=relay-reinject.d.ts.map

package/dist/webhook/shed-breadcrumb.d.ts

@@ -0,0 +1,15 @@
+import type { EventLogWriter } from './event-log.js';
+import type { RelayStartMeta } from './relay-buffer.js';
+export interface ShedBreadcrumbDeps {
+    /** Writer for the orchestrator `event_log`. Absent in wirings with no log. */
+    eventLog: EventLogWriter | undefined;
+    /** Routing key → owning org id. Must not throw; returns the resolved tenant. */
+    resolveOrgId: (routingKey: string) => Promise<string>;
+}
+/**
+ * Record that a relay delivery was shed. Best-effort and never throws: a
+ * breadcrumb failure must not change the `shed_retry_later` ack the sender
+ * gets. Returns whether a write was attempted and completed.
+ */
+export declare function recordShedBreadcrumb(deps: ShedBreadcrumbDeps, meta: RelayStartMeta, body: Buffer, reason: string): Promise<boolean>;
+//# sourceMappingURL=shed-breadcrumb.d.ts.map

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

@@ -4,26 +4,55 @@
  * 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.
+ * Authorization is five layers, every one of them resolved from server truth
+ * rather than from the request:
  *
- * 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.
+ *   1. job ownership — an agent may only request credentials for a job it was
+ *      dispatched, resolved through the dispatcher;
+ *   2. 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 (the forge 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;
+ *   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;
+ *   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
+ * agent claimed.
  */
+import type { TrustTier } from '@kici-dev/engine';
 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;
+    /**
+     * 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.
+     */
+    declaredCredentials: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** The run's resolved contributor trust tier, or undefined when unresolved. */
+    trustTier: TrustTier | undefined;
+    /** The branch the run presents, for the named context's branch restrictions. */
+    branch: string;
+    /** The event type that started the run, for a context's trigger-type filters. */
+    triggerType: string;
 }
 export interface GitCredentialHandlerDeps {
     broker: GitCredentialBroker;

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

@@ -1,4 +1,4 @@
-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 StateReplayRun, type OrchestratorToPlatformMessage, type WebhookRelay, type WebhookRelayResult, type TrustPolicyUpdate, type StaleCheckrunCleanup, type DashboardRunDetailRequest, type DashboardRunStructuredRequest, type DashboardRunStateRequest, type DashboardRunsListRequest, type DashboardRunsFiltersRequest, type DashboardSourcesListRequest, type DashboardAdminTokensListRequest, type DashboardStepLogsRequest, type DashboardAttestationsListRequest, type DashboardAttestationsListAllRequest, type DashboardAttestationGetRequest, type DashboardAttestationRetryRequest, type DashboardArtifactsListRequest, type DashboardOrchLogsRequest, type RunRerunRequest, type ManualScheduleRequest, type RunCancelRequest, type DashboardPayloadRequest, type DashboardPlatformToOrchMessage, type TestRelayRequest, type DashboardDiagnosticsRequest, type DashboardScalerCapacityRequest, type DashboardScalerAgentsRequest, type DashboardFleetHostsRequest, type DashboardFleetHostRequest, type DashboardFleetPreviewRequest, type DashboardFleetWorkflowsForHostRequest, type JoinRequest, type JoinResponse, type DeploymentIdentity, type ConfigPaths, type OrchCapabilities, type OrchRole } from '@kici-dev/engine';
 import type { PlanHeadroomStore } from '../cluster/plan-headroom-store.js';
 import { RelayBufferRegistry, type RelayStartMeta } from '../webhook/relay-buffer.js';
 import type { AdmitResult } from '../webhook/ingest-admission.js';
@@ -86,6 +86,8 @@ export interface PlatformClientOptions {
     scalerBackends?: string[];
     /** How the orchestrator process was deployed. Sent in source.register so the dashboard can build 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. */
+    configPaths?: ConfigPaths;
     /** Whether this orchestrator has 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. */
@@ -165,6 +167,8 @@ export interface PlatformClientOptions {
     onDashboardRunsFilters?: (msg: DashboardRunsFiltersRequest) => void;
     /** Optional callback for dashboard sources.list (operator console) requests from Platform. */
     onDashboardSourcesList?: (msg: DashboardSourcesListRequest) => void;
+    /** Optional callback for dashboard admin-tokens.list (RBAC drift report) requests from Platform. */
+    onDashboardAdminTokensList?: (msg: DashboardAdminTokensListRequest) => void;
     /** Optional callback for dashboard step logs requests from Platform. */
     onDashboardStepLogs?: (msg: DashboardStepLogsRequest) => void;
     /** Optional callback for dashboard attestations-list requests from Platform. */
@@ -247,11 +251,13 @@ export interface PlatformClientOptions {
      */
     onAdmit?: (routingKey: string) => Promise<AdmitResult>;
     /**
-     * Optional durable-overflow capture seam. Invoked with the pre-verify relay
-     * meta + assembled body on a shed, before the shed_retry_later ack. Best-effort
-     * — the client wraps it so a capture failure never blocks the ack.
+     * Optional shed-recording seam. Invoked with the pre-verify relay meta +
+     * assembled body + the admission controller's shed reason, before the
+     * shed_retry_later ack. The wiring records the delivery durably — an
+     * `event_log` breadcrumb, and the overflow-buffer row when that queue is
+     * enabled. Best-effort — the client wraps it so a failure never blocks the ack.
      */
-    onShedCapture?: (meta: RelayStartMeta, body: Buffer) => Promise<void>;
+    onShedCapture?: (meta: RelayStartMeta, body: Buffer, reason: string) => Promise<void>;
 }
 /** Error `*.response` frame shape for a dashboard request that failed validation. */
 export interface DashboardRequestErrorFrame {
@@ -333,6 +339,7 @@ export declare class PlatformClient {
     private readonly mode?;
     private readonly scalerBackends?;
     private readonly deployment?;
+    private readonly configPaths?;
     private readonly s3LogAccess?;
     private readonly queueTimeoutMs?;
     private readonly heartbeatIntervalMs;
@@ -351,6 +358,7 @@ export declare class PlatformClient {
     private readonly onDashboardRunsList?;
     private readonly onDashboardRunsFilters?;
     private readonly onDashboardSourcesList?;
+    private readonly onDashboardAdminTokensList?;
     private readonly onDashboardStepLogs?;
     private readonly onDashboardAttestationsList?;
     private readonly onDashboardAttestationsListAll?;
@@ -387,12 +395,27 @@ export declare class PlatformClient {
      * predates the alias plumbing, or before the first successful auth.
      */
     private _orgPublicAlias?;
+    /** Canonical Platform org id from `auth.success`; see {@link getOrgId}. */
+    private _orgId?;
     /**
      * Returns the cached public alias of the orchestrator's owning org,
      * or `undefined` if Platform has not supplied one yet. Read by
      * `check-run-reporter.ts` when building `details_url`.
      */
     getOrgPublicAlias(): string | undefined;
+    /**
+     * The canonical Platform organization id this orchestrator authenticated
+     * as, from `auth.success`. `undefined` before the first successful auth, or
+     * against a Platform that does not supply it.
+     *
+     * A generic source's routing key embeds the organization
+     * (`generic:<orgId>:<id>`), and the Platform now refuses to register a key
+     * naming a different one. So the source-create path reads this to refuse a
+     * mismatched `--org` up front, naming the correct value, instead of letting
+     * the operator create a source that registers, is rejected, and never
+     * delivers.
+     */
+    getOrgId(): string | undefined;
     constructor(options: PlatformClientOptions);
     /**
      * Merge `updates` into the stored orch capabilities and broadcast the

package/installer-image-digests.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.6.0",
+  "version": "0.7.0",
   "images": {
-    "kici-agent": "sha256:6a6dad749ae8a520774139588b6b83d194dcddc5fec58ed46207e0654eb9bc27",
-    "kici-orchestrator": "sha256:86cc2e5c316492bffce415ac55989681491de25085258f411928ed19ad7a36fb"
+    "kici-agent": "sha256:ad6028feb1eda81eb8c1b53490fad8530a0b9137650d436250a8cfd2ec699eed",
+    "kici-orchestrator": "sha256:f2706520bf3b8b196e2613deb8d0530ce4b50cc376261304b6eecee7f433385f"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/orchestrator",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -89,8 +89,8 @@
     "ws": "^8.21.3",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@kici-dev/shared": "0.6.0",
-    "@kici-dev/engine": "0.6.0"
+    "@kici-dev/shared": "0.7.0",
+    "@kici-dev/engine": "0.7.0"
   },
   "kici": {
     "metrics": {
@@ -105,7 +105,7 @@
     "@types/dockerode": "^4.0.1",
     "@types/ws": "^8.18.1",
     "kysely-ctl": "^0.21.0",
-    "@kici-dev/agent": "0.6.0"
+    "@kici-dev/agent": "0.7.0"
   },
   "scripts": {
     "build": "node ../../scripts/build-service.mjs && tsgo --emitDeclarationOnly",