@kici-dev/orchestrator 0.1.26 → 0.2.0

package/dist/cluster/cluster-settings-reader.d.ts

@@ -0,0 +1,78 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/** Numeric columns on cluster_settings readable via {@link ClusterSettingsReader}. */
+export type ClusterNumberColumn = 'max_github_payload_bytes' | 'event_log_max_payload_bytes' | 'lock_file_max_bytes' | 'webhook_dedup_ttl_ms' | 'contributor_cache_ttl_ms' | 'event_router_event_ttl_seconds' | 'event_router_max_dispatch_attempts' | 'queue_max_depth' | 'reroute_flap_grace_ms' | 'max_fanout_hosts' | 'event_router_rate_limit_per_workflow_per_minute' | 'cache_max_tarball_bytes' | 'cache_ttl_days' | 'check_run_tracking_ttl_days' | 'concurrency_wait_timeout_ms' | 'agent_token_ttl_ms' | 'ownership_db_check_timeout_ms';
+/** Text columns on cluster_settings readable via {@link ClusterSettingsReader}. */
+export type ClusterStringColumn = 'dashboard_verified_issuer';
+/**
+ * A knob read that keeps "the operator never set this" separate from "we could
+ * not read it".
+ *
+ * `{ ok: true, value: null }` is a genuine unset — a missing row, a null
+ * column, or a cleared (empty) string. `{ ok: false }` means the query failed,
+ * so the caller decides: most knobs want their cluster default, but one whose
+ * default is a weaker trust tier must hold its last known value instead.
+ */
+export type ClusterSettingRead<T> = {
+    ok: true;
+    value: T | null;
+} | {
+    ok: false;
+};
+/**
+ * Reads the single cluster_settings row (id='default') once per short TTL
+ * window and serves every fleet-wide knob from that snapshot. `getNumber` and
+ * `getString` degrade to the caller's `fallback` (the config.ts cluster
+ * default) on no-db / missing row / null column / DB error, so a hot-path read
+ * never blocks on a sick DB. {@link ClusterSettingsReader.tryGetString} is the
+ * one exception: it reports a failed query as `{ ok: false }` rather than a
+ * default, for the caller whose default would be a weaker trust tier.
+ *
+ * There is exactly one row, so a whole-row cache is strictly simpler than a
+ * per-column cache: one DB hit per TTL window serves every column and every
+ * read-site.
+ */
+export declare class ClusterSettingsReader {
+    private readonly db;
+    private readonly cacheTtlMs;
+    private cache;
+    constructor(db: Kysely<Database> | undefined, cacheTtlMs?: number);
+    /**
+     * The cached row plus whether it reflects a successful read.
+     *
+     * `readable` lives on the cache entry, not around the query, because the
+     * negative cache serves reads 2..N of a TTL window without touching the DB:
+     * deriving "unreadable" from the catch alone would report those reads as a
+     * genuine unset.
+     */
+    private loadSnapshot;
+    private loadRow;
+    /** Resolve a fleet-wide numeric knob; `fallback` is the config.ts cluster default. */
+    getNumber(column: ClusterNumberColumn, fallback: number): Promise<number>;
+    /**
+     * Resolve a fleet-wide text knob; `fallback` is the config.ts cluster default
+     * (which may itself be null). An empty stored string is treated as unset so an
+     * operator clearing the knob via the admin API behaves like a NULL.
+     */
+    getString(column: ClusterStringColumn, fallback: string | null): Promise<string | null>;
+    /**
+     * Resolve a fleet-wide text knob without collapsing a read failure into a
+     * default.
+     *
+     * There is deliberately no `fallback` parameter: the point of this variant is
+     * that the caller — not the reader — decides what an unreadable knob means.
+     * An empty stored string is unset, matching {@link getString}.
+     */
+    tryGetString(column: ClusterStringColumn): Promise<ClusterSettingRead<string>>;
+    /**
+     * The cluster_settings row version last seen in the cache (0 if never loaded).
+     *
+     * Synchronous — never awaits a DB read — so the heartbeat timer can read it
+     * safely and advertise it to workers. When the cache is cold or expired it
+     * kicks a non-blocking refresh so the advertised version self-heals within a
+     * cache-TTL window without depending on a `getNumber()` call, then returns
+     * the last-loaded value.
+     */
+    getCachedVersion(): number;
+}
+//# sourceMappingURL=cluster-settings-reader.d.ts.map

package/dist/cluster/coordinator.d.ts

@@ -93,6 +93,23 @@ export interface RunCoordinatorDeps {
     ackTimeoutMs?: number;
     /** Stale peer timeout in ms. Default: 60000 (60s). */
     staleTimeoutMs?: number;
+    /**
+     * Per-job reroute spawn window (ms): the post-ACK re-dispatch backstop
+     * window. Resolves the job's org override from
+     * `org_settings.reroute_spawn_window_ms`, else the cluster default. When
+     * absent, {@link DEFAULT_REROUTE_SPAWN_WINDOW_MS} is used.
+     */
+    getRerouteSpawnWindowMs?: (job: JobToRoute) => Promise<number>;
+    /**
+     * Per-job reroute ACK timeout (ms) for the `sendAndWaitAck` deadline. When
+     * absent, falls back to `ackTimeoutMs` / {@link DEFAULT_ACK_TIMEOUT_MS}.
+     */
+    getRerouteAckTimeoutMs?: (job: JobToRoute) => Promise<number>;
+    /**
+     * Per-job maximum peer hops for a rerouted job. When absent, falls back to
+     * {@link DEFAULT_MAX_HOPS}.
+     */
+    getRerouteMaxHops?: (job: JobToRoute) => Promise<number>;
 }
 export declare class RunCoordinator {
     private readonly instanceId;
@@ -104,9 +121,13 @@ export declare class RunCoordinator {
     private readonly sendAndWaitAckViaHandler?;
     private readonly sendToPeerViaHandler?;
     private readonly ackTimeoutMs;
+    private readonly getRerouteSpawnWindowMs;
+    private readonly getRerouteAckTimeoutMs;
+    private readonly getRerouteMaxHops;
     /**
      * Tracks which jobs have been rerouted to which peers, keyed by runId.
-     * Used for cancel propagation and progress tracking.
+     * Used for cancel propagation, progress tracking, and the post-ACK spawn
+     * re-dispatch backstop.
      */
     private readonly reroutedJobs;
     /**
@@ -142,7 +163,7 @@ export declare class RunCoordinator {
      * this split, every job-level event was silently funnelled into
      * `onStepStatus` and the run stayed in `running` forever.
      */
-    onPeerJobProgress(msg: JobProgress, reply?: (m: JobProgressAck) => void): void;
+    onPeerJobProgress(msg: JobProgress, fromPeerId: string, reply?: (m: JobProgressAck) => void): void;
     /**
      * Handle a scaler provisioning event forwarded by a worker peer.
      *
@@ -151,8 +172,25 @@ export declare class RunCoordinator {
      * coordinator's ExecutionTracker persists the event (provisioning log
      * line + dispatch-queue last-error column) just as it would for a
      * locally-emitted scaler event.
+     *
+     * Layer B fast path: a `scaler.failed` for a tracked rerouted job whose spawn
+     * window is still armed is the worker's NAK-after-accept — the peer accepted
+     * the reroute but its agent spawn failed asynchronously before reporting any
+     * progress. Re-dispatch immediately (the same routine the spawn-window timer
+     * runs) instead of waiting the window out. Idempotent with the Layer A timer:
+     * whichever fires first removes the tracking entry.
+     *
+     * Two guards make the re-dispatch safe. First, source provenance: the failure
+     * must come from `fromPeerId === tracked.peerId` (the authenticated connection
+     * identity), so a late `scaler.failed` relayed for the same jobId by a
+     * superseded peer after an earlier re-dispatch is ignored rather than bouncing
+     * the healthy replacement. Second, the armed-window check: once the first
+     * progress disarms the timer (`windowTimer` cleared to undefined), the job is
+     * executing and a stale failure must NOT cancel the running job. Persistence
+     * (`emitScalerEvent`) stays unconditional — it is keyed on `(runId, jobId)` and
+     * correct regardless of which peer relayed the event.
      */
-    onPeerScalerEvent(msg: PeerScalerEvent): void;
+    onPeerScalerEvent(msg: PeerScalerEvent, fromPeerId: string): void;
     /**
      * Handle peer job completion. Updates ExecutionTracker.
      * The execution tracker's onJobStatus fires the needs-aware scheduler hook,
@@ -189,11 +227,24 @@ export declare class RunCoordinator {
      */
     getBackoffUntil(peerId: string): number;
     /**
-     * Attempt to reroute a job to a peer with matching capacity.
-     * Tries peers in order of available capacity (most capacity first).
-     * Returns on first successful ACK.
+     * Attempt to reroute a job to a peer with matching capacity. Allocates the
+     * sender-side jobId (so the caller can register execution rows under the id
+     * the worker reports back against) and delegates to {@link attemptPeerRoute}.
      */
     private rerouteJob;
+    /**
+     * Try each peer with matching capacity (most capacity first) for a single
+     * job under a fixed `jobId`, returning on the first ACK. Reused by initial
+     * routing and by the post-ACK spawn re-dispatch backstop — the caller passes
+     * the accumulated `triedConnections` (this instance + any failed peers) so a
+     * re-dispatch never re-selects a peer that already failed and the receiving
+     * peer's loop-prevention stays correct.
+     */
+    private attemptPeerRoute;
+    /** Build the failure result when no peer has matching capacity (with debug log). */
+    private noCapacityResult;
+    /** Assemble the `job.reroute` wire message for a single routing attempt. */
+    private buildRerouteMessage;
     /**
      * Sort peers by available capacity for the given label sets.
      * Peers with more available capacity come first.
@@ -211,10 +262,31 @@ export declare class RunCoordinator {
      */
     private computeAvailableCapacity;
     /**
-     * Track a rerouted job for cancel propagation, and durably tag the projected
-     * `execution_jobs` row with the owning worker peer so run-recovery sweepers
-     * do not force-fail the job while its worker is connected.
+     * Track a rerouted job for cancel propagation, arm the post-ACK spawn-window
+     * backstop timer, and durably tag the projected `execution_jobs` row with the
+     * owning worker peer so run-recovery sweepers do not force-fail the job while
+     * its worker is connected.
      */
     private trackReroutedJob;
+    /**
+     * Post-ACK spawn-window backstop. Fires when a rerouted job's peer accepted
+     * but produced no progress within the window (Layer A), or immediately when a
+     * worker relays a `scaler.failed` for the job (Layer B, via onPeerScalerEvent).
+     * Best-effort cancels the original peer (double-execution guard against a
+     * slow-but-healthy spawn), then re-runs routing to another peer, then a local
+     * fallback, and finally records the job failed rather than leaving it pending.
+     * Idempotent: whichever trigger fires first removes the tracking entry, so the
+     * other no-ops.
+     */
+    private handleRerouteSpawnTimeout;
+    /** Best-effort cancel a single job on a peer (double-execution guard). */
+    private cancelPeerJob;
+    /**
+     * Local fallback for a re-dispatch: dispatch the job on this coordinator under
+     * the existing jobId. Returns true when the local dispatcher accepts it.
+     */
+    private tryLocalRedispatch;
+    /** Mark a job failed when no backend (peer or local) can run it after re-dispatch. */
+    private failUnroutableJob;
 }
 //# sourceMappingURL=coordinator.d.ts.map

package/dist/cluster/join-client.d.ts

@@ -16,7 +16,7 @@ import { type JoinRequest, type JoinResponse } from '@kici-dev/engine';
 import type { ConfigBundle } from './join-handler.js';
 interface JoinClientOptions {
     token: string;
-    /** Platform WebSocket URL for relay mode (e.g., wss://platform.kici.dev/ws) */
+    /** Platform WebSocket URL for relay mode (e.g., wss://api.kici.dev/ws) */
     platformUrl?: string;
     /** Peer HTTP URL for direct mode (e.g., https://orch-1:8080) */
     peerUrl?: string;

package/dist/cluster/leader-gated-scheduler.d.ts

@@ -0,0 +1,50 @@
+import { createLogger } from '@kici-dev/shared';
+type SchedulerLogger = ReturnType<typeof createLogger>;
+export interface LeaderGatedSchedulerOptions {
+    /** Human name for logs, e.g. "cron evaluation". */
+    name: string;
+    /** Interval between ticks, in ms. */
+    intervalMs: number;
+    /** The periodic body. Errors are caught and logged, never thrown out of the interval. */
+    tick: () => Promise<void> | void;
+    /**
+     * Optional setup run AFTER leader=true and BEFORE the interval starts (awaited), so the first
+     * tick can rely on it. Cron uses this for cache load + missed-schedule recovery.
+     */
+    onBecomeLeader?: () => Promise<void> | void;
+    /** Whether to unref the interval timer. Default true; pass false to keep the loop alive. */
+    unref?: boolean;
+    /**
+     * Logger for the lifecycle + tick-error lines. Pass the owning class's logger so the log
+     * prefix stays that of the scheduler site; defaults to a `leader-gated-scheduler` logger.
+     */
+    logger?: SchedulerLogger;
+}
+/**
+ * Raft-leader-only periodic scheduler. Encapsulates the become -> (optional async setup) ->
+ * start-interval / lose -> stop lifecycle that the orchestrator's leader-gated schedulers share.
+ * The interval runs only while this node is the leader.
+ */
+export declare class LeaderGatedScheduler {
+    private readonly opts;
+    private timer;
+    private leader;
+    private readonly logger;
+    /**
+     * Monotonic tenure counter. Bumped on every leadership transition
+     * (onBecomeLeader / onLoseLeadership / stop). onBecomeLeader captures its
+     * tenure at entry and re-checks it after the awaited setup: if it changed
+     * during the async setup, leadership was revoked (or superseded by a newer
+     * tenure) mid-flight and this stale tenure must NOT start the interval — that
+     * would leak a timer running tick() while no longer leader.
+     */
+    private generation;
+    constructor(opts: LeaderGatedSchedulerOptions);
+    get isLeader(): boolean;
+    onBecomeLeader(): Promise<void>;
+    onLoseLeadership(): void;
+    stop(): void;
+    private clearTimer;
+}
+export {};
+//# sourceMappingURL=leader-gated-scheduler.d.ts.map

package/dist/cluster/orphan-recovery.d.ts

@@ -17,11 +17,16 @@ import type { Database } from '../db/types.js';
 import type { RaftNode } from './raft.js';
 import type { PeerRegistry } from './peer-registry.js';
 import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+import type { ClusterSettingsReader } from './cluster-settings-reader.js';
 interface OrphanRecoveryDeps {
     db: Kysely<Database>;
     raft: RaftNode;
     peerRegistry: PeerRegistry;
     executionTracker: ExecutionTracker;
+    /** Reader for fleet-wide cluster tunables (reroute flap-grace override). */
+    clusterSettings: ClusterSettingsReader;
+    /** Cluster default for the reroute flap-grace window (config.rerouteFlapGraceMs). */
+    rerouteFlapGraceFallbackMs: number;
     /** Scan interval in ms. Default: 60000 (1 minute). */
     scanIntervalMs?: number;
     /** How long a run must be stale before considered orphaned. Default: 5 minutes. */
@@ -34,6 +39,8 @@ export declare class OrphanRecovery {
     private readonly raft;
     private readonly peerRegistry;
     private readonly executionTracker;
+    private readonly clusterSettings;
+    private readonly rerouteFlapGraceFallbackMs;
     private readonly scanIntervalMs;
     private readonly staleThresholdMs;
     private readonly jobStuckThresholdMs;
@@ -57,6 +64,13 @@ export declare class OrphanRecovery {
      * Attempt to recover a single potentially orphaned run.
      */
     private recoverRun;
+    /**
+     * Whether any job of the run moved within the stale window — a heartbeat, a
+     * start, or a completion. A crashed coordinator stops producing all three, so
+     * a genuinely orphaned run becomes eligible again within one window; a healthy
+     * long run never does.
+     */
+    private hasRecentProgress;
     /**
      * Check if a coordinator with the given routing key is still connected
      * as a peer in the cluster.

package/dist/cluster/peer-client.d.ts

@@ -10,7 +10,7 @@
  * Authentication uses ECDH key exchange followed by join token (first connect)
  * or HMAC credential proof (reconnection).
  */
-import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type JobProgressAck, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerLogsCollectRequest, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
+import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type JobProgressAck, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerClusterSettingsRequest, type PeerClusterSettingsResponse, type PeerLogsCollectRequest, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
 import type { PeerRegistry } from './peer-registry.js';
 import type { PeerAuthCoordinator } from './peer-auth-coordinator.js';
 type PeerConnectionState = 'disconnected' | 'connecting' | 'handshaking' | 'authenticating' | 'connected';
@@ -36,7 +36,7 @@ export interface PeerClientOptions {
     /** Callback when a job reroute request is received from peer. */
     onJobReroute: (msg: JobReroute) => Promise<void>;
     /** Callback when a job progress update is received from peer. */
-    onJobProgress: (msg: JobProgress, reply: (m: JobProgressAck) => void) => void;
+    onJobProgress: (msg: JobProgress, fromPeerId: string, reply: (m: JobProgressAck) => void) => void;
     /**
      * Callback invoked once this client reaches the `connected` state (initial
      * connect AND every reconnect). Carries this client's peer URL.
@@ -114,6 +114,7 @@ export declare class PeerClient {
     private readonly ackWaiters;
     private readonly cacheWaiters;
     private readonly configReloadWaiters;
+    private readonly clusterSettingsWaiters;
     /** Correlates peer.logs.collect.request with the peer's chunked subtree response. */
     private readonly logsCollectWaiters;
     private readonly url;
@@ -183,6 +184,14 @@ export declare class PeerClient {
      *   if the peer doesn't reply within the timeout.
      */
     sendConfigReloadAndWait(msg: PeerConfigReload, timeoutMs?: number): Promise<PeerConfigReloadResponse | null>;
+    /**
+     * Send a peer.clusterSettings.request to the connected leader and wait for the
+     * matching peer.clusterSettings.response carrying the worker-settings snapshot.
+     *
+     * @returns The response, or null if not connected or the leader doesn't reply
+     *   within the timeout — the caller keeps its current (config-default) settings.
+     */
+    sendClusterSettingsRequestAndWait(msg: PeerClusterSettingsRequest, timeoutMs?: number): Promise<PeerClusterSettingsResponse | null>;
     /**
      * Send a peer.logs.collect.request to the connected peer and await its
      * reassembled subtree-bundle ZIP. Rejects on timeout, an error frame, or
@@ -236,6 +245,7 @@ export declare class PeerClient {
     private clearAckWaiters;
     private clearCacheWaiters;
     private clearConfigReloadWaiters;
+    private clearClusterSettingsWaiters;
 }
 export {};
 //# sourceMappingURL=peer-client.d.ts.map

package/dist/cluster/peer-handler.d.ts

@@ -6,7 +6,7 @@
  * proof (reconnection), registers the peer in PeerRegistry, and routes
  * messages bidirectionally. Sends periodic heartbeats to the connecting peer.
  */
-import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type JobProgressAck, type PeerScalerEvent, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerLogsCollectRequest, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
+import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type JobProgressAck, type PeerScalerEvent, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerClusterSettingsRequest, type WorkerClusterSettings, type PeerLogsCollectRequest, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
 import type { PeerRegistry } from './peer-registry.js';
 import type { PeerCredentialStore } from './peer-credentials.js';
 import { type JoinTokenManager } from './join-token.js';
@@ -40,9 +40,9 @@ export interface PeerHandlerDeps {
     /** Callback when a job reroute request is received from peer. */
     onJobReroute: (msg: JobReroute) => Promise<void>;
     /** Callback when a job progress update is received from peer. */
-    onJobProgress: (msg: JobProgress, reply: (m: JobProgressAck) => void) => void;
+    onJobProgress: (msg: JobProgress, fromPeerId: string, reply: (m: JobProgressAck) => void) => void;
     /** Callback when a scaler provisioning event is forwarded by a worker peer. */
-    onPeerScalerEvent?: (msg: PeerScalerEvent) => void;
+    onPeerScalerEvent?: (msg: PeerScalerEvent, fromPeerId: string) => void;
     /** Callback when a job cancel request is received from peer. */
     onJobCancel: (msg: PeerJobCancel) => void;
     /** Callback when a log chunk is received from a worker peer. */
@@ -78,6 +78,17 @@ export interface PeerHandlerDeps {
         restartRequired?: string[];
         fieldsChanged?: string[];
     }>;
+    /**
+     * Callback when a peer.clusterSettings.request arrives from a DB-less worker.
+     * Resolves the worker-relevant settings snapshot (async DB read) and the
+     * current cluster_settings version; the result is sent back via
+     * peer.clusterSettings.response. If undefined, requests are answered with the
+     * config-default snapshot at version 0.
+     */
+    onPeerClusterSettingsRequest?: (msg: PeerClusterSettingsRequest) => Promise<{
+        version: number;
+        settings: WorkerClusterSettings;
+    }>;
     /**
      * Callback when a peer.logs.collect.request arrives from an incoming-dialed
      * peer. Builds this node's subtree bundle and streams it back through `send`
@@ -99,7 +110,7 @@ export declare function createPeerHandler(deps: PeerHandlerDeps): {
     sendConfigReloadAndWait: (targetInstanceId: string, msg: PeerConfigReload, timeoutMs?: number) => Promise<PeerConfigReloadResponse | null>;
     sendLogsCollectAndWait: (targetInstanceId: string, msg: PeerLogsCollectRequest, timeoutMs: number) => Promise<Buffer>;
     getConnectionCount: () => number;
-    broadcastHeartbeat: (inventory: Omit<PeerHeartbeat, "type">) => void;
+    broadcastHeartbeat: (inventory: Omit<PeerHeartbeat, 'type'>) => void;
     broadcastAgentTokenRevoke: (msg: PeerAgentTokenRevoke) => void;
     cleanup: () => void;
     closeAllInbound: () => void;

package/dist/cluster/peer-registry.d.ts

@@ -46,6 +46,8 @@ export interface PeerInfo {
     configVersion: number;
     /** Registry version reported by this peer (0 = unknown/legacy). */
     registryVersion: number;
+    /** Cluster-settings version reported by this peer (0 = unknown/legacy). */
+    clusterSettingsVersion: number;
     /** Cluster role of the peer. */
     role: 'coordinator' | 'worker';
     hostname?: string;
@@ -65,6 +67,8 @@ export interface PeerRegistryOptions {
     onConfigVersionBehind?: (peerVersion: number) => void;
     /** Called when a peer's registryVersion is higher than the local version. */
     onRegistryVersionBehind?: (peerVersion: number) => void;
+    /** Called when a peer's clusterSettingsVersion is higher than the local version. */
+    onClusterSettingsVersionBehind?: (peerVersion: number) => void;
     /** Called when a peer transitions to disconnected state. */
     onPeerDisconnected?: (instanceId: string) => void;
 }
@@ -72,8 +76,10 @@ export declare class PeerRegistry {
     private readonly peers;
     private localConfigVersion;
     private localRegistryVersion;
+    private localClusterSettingsVersion;
     private readonly onConfigVersionBehind?;
     private readonly onRegistryVersionBehind?;
+    private readonly onClusterSettingsVersionBehind?;
     private readonly onPeerDisconnected?;
     constructor(options?: PeerRegistryOptions);
     /**
@@ -84,6 +90,12 @@ export declare class PeerRegistry {
      * Update the local registry version for comparison with peer heartbeats.
      */
     setLocalRegistryVersion(version: number): void;
+    /**
+     * Update the local cluster-settings version for comparison with peer
+     * heartbeats. A worker sets this after pulling a snapshot so it stops
+     * re-firing the version-behind hook on every subsequent heartbeat.
+     */
+    setLocalClusterSettingsVersion(version: number): void;
     /**
      * Add or update a peer entry. Sets initial connected state to true.
      * If the peer already exists and is connected, preserves capabilities

package/dist/cluster/verified-issuer-poller.d.ts

@@ -0,0 +1,11 @@
+import { type VerifiedIssuerReader } from './verified-issuer.js';
+export interface VerifiedIssuerPollerOptions {
+    reader: VerifiedIssuerReader;
+    /** The value already broadcast, so the first tick only fires on a real change. */
+    initial: string | null;
+    intervalMs: number;
+    onChange: (issuer: string | null) => void;
+}
+/** Start polling. Returns the stop function. */
+export declare function startVerifiedIssuerPoller(opts: VerifiedIssuerPollerOptions): () => void;
+//# sourceMappingURL=verified-issuer-poller.d.ts.map

package/dist/cluster/verified-issuer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Resolves the Verified-tier issuer: the origin a browser fetches the
+ * orchestrator's dashboard-encryption key from directly, bypassing the hosted
+ * control plane, so TLS to the customer's own domain is the trust root.
+ *
+ * The tier is explicit opt-in and has NO environment-variable fallback. In
+ * particular `KICI_ORCHESTRATOR_PROVENANCE_ISSUER` (a build-attestation
+ * setting) must not enable it: configuring attestations is not consent to a
+ * different dashboard trust tier, and the Verified fetch is cross-origin, so
+ * switching a cluster into it unasked would hard-block every encrypted write
+ * whose browser cannot reach that origin.
+ *
+ * Every consumer resolves through this module — the capability broadcast via
+ * `tryResolveVerifiedIssuer`, the CLI via `resolveVerifiedIssuer` — so the two
+ * read the same setting and can never disagree about which tier is active.
+ * They differ only in what a failed read reports: unknown, or the opt-out
+ * default.
+ */
+import type { OrchCapabilities } from '@kici-dev/engine';
+import type { ClusterSettingsReader } from './cluster-settings-reader.js';
+export type VerifiedIssuerReader = Pick<ClusterSettingsReader, 'getString' | 'tryGetString'>;
+/**
+ * The opted-in verified issuer origin, or null when the tier is not enabled.
+ *
+ * Null is ambiguous here: an unreadable setting also lands on it, because the
+ * underlying `getString` swallows a DB error and takes the fallback. Anything
+ * that would ACT on the null — broadcasting a tier, choosing a key source —
+ * must use {@link tryResolveVerifiedIssuer} instead, or a transient DB failure
+ * silently downgrades the trust root. Only the CLI still reads through here,
+ * where the surrounding command already fails loudly on an unreachable DB.
+ */
+export declare function resolveVerifiedIssuer(reader: VerifiedIssuerReader): Promise<string | null>;
+/**
+ * The verified issuer, or `{ ok: false }` when the setting could not be read.
+ *
+ * The distinction matters only here: everywhere else a missing knob means "take
+ * the default", but this knob's default is the weaker Convenient tier, so
+ * answering "unset" for a failed read silently moves the trust root back to the
+ * hosted control plane. A caller that already knows the issuer holds it instead.
+ */
+export type VerifiedIssuerRead = {
+    ok: true;
+    issuer: string | null;
+} | {
+    ok: false;
+};
+/** Read the verified issuer, keeping a failed read distinct from an opt-out. */
+export declare function tryResolveVerifiedIssuer(reader: VerifiedIssuerReader): Promise<VerifiedIssuerRead>;
+/**
+ * The capability patch a `VerifiedIssuerRead` should broadcast.
+ *
+ * `broadcastCapabilities` MERGES its argument into the stored set, so an
+ * omitted key means "unchanged" and a present `null` means "the operator opted
+ * out". An unknown read must therefore produce an object with no key at all —
+ * not one whose value is `undefined`, which would still overwrite on spread.
+ *
+ * Extracted as a pure function because its only caller is a closure inside
+ * server.ts's connection handler, which has no test seam.
+ */
+export declare function verifiedIssuerCapabilityUpdate(read: VerifiedIssuerRead): Partial<Pick<OrchCapabilities, 'dashboardVerifiedIssuer'>>;
+/** The JWKS document URL for an issuer origin. */
+export declare function jwksUrlFor(issuer: string): string;
+//# sourceMappingURL=verified-issuer.d.ts.map

package/dist/cold-store/tables/access-log.d.ts

@@ -30,7 +30,7 @@ export interface AccessLogAdapterOptions {
 export declare class AccessLogAdapter implements TableAdapter<AccessLogColdStoreRow> {
     private readonly kdb;
     private readonly instanceId;
-    readonly db: "orchestrator";
+    readonly db: 'orchestrator';
     readonly table = "access_log";
     readonly tenantColumn = "org_id";
     readonly partitionColumn = "created_at";

package/dist/cold-store/tables/event-log.d.ts

@@ -36,7 +36,7 @@ export interface EventLogAdapterOptions {
 export declare class EventLogAdapter implements TableAdapter<EventLogColdStoreRow> {
     private readonly kdb;
     private readonly instanceId;
-    readonly db: "orchestrator";
+    readonly db: 'orchestrator';
     readonly table = "event_log";
     readonly tenantColumn = "routing_key";
     readonly partitionColumn = "received_at";

package/dist/cold-store/tables/execution-jobs.d.ts

@@ -29,7 +29,7 @@ export interface ExecutionJobsAdapterOptions {
 export declare class ExecutionJobsAdapter implements TableAdapter<ExecutionJobRow> {
     private readonly kdb;
     private readonly instanceId;
-    readonly db: "orchestrator";
+    readonly db: 'orchestrator';
     readonly table = "execution_jobs";
     readonly tenantColumn = "routing_key";
     readonly partitionColumn = "created_at";

package/dist/cold-store/tables/execution-runs.d.ts

@@ -24,7 +24,7 @@ export interface ExecutionRunsAdapterOptions {
 export declare class ExecutionRunsAdapter implements TableAdapter<ExecutionRunRow> {
     private readonly kdb;
     private readonly instanceId;
-    readonly db: "orchestrator";
+    readonly db: 'orchestrator';
     readonly table = "execution_runs";
     readonly tenantColumn = "routing_key";
     readonly partitionColumn = "created_at";

package/dist/cold-store/tables/execution-steps.d.ts

@@ -31,7 +31,7 @@ export interface ExecutionStepsAdapterOptions {
 export declare class ExecutionStepsAdapter implements TableAdapter<ExecutionStepRow> {
     private readonly kdb;
     private readonly instanceId;
-    readonly db: "orchestrator";
+    readonly db: 'orchestrator';
     readonly table = "execution_steps";
     readonly tenantColumn = "routing_key";
     readonly partitionColumn = "created_at";

package/dist/cold-store/tables/secret-audit-log.d.ts

@@ -23,7 +23,7 @@ export interface SecretAuditLogAdapterOptions {
 export declare class SecretAuditLogAdapter implements TableAdapter<SecretAuditLogRow> {
     private readonly kdb;
     private readonly instanceId;
-    readonly db: "orchestrator";
+    readonly db: 'orchestrator';
     readonly table = "secret_audit_log";
     readonly tenantColumn = "routing_key";
     readonly partitionColumn = "timestamp";

package/dist/config/loader.d.ts

@@ -14,7 +14,7 @@ import type { LocalConfig } from './types.js';
  * Shared config field paths that contain sensitive values.
  * Used by SharedConfigStore for encryption before DB storage.
  */
-export declare const SENSITIVE_FIELD_PATHS: readonly ["platform.token", "secrets.key", "secrets.bootstrapAdminToken", "cluster.joinToken"];
+export declare const SENSITIVE_FIELD_PATHS: readonly ['platform.token', 'secrets.key', 'secrets.bootstrapAdminToken', 'cluster.joinToken'];
 /**
  * Load and validate the local orchestrator YAML configuration.
  *

package/dist/config/resolver.d.ts

@@ -9,6 +9,7 @@
  *
  * Precedence: env var > local YAML > shared DB > defaults
  */
+import type { OrchestratorMode } from '@kici-dev/engine';
 import type { AppConfig, SharedConfig } from './types.js';
 /**
  * Phase 1 result: minimal config resolved from local sources only.
@@ -23,7 +24,7 @@ export interface LocalPhaseResult {
     /** Resolved server port */
     port: number;
     /** Resolved instance mode */
-    mode: 'platform' | 'hybrid' | 'independent';
+    mode: OrchestratorMode;
 }
 /**
  * Phase 1: Resolve local-only config.