@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/cluster/coordinator.d.ts

@@ -3,12 +3,11 @@
  *
  * The receiving orchestrator becomes the run coordinator: it claims jobs
  * it can dispatch locally and reroutes others to peers based on agent
- * inventory. Per locked decisions:
- * - "One orchestrator coordinates per webhook run"
- * - "Claim-based splitting"
- * - "Coordinator handles ALL check run reporting"
- * - "Peers report step-by-step progress back to coordinator"
- * - "Cancel mode: graceful -- finish current step, cancel remaining"
+ * inventory.
+ * - One orchestrator coordinates per webhook run.
+ * - The coordinator handles ALL check run reporting.
+ * - Peers report step-by-step progress back to the coordinator.
+ * - Cancel is graceful: finish the current step, cancel the remaining ones.
  */
 import type { JobReroute, JobProgress, JobProgressAck, PeerScalerEvent, PeerToPeerMessage, RerouteSpawnRetry, ResourceRequest, LabelMatcher } from '@kici-dev/engine';
 import type { PeerRegistry } from './peer-registry.js';
@@ -54,10 +53,9 @@ export interface JobToRoute {
     /** Labels that the dispatched agent must NOT have. */
     excludeLabels?: string[];
     /**
-     * Per-job resource request and limit (K8s-style). Forwarded to
-     * `Dispatcher.dispatch()` so the scaler's per-scaler / per-orchestrator /
-     * per-machine cap accounting sees the typed value rather than relying on
-     * the `jobConfig.resources` JSON blob (which the dispatcher does not parse).
+     * Per-job resource request and limit (K8s-style), forwarded typed to
+     * `Dispatcher.dispatch()` for the scaler's cap accounting: the dispatcher does
+     * not parse the `jobConfig.resources` JSON blob.
      */
     resources?: ResourceRequest;
 }
@@ -66,11 +64,7 @@ export interface RouteResult {
         jobName: string;
         jobId: string;
     }>;
-    /**
-     * Rerouted jobs include the pre-allocated jobId so the caller can
-     * register the execution_runs / execution_jobs rows under the same id
-     * the worker will report progress against.
-     */
+    /** The pre-allocated jobId, so the caller's execution rows match the worker's reports. */
     reroutedJobs: Array<{
         jobName: string;
         peerId: string;
@@ -98,28 +92,20 @@ export interface RunCoordinatorDeps {
     /** 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.
+     * Post-ACK re-dispatch backstop window (ms): the job's org override from
+     * `org_settings.reroute_spawn_window_ms`, else the cluster default. Absent:
+     * {@link DEFAULT_REROUTE_SPAWN_WINDOW_MS}.
      */
     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}.
-     */
+    /** `sendAndWaitAck` deadline (ms). Absent: `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}.
-     */
+    /** Absent: {@link DEFAULT_MAX_HOPS}. */
     getRerouteMaxHops?: (job: JobToRoute) => Promise<number>;
     /**
-     * Per-job spawn-retry budget sent to the receiving peer on `job.reroute` and
-     * enforced here on the peer's relayed spawn failures. Resolves the job's org
-     * overrides from `org_settings.reroute_spawn_max_attempts` /
-     * `reroute_spawn_retry_backoff_ms`, else the cluster defaults. When absent,
-     * {@link DEFAULT_REROUTE_SPAWN_RETRY} is used.
+     * Spawn-retry budget sent to the receiving peer on `job.reroute` and enforced
+     * here on its relayed spawn failures: the job's org overrides from
+     * `org_settings.reroute_spawn_max_attempts` / `reroute_spawn_retry_backoff_ms`,
+     * else the cluster defaults. Absent: {@link DEFAULT_REROUTE_SPAWN_RETRY}.
      */
     getRerouteSpawnRetry?: (job: JobToRoute) => Promise<RerouteSpawnRetry>;
 }
@@ -137,18 +123,10 @@ export declare class RunCoordinator {
     private readonly getRerouteAckTimeoutMs;
     private readonly getRerouteMaxHops;
     private readonly getRerouteSpawnRetry;
-    /**
-     * Tracks which jobs have been rerouted to which peers, keyed by runId.
-     * Used for cancel propagation, progress tracking, and the post-ACK spawn
-     * re-dispatch backstop.
-     */
+    /** runId → jobId → reroute target: cancel propagation, progress, and the spawn backstop. */
     private readonly reroutedJobs;
-    /**
-     * NAK tracking per peer: count of consecutive NAKs and backoff-until timestamp.
-     * Peers that repeatedly NAK are deprioritized via exponential backoff.
-     */
+    /** Consecutive NAKs per peer; a repeatedly NAKing peer is skipped under exponential backoff. */
     private readonly nakTracker;
-    /** Stale eviction timer handle. */
     private staleEvictionTimer;
     /** Plan-ceiling worker eviction (drain-then-disconnect). */
     private readonly workerEviction;
@@ -168,44 +146,31 @@ export declare class RunCoordinator {
      */
     reconcileWorkerEviction(ceiling: number, evictExcess: boolean): void;
     /**
-     * Route jobs for a webhook run. Claims jobs that local agents can handle,
-     * reroutes the rest to peers with matching capacity.
-     *
-     * Parallel fan-out: jobs targeting different peers are rerouted concurrently.
+     * Claim the jobs local agents can handle and reroute the rest, concurrently,
+     * to peers with matching capacity.
      */
     routeJobs(runContext: RunContext, jobs: JobToRoute[]): Promise<RouteResult>;
-    /**
-     * Handle a job reroute request received from a peer (this instance is the worker).
-     * Checks loop prevention, then attempts to dispatch locally.
-     */
+    /** Accept a peer's job reroute (this instance is the worker) by dispatching it locally. */
     handleIncomingReroute(msg: JobReroute): Promise<{
         accepted: boolean;
         reason?: string;
     }>;
     /**
-     * Handle peer job/step progress updates from a worker (or coord) peer.
-     *
-     * The discriminator `msg.kind` decides which downstream tracker call to
-     * make: 'job' updates feed `onJobStatus` (the path that drives run-level
-     * state transitions and the rerouted-job cleanup); 'step' updates feed
-     * `onStepStatus` (which only persists `execution_steps` rows). Without
-     * this split, every job-level event was silently funnelled into
-     * `onStepStatus` and the run stayed in `running` forever.
+     * Apply a worker (or coord) peer's job/step progress. `msg.kind` picks the
+     * tracker call: 'job' feeds `onJobStatus` (run-level state transitions and
+     * rerouted-job cleanup); 'step' feeds `onStepStatus` (only `execution_steps`
+     * rows). A job-level event sent to `onStepStatus` leaves the run in `running`
+     * forever.
      */
     onPeerJobProgress(msg: JobProgress, fromPeerId: string, reply?: (m: JobProgressAck) => void): void;
     /**
-     * Handle a scaler provisioning event forwarded by a worker peer.
-     *
-     * Workers have no database, so they relay scaler events for jobs the
-     * worker is provisioning to the coordinator that owns the run. The
-     * coordinator's ExecutionTracker persists the event (provisioning log
-     * line + dispatch-queue last-error column) just as it would for a
-     * locally-emitted scaler event.
+     * Persist a scaler event a worker peer relayed (workers have no database):
+     * provisioning log line + dispatch-queue last-error column, as for a local one.
      *
      * Layer B: a `scaler.failed` for a tracked rerouted job whose spawn window is
-     * still armed is the worker reporting that an agent spawn failed after it
-     * accepted the reroute. The worker retries within the spawn-retry budget sent on
-     * `job.reroute`, and the relay carries its verdict:
+     * still armed is an agent spawn failing after the worker accepted the reroute.
+     * The worker retries within the spawn-retry budget sent on `job.reroute`, and
+     * the relay carries its verdict:
      *
      * - `final: true` — the worker gave the job back. Re-dispatch immediately (the
      *   same routine the spawn-window timer runs). Idempotent with the Layer A
@@ -230,87 +195,58 @@ export declare class RunCoordinator {
      * A worker's verdict on a failed spawn for a job it holds. `final: true` means it
      * gave the job back, so re-dispatch now. `final: false` means it is retrying, so
      * restart the window for one more attempt plus the backoff this coordinator told it
-     * to wait. No verdict means a worker that retries without a bound, so leave the
-     * window as it is. The count caps a worker that never says `final`.
+     * to wait. No verdict means a repeated report of one failed spawn, or a failure
+     * the worker holds no retry budget for, so leave the window as it is. The count
+     * caps a worker that never says `final`.
      */
     private onRelayedSpawnFailure;
     /** Restart a rerouted job's spawn window for one more worker attempt plus its backoff. */
     private rearmAfterSpawnRetry;
     /**
-     * Handle peer job completion. Updates ExecutionTracker.
-     * The execution tracker's onJobStatus fires the needs-aware scheduler hook,
-     * which evaluates downstream jobs and dispatches newly-ready ones via onJobReadyCallback.
-     * The data parameter carries droppedJobs for drift reporting.
+     * Apply a peer's job completion. onJobStatus fires the needs-aware scheduler
+     * hook, which dispatches newly-ready downstream jobs via onJobReadyCallback.
+     * `data` carries droppedJobs for drift reporting.
      */
     onPeerJobComplete(runId: string, jobId: string, status: string, timestamp: number, data?: Record<string, unknown>): void;
     /**
-     * Cancel all rerouted jobs for a run. Sends peer.job.cancel to all
-     * peers that have jobs for this run.
-     *
-     * Per locked decision: "graceful -- finish current step, cancel remaining."
+     * Send peer.job.cancel for every rerouted job of a run. Graceful: the peer
+     * finishes the current step and cancels the remaining ones.
      */
     cancelRun(runId: string, reason: string): void;
-    /**
-     * Check if the peer registry has any connected peers.
-     */
     hasConnectedPeers(): boolean;
-    /**
-     * Start the stale eviction timer. Calls peerRegistry.evictStalePeers()
-     * every staleTimeoutMs/2 to detect and remove stale peers.
-     */
+    /** Evict stale peers every staleTimeoutMs/2. */
     startStaleEvictionTimer(staleTimeoutMs: number): void;
-    /**
-     * Stop the stale eviction timer.
-     */
     stopStaleEvictionTimer(): void;
-    /**
-     * Get the NAK count for a peer (used in tests).
-     */
+    /** Used in tests. */
     getNakCount(peerId: string): number;
-    /**
-     * Get the backoff-until timestamp for a peer (used in tests).
-     */
+    /** Used in tests. */
     getBackoffUntil(peerId: string): number;
-    /**
-     * 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}.
-     */
+    /** Allocate the sender-side jobId and delegate 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.
+     * Try each peer with matching capacity (most first) for one job under a fixed
+     * `jobId`, returning on the first ACK. Used by initial routing and the spawn
+     * backstop; the caller passes the accumulated `triedConnections` (this
+     * instance + any failed peers) so a re-dispatch never re-selects a failed peer
+     * and the receiving peer's loop-prevention stays correct.
      */
     private attemptPeerRoute;
-    /** Build the failure result when no peer has matching capacity (with debug log). */
+    /** Tell "no peer handles this label" from "peers exist but at capacity". */
     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.
-     */
     private sortPeersByCapacity;
     /**
-     * Compute total available capacity across matching agents on a peer.
-     *
-     * Applies the same `mandatoryLabels` gate the local label matcher
-     * applies — a gated agent only contributes capacity for label sets that
-     * include every gate label. Without it, the coordinator would route a
-     * job to a peer based on a gated agent's labels, and the peer would
-     * then refuse the dispatch in `AgentRegistry.findAvailable` because the
-     * agent's gate is not satisfied.
+     * Free capacity across a peer's matching agents. A gated agent counts only for
+     * label sets that include every `mandatoryLabels` gate label, as the local
+     * matcher does; otherwise the peer refuses the dispatch in
+     * `AgentRegistry.findAvailable`.
      */
     private computeAvailableCapacity;
     /**
-     * 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.
+     * Track a rerouted job, arm its spawn-window backstop, and durably tag its
+     * `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;
     /** Arm a spawn-window / reap timer that fires {@link handleRerouteSpawnTimeout}. */
@@ -320,10 +256,9 @@ export declare class RunCoordinator {
      * shared `execution_jobs` row.
      *
      * A read failure answers "not running" so a transient database fault cannot
-     * silently disable the backstop — the re-dispatch it then performs is the
-     * behavior that shipped before this check existed, and it is idempotent.
-     * Only the FIRST observation goes through this path: once `peerStarted`
-     * latches, a read fault can no longer bounce a running job.
+     * silently disable the backstop; the re-dispatch it then performs is
+     * idempotent. Only the FIRST observation goes through this path: once
+     * `peerStarted` latches, a read fault can no longer bounce a running job.
      */
     private rerouteTargetIsRunning;
     /**
@@ -331,24 +266,21 @@ export declare class RunCoordinator {
      * tracking entry once the shared row is terminal, otherwise re-arm the window
      * as a reap poll.
      *
-     * The entry cannot be dropped here: cancel propagation still needs it
-     * while the job runs. It also cannot be kept, because a peer
-     * COORDINATOR relays no terminal `job.progress` — the shared row IS its
-     * report — so nothing else would ever release it and `reroutedJobs` would
-     * grow for the lifetime of the process. A read fault re-arms (never releases),
+     * The entry cannot be dropped: cancel propagation needs it while the job runs.
+     * It cannot be kept: a peer COORDINATOR relays no terminal `job.progress` (the
+     * shared row IS its report), so nothing else releases it and `reroutedJobs`
+     * would grow for the process lifetime. A read fault re-arms (never releases),
      * so a transient fault costs one more poll rather than tracking.
      */
     private reapOrDeferRerouteTracking;
     /**
      * 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 its final spawn-failure verdict for the job (Layer B, via
-     * onPeerScalerEvent).
+     * but produced no progress within the window (Layer A), or when a worker
+     * relays its final spawn-failure verdict (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.
+     * slow-but-healthy spawn), then re-routes to another peer, then local, and
+     * finally records the job failed rather than leaving it pending. Idempotent:
+     * whichever trigger fires first removes the tracking entry.
      */
     private handleRerouteSpawnTimeout;
     /** Best-effort cancel a single job on a peer (double-execution guard). */
@@ -365,12 +297,11 @@ export declare class RunCoordinator {
      */
     cancelJobOnPeer(peerId: string, runId: string, jobId: string, reason: string, force?: boolean): boolean;
     /**
-     * Send a fire-and-forget message to a peer. The outbound client carries it
-     * when connected; otherwise the peer's own connection to this process does.
-     * The outbound client is down while it reconnects, and for good on a
-     * coordinator whose credential an operator revoked.
-     * `PeerClient.send` returns false only when it sent nothing, so the fallback
-     * never delivers a message twice.
+     * Fire-and-forget to a peer: over the outbound client when connected, else
+     * over the peer's own connection to this process. The outbound client is down
+     * while it reconnects, and for good on a coordinator whose credential an
+     * operator revoked. `PeerClient.send` returns false only when it sent nothing,
+     * so the fallback never delivers a message twice.
      */
     private sendToPeer;
     /**
@@ -379,10 +310,7 @@ export declare class RunCoordinator {
      * timeout, and resending would deliver the job twice.
      */
     private rerouteTransport;
-    /**
-     * Local fallback for a re-dispatch: dispatch the job on this coordinator under
-     * the existing jobId. Returns true when the local dispatcher accepts it.
-     */
+    /** Re-dispatch locally under the existing jobId; true when the dispatcher accepts it. */
     private tryLocalRedispatch;
     /** Mark a job failed when no backend (peer or local) can run it after re-dispatch. */
     private failUnroutableJob;

package/dist/cluster/health-api.d.ts

@@ -1,12 +1,10 @@
 /**
- * Cluster health HTTP endpoints.
- *
- * Provides visibility into cluster state for monitoring and debugging:
+ * Cluster health HTTP endpoints:
  * - GET /cluster/health -- overall cluster health status
  * - GET /cluster/peers -- per-peer details including connectivity
  * - GET /cluster/runs -- active execution runs with job counts
  *
- * Follows the existing Hono route factory pattern from routes/health.ts.
+ * Follows the Hono route factory pattern of routes/health.ts.
  */
 import { Hono } from 'hono';
 import type { RaftNode } from './raft.js';
@@ -20,11 +18,5 @@ export interface ClusterHealthRoutesDeps {
     executionTracker: ExecutionTracker;
     agentRegistry: AgentRegistry;
 }
-/**
- * Create cluster health routes.
- *
- * @param deps - Dependencies for cluster state introspection
- * @returns Hono app with /cluster/health, /cluster/peers, /cluster/runs endpoints
- */
 export declare function createClusterHealthRoutes(deps: ClusterHealthRoutesDeps): Hono;
 //# sourceMappingURL=health-api.d.ts.map

package/dist/cluster/index.d.ts

@@ -1,9 +1,4 @@
-/**
- * Barrel export for the cluster coordination module.
- *
- * All cluster-related functionality is exported from this single entry point
- * for clean imports in server.ts and standalone.ts.
- */
+/** Barrel export for the cluster coordination module. */
 export { PeerRegistry } from './peer-registry.js';
 export type { PeerInfo, PeerAgentInfo, PeerRegistryOptions } from './peer-registry.js';
 export { PeerClient, PeerDialOrigin } from './peer-client.js';

package/dist/cluster/instance-heartbeat.d.ts

@@ -3,24 +3,20 @@ import type { Database } from '../db/types.js';
 /** Default interval between `cluster_instances` heartbeat writes. */
 export declare const DEFAULT_INSTANCE_HEARTBEAT_MS = 10000;
 /**
- * How many missed ticks a coordinator gets before it reads as dead. Six ticks
- * (60 s at the default interval) is wide enough that a GC pause, a slow DB or a
- * brief network stall does not evict a healthy coordinator — the cost of a
- * false "dead" verdict is another coordinator recovering jobs it is watching.
+ * Missed ticks before a coordinator reads as dead. Six (60 s at the default
+ * interval) survives a GC pause, slow DB or brief network stall; a false "dead"
+ * verdict makes another coordinator recover jobs this one is watching.
  */
 export declare const HEARTBEAT_MISSES_BEFORE_DEAD = 6;
 /**
- * The dispatcher's recovery grace period at the default config: twice
- * `agentMaxReconnectDelayMs` (60 s). Used as the fallback floor when a caller
- * has no configured grace period to hand in.
+ * The dispatcher's default recovery grace: twice `agentMaxReconnectDelayMs` (60 s).
+ * The fallback floor when a caller has no configured grace period.
  */
 export declare const DEFAULT_RECOVERY_GRACE_MS = 120000;
 /**
- * The window inside which a `cluster_instances` row counts as live.
- *
- * Deliberately the larger of the recovery grace period and six heartbeat ticks:
- * the ownership predicate must never call a coordinator dead sooner than the
- * recovery machinery would have given it to reconnect.
+ * Window inside which a `cluster_instances` row counts as live: the larger of the
+ * recovery grace and six ticks, so the ownership predicate never calls a
+ * coordinator dead sooner than recovery would have let it reconnect.
  */
 export declare function instanceLivenessGraceMs(gracePeriodMs: number, heartbeatMs?: number): number;
 /**
@@ -41,18 +37,15 @@ export interface InstanceHeartbeatOptions {
 /**
  * Writes this coordinator's liveness into `cluster_instances` on a fixed tick.
  *
- * Every ownership predicate in the dispatch plane asks "is the coordinator that
- * owns this row still alive?", and the answer has to come from the database.
- * The in-memory peer registry cannot answer it: it is empty at exactly the
- * moment startup recovery runs, because a freshly booted process has not
- * handshaken with any peer yet, so it reads every live sibling as dead — which
- * is the boot-time bug the predicate exists to fix. Raft membership is worse:
- * a partitioned coordinator self-elects and reads the other half as gone.
+ * Dispatch-plane ownership predicates ("is this row's owner alive?") must read the
+ * DB. The in-memory peer registry is empty when startup recovery runs (no peer
+ * handshakes yet), so it reads every live sibling as dead — the boot-time bug the
+ * predicate exists to fix. Raft membership is worse: a partitioned coordinator
+ * self-elects and reads the other half as gone.
  *
- * A DB heartbeat needs no peer connectivity, so it behaves the same in a
- * Raft cluster, a plain multi-coordinator deployment and a standalone one.
- * `host_roster` already derives agent liveness this way; this is the same
- * mechanism pointed at coordinators.
+ * A DB heartbeat needs no peer connectivity, so it behaves the same in Raft,
+ * plain multi-coordinator and standalone deployments — the mechanism
+ * `host_roster` uses for agent liveness.
  */
 export declare class InstanceHeartbeat {
     private readonly db;
@@ -63,39 +56,30 @@ export declare class InstanceHeartbeat {
     private timer;
     constructor(opts: InstanceHeartbeatOptions);
     /**
-     * Write one heartbeat immediately, then every `intervalMs`.
-     *
-     * The immediate write matters: startup recovery runs moments after boot and
-     * reads this table, so a coordinator that had not yet written a row would be
-     * invisible to its own siblings' predicates.
+     * Write one heartbeat immediately, then every `intervalMs`. The immediate write
+     * matters: startup recovery reads this table moments after boot, and a
+     * coordinator with no row yet is invisible to its siblings' predicates.
      */
     start(): Promise<void>;
     stop(): void;
     /**
-     * Remove this instance's row on a clean shutdown, so a coordinator that
-     * stopped on purpose is dead to its siblings immediately rather than after
-     * the grace window. Best-effort: a crash leaves the row to expire.
+     * Delete this row on clean shutdown so siblings see it dead immediately, not
+     * after the grace window. Best-effort: a crash leaves the row to expire.
      */
     retire(): Promise<void>;
     /**
      * One heartbeat write. Best-effort: a failed tick is retried on the next.
-     *
-     * `processStart` is set for the write `start()` makes, and is the only one
-     * that rewrites `started_at` — the column records when THIS process came up,
-     * so a restart under the same instance id must move it while an ordinary tick
-     * must not.
+     * Only `start()`'s write (`processStart`) rewrites `started_at`, which records
+     * when THIS process came up: a restart under the same id moves it, a tick does not.
      */
     beat(opts?: {
         processStart?: boolean;
     }): Promise<void>;
 }
 /**
- * Which of the given coordinator instance ids are alive right now.
- *
- * Reads `cluster_instances` directly rather than the peer registry, for the
- * reason the class above documents: the peer registry is empty during boot and
- * blind under a partition, and a wrong "dead" verdict here means acting on a
- * row a working coordinator owns.
+ * Which of the given coordinator ids are alive now. Reads `cluster_instances`, not
+ * the peer registry (empty at boot, blind under a partition — see the class above):
+ * a wrong "dead" verdict means acting on a row a working coordinator owns.
  */
 export declare function liveInstanceIds(db: Kysely<Database>, instanceIds: readonly string[], graceMs: number): Promise<Set<string>>;
 //# sourceMappingURL=instance-heartbeat.d.ts.map

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

@@ -38,10 +38,9 @@ export declare function describeJoinRefusal(response: JoinResponse): string;
  * through.
  *
  * The `satisfies` clause makes a bundle storage field with no entry here a
- * compile error, so the projection cannot silently drop one — which is the
- * whole defect this artifact exists to avoid. The companion test pins the
- * other half: every field `sharedConfigSchema.storage` accepts, and every
- * variable named here, resolves in the startup env definition.
+ * compile error, so the projection cannot silently drop one. The companion test
+ * pins the other half: every field `sharedConfigSchema.storage` accepts, and
+ * every variable named here, resolves in the startup env definition.
  */
 export declare const STORAGE_ENV_VARS: {
     readonly type: 'KICI_STORAGE_TYPE';
@@ -61,9 +60,7 @@ export declare const STORAGE_ENV_VARS: {
  * rejected by name rather than written.
  */
 export declare function buildEnvFile(bundle: ConfigBundle): string;
-/**
- * Write the env file the orchestrator boots from.
- */
+/** Write the env file the orchestrator boots from. */
 export declare function writeEnvFile(path: string, bundle: ConfigBundle): Promise<void>;
 export declare class JoinClient {
     private readonly options;

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

@@ -23,10 +23,7 @@ interface JoinHandlerDeps {
      */
     secretKey?: string;
 }
-/**
- * Config bundle distributed to new orchestrators via join token.
- * Contains everything needed to configure and start an orchestrator instance.
- */
+/** Config bundle a join seals to a new orchestrator: everything it needs to start. */
 export interface ConfigBundle {
     databaseUrl: string;
     storage?: {
@@ -57,9 +54,8 @@ export declare class JoinHandler {
     handleJoinRequest(raw: unknown): Promise<JoinResponse>;
     private answer;
     /**
-     * Build the config bundle from SharedConfig + local config. The secrets key is
-     * the shared configuration's `secrets.key`, else this orchestrator's own key, so
-     * a joined orchestrator decrypts what the cluster encrypted.
+     * The secrets key is the shared configuration's `secrets.key`, else this
+     * orchestrator's own key, so a joined orchestrator decrypts what the cluster encrypted.
      */
     buildConfigBundle(): Promise<ConfigBundle>;
 }

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

@@ -14,10 +14,7 @@
 import { OrchRole } from '@kici-dev/engine';
 import { Kysely } from 'kysely';
 import { z } from 'zod';
-/**
- * Silence the module-level logger (e.g. when a CLI is emitting JSON on stdout
- * and a stray log line would break the contract).
- */
+/** Silence the module logger, e.g. while a CLI emits JSON on stdout. */
 export declare function silenceJoinTokenLogger(): void;
 export declare const TOKEN_ALREADY_USED_MESSAGE = "Join token has already been used. Create a new token with: kici-admin peer create-token";
 export declare const TOKEN_EXPIRED_MESSAGE = "Join token has expired. Create a new token with: kici-admin peer create-token";
@@ -62,10 +59,7 @@ interface JoinTokenManagerDeps {
 export declare class JoinTokenManager {
     private readonly deps;
     constructor(deps: JoinTokenManagerDeps);
-    /**
-     * Create a new join token.
-     * Returns the full token string (only available at creation time).
-     */
+    /** Returns the full token string, available only at creation time. */
     createToken(opts: {
         orgId: string;
         routingKey: string;
@@ -77,12 +71,11 @@ export declare class JoinTokenManager {
      * Peer token mode: claim the row the presented token's secret hashes to. Role and
      * routing come from the row (`claimByHash`), never from the token's routing part.
      *
-     * Self-healing reuse: a join token is re-consumable by the same joining peer
-     * (`peerInstanceId`) until its `expires_at`. A peer that lost its credential
-     * re-presents the still-valid join token already in its env, and the coordinator
-     * issues a fresh credential without an operator action. Reuse is bounded by both
-     * `expires_at` and the consuming instanceId, so it never widens a leaked token's
-     * usefulness beyond the instance that first consumed it.
+     * Self-healing reuse: the same joining peer (`peerInstanceId`) can re-consume
+     * the token until `expires_at`, so a peer that lost its credential re-presents
+     * the token in its env and gets a fresh credential without an operator action.
+     * Bounding reuse by `expires_at` and the consuming instanceId keeps a leaked
+     * token useless beyond the instance that first consumed it.
      */
     validateAndConsumeToken(token: string, consumedBy: string, peerInstanceId: string): Promise<ClaimedJoinToken>;
     /**
@@ -110,10 +103,8 @@ export declare class JoinTokenManager {
     } | null>;
 }
 /**
- * Build a JoinTokenManager backed by its own connection pool to the given
- * orchestrator database URL. Mirrors `createPeerCredentialStoreFromUrl`;
- * used by tests that need to exercise token validation/reuse against a real
- * cluster DB.
+ * A JoinTokenManager with its own connection pool, for tests against a real
+ * cluster DB. Mirrors `createPeerCredentialStoreFromUrl`.
  */
 export declare function createJoinTokenManagerFromUrl(databaseUrl: string, opts?: {
     maxConnections?: number;
@@ -122,17 +113,12 @@ export declare function createJoinTokenManagerFromUrl(databaseUrl: string, opts?
     dispose: () => Promise<void>;
 };
 /**
- * Narrow detector for the "already been used" error thrown by
- * validateAndConsumeToken(). Used by peer-handler.ts to branch into the
- * idempotent recovery path on legitimate mesh-join races (sibling
- * peer-clients on the same peer identity racing on a shared join token
- * across a multi-coordinator shared-DB mesh). Other validation failures
- * (expired, not found, bad parse) MUST NOT be treated as recoverable.
+ * Detects the "already been used" error from validateAndConsumeToken(), which
+ * peer-handler.ts treats as recoverable: sibling peer-clients of one peer
+ * identity race on a shared token across a shared-DB mesh. Other validation
+ * failures (expired, not found, bad parse) MUST NOT be treated as recoverable.
  */
 export declare function isTokenAlreadyUsedError(err: unknown): boolean;
-/**
- * Parse a join token string into routing info and secret hex.
- */
 export declare function parseToken(token: string): {
     routing: TokenRouting;
     routingB64: string;