@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/storage/types.d.ts

@@ -1,44 +1,33 @@
 /**
- * Cache storage abstraction for the orchestrator.
+ * Pluggable cache storage for the orchestrator (compiled workflow bundles,
+ * etc.). Implementations handle TTL-based expiry via lastAccessedAt.
  *
- * Provides a pluggable backend interface for storing and retrieving
- * cached data (compiled workflow bundles, etc.). Implementations
- * must handle TTL-based expiry via lastAccessedAt timestamps.
- *
- * Backends:
- *   - `S3CacheStorage` for production / multi-host deployments
- *   - `FilesystemCacheStorage` for single-host / test sandboxes
- */
-/**
- * Metadata tracked alongside each cached item.
- * Used for TTL-based expiry (based on lastAccessedAt).
+ * Backends: `S3CacheStorage` (production / multi-host) and
+ * `FilesystemCacheStorage` (single-host / test sandboxes).
  */
+/** Metadata tracked alongside each cached item; drives TTL-based expiry. */
 export interface CacheMetadata {
-    /** ISO timestamp of when the item was first stored */
+    /** ISO timestamp of the first store. */
     createdAt: string;
-    /** ISO timestamp of when the item was last accessed (read or touched) */
+    /** ISO timestamp of the last access (read or touch). */
     lastAccessedAt: string;
 }
 /**
- * Pluggable cache storage interface.
- *
- * All operations are async. Implementations must handle TTL-based expiry:
- * an item is considered expired when (now - lastAccessedAt) > ttlMs.
- * Expired items are cleaned up lazily on access.
+ * Pluggable cache storage. An item is expired when
+ * (now - lastAccessedAt) > ttlMs; expired items are cleaned up lazily on access.
  */
 export interface CacheStorage {
-    /** Store a value under the given key. Overwrites if key already exists. */
+    /** Store a value; overwrites an existing key. */
     put(key: string, data: Buffer | string): Promise<void>;
     /**
-     * Retrieve a value by key. Returns null if not found or expired.
-     * `ttlMsOverride` applies a per-operation TTL instead of the backend's
-     * constructor-time default (lets per-org cache TTLs override the
-     * cluster-wide default without re-constructing the backend).
+     * Retrieve a value; null if not found or expired. `ttlMsOverride` replaces
+     * the backend's constructor-time TTL for this call, so a per-org cache TTL
+     * overrides the cluster-wide default without re-constructing the backend.
      */
     get(key: string, ttlMsOverride?: number): Promise<Buffer | null>;
     /**
-     * Check if a key exists and is not expired, without retrieving data.
-     * `ttlMsOverride` applies a per-operation TTL (see `get`).
+     * Whether a key exists and is not expired, without retrieving data.
+     * `ttlMsOverride`: see `get`.
      */
     has(key: string, ttlMsOverride?: number): Promise<boolean>;
     /** Delete a key. Returns true if the key existed (even if expired). */
@@ -46,68 +35,58 @@ export interface CacheStorage {
     /** Update lastAccessedAt to now, refreshing the TTL. No-op if key doesn't exist. */
     touch(key: string): Promise<void>;
     /**
-     * Get a pre-signed download URL for the cached item.
-     * Returns null if not found or expired.
-     * `ttlMsOverride` applies a per-operation TTL (see `get`).
+     * A pre-signed download URL; null if not found or expired.
+     * `ttlMsOverride`: see `get`.
      */
     getUrl(key: string, ttlMsOverride?: number): Promise<string | null>;
     /**
-     * The validity window, in seconds, of the pre-signed download URLs this
-     * backend mints via `getUrl` — i.e. how long after minting a `getUrl` link
-     * still authorizes a download before its signature expires. This is the
-     * signature expiry, NOT the artifact-retention TTL; consumers that render a
-     * `getUrl` link (e.g. the dashboard artifacts panel) use it to refresh the
-     * link before it stops working.
+     * How long, in seconds, a `getUrl` link authorizes a download before its
+     * signature expires. This is the signature expiry, NOT the
+     * artifact-retention TTL; consumers that render a `getUrl` link (e.g. the
+     * dashboard artifacts panel) use it to refresh the link in time.
      */
     presignedGetTtlSeconds(): number;
     /**
-     * Generate a pre-signed PUT URL for direct agent upload.
-     * Uses the external endpoint (container-routable) when configured.
+     * A pre-signed PUT URL for direct agent upload, signed with the external
+     * (container-routable) endpoint when configured.
      */
     getUploadUrl(key: string): Promise<string>;
     /**
-     * Generate a pre-signed PUT URL using the internal endpoint.
-     * Use this when the uploader is on the host (e.g., CLI uploads),
-     * not in a container. Falls back to getUploadUrl() when no
-     * external endpoint is configured.
+     * The pre-signed PUT URL a developer machine running `kici run remote`
+     * uploads the overlay to. The S3 backend signs it with
+     * `KICI_STORAGE_UPLOAD_ENDPOINT`, else the agent-facing
+     * `KICI_STORAGE_EXTERNAL_ENDPOINT`, else `KICI_STORAGE_ENDPOINT`.
      */
     getInternalUploadUrl(key: string): Promise<string>;
     /**
-     * Set initial metadata on an object that was uploaded via pre-signed URL.
-     * Pre-signed PUT URLs cannot carry custom metadata, so this must be called
-     * after the agent confirms upload via cache.upload.complete.
-     * Sets created-at and last-accessed-at to now.
+     * Set created-at and last-accessed-at to now on an object uploaded via
+     * pre-signed URL. A pre-signed PUT cannot carry custom metadata, so call this
+     * after the agent confirms the upload via cache.upload.complete.
      */
     initMeta(key: string): Promise<void>;
     /**
-     * List object keys (relative to the configured prefix) under a sub-prefix,
-     * newest first (by createdAt/last-modified metadata; falls back to
-     * lexicographic when metadata is unavailable). Returns full cache keys
-     * (without the storage prefix). Returns an empty array when nothing matches.
+     * Full cache keys (without the storage prefix) under a sub-prefix, newest
+     * first by createdAt/last-modified metadata (lexicographic when metadata is
+     * unavailable); empty when nothing matches.
      */
     list(subPrefix: string): Promise<string[]>;
-    /** Server-side copy from one cache key to another (used for atomic temp -> final commit). */
+    /** Server-side copy between keys (used for atomic temp -> final commit). */
     copy(srcKey: string, destKey: string): Promise<void>;
     /**
-     * Read the stored metadata (createdAt + lastAccessedAt) for a key WITHOUT
-     * refreshing lastAccessedAt. Returns null when the key is missing or carries
-     * no metadata. A pure read (no TTL-expiry side effect) — used by quota
-     * eviction to order candidates by access recency.
+     * The stored metadata, read WITHOUT refreshing lastAccessedAt or any
+     * TTL-expiry side effect; null when the key is missing or has no metadata.
+     * Quota eviction uses it to order candidates by access recency.
      */
     getMetadata(key: string): Promise<CacheMetadata | null>;
     /**
-     * Byte size of the stored object, or null when the object is missing. A pure
-     * stat — no metadata write and no TTL/last-accessed side effect. Used to
-     * verify an artifact's real size server-side instead of trusting the
-     * agent-declared value.
+     * Byte size of the stored object, or null when missing. A pure stat (no
+     * metadata write, no TTL/last-accessed side effect), used to verify an
+     * artifact's real size server-side instead of trusting the agent's value.
      */
     getObjectSize(key: string): Promise<number | null>;
 }
 import type { SharedS3Config } from '@kici-dev/shared';
-/**
- * S3 backend config. Extends the generic `SharedS3Config` from
- * `@kici-dev/shared` with the cache-specific `ttlMs` knob.
- */
+/** S3 backend config: `SharedS3Config` plus the cache-specific `ttlMs`. */
 export type S3CacheStorageConfig = SharedS3Config & {
     type: 's3';
     ttlMs: number;
@@ -115,12 +94,10 @@ export type S3CacheStorageConfig = SharedS3Config & {
     uploadEndpoint?: string;
 };
 /**
- * Filesystem backend config. Stores blobs as files under `basePath` and
- * mints HMAC-signed `http://baseUrl<routePrefix>...` URLs that the
- * orchestrator's `/api/v1/cache/blob/*` route verifies before serving.
- *
- * Intended for single-host / test sandboxes where standing up an
- * S3-compatible service is overkill.
+ * Filesystem backend config. Stores blobs under `basePath` and mints
+ * HMAC-signed `http://baseUrl<routePrefix>...` URLs that the orchestrator's
+ * `/api/v1/cache/blob/*` route verifies before serving. For single-host / test
+ * sandboxes.
  */
 export interface FilesystemCacheStorageConfig {
     type: 'filesystem';
@@ -133,9 +110,6 @@ export interface FilesystemCacheStorageConfig {
     /** Per-process HMAC secret used to sign URLs. */
     signingSecret: string;
 }
-/**
- * Configuration for creating a cache storage backend. Discriminated union
- * keyed on `type` so new backends slot in without breaking consumers.
- */
+/** Cache storage backend config, discriminated on `type`. */
 export type CacheStorageConfig = S3CacheStorageConfig | FilesystemCacheStorageConfig;
 //# sourceMappingURL=types.d.ts.map

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

@@ -4,7 +4,6 @@ import type { Database } from '../db/types.js';
 import type { LogStorage } from '../reporting/log-storage.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import type { WebhookInfo } from './handler.js';
-/** Configuration for the writer. */
 export interface EventLogWriterOptions {
     /**
      * Cluster-wide fallback soft cap in bytes for payload upload (default 5 MB),
@@ -27,7 +26,6 @@ export interface EventLogOutcome {
     orgId: string;
     /** Where the delivery arrived. */
     source: EventLogSource;
-    /** Outcome status. */
     status: EventLogStatus;
     /** Workflows matched by trigger evaluation (default 0). */
     matchedCount?: number;

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

@@ -10,9 +10,6 @@ import type { Database, GenericWebhookSource } from '../db/types.js';
 import type { VerificationMethod } from '../providers/generic/verification.js';
 import { type UniversalGitConfig } from '../providers/universal-git/config.js';
 import { type LocalSourceConfig } from '../providers/local/local-source-config.js';
-/**
- * Input for creating a new generic webhook source.
- */
 interface CreateSourceInput {
     orgId: string;
     name: string;
@@ -54,8 +51,6 @@ type UpdateSourceInput = Partial<Omit<CreateSourceInput, 'orgId' | 'gitConfig' |
     localConfig?: LocalSourceConfig | null;
 };
 /**
- * Generic webhook source manager.
- *
  * Manages CRUD operations for generic_webhook_sources table.
  * Sources are identified by routing keys with format `generic:<orgId>:<sourceId>`.
  */
@@ -63,7 +58,6 @@ export declare class GenericSourceManager {
     private readonly db;
     constructor(db: Kysely<Database>);
     /**
-     * Create a new generic webhook source.
      * Generates a routing key in format `generic:<orgId>:<sourceId>`.
      */
     create(input: CreateSourceInput): Promise<GenericWebhookSource>;
@@ -79,9 +73,6 @@ export declare class GenericSourceManager {
      * Get a source by org ID and name (unique lookup, excludes soft-deleted).
      */
     getByOrgAndName(orgId: string, name: string): Promise<GenericWebhookSource | null>;
-    /**
-     * List all sources for an org.
-     */
     list(orgId: string, includeDeleted?: boolean): Promise<GenericWebhookSource[]>;
     /**
      * List all enabled, non-deleted sources matching a provider type.
@@ -113,9 +104,6 @@ export declare class GenericSourceManager {
      * `git_config.repoBasePath`) under the source's routing key.
      */
     listLocalSources(): Promise<GenericWebhookSource[]>;
-    /**
-     * Update a source's configuration.
-     */
     update(id: string, input: UpdateSourceInput): Promise<GenericWebhookSource | null>;
     /**
      * Soft delete a source (sets deleted_at timestamp).
@@ -125,19 +113,12 @@ export declare class GenericSourceManager {
      * Hard delete a source (removes the row entirely).
      */
     hardDelete(id: string): Promise<void>;
-    /**
-     * Enable a source.
-     */
     enable(id: string): Promise<void>;
-    /**
-     * Disable a source.
-     */
     disable(id: string): Promise<void>;
     /**
      * Check if a request is a duplicate within the dedup window.
      * Uses the kici_events table for idempotency checking.
      *
-     * @param sourceId - Source ID
      * @param idempotencyKey - Idempotency key from header or payload
      * @returns true if this is a duplicate request
      */
@@ -147,14 +128,12 @@ export declare class GenericSourceManager {
      * Inserts a `__dedup:<key>` event into kici_events so that
      * checkIdempotency can detect retries within the dedup window.
      *
-     * @param sourceId - Source ID
      * @param idempotencyKey - Idempotency key from header or payload
      */
     markIdempotency(sourceId: string, idempotencyKey: string): Promise<void>;
     /**
      * Check if payload size is within the source's limit.
      *
-     * @param sourceId - Source ID
      * @param bodyLength - Length of the request body in bytes
      * @returns Whether the payload is allowed and what the max is
      */

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

@@ -26,7 +26,6 @@ export type AdmitResult = {
     admitted: false;
     reason: IngestShedReason;
 };
-/** Per-call admission options. */
 export interface AdmitOptions {
     /**
      * When true (HTTP direct ingress), a request that cannot be admitted

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

@@ -66,8 +66,8 @@ export declare class RelayBufferRegistry {
     /** Number of in-flight reassembly buffers. Useful for metrics + tests. */
     get size(): number;
     /**
-     * Begin a new reassembly stream. Allocates an entry keyed by `meta.messageId`
-     * (passed through the meta object's caller — actually keyed externally below).
+     * Begin a new reassembly stream. Allocates an entry keyed by the `messageId`
+     * argument, not by a field of `meta`.
      *
      * Returns an error if `messageId` is already in flight (Platform sent two
      * `start` frames with the same id, indicates a sender bug or abuse).

package/dist/webhook/verify-inbound.d.ts

@@ -58,7 +58,6 @@ export interface VerifyInboundInput {
     /** Inbound HTTP request client IP, for IP-allowlist verification. */
     clientIp: string | null;
 }
-/** Dependencies the dispatcher reads from. */
 export interface VerifyInboundDeps {
     /** Kysely DB handle for `sources` table lookups (github sources). */
     db: Kysely<Database>;

package/dist/worker/in-memory-execution-tracker.d.ts

@@ -1,13 +1,8 @@
 /**
- * In-memory execution tracker for worker nodes.
- *
- * Workers have no database access. This lightweight implementation
- * satisfies the same interface subset that the dispatcher and processor
- * call (onExecutionStarted, onJobStatus, onStepStatus, getRunStatus),
- * allowing those subsystems to work unchanged on workers.
- *
- * Optionally forwards status updates via a callback for coordinator relay,
- * and maintains a ring buffer of recently completed jobs for /status.
+ * Execution tracker for DB-less worker nodes. It implements the subset the
+ * dispatcher and processor call (onExecutionStarted, onJobStatus, onStepStatus,
+ * getRunStatus), so they run unchanged on workers. It can forward status updates
+ * to the coordinator, and keeps a ring buffer of recently completed jobs for /status.
  */
 import type { ObserverRegistry } from '../ws/observer-registry.js';
 /** A status update forwarded to the coordinator. */
@@ -21,7 +16,6 @@ export interface StatusUpdate {
     timestamp: number;
     data?: Record<string, unknown>;
 }
-/** A completed job entry in the ring buffer. */
 interface CompletedJobInfo {
     runId: string;
     jobId: string;
@@ -32,21 +26,19 @@ interface CompletedJobInfo {
     durationMs: number;
 }
 interface InMemoryExecutionTrackerOptions {
-    /** Callback to forward status updates to coordinator via P2P. */
+    /** Forwards status updates to the coordinator over P2P. */
     onStatusForward?: (update: StatusUpdate) => void;
-    /** Maximum number of recent completed jobs to keep. Default: 50. */
+    /** Default: 50. */
     recentJobsLimit?: number;
-    /** Optional observer registry for broadcasting to CLI observers. */
+    /** Broadcasts to CLI observers. */
     observerRegistry?: ObserverRegistry;
 }
-/** In-memory state for a single job within a run. */
 interface JobState {
     name: string;
     status: string;
     startedAt?: number;
     completedAt?: number;
 }
-/** In-memory state for a single execution run. */
 interface RunState {
     workflowName: string;
     provider: string;
@@ -63,35 +55,21 @@ export declare class InMemoryExecutionTracker {
     private readonly runs;
     private readonly recentJobs;
     constructor(options: InMemoryExecutionTrackerOptions);
-    /**
-     * Record a new execution run with its initial jobs.
-     * Signature matches ExecutionTracker.onExecutionStarted (positional args).
-     */
+    /** Positional signature matches ExecutionTracker.onExecutionStarted. */
     onExecutionStarted(runId: string, workflowName: string, provider: string, repoIdentifier: string, ref: string, sha: string, _deliveryId: string | null, _providerContext: Record<string, unknown>, _triggerDecision: Record<string, unknown> | null, jobs: Array<{
         jobId: string;
         jobName: string;
         matrixValues?: Record<string, unknown>;
     }>): Promise<void>;
-    /**
-     * Update job status. Forwards to coordinator callback if configured.
-     */
     onJobStatus(runId: string, jobId: string, status: string, timestamp: number, agentId?: string, data?: Record<string, unknown>): Promise<void>;
-    /**
-     * Update step status. Forwards to coordinator callback if configured.
-     */
     onStepStatus(runId: string, jobId: string, stepIndex: number, stepName: string, status: string, timestamp: number, data?: Record<string, unknown>): Promise<void>;
     /**
      * Forget a job this worker gave up or was told to stop before it ran. Nothing is
      * forwarded: the coordinator that owns the run already decided what happens to it.
      */
     dropJob(runId: string, jobId: string): void;
-    /**
-     * Get the current status of a run.
-     */
     getRunStatus(runId: string): RunState | null;
-    /**
-     * Get recent completed jobs (most recent first).
-     */
+    /** Most recent first. */
     getRecentJobs(): CompletedJobInfo[];
     private addToRecentJobs;
 }

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

@@ -1,13 +1,7 @@
 /**
- * In-memory job queue for worker nodes.
- *
- * Workers receive jobs directly from the coordinator via P2P dispatch,
- * not from a database queue. This implementation satisfies the JobQueue
- * interface with ephemeral in-memory storage, allowing the dispatcher
- * subsystem to work unchanged on workers.
- *
- * Jobs enqueued here (when no agent is immediately available) are stored
- * in memory and dequeued when an agent with matching labels connects.
+ * Ephemeral JobQueue for worker nodes, which get jobs from the coordinator over
+ * P2P rather than a database queue, so the dispatcher runs unchanged on workers.
+ * A job enqueued with no agent available waits here until a matching agent connects.
  */
 import { DispatchQueueStatus, type QueuedJobInput, type QueuedJob } from '../queue/job-queue.js';
 export declare class InMemoryJobQueue {
@@ -17,10 +11,9 @@ export declare class InMemoryJobQueue {
     /** Per-job re-dispatch counter (parity with dispatch_queue.dispatch_attempts). */
     private readonly attempts;
     /**
-     * Jobs the owning coordinator stopped (a cancel), or that this worker gave back
-     * after its spawn retries ran out. A stopped job is never claimed, listed or
-     * re-pended, which is this queue's counterpart of the database queue's
-     * stopped-run guard. The mark goes with the job's entry.
+     * Jobs the owning coordinator stopped (a cancel), or this worker gave back after
+     * its spawn retries ran out. Never claimed, listed or re-pended — the counterpart
+     * of the database queue's stopped-run guard. The mark goes with the job's entry.
      */
     private readonly stopped;
     /** Stop-mark every job of `runId` (or just `jobId`), pending or dispatched. Synchronous. */
@@ -35,67 +28,46 @@ export declare class InMemoryJobQueue {
      * requeue. `requeue` already dropped a stopped job, so nothing is left to settle.
      */
     settleClaimOfStoppedRun(_jobId: string, _runId: string): Promise<boolean>;
-    /** Enqueue a job in memory and return its ID. */
     enqueue(input: QueuedJobInput): Promise<string>;
     /**
-     * Returns a generated UUID for direct-dispatch tracking, or honors the
-     * caller's pre-allocated jobId when set (cluster reroute path). The in-memory
-     * queue has no unique-key constraint, so an insert is always treated as new.
+     * Honors a pre-allocated jobId (cluster reroute) or generates one. No unique-key
+     * constraint here, so an insert is always new.
      */
     insertDispatched(input: QueuedJobInput, _agentId: string): Promise<{
         id: string;
         inserted: boolean;
     }>;
     /**
-     * Dequeue the first pending job matching the given labels.
-     *
-     * `agentMandatoryLabels` mirrors the DB-backed `JobQueue.dequeueForLabels`
-     * gate: a job is only dequeued when its `runsOnLabels` includes every
-     * label in the gate set. Empty (default) is a no-op for static / non-scaler
-     * agents — the gate trivially passes.
+     * First pending job matching the labels. `agentMandatoryLabels` mirrors the
+     * `JobQueue.dequeueForLabels` gate; empty (static / non-scaler agents) passes.
      */
     dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[], _agentId?: string, canServe?: (job: QueuedJob) => boolean): Promise<QueuedJob | null>;
     /**
-     * Dequeue a specific pending job by id, validating that the agent's labels
-     * still satisfy the job's runsOn / excludeLabels and the agent's
-     * `mandatoryLabels` gate. Mirrors the DB-backed `JobQueue.dequeueById`
-     * used by `Dispatcher.dispatchBoundJob()` when a scaler-managed agent
-     * registers and the scaler had bound a queued jobId to that agent at
-     * spawn time. Returns null if the job is missing, no longer Pending,
-     * labels no longer match, or the agent's gate is not satisfied.
+     * Mirrors `JobQueue.dequeueById`, which `Dispatcher.dispatchBoundJob()` calls
+     * when a scaler agent registers for the jobId it was spawned for. Null when the
+     * job is missing, not Pending, or fails {@link matchesGate}.
      */
     dequeueById(jobId: string, agentLabels: string[], agentMandatoryLabels?: string[]): Promise<QueuedJob | null>;
     /**
-     * Dequeue the oldest pending job pinned to a specific agent. Mirrors the
-     * DB-backed `JobQueue.dequeueByPinnedAgent` that `Dispatcher.onAgentAvailable`
-     * calls — host-fanout children pinned to THIS agent drain before the generic
-     * label drain. Like the DB version, a pinned job relaxes the label-subset
-     * gate (the agent is its designated runner) and only the JS regex
-     * post-filter is applied.
+     * Oldest pending job pinned to the agent; mirrors `JobQueue.dequeueByPinnedAgent`
+     * (host-fanout children drain before the label drain). A pinned job skips the
+     * label-subset gate; only the JS regex post-filter applies.
      *
-     * The worker receives jobs via direct P2P dispatch and does not currently
-     * pin jobs to agents, so in practice no in-memory job carries a
-     * `pinnedAgentId` and this returns null — `onAgentAvailable` then falls back
-     * to `dequeueForLabels`. Implementing it (rather than leaving it undefined)
-     * is mandatory: `Dispatcher.onAgentAvailable` invokes it unconditionally, so
-     * its absence threw `TypeError: this.queue.dequeueByPinnedAgent is not a
-     * function` as an unhandled rejection that crashed the worker.
+     * Workers do not pin jobs, so this returns null in practice and
+     * `onAgentAvailable` falls back to `dequeueForLabels`. It must exist:
+     * `Dispatcher.onAgentAvailable` calls it unconditionally, and a missing method
+     * is an unhandled `TypeError` that crashes the worker.
      */
     dequeueByPinnedAgent(agentId: string, agentLabels?: string[]): Promise<QueuedJob | null>;
-    /** Return count of pending jobs. */
     getDepth(): Promise<number>;
     /** No-op — the job is already tracked in `dispatched` from dequeue. */
     markDispatched(_jobId: string, _agentId: string): Promise<void>;
-    /** Drop the dispatched entry — the job reached a terminal state. */
     markFailed(jobId: string, _reason: string): Promise<void>;
-    /** Drop the dispatched entry — the job completed. */
     markCompleted(jobId: string): Promise<void>;
-    /** No-op. */
     markRecovering(_jobId: string): Promise<void>;
     /**
-     * No-op. The worker's dispatch-ack deadline lives entirely in the
-     * in-memory timer; HA-safe persistence belongs to the coord's DB-backed
-     * queue, not the worker's in-memory queue.
+     * No-op: the worker's ack deadline lives in its in-memory timer; HA-safe
+     * persistence belongs to the coordinator's DB queue.
      */
     setAckDeadline(_jobId: string, _deadline: Date, _agentId: string): Promise<void>;
     /** No-op (see setAckDeadline). */
@@ -114,54 +86,42 @@ export declare class InMemoryJobQueue {
         agentId: string | null;
     }>>;
     /**
-     * Return a dispatched job to pending for re-dispatch, bumping its attempt
-     * counter unless `countAttempt` is false. Mirrors the DB-backed
-     * `JobQueue.requeue`. Returns the attempt count, or null when the job is
-     * not currently dispatched. A stopped job is dropped instead of re-pended, and
-     * also returns null.
+     * Mirrors `JobQueue.requeue`: re-pend a dispatched job, bumping attempts unless
+     * `countAttempt` is false. Returns the attempt count, or null when the job is not
+     * dispatched or is stopped (a stopped job is dropped instead).
      */
     requeue(jobId: string, opts?: {
         countAttempt?: boolean;
     }): Promise<number | null>;
     /**
-     * The sealed-secrets back-off of `JobQueue.isDeferredUnopenable`. A worker's
-     * in-memory jobs are never sealed, so none is ever deferred; the dispatcher's
-     * requeue redispatch asks every queue this.
+     * `JobQueue.isDeferredUnopenable`'s sealed-secrets back-off, which the requeue
+     * redispatch asks every queue. Worker jobs are never sealed, so never deferred.
      */
     isDeferredUnopenable(_jobId: string): boolean;
-    /** Full job lookup across pending and dispatched jobs. */
+    /** Pending or dispatched. */
     getFullJobById(jobId: string): Promise<QueuedJob | null>;
-    /** Return all pending jobs. */
     getPendingJobs(): Promise<QueuedJob[]>;
     /**
-     * Oldest-first listing of pending jobs, capped at `limit` — the worker-side
-     * twin of `JobQueue.listPending`. The dispatcher's capacity-freed re-drive
-     * (`retryPendingScaleRequests`) reads it on every worker whose scaler frees
-     * a slot; `worker-core` wires that hook exactly as the coordinator does.
-     * Insertion order is the enqueue order, which is what `created_at ASC` gives
-     * the DB queue.
+     * Twin of `JobQueue.listPending`: oldest first (insertion order = `created_at
+     * ASC`), capped at `limit`. `retryPendingScaleRequests` reads it on every worker
+     * whose scaler frees a slot; `worker-core` wires that hook as the coordinator does.
      */
     listPending(limit: number): Promise<QueuedJob[]>;
-    /** Always returns empty array. */
     getDispatchedJobIdsByRunId(_runId: string): Promise<string[]>;
-    /** Lookup across pending and dispatched jobs (id / runId / status). */
+    /** Pending or dispatched. */
     getJobById(jobId: string): Promise<{
         id: string;
         runId: string;
         status: DispatchQueueStatus;
     } | null>;
-    /** Always returns false. */
     markFailedIfRecovering(_jobId: string, _reason: string): Promise<boolean>;
-    /** Always returns false. */
     markDispatchedIfRecovering(_jobId: string, _agentId: string): Promise<boolean>;
-    /** Always returns empty array. */
     getJobsByStatus(_status: DispatchQueueStatus): Promise<Array<{
         id: string;
         runId: string;
         status: DispatchQueueStatus;
         agentId: string | null;
     }>>;
-    /** No-op — nothing to expire. */
     markExpired(): Promise<number>;
 }
 //# sourceMappingURL=in-memory-job-queue.d.ts.map

package/dist/worker/peer-outbox.d.ts

@@ -16,14 +16,11 @@ export declare class PeerOutbox {
     loadFromDisk(): Promise<void>;
     enqueue(coordUrl: string, message: JobProgress): Promise<void>;
     /**
-     * Synchronous, durably-fsynced enqueue. The terminal job status is on disk
-     * before this method returns — there is no async window in which an
-     * un-flushed write can be lost if the worker process is killed moments
-     * later (e.g. a worker orchestrator that crashes during microVM teardown
-     * right after the job completes). The asynchronous {@link enqueue} is
-     * fire-and-forget at its call site, so its fsync can be dropped when the
-     * event loop never runs again; this variant blocks the (infrequent,
-     * once-per-job-terminal) call path until the bytes are durable instead.
+     * Synchronous, fsynced enqueue: the terminal job status is on disk before this
+     * returns, so a worker killed moments later (e.g. crashing during microVM
+     * teardown) cannot lose it. The async {@link enqueue} is fire-and-forget at its
+     * call site, so its fsync is lost when the event loop never runs again; this
+     * variant blocks the once-per-job-terminal path until the bytes are durable.
      */
     enqueueSync(coordUrl: string, message: JobProgress): void;
     ack(coordUrl: string, runId: string, jobId: string): Promise<void>;

package/dist/worker/reroute-dispatch.d.ts

@@ -1,10 +1,8 @@
 /**
- * Worker-mode dispatch of a job rerouted from a coordinator.
- *
- * A worker holds no provider credentials. The coordinator pre-resolves the
- * clone tokens and carries them on the `job.reroute` message. The worker keeps
- * them in the queued job's config and turns them into the agent's clone auth
- * at dispatch time.
+ * Worker-mode dispatch of a job rerouted from a coordinator. A worker holds no
+ * provider credentials: the coordinator pre-resolves clone tokens onto the
+ * `job.reroute` message, and the worker keeps them in the queued job's config and
+ * turns them into the agent's clone auth at dispatch time.
  */
 import type { JobReroute } from '@kici-dev/engine';
 /** The queued job's config for a reroute message, carrying the pre-resolved clone tokens. */