@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/reporting/execution-tracker.d.ts

@@ -1,12 +1,11 @@
 /**
  * Execution state tracker with write-through DB persistence.
  *
- * Aggregates job/step status updates from agents and persists execution
- * history to PostgreSQL. Maintains in-memory state for fast lookups
- * (job name resolution, run completion detection) with write-through
- * to the execution_runs/execution_jobs/execution_steps tables.
+ * Aggregates agent job/step status updates in memory (job name resolution, run
+ * completion detection) and writes through to the
+ * execution_runs/execution_jobs/execution_steps tables.
  *
- * Overall run status follows locked decision:
+ * Overall run status:
  * - success ONLY if ALL jobs succeed
  * - failed if ANY job fails
  * - cancelled if ANY job is cancelled (and none failed)
@@ -153,18 +152,17 @@ export interface ExecutionTrackerDeps {
      * Drop the in-process state a run leaves behind — its pending job contexts
      * and its still-open eval gates.
      *
-     * Separate from {@link ExecutionTrackerDeps.onExecutionComplete} because that
-     * callback is NOT the terminalization chokepoint it reads as. It fires on the
-     * three paths that finish a run whose jobs ran (`completeRun`, and both
-     * stale-detector arms) and on none of the paths that terminalize a run whose
-     * jobs never did — `failRun` (the expired-approval sweep and every
-     * pre-dispatch abort) and `cancelHeldRun` (an install gate rejected). Those
-     * are exactly the runs most likely to be holding a pending job context, since
-     * a context is only stored for a job that was gated rather than dispatched.
+     * Separate from {@link ExecutionTrackerDeps.onExecutionComplete}, which is NOT
+     * a terminalization chokepoint: it fires on the paths that finish a run whose
+     * jobs ran (`completeRun`, and both stale-detector arms) and on none that
+     * terminalize a run whose jobs never did — `failRun` (the expired-approval
+     * sweep and every pre-dispatch abort) and `cancelHeldRun` (an install gate
+     * rejected). Those runs are the likeliest to hold a pending job context, since
+     * a context is stored only for a job that was gated rather than dispatched.
      *
-     * Synchronous by contract: the in-memory half of the cleanup must not be
-     * deferred behind an await the caller does not hold, and the DB half is
-     * fire-and-forget inside the callback.
+     * Synchronous by contract: the in-memory half must not be deferred behind an
+     * await the caller does not hold; the DB half is fire-and-forget inside the
+     * callback.
      */
     onRunTerminalCleanup?: (runId: string) => void;
     /** Optional callback to forward step status to Platform. */
@@ -250,12 +248,11 @@ export interface ExecutionTrackerDeps {
     /** Optional job queue for cascading run failures to dispatch_queue entries. */
     jobQueue?: JobQueue;
     /**
-     * Resolves a routing key to its owning org (customer_id), used to populate
-     * `execution_runs.customer_id` at insert time so the concurrency-gate running
-     * count is scoped per tenant. Injected (bound to `(rk) => resolveOrgId(db, rk)`
-     * at construction) to keep the tracker free of a pipeline import cycle. When
-     * absent — or when a run has no routing key — the row falls back to the
-     * `'__default__'` column default (the no-source fallback org).
+     * Resolves a routing key to its owning org, stamped on
+     * `execution_runs.customer_id` at insert so the concurrency-gate running count
+     * is scoped per tenant. Injected (bound to `(rk) => resolveOrgId(db, rk)`) to
+     * avoid a pipeline import cycle. Absent, or for a run with no routing key, the
+     * row falls back to the `'__default__'` column default (the no-source org).
      */
     resolveOrgId?: (routingKey: string) => Promise<string>;
     /**
@@ -278,11 +275,9 @@ export interface ExecutionTrackerDeps {
 /**
  * The per-job fields the tracker persists to an execution_jobs row.
  *
- * Exported and shared by every registration entry point (`onExecutionStarted`,
- * `addJobsToRun`) rather than restated inline at each one: three structural
- * copies had already drifted apart on which optional fields they carried, so a
- * new column had to be added in three places or silently go unwritten from one
- * of them.
+ * Shared by every registration entry point (`onExecutionStarted`,
+ * `addJobsToRun`) rather than restated inline: inline copies drift on which
+ * optional fields they carry, so a new column silently goes unwritten from one.
  */
 export interface TrackedJobRow {
     jobId: string;
@@ -358,15 +353,11 @@ export declare class ExecutionTracker {
     /** Tracks which runs are test runs for observer broadcasting. */
     private readonly testRunIds;
     /**
-     * Per-(run, job) raw log byte accumulator.
+     * Per-(run, job) raw log bytes: runId -> jobId -> bytes.
      *
-     * Populated from the agent-reported `logBytesStreamed` field on terminal
-     * `step.status` messages and folded into `execution_jobs.log_bytes` when
-     * the job reaches terminal state. The per-run total is then computed by
-     * summing the per-job entries and written into `execution_runs.log_bytes`
-     * at run completion. Deleted on run prune to avoid Map growth.
-     *
-     * Map shape: runId -> jobId -> bytes.
+     * Fed by `logBytesStreamed` on terminal `step.status` messages, written to
+     * `execution_jobs.log_bytes` at job terminal state and summed into
+     * `execution_runs.log_bytes` at run completion. Deleted on run prune.
      */
     private readonly jobLogBytes;
     /** Callback fired when a job's needs are satisfied and it's ready for dispatch. */
@@ -384,10 +375,8 @@ export declare class ExecutionTracker {
      */
     setOnJobReadyCallback(cb: (runId: string, jobName: string) => Promise<void>): void;
     /**
-     * Record a new execution run with its initial jobs.
-     *
-     * Inserts execution_runs and execution_jobs rows in the DB and
-     * sets up in-memory tracking state.
+     * Record a new execution run with its initial jobs: inserts the
+     * execution_runs and execution_jobs rows and sets up in-memory state.
      */
     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: TrackedJobRow[], routingKey?: string, 
     /** Secret context names dispatched with jobs (for context-disable job lookup). */
@@ -467,21 +456,18 @@ export declare class ExecutionTracker {
      * Cancel job rows just registered under a run that has already stopped.
      *
      * A job registers after its dispatch, so a cancel landing in between leaves
-     * the run terminal while the job's row is written `pending`. The queue
-     * refuses that job's dispatch (`JobQueue.insertDispatched`), so no agent
-     * will ever report on it: its row is cancelled here, as the cancel cancels
-     * the queued jobs it can see.
+     * the run terminal and the job row `pending`. The queue refuses that dispatch
+     * (`JobQueue.insertDispatched`), so no agent will report on it; the row is
+     * cancelled here, as the cancel cancels the queued jobs it can see.
      */
     private cancelJobsOfStoppedRun;
     /**
-     * Find the synthetic needs-pending job ID for a given job name in a run.
-     * Used by dispatchReadyJob to locate the placeholder entry before replacing it.
+     * Find the synthetic needs-pending job ID that dispatchReadyJob replaces.
      *
-     * Cluster correctness: the synthetic row is inserted by the peer that
-     * ingested the webhook. In an HA cluster `dispatchReadyJob` can fire on a
-     * different peer whose in-memory map has no entry for this run. Fall back
-     * to the DB so the leftover synthetic row gets cleaned up regardless of
-     * which peer owns the downstream dispatch.
+     * Cluster correctness: the peer that ingested the webhook inserts the
+     * synthetic row, but `dispatchReadyJob` can fire on a peer whose in-memory map
+     * has no entry for this run. The DB fallback cleans up the synthetic row
+     * whichever peer owns the downstream dispatch.
      */
     findSyntheticJobId(runId: string, jobName: string): Promise<string | undefined>;
     /**
@@ -502,28 +488,23 @@ export declare class ExecutionTracker {
      * Whether a rerouted job has visibly started, read from the shared
      * `execution_jobs` row rather than from a relayed progress frame.
      *
-     * The coordinator's spawn-window backstop learns about progress from
-     * `job.progress`, which only a WORKER peer sends — a worker has no database,
-     * so relaying is its only channel. A peer COORDINATOR writes the job's status
-     * straight into this table instead, so silence on the wire says nothing about
-     * whether the job is running, and the backstop would cancel a healthy job.
+     * The spawn-window backstop learns progress from `job.progress`, which only a
+     * WORKER peer (no database) sends. A peer COORDINATOR writes the status
+     * straight into this table, so wire silence says nothing and the backstop
+     * would cancel a healthy job.
      *
-     * False when no row exists yet (the peer has not started the job) and when the
-     * row is still `pending`; the `started_at` half covers a status that has
-     * already moved on to a terminal value.
+     * False when no row exists yet or the row is still `pending`; the
+     * `started_at` half covers a status already moved on to a terminal value.
      */
     hasJobStarted(runId: string, jobId: string): Promise<boolean>;
     /**
-     * Whether a job has reached a terminal state in the shared `execution_jobs`
-     * row.
+     * Whether the shared `execution_jobs` row records a terminal state.
      *
-     * The companion read to {@link hasJobStarted}: a peer COORDINATOR runs a
-     * rerouted job against this same table and relays no terminal `job.progress`,
-     * so the row is the only signal the routing coordinator gets that the job is
-     * over and its reroute tracking can be released.
+     * Companion to {@link hasJobStarted}: a peer COORDINATOR relays no terminal
+     * `job.progress`, so the row is the routing coordinator's only signal that the
+     * job is over and its reroute tracking can be released.
      *
-     * False when no row exists yet — an absent row is a job that has not started,
-     * never a finished one.
+     * False when no row exists — an absent row is a job not yet started.
      */
     isJobTerminal(runId: string, jobId: string): Promise<boolean>;
     /**
@@ -543,14 +524,13 @@ export declare class ExecutionTracker {
      * (`onJobStatus`, `addJobsToRun`) so a status reply cannot interleave with the
      * synthetic→real job swap and wedge the run in `running`.
      *
-     * The lock is **reentrant**: three paths re-enter a locked method within the
-     * same async context for the same runId — onJobStatus → scheduler hook →
+     * The lock is **reentrant**: these paths re-enter a locked method in the same
+     * async context for the same runId — onJobStatus → scheduler hook →
      * dispatchReadyJob → addJobsToRun; onJobStatus → enforceSchedulerInvariant →
-     * onJobStatus; runSchedulerHook → onJobStatus (skip). A non-reentrant mutex
-     * would deadlock on these, so a context that already holds the runId's lock
-     * (tracked via `heldRunLocks`) runs `fn` inline. A genuinely concurrent caller
-     * for the same runId (a separate WS message) is a different async context and
-     * correctly waits. All reentrant paths are same-runId, so there is no
+     * onJobStatus; runSchedulerHook → onJobStatus (skip). A context already
+     * holding the runId's lock (`heldRunLocks`) runs `fn` inline instead of
+     * deadlocking; a concurrent caller (a separate WS message) is a different async
+     * context and waits. Reentrant paths are all same-runId, so there is no
      * cross-run lock-ordering deadlock.
      */
     private withRunLock;
@@ -558,14 +538,8 @@ export declare class ExecutionTracker {
     /** Synthetic job ID to replace (e.g. needs-pending-deploy-{uuid}). */
     replaceSyntheticId?: string): Promise<void>;
     private addJobsToRunImpl;
-    /**
-     * Mark a run as a test run for observer broadcasting.
-     * Called by the test pipeline after creating the execution run.
-     */
+    /** Mark a run as a test run for observer broadcasting (called by the test pipeline). */
     markTestRun(runId: string): void;
-    /**
-     * Check if a run is a test run.
-     */
     isTestRun(runId: string): boolean;
     /**
      * Update job status within a run.
@@ -579,30 +553,26 @@ export declare class ExecutionTracker {
     /**
      * Whether this coordinator may finalize the run now.
      *
-     * The in-memory job map is only this coordinator's view: a run rehydrated
-     * from the database holds just the jobs its own agents reported, and even
-     * the run's owner holds a sibling-claimed job at the status it last heard.
-     * So once the map reads complete, the shared `execution_jobs` rows are
-     * folded in ({@link syncRunJobsFromRows}) and the check is repeated over the
-     * whole set — a job another coordinator is still running keeps the run
-     * open, and the status computed afterwards covers every job, not a subset.
+     * The in-memory map is only this coordinator's view: a rehydrated run holds
+     * just the jobs its own agents reported, and even the owner holds a
+     * sibling-claimed job at its last-heard status. So once the map reads
+     * complete, the shared `execution_jobs` rows are folded in
+     * ({@link syncRunJobsFromRows}) and the check repeats over every job — a job a
+     * sibling still runs keeps the run open.
      *
      * Then the registration window: while a LIVE sibling still has jobs to
-     * register (a build-window owner whose real jobs are dispatched only once
-     * the build finishes), the rows say nothing yet, so finalization is deferred
-     * to whichever coordinator sees the last job finish — or to that owner's
-     * own release, which re-runs this check. A dead holder reads as no window,
-     * and a run it left behind is finished by the stale detector's
-     * all-terminal sweep.
+     * register (a build-window owner dispatches its real jobs after the build),
+     * finalization defers to whichever coordinator sees the last job finish, or
+     * to that owner's release, which re-runs this check. A dead holder reads as no
+     * window; the stale detector's all-terminal sweep finishes its run.
      */
     private readyToFinalize;
     /**
-     * Fold the run's persisted `execution_jobs` rows into its in-memory map:
-     * a row this coordinator never registered is added at the row's status, and
-     * a job it holds as non-terminal is lifted to the terminal status the row
-     * carries. Memory is never downgraded — the row for the job being reported
-     * was upserted before any completion check runs, so a terminal entry in
-     * memory is always at least as current as its row.
+     * Fold the run's `execution_jobs` rows into its in-memory map: an unknown row
+     * is added at its status, and a non-terminal job is lifted to the row's
+     * terminal status. Memory is never downgraded — the reported job's row is
+     * upserted before any completion check, so a terminal memory entry is at
+     * least as current as its row.
      */
     private syncRunJobsFromRows;
     /**
@@ -613,56 +583,51 @@ export declare class ExecutionTracker {
     private registrationWindowHeldByLiveSibling;
     /**
      * Phase 1a: recover run state from the DB when in-memory tracking is empty.
-     * Returns the rehydrated RunState or null if the run is unknown to the DB
-     * (in which case the caller skips this status update entirely).
+     * Null when the run is unknown to the DB; the caller then skips the update.
      */
     private recoverRunFromDb;
     /**
      * Reopen a run rehydrated from a prematurely `failed` row (e.g. "No agents
      * available to dispatch jobs", but a queued job is now running): reset the
      * row to `running`, clear the failure it recorded, and raise its status
-     * generation. The run completion logic then sets the correct final status.
+     * generation; run completion then sets the final status.
      *
-     * Called only once the job report that rehydrated the run has been applied to
-     * its job row. A replay of a frame the row already records must not reopen a
-     * finished run: it would roll the run up a second time. A run that failed on
-     * a build failure is never reopened — that failure is intentionally terminal.
+     * Called only after the rehydrating job report is applied to its job row: a
+     * replay of a frame the row already records must not reopen (and roll up
+     * again) a finished run. A build failure is intentionally terminal and is
+     * never reopened.
      */
     private reopenRecoveredRun;
     /**
      * Read the run row's status generation into the in-memory run after this
      * coordinator's reopen matched nothing.
      *
-     * The reopen loses when another coordinator already reopened the run, or when
-     * this view is a generation behind the row. Either way the row's generation
-     * is the current one: a coordinator that kept its own older value would send
-     * every later frame of the run at a generation the Platform keeps as older, so
-     * none of them would apply.
+     * The reopen loses when another coordinator reopened the run first, or when
+     * this view is a generation behind. Either way the row's generation is
+     * current: keeping an older value would send every later frame at a
+     * generation the Platform treats as older, so none would apply.
      */
     private adoptStoredStatusEpoch;
     /**
-     * Phase 1b: recover job state from the dispatch_queue and add it to the
-     * run's in-memory map. Returns the freshly-inserted job entry.
+     * Phase 1b: recover job state from the dispatch_queue into the run's
+     * in-memory map.
      */
     private recoverJobFromDispatchQueue;
     /**
      * Phase 2: build the upsert payload for execution_jobs and execute it.
      *
-     * The conflict update is guarded so it cannot rewrite a row that already
-     * reached a terminal state. `applied` reports the guard's verdict; the log
-     * byte total is the per-job value when the job reached a terminal state (used
-     * downstream by the run-completion phase to populate run.log_bytes).
+     * The conflict update cannot rewrite a terminal row; `applied` reports the
+     * guard's verdict. The log byte total is set on a terminal state and feeds
+     * run.log_bytes at run completion.
      */
     private persistJobStatusUpdate;
     /**
-     * Phase 3a: transition run from pending -> running when the first job
-     * starts executing.
+     * Phase 3a: pending -> running when the first job starts.
      */
     private maybeTransitionRunToRunning;
     /**
-     * Phase 3b: when an agent reports 'cancelling', transition the run-level
-     * status too. 'cancelling' means "graceful cancel in progress, hooks
-     * running" — the run should reflect this intermediate state.
+     * Phase 3b: an agent's 'cancelling' (graceful cancel in progress, hooks
+     * running) moves the run to 'cancelling' too.
      */
     private maybeTransitionRunToCancelling;
     /**
@@ -675,32 +640,27 @@ export declare class ExecutionTracker {
      */
     private fireJobStatusChangeCallback;
     /**
-     * Phase 6: reconcile orphaned steps. If a job reaches terminal state but
-     * some steps are still 'running' (because a step.complete IPC message was
-     * lost), mark them as the job's terminal state. Without this safety net,
-     * the dashboard shows "running" with an ever-growing duration for the lost
-     * step.
+     * Phase 6: reconcile orphaned steps. Steps still 'running' when their job
+     * is terminal (a lost step.complete IPC message) take the job's terminal
+     * state; otherwise the dashboard shows the step running forever.
      */
     private reconcileOrphanedSteps;
     /**
-     * Phase 7: drift report handling.
-     * When an agent reports droppedJobs, transition those sibling jobs to
-     * drift_dropped. drift_dropped is a terminal state, so the scheduler hook
-     * (Phase 8) will propagate failures to any downstreams.
+     * Phase 7: drift report handling. Jobs an agent reports as droppedJobs move
+     * to the terminal drift_dropped, so the scheduler hook (Phase 8) propagates
+     * failure to their downstreams.
      */
     private handleDriftDroppedJobs;
     /**
-     * Phase 8: needs-aware scheduler hook.
-     * When a job reaches terminal state, evaluate its downstreams for dispatch.
-     * The DAG is acyclic (validated at compile time L1 and eval time L2),
-     * so recursive skip propagation terminates naturally.
+     * Phase 8: needs-aware scheduler hook: evaluate a terminal job's downstreams
+     * for dispatch. The DAG is acyclic (validated at compile time L1 and eval
+     * time L2), so recursive skip propagation terminates.
      */
     private runSchedulerHook;
     /**
      * Rolling-wave hook: fires beside the needs-scheduler when a fan-out child of
-     * a bounded wave (`maxParallel` set) reaches terminal. Reads the completed
-     * child's row to recover the base + wave policy, asks {@link evaluateWave}
-     * what to do, then performs it:
+     * a bounded wave (`maxParallel` set) reaches terminal, and performs what
+     * {@link evaluateWave} decides:
      *
      * - `release`: clear the next held sibling's `wave_gated` flag and fire the
      *   onJobReady callback (the existing ready→dispatch path).
@@ -710,17 +670,15 @@ export declare class ExecutionTracker {
     private runWaveSchedulerHook;
     /**
      * When a proxy job of an invoke gate reaches terminal, aggregate the gate once
-     * every sibling proxy is terminal: the gate is set `failed` if any proxy
-     * failed, else `success`. Setting the gate terminal drives its own downstream
-     * `needs` release via the scheduler hook. A no-op for any non-proxy job.
+     * every sibling proxy is terminal: `failed` if any proxy failed, else
+     * `success`. The terminal gate releases its downstream `needs` through the
+     * scheduler hook. A no-op for any non-proxy job.
      */
     private runInvokeGateAggregationHook;
     /**
-     * Phase 9: stuck-jobs invariant check (Layer 3).
-     * Before declaring a run complete, verify no stuck jobs exist. If any are
-     * found, fail them via recursive onJobStatus calls and signal the caller to
-     * stop (returns true) — the recursive calls will re-enter and re-check
-     * completion with fresh state.
+     * Phase 9: stuck-jobs invariant check (Layer 3), before declaring a run
+     * complete. Stuck jobs are failed via recursive onJobStatus calls, which
+     * re-check completion with fresh state; true tells the caller to stop.
      */
     private enforceSchedulerInvariantOrFail;
     /**
@@ -730,9 +688,8 @@ export declare class ExecutionTracker {
      */
     private finalizeRunCompletion;
     /**
-     * Map a terminal run status to the terminal job status a proxy should carry.
-     * A failure class collapses to `failed`; a cancel to `cancelled`; everything
-     * else (success) to `success`.
+     * The terminal job status a proxy carries for a terminal run status:
+     * `success` and `cancelled` map through; every other status is `failed`.
      */
     private mapRunStatusToProxyStatus;
     /**
@@ -743,9 +700,8 @@ export declare class ExecutionTracker {
      */
     private readNonSecretRunOutputs;
     /**
-     * Normalize an `outputs` JSONB cell to a plain object. The Postgres driver may
-     * return it already parsed (object) or as a JSON string; both are accepted. A
-     * null / empty / malformed cell yields `null`.
+     * Normalize an `outputs` JSONB cell (already-parsed object or JSON string)
+     * to a plain object; `null` for a null / empty / malformed cell.
      */
     private parseOutputsCell;
     /**
@@ -756,52 +712,42 @@ export declare class ExecutionTracker {
      */
     private mirrorSummonedRunOntoProxy;
     /**
-     * Set a proxy job's timeline span to the summoned run's own started_at /
-     * completed_at so its dashboard bar reflects the run it mirrors. A run rejected
-     * before executing any step has no start; fall back to its completion (and, for
-     * a run with no completion recorded, to the mirror timestamp) so the proxy
-     * still renders a point-width bar rather than a status-only placeholder.
+     * Set a proxy job's timeline span to the summoned run's started_at /
+     * completed_at. A run rejected before any step has no start, so it falls back
+     * to its completion (or, with none recorded, the mirror timestamp) and still
+     * renders a point-width bar.
      */
     private mirrorSummonedRunSpanOntoProxy;
     /**
-     * Reconcile a just-tagged summoned run against its proxy: if the run is already
-     * terminal, drive the mirror now. Closes the tag race — a run that finalizes
-     * before `summoned_by_run_id` lands (a synchronous all-jobs-rejected completion,
-     * or an HA peer finalizing it first) reads a null tag in `mirrorSummonedRunOntoProxy`
-     * and skips, so nothing else terminalizes its proxy and the gate hangs until
-     * its timeout. The invoke gate calls this after tagging each spawned run; the
-     * `onJobStatus` idempotency guard makes a double-fire with the normal finalize
-     * a no-op.
+     * Drive the proxy mirror now when a just-tagged summoned run is already
+     * terminal. Closes the tag race: a run that finalizes before
+     * `summoned_by_run_id` lands (a synchronous all-jobs-rejected completion, or
+     * an HA peer finalizing first) reads a null tag and skips, so the gate hangs
+     * until its timeout. The invoke gate calls this after tagging each spawned
+     * run; the `onJobStatus` idempotency guard makes a double-fire a no-op.
      */
     reconcileSummonedRunIfTerminal(spawnedRunId: string): Promise<void>;
     /**
-     * Mark a run as failed when its build fails (timeout or error).
-     *
-     * Called by the processor when a build job was tracked early via
-     * onExecutionStarted but the build subsequently fails. Without this,
-     * the execution_runs row would stay in a non-terminal state.
+     * Mark a run failed when its build fails (timeout or error) after the
+     * processor tracked it early via onExecutionStarted; otherwise the row stays
+     * non-terminal.
      */
     onBuildFailed(runId: string, initFailure?: InitFailure): Promise<void>;
     /**
-     * Create a failed execution run when the build timed out before onExecutionStarted
-     * had a chance to insert the row (buildJobTrackedEarly was false).
-     *
-     * Inserts a minimal execution_runs row with status='failed' directly so the
-     * dashboard (and any run query) can observe the failure instead of a missing run.
+     * Insert a minimal `failed` execution_runs row when the build timed out
+     * before onExecutionStarted inserted one (buildJobTrackedEarly was false), so
+     * the dashboard and run queries see the failure instead of a missing run.
      *
-     * The fifth pre-dispatch recording site, and the third that writes the row and
-     * returns. Its row is terminal with no resume path, so no invoke gate ever
-     * reads its `chain_depth` — the stamp is here for the same reason as on
+     * A pre-dispatch recording site that writes the row and returns. The row is
+     * terminal, so no invoke gate reads its `chain_depth`; it is stamped as in
      * {@link ExecutionTracker.recordInitFailureRun}: this row is the run's ONLY
-     * record, and one that says `0` claims to have started the chain it actually
-     * died inside.
+     * record, and a `0` claims it started the chain it died inside.
      */
     onBuildFailedBeforeTracking(runId: string, workflowName: string, provider: string, repoIdentifier: string, ref: string, sha: string, deliveryId: string | null, providerContext: Record<string, unknown>, routingKey: string, triggerEvent?: string, commitMessage?: string, failureReason?: string, initFailure?: InitFailure, 
     /**
-     * Internal-trigger provenance, as one object rather than two more
-     * positional args on an already 13-wide signature. Shape matches
-     * `preDispatchRunProvenance` in `dispatch-matched-workflow.ts`, which is
-     * the only caller.
+     * Internal-trigger provenance, one object rather than more positional
+     * args. Shape matches `preDispatchRunProvenance` in
+     * `dispatch-matched-workflow.ts`, the only caller.
      */
     provenance?: {
         chainDepth?: number;
@@ -809,21 +755,19 @@ export declare class ExecutionTracker {
         rerunLineage?: RerunLineage;
     }): Promise<void>;
     /**
-     * Write a `failed` execution_runs row directly for an init failure, and drop
-     * any in-memory run so the recorded failure is the run's final word. Also
-     * writes the structured init_failure signal and fires onExecutionStatusChange
-     * so Platform's projection picks it up via the normal forward path.
+     * Write a `failed` execution_runs row (with the structured init_failure) for
+     * an init failure, and stamp any in-memory run complete so the recorded failure
+     * is the run's final word. Forwarded via onExecutionStatusChange to the Platform
+     * projection.
      *
-     * An existing row for this runId is overwritten while it is still live —
-     * dispatch may already have registered the run before init failed — and left
-     * alone once it is terminal, so a run that genuinely finished is never
-     * rewritten as failed. When the guard leaves the row alone, the failure
-     * metric and the Platform forward are suppressed with it: this orchestrator
-     * did not record the init failure, so it must not report one.
+     * An existing row is overwritten while live (dispatch may have registered the
+     * run before init failed) and left alone once terminal, so a finished run is
+     * never rewritten as failed. When the guard leaves it alone, the failure
+     * metric and Platform forward are suppressed too: this orchestrator did not
+     * record the init failure, so it must not report one.
      *
-     * Closes the silent pre-run-failure gap — without this helper, secret /
-     * install-secret / all-jobs-rejected early-exits in dispatch-matched-workflow
-     * leave no trace on the dashboard.
+     * Without this, the secret / install-secret / all-jobs-rejected early exits in
+     * dispatch-matched-workflow leave no trace on the dashboard.
      */
     recordInitFailureRun(args: {
         runId: string;
@@ -840,25 +784,21 @@ export declare class ExecutionTracker {
         commitMessage?: string;
         /**
          * The repository that DEFINES the workflow this run was about to execute.
-         * REQUIRED: every run has one, and a caller that does not state it must not
-         * compile. Left optional, a global dispatch path added later would record a
-         * null marker — and a null marker does not mean "unknown", it means "the
-         * workflow lives in this run's own repository", which the whole
-         * defining-repository predicate then reads as fact.
+         * REQUIRED so a caller that omits it does not compile: a null marker means
+         * "the workflow lives in this run's own repository", not "unknown", and the
+         * defining-repository predicate reads it as fact.
          *
-         * Narrowed to the differing case here, exactly as `onExecutionStarted`
-         * does, so passing `repoIdentifier` (the per-repository case) is correct
-         * and records nothing.
+         * Narrowed to the differing case as in `onExecutionStarted`, so passing
+         * `repoIdentifier` (the per-repository case) records nothing.
          */
         workflowRepoIdentifier: string;
         /**
          * Inherited invoke-chain depth for a run summoned by an invoke gate.
          *
-         * An init failure is terminal, so unlike the hold on
-         * {@link ExecutionTracker.recordRunHeld} this run never fires a gate of its
-         * own and nothing reads the column back to bound recursion. It is recorded
-         * because this row is the run's ONLY record: one that says `0` claims to
-         * have started the chain it actually died inside.
+         * Unlike a hold ({@link ExecutionTracker.recordRunHeld}), an init failure is
+         * terminal and never fires a gate, so nothing reads it to bound recursion.
+         * It is recorded because this row is the run's ONLY record, and a `0`
+         * claims it started the chain it died inside.
          */
         chainDepth?: number;
         /**
@@ -866,12 +806,10 @@ export declare class ExecutionTracker {
          * the run's `trigger_decision` marker
          * (`EventRouter.isFailureLifecycleRun`).
          *
-         * Consistency rather than a live reader: this path emits no
-         * `__workflow_complete`, so no accumulator reads the marker back today. It
-         * is recorded so the row does not disagree with the one
-         * {@link ExecutionTracker.recordRunHeld} writes for the same dispatch, and
-         * so adding an emit here later cannot silently re-open the self-retrigger
-         * loop.
+         * For consistency, not a live reader: this path emits no
+         * `__workflow_complete`. The row then agrees with the one
+         * {@link ExecutionTracker.recordRunHeld} writes for the same dispatch, and a
+         * later emit here cannot silently re-open the self-retrigger loop.
          */
         dispatchedByFailureLifecycle?: boolean;
         /** Re-run lineage, when this run re-runs another. */
@@ -881,20 +819,16 @@ export declare class ExecutionTracker {
      * Write one `failed` execution_runs row for a global eval round that never
      * produced verdicts.
      *
-     * The round decides which organization-wide workflows apply to an event, so a
-     * round that fails suppresses every workflow it was deciding on. Without a row
-     * that outcome is invisible: no run was ever created for those workflows, so
-     * there is nothing on the dashboard to explain why they did not appear.
+     * A failed round suppresses every organization-wide workflow it was deciding
+     * on; without this row nothing on the dashboard explains their absence.
      *
-     * **One row for the whole round, not one per workflow.** The round exists to
-     * collapse N candidate workflows into a single pre-run job; fanning its
-     * failure back out into N rows would undo exactly that. The reason names every
-     * affected workflow instead.
+     * **One row for the whole round, not one per workflow:** the round collapses
+     * N candidate workflows into one pre-run job, and N rows would undo that. The
+     * reason names every affected workflow instead.
      *
-     * Its `runId` is the round job's own — the last attempt's — so the row, the
-     * `dispatch_queue` row, and the attempt's logs all carry one id. No conflict
-     * guard is needed beyond `doNothing`: the id was minted for this round and
-     * belongs to no other run.
+     * `runId` is the round job's (last attempt's) own, so the row, the
+     * `dispatch_queue` row and the attempt's logs share one id. `doNothing` is
+     * guard enough: the id was minted for this round and belongs to no other run.
      */
     recordGlobalEvalRoundFailureRun(args: {
         runId: string;
@@ -910,30 +844,26 @@ export declare class ExecutionTracker {
          * The source `providerContext` was taken from, when a cross-provider
          * lock-file fallback made it a different source from `routingKey`.
          *
-         * Recorded because the two are a PAIR: a re-run of this round re-drives the
-         * organization-wide pass and must hand it the same bundle those credentials
-         * belong to. Pairing the stored context with the inbound routing key instead
-         * gives one source's credentials to another source's API client.
+         * The two are a PAIR: a re-run re-drives the organization-wide pass with the
+         * bundle those credentials belong to. Pairing the stored context with the
+         * inbound routing key gives one source's credentials to another's API client.
          */
         dispatchRoutingKey?: string;
         failureReason: string;
         triggerEvent?: string;
         /**
-         * The repository whose global workflows the round was deciding. A round is
-         * definitionally the cross-repository case, so this is normally a different
-         * repository from `repoIdentifier` — recorded, like everywhere else, only
-         * when the two actually differ.
+         * The repository whose global workflows the round was deciding — normally
+         * not `repoIdentifier`, and recorded only when the two differ.
          */
         workflowRepoIdentifier: string;
     }): Promise<void>;
     /**
      * Record a run paused at the workflow install gate (a `registries:` /
-     * `installEnv:` protection rule returned hold / wait / queue). Writes an
-     * `execution_runs` row in the `held` state — alive and resumable — so the
-     * dashboard run list surfaces the paused workflow. No jobs are tracked: the
-     * workflow-scoped held_runs row + pending workflow context (written by the
-     * caller) keep the run from being counted complete, and any in-memory run is
-     * dropped so jobs registered before the gate cannot roll it up.
+     * `installEnv:` protection rule returned hold / wait / queue) as a resumable
+     * `held` `execution_runs` row the dashboard run list shows. No jobs are
+     * tracked: the caller's held_runs row and pending workflow context keep the
+     * run from counting as complete, and any in-memory run is dropped so jobs
+     * registered before the gate cannot roll it up.
      *
      * An existing row for this runId is flipped to `held` while it is still live
      * and left alone once it is terminal — a finished run is never re-held.
@@ -953,35 +883,26 @@ export declare class ExecutionTracker {
         triggerEvent?: string;
         commitMessage?: string;
         /**
-         * Pull-request number for PR-triggered holds; null/omitted for non-PR runs.
-         * Stamped so PR-scoped `/kici approve|reject` (which joins `execution_runs`
-         * on `pr_number`) can attribute the held run to its PR — a NULL leaves a
-         * security hold fail-closed unreachable by the comment path.
+         * Pull-request number for PR-triggered holds. PR-scoped
+         * `/kici approve|reject` joins `execution_runs` on `pr_number`; a NULL
+         * leaves a security hold fail-closed unreachable by the comment path.
          */
         prNumber?: number | null;
         /**
-         * The repository that DEFINES the held workflow. REQUIRED for the same
-         * reason as on {@link ExecutionTracker.recordInitFailureRun}: a hold is a
-         * live, resumable run, so a null marker here would misattribute it for the
-         * whole time it sits in the queue and for the run it resumes into.
+         * The repository that DEFINES the held workflow. REQUIRED as on
+         * {@link ExecutionTracker.recordInitFailureRun}: a null marker would
+         * misattribute the hold while it waits and the run it resumes into.
          */
         workflowRepoIdentifier: string;
-        /**
-         * Commit of the workflow repository the held run dispatches, recorded only
-         * when the workflow is defined in another repository.
-         */
+        /** Workflow repository commit, recorded only for a cross-repository workflow. */
         workflowSha?: string | null;
-        /**
-         * The workflow repository's registered branch, recorded only when the
-         * workflow is defined in another repository.
-         */
+        /** Workflow repository registered branch, recorded only for a cross-repository workflow. */
         workflowBranch?: string | null;
         /**
-         * Inherited invoke-chain depth for a run summoned by an invoke gate.
-         * REQUIRED to be threaded by any caller that has one: a hold is resumable,
-         * so the resumed run can fire its own invoke gate, and the chain-depth
-         * circuit breaker reads this column back. Absent ⇒ the column's `0`
-         * default, which means "this run starts a chain".
+         * Inherited invoke-chain depth for a run summoned by an invoke gate. Any
+         * caller that has one MUST thread it: the resumed run can fire its own
+         * invoke gate, and the chain-depth circuit breaker reads this column back.
+         * Absent ⇒ the `0` default, meaning "this run starts a chain".
          */
         chainDepth?: number;
         /**
@@ -993,51 +914,46 @@ export declare class ExecutionTracker {
         /** Re-run lineage, when this run re-runs another. */
         rerunLineage?: RerunLineage;
         /**
-         * True when the held run is a pre-run global evaluation round rather than a
-         * workflow: the structural marker the release and re-run paths branch on,
-         * written here because a held round is recorded through this method.
+         * True for a held pre-run global evaluation round: the marker the release
+         * and re-run paths branch on.
          */
         isGlobalEvalRound?: boolean;
         /**
-         * For a held evaluation round: the workflows the round covers, recorded so
-         * its release can refuse when one of them lost its registration while the
-         * round waited. Stored in the row's `trigger_decision` blob.
+         * For a held evaluation round: the workflows it covers (in the
+         * `trigger_decision` blob), so its release can refuse when one lost its
+         * registration while the round waited.
          */
         heldRoundWorkflows?: readonly string[];
         /**
-         * The source `providerContext` was taken from, when it is not
-         * `routingKey`. Recorded for a held evaluation round, whose release re-drives
-         * the organization-wide pass with that same pair — see
-         * {@link ExecutionTracker.recordGlobalEvalRoundFailureRun}.
+         * The source `providerContext` was taken from, when not `routingKey`; a held
+         * round's release re-drives the organization-wide pass with that pair (see
+         * {@link ExecutionTracker.recordGlobalEvalRoundFailureRun}).
          */
         dispatchRoutingKey?: string;
     }): Promise<void>;
     /**
-     * Claim a held global evaluation round for its release: move it from `held`
-     * to `pending`. Returns false when the row is not a held round — another
-     * release already claimed it — so a re-fired release signal dispatches the
-     * round at most once.
+     * Claim a held global evaluation round for release (`held` → `pending`).
+     * False when another release already claimed it, so a re-fired release
+     * signal dispatches the round at most once.
      *
-     * `pending`, as a resumed per-repository run (`resumeHeldRun`), and not
-     * `running`: orphan recovery fails a `running` row older than its stale
-     * threshold that has no job rows, and a round row keeps the `started_at` of
-     * its hold and never has job rows. No sweeper selects a `pending` row with no
-     * job rows and no workflow timeout.
+     * `pending` (as `resumeHeldRun`), not `running`: orphan recovery fails a
+     * jobless `running` row older than its stale threshold, and a round row keeps
+     * its hold's `started_at` and never has job rows. No sweeper selects a
+     * jobless `pending` row with no workflow timeout.
      */
     claimHeldGlobalEvalRound(runId: string): Promise<boolean>;
     /**
      * Terminalize a held global evaluation round whose hold was released.
      *
-     * The released round runs as a job of its own and creates no run row when it
-     * decides, so nothing else ever moves this row out of `held`. `success`
-     * records that the round reached a verdict for its workflow repository;
-     * `failed` that it did not, with the reason. Guarded on `pending`, the
-     * state {@link ExecutionTracker.claimHeldGlobalEvalRound} moved the row to,
-     * so only the release that claimed it settles it.
+     * The released round runs as its own job and creates no run row, so nothing
+     * else settles this row. `success` means it reached a verdict for its
+     * workflow repository; `failed` that it did not, with the reason. Guarded on
+     * `pending` (set by {@link ExecutionTracker.claimHeldGlobalEvalRound}), so
+     * only the claiming release settles it.
      *
-     * A settled round is not an execution: no `executions_total` sample is
-     * counted for a success, and the forwarded frame carries `isGlobalEvalRound`
-     * so the Platform raises no run notification or outbound webhook for it.
+     * A settled round is not an execution: a success counts no
+     * `executions_total` sample, and the frame carries `isGlobalEvalRound` so the
+     * Platform raises no run notification or outbound webhook.
      */
     completeReleasedGlobalEvalRound(runId: string, outcome: {
         status: typeof ExecutionRunStatus.enum.success;
@@ -1046,8 +962,8 @@ export declare class ExecutionTracker {
         reason: string;
     }): Promise<void>;
     /**
-     * Flip a `held` run back to `pending` so the resumed dispatch can proceed
-     * into job dispatch. Returns true when a held row was found and updated.
+     * Flip a `held` run back to `pending` for the resumed dispatch. True when a
+     * held row was updated.
      */
     resumeHeldRun(runId: string): Promise<boolean>;
     /**
@@ -1058,93 +974,73 @@ export declare class ExecutionTracker {
     /**
      * Cancel a run that has no job rows: a run cancelled before it dispatched
      * any job, a pre-run evaluation round, or a `pending` row a crash left
-     * behind. No job will ever report a terminal status for it, so the cancel
-     * itself writes the terminal row and forwards it, as `cancelHeldRun` does.
+     * behind. No job will report a terminal status, so the cancel writes and
+     * forwards the terminal row itself, as `cancelHeldRun` does.
      *
-     * Guarded on the row being non-terminal, not `held`, and having no job rows,
-     * so a run a job registered on in the meantime is left to the job-driven
-     * completion and a held run to the hold-rejection path.
-     * The cancellation reason already stamped on the row wins over `reason`.
+     * Guarded on non-terminal, not `held`, and no job rows: a run that gained a
+     * job meanwhile is left to job-driven completion, a held run to the
+     * hold-rejection path. A reason already on the row wins over `reason`.
      * Returns whether a row was cancelled.
      */
     cancelJoblessRun(runId: string, reason: string): Promise<boolean>;
     /**
-     * Mark a run as failed immediately with a reason message.
-     *
-     * Used when no agents are available to dispatch any jobs (e.g. cron-triggered
-     * runs on a cluster leader without matching local agents and no reachable peers).
-     * Instead of leaving the run in 'running' for OrphanRecovery to catch after 5 min,
-     * this fails it right away.
+     * Fail a run immediately, e.g. when no agents can take any job (cron-triggered
+     * runs on a cluster leader without matching local agents and no reachable
+     * peers), rather than leave it 'running' for OrphanRecovery to catch after
+     * 5 min.
      */
     failRun(runId: string, reason: string, initFailure?: InitFailure): Promise<void>;
     /**
-     * Update step status within a job.
+     * Upsert a step's execution_steps row (started_at on 'running';
+     * completed_at, duration_ms, exit_code on terminal), with its log_path, and
+     * forward it to the Platform.
      *
-     * Upserts execution_steps row with timing information. On 'running',
-     * sets started_at. On terminal state, sets completed_at, duration_ms,
-     * exit_code. Also constructs log_path and forwards to Platform.
-     *
-     * @param logBytesStreamed Raw byte total reported by the agent's
-     *   LogStreamer at terminal step time. Accumulated into a per-(run, job)
-     *   counter that lands in `execution_jobs.log_bytes` and
-     *   `execution_runs.log_bytes` when the job and run reach terminal state,
-     *   feeding the operator-side `kici_org_log_bytes` capacity-planning gauge
-     *   on the Platform.
+     * @param logBytesStreamed Raw byte total from the agent's LogStreamer at
+     *   terminal step time; summed into `execution_jobs.log_bytes` and
+     *   `execution_runs.log_bytes`, feeding the Platform's operator-side
+     *   `kici_org_log_bytes` capacity-planning gauge.
      */
     onStepStatus(runId: string, jobId: string, stepIndex: number, stepName: string, state: string, timestamp: number, data?: Record<string, unknown>, logBytesStreamed?: number): Promise<void>;
-    /**
-     * Check if all tracked jobs in a run have reached terminal state.
-     */
+    /** Whether every tracked job of the run is terminal. */
     isRunComplete(runId: string): boolean;
     /**
      * Take a token holding a run open while some of its jobs are still to be
-     * registered. Returns true when a token was taken, false for an unknown or
-     * already-completed run (nothing to hold).
+     * registered. False for an unknown or already-completed run.
+     *
+     * The registration windows: a run whose source-pack `__build__` job goes
+     * first is registered with that job ALONE, its real jobs dispatched after the
+     * build; a run without a build is registered with NO jobs before its dispatch
+     * loop; a deferred init job and a deferred dynamic entry register from a
+     * fire-and-forget task that outlives the dispatch call. Without a token, the
+     * already-registered jobs going terminal satisfy {@link isRunComplete}, so a
+     * terminal status is written, the provider check posted and the status
+     * forwarded — before a single real job has run.
      *
-     * Four registration windows need this. A run whose source-pack `__build__`
-     * job is dispatched first is registered with that job ALONE, and its real
-     * jobs are only dispatched once the build finishes; a run without a build is
-     * registered with NO jobs before its dispatch loop, so its jobs land once
-     * every dispatch has returned. A deferred init job and a deferred dynamic
-     * entry each register their jobs from a fire-and-forget task that outlives
-     * the dispatch call. In every case, without a token the already
-     * -registered jobs reaching a terminal state satisfies {@link isRunComplete},
-     * so the run is finalized early: a terminal run status is written, the
-     * provider check is posted, and the status is forwarded to the Platform — all
-     * before a single real job has run.
+     * The hold is a counter read only by {@link isRunComplete}, deliberately NOT
+     * a synthetic job-map entry: every outward projection enumerates the job map
+     * (the Platform `state.replay` snapshot and its `execution_jobs` mirror, the
+     * job count, workflow-complete job results, the active-run summary), so a
+     * marker there would be a phantom pending job and an off-by-one count. The
+     * counter writes no `execution_jobs` row either.
      *
-     * The hold is a counter on the in-memory run, read only by
-     * {@link isRunComplete} — deliberately NOT a synthetic entry in the run's job
-     * map. The job map is what every outward projection enumerates (the Platform
-     * `state.replay` snapshot and its `execution_jobs` mirror, the reported job
-     * count, the workflow-complete job results, the active-run summary), so a
-     * marker parked there would surface as a phantom pending job on the dashboard
-     * and an off-by-one job count for the length of the window. A counter holds
-     * the completion check open without being visible to any of them, and it
-     * writes no `execution_jobs` row, so it never surfaces as a phantom job.
      * A token whose holder never settles keeps the run open until the stale
-     * detector reaps it — the same backstop that covers a job that never
-     * reports. That backstop only reaches a run that has at least one job: every
-     * sub-scan of the stale detector starts from `execution_jobs` or
-     * `dispatch_queue`. So a holder that registers NO jobs must terminalize the
-     * run itself rather than rely on the sweep — which is what
+     * detector reaps it, which reaches only a run with at least one job (every
+     * sub-scan starts from `execution_jobs` or `dispatch_queue`). So a holder that
+     * registers NO jobs must terminalize the run itself, as
      * `dispatchMatchedWorkflow` does when its dispatch loop throws.
      *
      * Each token must be paired with exactly one {@link releasePendingJobsHold}.
      */
     holdRunForPendingJobs(runId: string): boolean;
     /**
-     * Record this coordinator as the run's registration-window holder in
-     * `execution_runs.registration_window_instance_id` — the token's durable
-     * form, which a sibling coordinator finalizing the run consults.
+     * Record this coordinator in `execution_runs.registration_window_instance_id`
+     * — the token's durable form, which a sibling finalizing the run consults.
      *
-     * Chained rather than awaited: the caller is synchronous by contract (the
-     * token must be counted before the next `await` can drop a sibling token),
-     * so the write rides a per-run chain that the clear on the last release
-     * awaits. `registrationWindowSettled` exposes the chain to a caller that
-     * must know the window is durable before it starts waiting on a job a
-     * sibling may finish. A coordinator with no instance id holds no durable
-     * window.
+     * Chained, not awaited: the caller is synchronous by contract (the token must
+     * be counted before the next `await` can drop a sibling token), and the clear
+     * on the last release awaits the chain. `registrationWindowSettled` exposes
+     * it to a caller that needs the window durable before waiting on a job a
+     * sibling may finish. No instance id, no durable window.
      */
     private openRegistrationWindow;
     /**
@@ -1159,108 +1055,78 @@ export declare class ExecutionTracker {
      * Drop one token taken by {@link holdRunForPendingJobs}, and finalize the run
      * if dropping the LAST one left every remaining job terminal.
      *
-     * The re-evaluation matters for the same reason it does in `addJobsToRun`:
-     * once the last token is gone nothing else drives a completion check (no
-     * further `job.status` messages are coming for already-finished jobs), so a
-     * run whose jobs all finished while a token was held would otherwise hang in
-     * `running` forever. Only the last release may finalize — while any other
-     * token is outstanding more jobs are still on their way.
+     * As in `addJobsToRun`, nothing else drives a completion check once the last
+     * token is gone, so a run whose jobs all finished meanwhile would hang in
+     * `running` forever. Only the last release may finalize: while another token
+     * is outstanding, more jobs are on their way.
      *
-     * Idempotent — a no-op when no token is outstanding. The count clamps at
-     * zero so a stray extra release cannot drive it negative, which would
-     * permanently un-hold the run and stop a genuinely outstanding token from
-     * holding it open.
+     * Idempotent: a no-op with no token outstanding. The count clamps at zero, so
+     * a stray extra release cannot go negative and stop a genuinely outstanding
+     * token from holding the run open.
      */
     releasePendingJobsHold(runId: string): Promise<void>;
-    /**
-     * Get the current overall status of a run.
-     */
     getRunStatus(runId: string): Extract<ExecutionRunStatus, 'running' | 'success' | 'failed' | 'cancelled'>;
-    /**
-     * Look up a job name from in-memory state.
-     * Used by LogWriter to construct log paths.
-     */
+    /** In-memory job name lookup, used by LogWriter for log paths. */
     getJobName(runId: string, jobId: string): string | undefined;
     /**
-     * Resolve the job name that names a step-log storage path, with a durable
-     * fallback. The step-log path is `executions/{runId}/job-{jobName}/…` and it
-     * is written from two sites — the chunk writer (`log-chunk-sink`) and the
-     * `execution_steps.log_path` upsert in `onStepStatus`. A purely in-memory
-     * lookup (`getJobName`) returns `undefined` during the brief window between
-     * dispatch and `addJobsToRun` populating `run.jobs`, so an early chunk would
-     * land under `job-{jobId}` while the reader later keys on `job-{realName}` —
-     * silently losing those lines. Both write sites go through this resolver so
-     * they cannot disagree: in-memory first, then the authoritative
-     * `dispatch_queue.job_name` (the same source `recoverJobFromDispatchQueue`
-     * trusts), and only `jobId` when the job is genuinely unknown.
+     * Resolve the job name in a step-log storage path
+     * (`executions/{runId}/job-{jobName}/…`), with a durable fallback. Both
+     * writers — the chunk writer (`log-chunk-sink`) and the
+     * `execution_steps.log_path` upsert in `onStepStatus` — use this, so they
+     * cannot disagree. `getJobName` is `undefined` between dispatch and
+     * `addJobsToRun`, which would put an early chunk under `job-{jobId}` while the
+     * reader keys on `job-{realName}`, silently losing lines. Order: in-memory,
+     * then `dispatch_queue.job_name` (as `recoverJobFromDispatchQueue` trusts),
+     * then `jobId` for a genuinely unknown job.
      */
     resolveJobName(runId: string, jobId: string): Promise<string>;
     /**
-     * Seed the in-memory job name for a job the coordinator did not itself
-     * dispatch — a worker-rerouted job. Such a job is tracked in the cluster
-     * coordinator's own map, never enters this tracker's `run.jobs` via
-     * `addJobsToRun`, and has no coordinator-owned `dispatch_queue` row (the
-     * worker owns it under a fresh id), so `resolveJobName` would fall back to
-     * the bare `jobId` for its early log chunks while the reader keys on the real
-     * name — the same split-brain that loses lines. Seeding the name here, at
-     * reroute time, makes `resolveJobName`'s fast path correct from the first
-     * relayed chunk, independent of when the worker's `dispatch_queue` row becomes
-     * visible. In-memory only: the `execution_jobs` row is still created lazily by
-     * the worker's first status update. Guarded against clobbering an existing
-     * entry so a later terminal status is never overwritten.
+     * Seed the in-memory job name of a worker-rerouted job at reroute time. It
+     * never enters `run.jobs` via `addJobsToRun` and has no coordinator-owned
+     * `dispatch_queue` row (the worker owns it under a fresh id), so
+     * `resolveJobName` would fall back to the bare `jobId` for early log chunks
+     * while the reader keys on the real name, losing lines. In-memory only: the
+     * worker's first status update creates the `execution_jobs` row. An existing
+     * entry is never clobbered, so a later terminal status survives.
      */
     registerJobName(runId: string, jobId: string, jobName: string): void;
     /**
-     * Find the runId of the in-memory run that owns a given dispatched jobId.
-     *
-     * The agent's `event.emit` message is job-scoped (it carries only the
-     * emitting jobId), but run context is keyed by runId. This maps job → run so
-     * `getExecutionContext(runId)` resolves for an agent-emitted custom event.
-     * In-memory only (matches `getExecutionContext`'s semantics); emit happens
-     * mid-execution, so the owning run is always live in `this.runs`.
+     * The in-memory run owning a dispatched jobId, so `getExecutionContext`
+     * resolves for a job-scoped agent `event.emit`. In-memory only, like
+     * `getExecutionContext`: emit happens mid-execution, so the run is live.
      */
     getRunIdForJob(jobId: string): string | undefined;
     /**
-     * Get execution context for a run from in-memory state.
-     * Used by commit status reporting to access provider/repo/sha info.
+     * In-memory execution context of a run, for commit status reporting.
      */
     getExecutionContext(runId: string): ExecutionContext | undefined;
     /**
      * Stamp the run's resolved trust tier and lock-file branch onto the in-memory
      * state, after `onExecutionStarted` recorded the row.
      *
-     * Separate from the start call because trust resolves on its own path and is
-     * written to `execution_runs` by its own update. The dispatch site that
-     * writes those two columns calls this with the same values, but the two
-     * writes are independent and either can be lost: the DB update is
-     * fire-and-forget with its own `.catch()`, and this call is wrapped in a
-     * `try`/`catch` there. Both are deliberate — the note is worth less than the
-     * run — so the in-memory copy and the row CAN disagree, and neither is
-     * authoritative for the other. `recoverRunFromDb` reconciles by reading the
-     * row, so the durable value is the one that survives.
+     * Trust resolves on its own path with its own `execution_runs` update. The
+     * dispatch site calls this with the same values, but either write can be
+     * lost (the DB update is fire-and-forget with its own `.catch()`, and this
+     * call sits in a `try`/`catch`) — deliberately, as the note is worth less
+     * than the run. So memory and the row CAN disagree; `recoverRunFromDb` reads
+     * the row, so the durable value survives.
      *
-     * A run this tracker does not know is a no-op: a missing run means the status
-     * updates that would read the fields are not coming either.
+     * An unknown run is a no-op: the status updates that would read the fields
+     * are not coming either.
      *
-     * Keep this synchronous. Each caller wraps it in `try`/`catch`, which catches
-     * a throw but not a rejected promise, so an async body would put the failure
-     * back outside the guard.
+     * Keep this synchronous: callers' `try`/`catch` catches a throw, not a
+     * rejected promise.
      */
     setRunTrustContext(runId: string, trustTier: string, lockFileSource?: string): void;
     /**
-     * Update the heartbeat timestamp for a running job.
-     *
-     * Uses optimistic WHERE status='running' so completed jobs are not updated.
-     * Called when the agent sends a job.heartbeat message.
+     * Stamp a running job's heartbeat on an agent job.heartbeat; the
+     * status='running' predicate leaves completed jobs alone.
      */
     updateJobHeartbeat(runId: string, jobId: string): Promise<void>;
-    /**
-     * Get the count of active (non-completed) runs in memory.
-     */
+    /** Count of non-completed runs in memory. */
     getActiveRunCount(): number;
     /**
-     * Get a summary of all active runs for the cluster health API.
-     * Returns run ID, workflow name, status, and job routing counts.
+     * Summary of active runs (with job counts) for the cluster health API.
      */
     getActiveRuns(): Array<{
         runId: string;
@@ -1274,9 +1140,9 @@ export declare class ExecutionTracker {
         };
     }>;
     /**
-     * Get replay data for all in-memory runs (both active and recently completed).
-     * Used to send a state.replay message to Platform on reconnection so the Platform
-     * can reconcile its execution_runs and execution_jobs projection tables.
+     * Replay data for every in-memory run (active and recently completed), sent
+     * as state.replay on reconnection so the Platform reconciles its
+     * execution_runs and execution_jobs projections.
      */
     getReplayData(): Array<{
         runId: string;
@@ -1312,38 +1178,31 @@ export declare class ExecutionTracker {
     /**
      * Replay data merged with terminal runs read from the orchestrator's local DB.
      *
-     * `getReplayData()` only sees runs still in memory. After an orchestrator
-     * crash/restart, in-memory state is empty until new webhooks arrive — but
-     * any run that completed before the crash still lives in `execution_runs`
-     * on disk. Without re-emitting those, Platform's mirror table (and the
-     * `kici_org_executions_count` operator-aggregate gauge) silently undercounts.
+     * After a crash/restart memory is empty, but runs completed before it are
+     * still in `execution_runs`; without re-emitting them the Platform mirror
+     * (and the `kici_org_executions_count` operator-aggregate gauge) silently
+     * undercounts.
      *
-     * This wrapper fills that gap: it returns the in-memory replay items first,
-     * then unions in any terminal-state runs from the local DB completed within
-     * `windowHours` (default 24h) that aren't already covered. Order is preserved
-     * for in-memory entries (callers may rely on that for active-run metadata);
-     * DB-backed entries are appended in `completed_at ASC` order.
+     * Returns the in-memory items first, in order (callers may rely on it for
+     * active-run metadata), then appends uncovered terminal DB runs completed
+     * within `windowHours` (default 24h), in `completed_at ASC` order.
      *
-     * Idempotent: Platform's `state.replay` handler upserts on `run_id`, so
-     * re-emitting an already-mirrored run is a no-op for billing and dashboard
-     * state alike.
+     * Idempotent: the Platform's `state.replay` handler upserts on `run_id`, so
+     * re-emitting a mirrored run is a no-op for billing and dashboard state.
      */
     getReplayDataWithDb(windowHours?: number): Promise<ReturnType<ExecutionTracker['getReplayData']>>;
     /**
-     * Update a job's in-memory status without touching the DB.
-     * Used by StaleRunDetector which does direct DB updates and only needs
-     * the in-memory state kept in sync for run completion detection.
+     * Update a job's in-memory status only, for StaleRunDetector, which writes
+     * the DB itself and needs memory in sync for completion detection.
      */
     updateInMemoryJob(runId: string, jobId: string, status: string): void;
     /**
-     * Forward a terminal job status to Platform via the onJobStatusChange callback.
-     * Used by StaleRunDetector and OrphanRecovery which update the DB directly
-     * but need to notify Platform so its execution_jobs projection stays in sync.
+     * Forward a terminal job status to the Platform's execution_jobs projection,
+     * for StaleRunDetector and OrphanRecovery, which write the DB directly.
      */
     forwardJobTerminalStatus(runId: string, jobId: string, jobName: string, status: string, errorMessage?: string): void;
     /**
-     * Emit a run.event message via the onRunEventEmit callback.
-     * Public wrapper for use by StaleRunDetector and OrphanRecovery.
+     * Public run.event emitter for StaleRunDetector and OrphanRecovery.
      */
     emitInfraEvent(runId: string, eventType: string, opts?: {
         jobId?: string;
@@ -1351,95 +1210,71 @@ export declare class ExecutionTracker {
         durationMs?: number;
     }): void;
     /**
-     * Cancel all non-terminal steps for a job.
-     *
-     * When a job is terminated by infrastructure (stale detection, orphan recovery,
-     * recovery timeout), any in-progress steps remain with status='running' in the DB.
-     * This method marks them as 'cancelled' so the dashboard doesn't show stale
-     * running indicators for steps that are no longer executing.
+     * Cancel a job's non-terminal steps after infrastructure terminated it (stale
+     * detection, orphan recovery, recovery timeout), so the dashboard shows no
+     * stale running steps.
      */
     cancelStepsForJob(runId: string, jobId: string, reason: string): Promise<void>;
     /**
-     * Check if all jobs for a run are terminal, and if so, complete the run.
-     * Works with in-memory state (normal operation) or falls back to DB query
-     * (crash recovery / pruned runs). Called by StaleRunDetector after marking
-     * stale jobs.
+     * Complete the run when every job is terminal, from memory or else from the
+     * DB (crash recovery / pruned runs). Called by StaleRunDetector after
+     * marking stale jobs.
      */
     completeRunIfAllJobsTerminal(runId: string): Promise<void>;
     /**
-     * Path A helper: complete a run using in-memory state. Called by the
-     * stale detector when memRun is still tracked locally — writes the
-     * execution_runs terminal row, fires Platform-forwarding +
-     * workflow-complete callbacks, and schedules in-memory pruning.
+     * Path A helper: complete a locally tracked run from memory — terminal row,
+     * Platform-forwarding and workflow-complete callbacks, pruning.
      *
-     * The terminal write is clobber-guarded. If the guard rejects it (the run
-     * already finished through the normal path), only the pruning happens: the
-     * recomputed status is not this orchestrator's record of the run, so neither
-     * the callbacks nor the completion metrics may claim it.
+     * The terminal write is clobber-guarded. On rejection (the run finished on
+     * the normal path) only pruning happens: the recomputed status is not this
+     * orchestrator's record, so no callback or metric may claim it.
      */
     private completeRunFromMemoryState;
     /**
      * Drop the in-memory state of every run another writer already finished.
      *
-     * A coordinator finalizes a run — and schedules its own prune — only when it
-     * sees the run's last job finish. In a cluster the last job's frames may go
-     * to a sibling, which finalizes the run and prunes ITS state; this
-     * coordinator's copy has no later trigger and, without this sweep, stays in
-     * memory for the life of the process, one `RunState` per cross-coordinator
-     * run. The stale detector calls this on every tick. One query over the
-     * non-finished runs held here; a run whose row is terminal is released the
-     * way the finalizing path releases its own, minus the completion events and
-     * the row write, which the finalizer already did.
+     * A coordinator prunes a run only when it sees the last job finish. In a
+     * cluster a sibling may see it instead, leaving this copy in memory for the
+     * process lifetime (one `RunState` per cross-coordinator run). The stale
+     * detector calls this every tick; a run whose row is terminal is released
+     * like the finalizer's own, minus the completion events and row write.
      *
-     * A run this coordinator legitimately still holds — its row non-terminal,
-     * with or without an open registration window — is not touched.
+     * A run whose row is non-terminal (with or without an open registration
+     * window) is not touched.
      */
     pruneRunsFinishedElsewhere(): Promise<number>;
     /**
-     * Treat a run whose row another writer finished as finished here too:
-     * mark it complete so no completion path re-enters it, shed the per-run
-     * state the terminal callback sheds, and schedule the prune. Emits no
-     * completion event and writes no row. Returns false when the run is not
-     * held here or is already finishing.
+     * Finish here a run another writer finished: mark it complete so no
+     * completion path re-enters it, shed its terminal-callback state, schedule
+     * the prune. No event, no row write. False when not held or already
+     * finishing.
      */
     private releaseRunFinishedElsewhere;
     /**
      * Drop a finished run's in-memory state after a grace period, so a late
      * status/heartbeat arriving just after completion still finds its run.
      *
-     * This is the single owner of run-lifetime state teardown, so every
-     * run-lifetime map is cleared here — including `testRunIds`: a run finished by
-     * the stale detector rather than the normal completion path would otherwise
-     * leave its observer-broadcast marker behind for the process's lifetime.
-     * (`runLockTails` is deliberately not touched: it is keyed by runId but scoped
-     * to a lock's holders, and `withRunLock` drops its own entry on release.)
+     * The single owner of run-lifetime teardown, so every run-lifetime map is
+     * cleared here — `testRunIds` too, or a stale-detector-finished run leaks its
+     * observer marker. (`runLockTails` is deliberately skipped: scoped to a
+     * lock's holders, `withRunLock` drops its own entry on release.)
      */
     private scheduleRunPrune;
     /**
-     * Path B helper: complete a run using DB rows only (crash recovery /
-     * pruned runs). Loads jobs + run row from execution_jobs/execution_runs,
-     * checks the all-terminal predicate + run-state guard, then writes the
-     * terminal row and fires Platform-forwarding callbacks.
+     * Path B helper: complete a run from DB rows only (crash recovery / pruned
+     * runs) — all-terminal predicate, run-state guard, terminal row,
+     * Platform-forwarding callbacks.
      *
-     * The run-state read and the terminal write are separate statements, so the
-     * write carries its own clobber guard. If that guard rejects it — a
-     * concurrent normal completion landed in between — the callbacks and the
-     * completion metrics are suppressed with it.
+     * The run-state read and the write are separate statements, so the write has
+     * its own clobber guard; when a concurrent normal completion lands between
+     * them, callbacks and metrics are suppressed too.
      */
     private completeRunFromDbFallback;
-    /**
-     * Emit a run.event message to Platform via the onRunEventEmit callback.
-     * Called at orchestrator lifecycle points for infrastructure event tracking.
-     */
+    /** Emit a run.event to the Platform at an orchestrator lifecycle point. */
     private emitRunEvent;
     /**
-     * Emit a scaler lifecycle event for a job.
-     * Stores the event in the event_log table via the existing run.event pipeline
-     * and writes a log line to the provisioning JSONL file.
-     *
-     * @param runId - The run this event belongs to
-     * @param jobId - The job this event belongs to
-     * @param event - The scaler event with type, detail, and timestamp
+     * Emit a job's scaler lifecycle event: stored in event_log via the run.event
+     * pipeline and written to the provisioning JSONL file.
      */
     emitScalerEvent(runId: string, jobId: string, event: {
         agentId: string;
@@ -1448,34 +1283,29 @@ export declare class ExecutionTracker {
         timestampMs: number;
     }): void;
     /**
-     * Append a line to a per-job orchestration log file via LogStorage.
-     * Log format is JSONL for structured parsing on the frontend.
-     * Path convention: executions/{runId}/jobs/{jobId}/orchestration.jsonl
+     * Append a JSONL line to a job's orchestration log
+     * (executions/{runId}/jobs/{jobId}/orchestration.jsonl).
      */
     private writeOrchLog;
     /**
-     * Build a human-readable description for a completed run.
-     * Lists failed job names for non-success outcomes.
+     * Human-readable description of a non-success run (its failed job names).
      */
     private buildRunDescription;
     /**
-     * Compute the overall run status from job statuses.
-     *
-     * Per locked decision:
+     * Overall run status from job statuses:
      * - success ONLY if ALL jobs pass (skipped jobs count as success)
      * - failed if ANY job ended in a failure status (see `STATUS_FAILURE_CLASS`)
      * - cancelled if ANY job cancelled (and none failed)
      */
     private computeRunStatus;
     /**
-     * Derive the failure class from a terminal run's job statuses. Null for
+     * Derive the failure class from a terminal run's job statuses; null for
      * success (and any non-terminal status). `timed_out_stale` / `drift_dropped`
-     * / `unroutable` jobs — a job that never dispatched, whose `runsOn` matched no
-     * agent, whose agent went silent, or that was dropped by a topology reroute —
-     * are infra-class and collapse to `timed_out`; any other `failed` run is a
-     * `step_failure` (a job actually ran and failed). `never_started` (init
-     * failure) and `dead_orchestrator` (Platform-detected) are stamped by their
-     * own paths, not here.
+     * / `unroutable` jobs (never dispatched, `runsOn` matched no agent, agent went
+     * silent, or dropped by a topology reroute) are infra-class and collapse to
+     * `timed_out`; any other `failed` run is a `step_failure`. `never_started`
+     * (init failure) and `dead_orchestrator` (Platform-detected) are stamped by
+     * their own paths.
      */
     private computeFailureClass;
 }