@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/sources/source-manager.d.ts

@@ -12,9 +12,6 @@ import type pg from 'pg';
 import { ProviderRegistry } from '../provider-registry.js';
 import type { ProviderSource } from '../entry-helpers.js';
 import type { SourceStore } from './source-store.js';
-/**
- * Options for creating a SourceManager.
- */
 export interface SourceManagerOptions {
     /** Raw pg pool for LISTEN/NOTIFY subscriber. */
     pool: pg.Pool;

package/dist/sources/source-store.d.ts

@@ -9,9 +9,6 @@
 import { type Kysely } from 'kysely';
 import type { Database, Source } from '../db/types.js';
 import type { PgSecretStore } from '../secrets/pg-secret-store.js';
-/**
- * Parameters for adding a new source.
- */
 export interface AddSourceParams {
     /** Provider type (e.g. 'github') */
     provider: string;
@@ -30,9 +27,6 @@ export interface AddSourceParams {
     /** Customer/org identifier for secret and environment scoping */
     customerId?: string;
 }
-/**
- * A source with its decrypted secrets.
- */
 export interface SourceWithSecrets extends Source {
     privateKey: string;
     webhookSecret?: string;
@@ -54,9 +48,6 @@ export declare class SourceStore {
      * List all sources (no secrets exposed).
      */
     listSources(): Promise<Source[]>;
-    /**
-     * Get a single source by routing key, or null if not found.
-     */
     getSource(routingKey: string): Promise<Source | null>;
     /**
      * Get a single source by its UUID primary key, or null if not found. Used by

package/dist/sources/source-validator.d.ts

@@ -1,6 +1,3 @@
-/**
- * Result of a source credential validation.
- */
 export interface ValidationResult {
     valid: boolean;
     appName?: string;

package/dist/stale-detector/all-terminal-runs.d.ts

@@ -3,22 +3,19 @@ import type { Database } from '../db/types.js';
 /**
  * Runs whose every job row is terminal while the run row is not.
  *
- * Every coordinator finalizes a run from its own in-memory view when the
- * last job it hears about finishes, and defers while a sibling still has a
- * registration window open on the run. So one shape reaches no finalizer at
- * all: the coordinator that saw the last job deferred to a live window holder,
- * and that holder then died before releasing it — its stale id reads as no
- * window, but nothing re-drives the check on the coordinator that deferred.
- * The same shape appears when a coordinator dies between its jobs going
- * terminal and its own finalization.
+ * A coordinator finalizes a run from its in-memory view when the last job it
+ * hears about finishes, but defers while a sibling holds a registration window
+ * on the run. If that holder dies before releasing it, its stale id reads as no
+ * window, yet nothing re-drives the check on the deferring coordinator. A
+ * coordinator dying between its jobs going terminal and its own finalization
+ * leaves the same shape.
  *
  * This sweep is the backstop: every job row terminal, the run row still
  * `pending` or `running`, the last completion older than the stale threshold
  * (so a normal completion in flight is not raced), and no LIVE registration
  * window holder. The caller finishes each candidate through the tracker's
- * DB-fallback completion, which is clobber-guarded and computes the status
- * from the rows — so a run a coordinator finishes in the meantime is left as
- * that coordinator wrote it.
+ * clobber-guarded DB-fallback completion, which computes the status from the
+ * rows, so a run a coordinator finishes in the meantime keeps what it wrote.
  */
 export declare function selectAllTerminalRunCandidates(db: Kysely<Database>, opts: {
     /** Runs whose last job completed before this instant qualify. */

package/dist/stale-detector/gate-deadline-detector.d.ts

@@ -1,17 +1,14 @@
 /**
- * GateDeadlineDetector: periodic DB scanner enforcing an invoke gate's own
- * job-level `timeout`.
+ * Periodic DB scanner enforcing an invoke gate's own job-level `timeout`.
  *
- * A gate runs no steps on an agent, so the agent-side job timeout can never fire
- * for it. Instead the orchestrator owns the gate deadline: this scanner finds
- * non-terminal `gate` jobs whose `timeout_ms` has elapsed since the gate began
- * summoning and fails each one. Failing the gate drives its downstream `needs`
- * cascade through the normal job-status path; the summoned source-repo runs are
- * the repos' own runs and are left untouched.
+ * A gate runs no steps on an agent, so the agent-side job timeout never fires for it;
+ * the orchestrator fails non-terminal `gate` jobs whose `timeout_ms` has elapsed since
+ * the gate began summoning. Failing drives the downstream `needs` cascade through the
+ * normal job-status path; the summoned source-repo runs are the repos' own and are left
+ * untouched.
  *
- * The gate's timeout clock is `ready_at` (when the needs scheduler released it to
- * summon), falling back to `created_at` for a root gate that never carried a
- * `ready_at`.
+ * The clock is `ready_at` (when the needs scheduler released the gate to summon),
+ * falling back to `created_at` for a root gate that never carried a `ready_at`.
  */
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -24,9 +21,9 @@ import type { ExecutionTracker } from '../reporting/execution-tracker.js';
 export declare const GATE_DEADLINE_RECENCY_WINDOW_MS: number;
 export interface GateDeadlineDetectorDeps {
     db: Kysely<Database>;
-    /** Used to fail an overdue gate through the canonical job-status path. */
+    /** Fails an overdue gate through the canonical job-status path. */
     executionTracker: Pick<ExecutionTracker, 'onJobStatus'>;
-    /** How often to scan in ms (reuses the stale-detector interval). */
+    /** Scan interval in ms (reuses the stale-detector interval). */
     scanIntervalMs: number;
 }
 export declare class GateDeadlineDetector {
@@ -35,16 +32,14 @@ export declare class GateDeadlineDetector {
     private readonly scanIntervalMs;
     private interval;
     constructor(deps: GateDeadlineDetectorDeps);
-    /** Start the detector: an immediate crash-recovery scan, then periodic scans. */
+    /** An immediate crash-recovery scan, then periodic scans. */
     start(): Promise<void>;
     stop(): void;
-    /** Find non-terminal gates past their timeout and fail each one. */
     scan(): Promise<void>;
     /**
-     * Build the SELECT for overdue gates. Extracted so a unit test can compile the
-     * exact predicate set (Kysely `.compile()`) without a live database. A gate is
-     * overdue when `coalesce(ready_at, created_at) + timeout_ms` is in the past;
-     * the recency bound keeps the scan off ancient history each tick.
+     * Extracted so a unit test can compile the exact predicate set (Kysely `.compile()`)
+     * without a live database. Overdue means `coalesce(ready_at, created_at) + timeout_ms`
+     * is in the past; the recency bound keeps each tick off ancient history.
      */
     private buildOverdueQuery;
     private failOverdueGate;

package/dist/stale-detector/reboot-deadline-sweep.d.ts

@@ -1,21 +1,18 @@
 /**
- * RebootDeadlineSweep: clears expired host-reboot-pending flags.
+ * Clears expired host-reboot-pending flags.
  *
- * When a workflow's `restartHost()` step runs, the orchestrator sets a
- * `host_roster.reboot_pending_until` deadline and holds the pinned post-restart
- * job until the host completes a reboot cycle. If the host never returns by the
- * deadline, this sweep clears the stale flag. With the flag cleared and the
- * agent still gone, the held post-restart job hits the existing dispatch-queue
- * timeout and the run fails — the "host did not return after reboot" outcome.
+ * A `restartHost()` step sets `host_roster.reboot_pending_until` and holds the pinned
+ * post-restart job until the host completes a reboot cycle. If the host misses the deadline,
+ * this clears the flag; with the agent still gone, the held job hits the dispatch-queue timeout
+ * and the run fails — the "host did not return after reboot" outcome.
  *
- * Driven by the leader-only host-roster reaper's tick (one timer, one leader),
- * so this class owns no timer of its own — just a testable `scan()`.
+ * Driven by the leader-only host-roster reaper's tick (one timer, one leader), so it owns no
+ * timer — just a testable `scan()`.
  */
 /** Narrow roster slice the sweep needs (set on the full HostRosterStore). */
 export interface RebootDeadlineRosterStore {
     /** Agent ids whose reboot-pending deadline has passed at `nowMs`. */
     listExpiredRebootPending(nowMs: number): Promise<string[]>;
-    /** Clear the reboot-pending flag for an agent. */
     clearRebootPending(agentId: string): Promise<void>;
 }
 export declare class RebootDeadlineSweep {
@@ -23,7 +20,6 @@ export declare class RebootDeadlineSweep {
     constructor(deps: {
         rosterStore: RebootDeadlineRosterStore;
     });
-    /** Clear every reboot-pending flag whose deadline has passed. */
     scan(): Promise<void>;
 }
 //# sourceMappingURL=reboot-deadline-sweep.d.ts.map

package/dist/stale-detector/stale-dispatch-candidates.d.ts

@@ -17,27 +17,20 @@ export interface StaleDispatchCandidate {
     routing_key: string | null;
 }
 /**
- * The dispatch rows that have gone unacknowledged long enough to reap.
+ * The dispatch rows that have gone unacknowledged long enough to reap. Separate from the
+ * detector so its raw-SQL predicates are asserted against a real Postgres, not a mock.
  *
- * Split out of the detector so the three predicates that decide the verdict can
- * be asserted against a real Postgres — they are raw SQL, and a mock records
- * them without evaluating them.
- *
- * - **Both bounds read the DISPATCH clock**, not the enqueue clock.
- *   `created_at` is when the job was queued, so keying on it measured "enqueued
- *   more than two minutes ago and not yet reported running" — true of every job
- *   that waited behind a busy fleet. A job claimed at 3:00 after a scaler cold
- *   start, then cloning its repo and installing dependencies, was reaped at 3:30
- *   with "dispatch never acknowledged" while the agent ran it to completion for
- *   nothing.
- * - **The COALESCE is the rolling-upgrade bridge.** A row dispatched before
- *   `dispatched_at` existed carries NULL and keeps exactly the previous
- *   behaviour. That is also what makes startup recovery's decision to spare an
- *   unknown-owner row safe: a spared orphan is still reaped here.
- * - **An acked dispatch is never reaped.** A row whose `ack_deadline` was
- *   cleared while `ack_agent_id` is stamped was acknowledged, and the ack path
- *   owns it. This scan's residual job is the never-acked, crashed-coordinator
- *   case; the heartbeat sub-scans cover a job that acked and then went quiet.
+ * - **Both bounds read the DISPATCH clock**, not the enqueue clock. `created_at` measures
+ *   "enqueued long ago and not yet running", true of every job that waited behind a busy
+ *   fleet: a job claimed after a scaler cold start would be reaped mid-clone with "dispatch
+ *   never acknowledged" while the agent ran it to completion for nothing.
+ * - **The COALESCE is the rolling-upgrade bridge.** A row dispatched before `dispatched_at`
+ *   existed carries NULL and falls back to `created_at`. That also makes startup recovery's
+ *   sparing of an unknown-owner row safe: a spared orphan is still reaped here.
+ * - **An acked dispatch is never reaped.** A row with `ack_deadline` cleared and
+ *   `ack_agent_id` stamped was acknowledged, and the ack path owns it. This scan covers the
+ *   never-acked, crashed-coordinator case; the heartbeat sub-scans cover a job that acked and
+ *   then went quiet.
  */
 export declare function selectStaleDispatchCandidates(db: Kysely<Database>, threshold: Date, timeBound: Date): Promise<StaleDispatchCandidate[]>;
 //# sourceMappingURL=stale-dispatch-candidates.d.ts.map

package/dist/stale-detector/stale-run-detector.d.ts

@@ -1,22 +1,18 @@
 /**
- * StaleRunDetector: periodic DB scanner for stale execution jobs.
+ * Periodic DB scanner that marks jobs whose heartbeats stopped (agent died, network
+ * partition, container killed) as timed_out_stale, and fails dispatch_queue entries
+ * that were dispatched but never acknowledged.
  *
- * Detects jobs that have stopped sending heartbeats (agent died, network partition,
- * container killed, etc.) and marks them as timed_out_stale. Also detects stale
- * dispatch_queue entries that were dispatched but never acknowledged.
- *
- * Key behaviors:
- * - Immediate startup scan for crash recovery (finds stale jobs from before restart)
- * - Periodic scans at configurable interval (default 60s)
- * - Uses timed_out_stale as distinct DB status (not just 'failed')
- * - Optimistic concurrency: WHERE status='running' prevents race with agent completion
- * - Does NOT call executionTracker.onJobStatus() to avoid redundant DB writes
- * - Updates in-memory state and calls completeRunIfAllJobsTerminal for run completion
+ * - Scans once at startup for crash recovery, then every scan interval (default 60s).
+ * - timed_out_stale is a distinct DB status, not 'failed'.
+ * - Optimistic concurrency: WHERE status='running' prevents a race with agent completion.
+ * - Does NOT call executionTracker.onJobStatus(), to avoid redundant DB writes; it
+ *   updates in-memory state and calls completeRunIfAllJobsTerminal instead.
  * - Finishes a run whose every job is terminal but whose finalizer never ran
  *   (a coordinator that died mid-way, or a registration-window holder that
- *   died after a sibling deferred to it)
- * - Force-terminates stale agents via scaler manager
- * - Updates GitHub check runs with timed_out conclusion
+ *   died after a sibling deferred to it).
+ * - Force-terminates stale agents via the scaler manager and completes their GitHub
+ *   check runs as timed_out.
  */
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -39,18 +35,17 @@ export interface StaleRunDetectorDeps {
     dispatcher: Dispatcher;
     registry: AgentRegistry;
     /**
-     * Peer registry used to defer failing a job that was rerouted to a remote
-     * worker peer while that peer is still connected — its terminal status may
-     * still be replayed from the worker's durable outbox.
+     * Defers failing a job rerouted to a remote worker peer while that peer is still
+     * connected — its terminal status may still be replayed from the worker's durable outbox.
      */
     peerRegistry: PeerRegistry;
-    /** Reader for fleet-wide cluster tunables (reroute flap-grace override). */
+    /** Fleet-wide cluster tunables (reroute flap-grace override). */
     clusterSettings: ClusterSettingsReader;
     /** Cluster default for the reroute flap-grace window (config.rerouteFlapGraceMs). */
     rerouteFlapGraceFallbackMs: number;
-    /** Threshold in ms after which a job is considered stale. Default: heartbeatIntervalMs * multiplier */
+    /** Ms after which a job is stale. Default: heartbeatIntervalMs * multiplier */
     staleThresholdMs: number;
-    /** How often to scan for stale jobs in ms. Default: 60_000 */
+    /** Scan interval in ms. Default: 60_000 */
     scanIntervalMs: number;
     /**
      * How stale a `cluster_instances` heartbeat may be and still read as live,
@@ -58,42 +53,37 @@ export interface StaleRunDetectorDeps {
      * {@link instanceLivenessGraceMs} at the default recovery grace period.
      */
     instanceLivenessGraceMs?: number;
-    /** Held run store for expiring overdue held runs. Optional -- if not set, held run cleanup is skipped. */
+    /** Expires overdue held runs. If not set, held run cleanup is skipped. */
     heldRunStore?: HeldRunStore;
-    /** Step-approval bridge — notified when a step-scoped hold expires so the waiting agent fails the step. Optional. */
+    /** Notified when a step-scoped hold expires, so the waiting agent fails the step. */
     stepApprovalBridge?: StepApprovalBridge;
-    /** Fail a whole run when a job/workflow-scoped approval hold expires. Optional. */
+    /** Fails a whole run when a job/workflow-scoped approval hold expires. */
     failRun?: (runId: string, reason: string) => Promise<void>;
     /**
-     * Resume a workflow whose install-gate wait-timer hold has elapsed. Wired to
-     * the same `resumeWorkflow` path as reviewer approvals. Optional -- if not
-     * set, wait-timer workflow holds are not auto-released.
+     * Resumes a workflow whose install-gate wait-timer hold has elapsed, via the same
+     * `resumeWorkflow` path as reviewer approvals. If not set, wait-timer workflow holds
+     * are not auto-released.
      */
     onWorkflowRelease?: (signal: ReleaseSignal) => Promise<void>;
     /**
-     * Resume a released JOB-scoped hold by re-dispatching the job. A job-scoped
-     * wait-timer hold has a pending job context, not a pending workflow context,
-     * so it cannot go through `onWorkflowRelease`.
+     * Re-dispatches the job of a released JOB-scoped hold. Such a hold has a pending job
+     * context, not a pending workflow context, so it cannot go through `onWorkflowRelease`.
      */
     onJobRelease?: (signal: ReleaseSignal) => Promise<void>;
     /**
-     * Resolve a context by name, for the queued-concurrency sweep — it needs each
-     * group's configured `concurrency_limit` to know how many holds a freed slot
-     * lets through. `ContextStore.matchContext`.
+     * `ContextStore.matchContext`: the queued-concurrency sweep needs each group's
+     * `concurrency_limit` to know how many holds a freed slot lets through.
      */
     matchContext?: (orgId: string, name: string) => Promise<{
         concurrency_limit: number | null;
     } | null>;
-    /** Access-log writer for the orchestrator audit stream. Optional -- if not set, expiry audit rows (`held_run.expire`) are skipped. */
+    /** If not set, expiry audit rows (`held_run.expire`) are skipped. */
     accessLogWriter?: AccessLogWriter;
     /**
-     * Resolve the check poster of the provider bundle serving a routing key, so an
-     * expiring security hold's `KiCI Security` check can be completed. A function
-     * rather than the registry itself because the registry instance is replaced
-     * when sources are (re)loaded, and this detector outlives that.
-     *
-     * Optional -- if not set, an expiring security hold's check is left alone,
-     * which is the pre-existing behaviour rather than a wrong one.
+     * Resolves the check poster serving a routing key, so an expiring security hold's
+     * `KiCI Security` check can be completed. A function rather than the registry, because
+     * the registry instance is replaced when sources are (re)loaded and this detector
+     * outlives that. If not set, an expiring security hold's check is left alone.
      */
     resolveCheckStatusPoster?: ResolveCheckStatusPoster;
 }
@@ -123,123 +113,86 @@ export declare class StaleRunDetector {
     /**
      * Release queued concurrency holds whose group now has a free slot.
      *
-     * A context's concurrency gate returns `queue` when its limit is met, holding
-     * the job. Nothing released those holds: they sat pending until the expiry
-     * sweep marked them expired and their jobs never ran. This is the release
-     * half.
+     * This is the release half of a context's concurrency gate, which returns `queue` and
+     * holds the job when its limit is met; without it, holds sit pending until the expiry
+     * sweep expires them and their jobs never run.
      *
-     * Driven from the periodic scan rather than from job completion: the
-     * completion callback is constructed before the dispatcher, coordinator and
-     * context store exist, so wiring it there would mean threading four refs
-     * through a hot path. The cost is up to one scan interval of latency before a
-     * freed slot is reused, which for a throughput control is an acceptable
-     * trade — and every release still re-checks the limit, so the bound is never
-     * exceeded regardless of when the sweep runs.
+     * Driven from the periodic scan rather than from job completion: the completion
+     * callback is constructed before the dispatcher, coordinator and context store exist,
+     * so wiring it there would thread four refs through a hot path. The cost is up to one
+     * scan interval before a freed slot is reused, acceptable for a throughput control —
+     * and every release re-checks the limit, so the bound is never exceeded.
      */
     private releaseFreedConcurrencyHolds;
     /**
-     * Release wait-timer holds whose timer has elapsed, at ANY scope, and route
-     * each to the resume path its shape requires: a workflow install-gate hold
-     * rebuilds its workflow dispatch context, a job-scoped hold re-dispatches the
-     * one job it held.
+     * Release elapsed wait-timer holds at ANY scope: a workflow install-gate hold
+     * rebuilds its workflow dispatch context, a job-scoped hold re-dispatches its job.
      *
-     * Runs BEFORE `expireOverdueHolds` so a wait hold resumes rather than being
-     * failed by the expire-and-fail sweep — that sweep is not scope-filtered, so
-     * the ordering is load-bearing.
+     * Runs BEFORE `expireOverdueHolds` so a wait hold resumes rather than being failed;
+     * that sweep is not scope-filtered, so the ordering is load-bearing.
      */
     private releaseDueWaitHolds;
     /**
-     * Expire overdue approval holds. Routes each overdue hold by scope BEFORE the
-     * bulk status flip: step-scoped holds notify the waiting agent (which fails
-     * the step), job/workflow-scoped holds fail the whole run. Then the bulk
-     * `expireOverdue()` flips every overdue row to `expired`.
+     * Routes each overdue approval hold by scope BEFORE the bulk `expireOverdue()` flip:
+     * step-scoped holds notify the waiting agent (which fails the step), job/workflow-scoped
+     * holds fail the whole run.
      *
-     * Every overdue row's id is excluded from the security check's contention
-     * query for the whole loop, because `expireOverdue()` has not run yet: each
-     * of them is still `pending` in the database while its siblings are being
-     * routed, and without the exclusion a commit whose two holds both expired
-     * would see each hold refuse on account of the other and leave the check
-     * pending forever. The commits already settled are tracked so one sweep
-     * writes each shared check once.
+     * Every overdue id is excluded from the security check's contention query for the whole
+     * loop: until `expireOverdue()` runs each is still `pending`, so a commit whose two holds
+     * both expired would see each refuse on account of the other and leave the check pending
+     * forever. Settled commits are tracked so one sweep writes each shared check once.
      */
     private expireOverdueHolds;
     /**
-     * Clean up orphaned jobs left in 'recovering' state from a previous orchestrator instance.
+     * Fail jobs left in 'recovering' state by a previous orchestrator instance.
      *
-     * Recovery timers are in-memory (Dispatcher) and lost on restart. Any jobs still
-     * in 'recovering' state after a restart have no timer and no path to completion,
-     * so they must be failed immediately.
-     *
-     * Call this during startup, before the first periodic scan.
+     * Recovery timers are in-memory (Dispatcher) and lost on restart, so such jobs have
+     * no path to completion. Call during startup, before the first periodic scan.
      */
     cleanupOrphanedRecoveryJobs(): Promise<void>;
-    /**
-     * Start the stale run detector.
-     * Runs an immediate scan for crash recovery, then starts periodic scans.
-     */
+    /** Runs an immediate scan for crash recovery, then starts periodic scans. */
     start(): Promise<void>;
-    /**
-     * Stop the stale run detector.
-     */
     stop(): void;
     /**
-     * Run a single stale detection scan.
-     *
-     * Three sub-scans:
+     * Run a single stale detection scan:
      * A. Running jobs with old heartbeat (last_heartbeat_at < threshold)
      * B. Running jobs with NULL heartbeat (created_at < threshold, pre-heartbeat jobs)
      * C. Dispatched queue entries that were never acknowledged
+     * then checks run completion for affected runs.
      *
-     * After all sub-scans, checks run completion for affected runs.
-     *
-     * Note: jobs in 'recovering' state are NOT scanned -- they have their own
-     * per-job recovery timers managed by the Dispatcher.
-     * All sub-scans filter on status='running' or status='dispatched',
-     * so recovering jobs are naturally excluded.
+     * Jobs in 'recovering' state are NOT scanned: the Dispatcher owns their per-job
+     * recovery timers, and every sub-scan filters on status='running' or 'dispatched'.
      */
     scan(): Promise<void>;
     /**
      * Sub-scan F: runs left non-terminal after every job row went terminal.
      *
-     * The coordinator that saw the last job finish defers finalization while a
-     * live sibling still has a registration window open on the run; a holder
-     * that then dies leaves nothing to re-drive that check. A coordinator that
-     * dies between its jobs going terminal and its own finalization leaves the
-     * same shape. Both are finished here from the rows.
+     * Two causes, both finished here from the rows: the coordinator that saw the last job
+     * finish defers finalization while a live sibling holds a registration window open, and
+     * a holder that then dies leaves nothing to re-drive the check; or a coordinator dies
+     * between its jobs going terminal and its own finalization.
      */
     private scanAllTerminalRuns;
-    /**
-     * Sub-scan A: Find running jobs with stale heartbeats.
-     */
+    /** Sub-scan A: running jobs with stale heartbeats. */
     private scanStaleRunningJobs;
     /**
-     * Sub-scan B: Find running jobs with NULL heartbeat and old created_at.
-     * These are jobs that started before the heartbeat system existed or where
-     * the initial heartbeat was never set.
+     * Sub-scan B: running jobs with NULL heartbeat and old created_at — started before the
+     * heartbeat system existed, or the initial heartbeat was never set.
      */
     private scanStaleRunningJobsNullHeartbeat;
     /**
-     * Sub-scan C: Find dispatched entries that were never acknowledged.
+     * Sub-scan C: dispatches the agent never started — the dispatch_queue row is still
+     * 'dispatched' AND no execution_jobs row is 'running'. Once the agent reports the job
+     * running, sub-scans A and B supervise `execution_jobs.last_heartbeat_at`. Without this
+     * filter, a job whose first step legitimately exceeds the dispatch threshold (e.g. an
+     * inline `npm install` for a workflow that imports `@kici-dev/sdk`) would be marked
+     * stale before sub-scan A's heartbeat path could keep it alive.
      *
-     * Only catches dispatches that the agent never started — i.e., the
-     * dispatch_queue row is still 'dispatched' AND there is no
-     * execution_jobs row in 'running' state. When the agent has reported
-     * the job as running (so execution_jobs.status='running'), heartbeat
-     * supervision falls to sub-scans A and B, which look at
-     * `execution_jobs.last_heartbeat_at`. Without this filter, a long
-     * job whose first step legitimately exceeds the dispatch threshold
-     * (e.g. an inline `npm install` for a workflow that imports
-     * `@kici-dev/sdk`) would be marked stale here before sub-scan A's
-     * heartbeat path has a chance to keep it alive.
-     *
-     * 'queued' jobs are legitimately waiting for agents and handled by
-     * the queue timeout in {@link JobQueue.markExpired} instead.
+     * 'queued' jobs are legitimately waiting for agents; the queue timeout in
+     * {@link JobQueue.markExpired} handles them.
      */
     private scanStaleDispatchedJobs;
-    /**
-     * Mark a single running job as timed_out_stale.
-     * Shared by sub-scans A and B.
-     */
+    /** Mark a running job timed_out_stale. Shared by sub-scans A and B. */
     private markJobStale;
 }
 //# sourceMappingURL=stale-run-detector.d.ts.map

package/dist/stale-detector/workflow-deadline-detector.d.ts

@@ -1,39 +1,26 @@
 /**
- * WorkflowDeadlineDetector: periodic DB scanner enforcing the workflow-level
- * run deadline.
- *
- * A workflow `timeout` caps the whole run's wall-clock across all jobs.
- * Because jobs span multiple agents, the cap is a run-level deadline owned by
- * the orchestrator. This scanner finds non-terminal runs whose
- * `started_at + workflow_timeout_ms` has passed and cancels them through the
- * canonical run-cancel path, recording the distinct
- * TimeoutReason.workflow_timeout so the dashboard labels the run "timed out"
- * rather than a generic cancel.
+ * Periodic DB scanner enforcing the workflow `timeout`: a run-level wall-clock deadline the
+ * orchestrator owns because jobs span multiple agents. It cancels non-terminal runs past
+ * `started_at + workflow_timeout_ms` through the canonical run-cancel path with
+ * TimeoutReason.workflow_timeout, so the dashboard labels the run "timed out", not cancelled.
  */
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { JobQueue } from '../queue/job-queue.js';
 /**
- * Recency window for the deadline-bounded scan: a run stays in scope while its
- * deadline (`started_at + workflow_timeout_ms`) lapsed within this window. 24h is
- * the crash-recovery horizon — a run whose deadline lapsed while the orchestrator
- * was down for less than this is still caught by the immediate `start()` scan; a
- * deadline that lapsed longer ago is out of scope (separate stale-recovery concern).
- * The window bounds the DEADLINE, not `started_at`, so timeouts >= 24h are enforced.
+ * A run is in scope while its deadline lapsed within this window: the 24h crash-recovery
+ * horizon for the immediate `start()` scan; older lapses are a separate stale-recovery
+ * concern. It bounds the DEADLINE, not `started_at`, so timeouts >= 24h are enforced.
  */
 export declare const DEADLINE_RECENCY_WINDOW_MS: number;
 export interface WorkflowDeadlineDetectorDeps {
     db: Kysely<Database>;
-    /**
-     * Canonical "cancel this whole run with a reason" callback — the same
-     * implementation the user-initiated `kici cancel` route uses
-     * (cancelRunWithReason bound to the orchestrator's deps).
-     */
+    /** cancelRunWithReason bound to the orchestrator's deps, as the `kici cancel` route uses. */
     cancelRun: (runId: string, reason: string, options: {
         force: boolean;
     }) => Promise<unknown>;
     jobQueue: JobQueue;
-    /** How often to scan in ms. Default supplied by the caller (reuses the stale-detector interval). */
+    /** Milliseconds; the caller reuses the stale-detector interval. */
     scanIntervalMs: number;
 }
 export declare class WorkflowDeadlineDetector {
@@ -43,32 +30,17 @@ export declare class WorkflowDeadlineDetector {
     private readonly scanIntervalMs;
     private interval;
     constructor(deps: WorkflowDeadlineDetectorDeps);
-    /**
-     * Start the detector: an immediate scan (crash recovery — catch runs that
-     * blew their deadline while the orchestrator was down), then periodic scans.
-     */
+    /** An immediate scan catches deadlines that lapsed while the orchestrator was down. */
     start(): Promise<void>;
     stop(): void;
-    /**
-     * Run a single deadline scan: find non-terminal runs with a configured
-     * workflow timeout whose `started_at + workflow_timeout_ms` has passed and
-     * cancel each one.
-     */
     scan(): Promise<void>;
     /**
-     * Build the SELECT for overdue runs. Extracted so a unit test can compile the
-     * exact predicate set (Kysely `.compile()`) and assert the deadline-recency
-     * bound without a live database.
+     * Separate so a unit test can `.compile()` the exact predicates without a live database.
      *
-     * Bound the scan to runs whose DEADLINE lapsed within the recency window:
-     * overdue (deadline < now) AND recent (deadline > now - window). Bounding by
-     * the deadline (`started_at + workflow_timeout_ms`) rather than `started_at`
-     * keeps long-timeout runs (timeout >= the window, e.g. >= 24h) in scope once
-     * overdue — a `started_at > (now - window)` guard silently excluded those
-     * forever because their deadline only lapses after `started_at` has already
-     * aged past the window — while still skipping runs whose deadline passed long
-     * ago (already handled), preserving the "don't re-scan ancient history every
-     * tick" performance intent.
+     * Overdue (deadline < now) AND recent (deadline > now - window). A
+     * `started_at > (now - window)` guard would exclude timeouts >= the window forever, since
+     * their deadline lapses only after `started_at` aged past it; the deadline bound still skips
+     * long-past deadlines, so ancient history is not re-scanned every tick.
      */
     private buildOverdueQuery;
     /**