@kici-dev/orchestrator 0.1.3 → 0.1.6

package/dist/events/types.d.ts

@@ -23,6 +23,20 @@ export interface EventRouterConfig {
     retryMaxBackoffMs: number;
     /** Interval at which the leader-only retry scanner ticks (default: 10_000) */
     retryScanIntervalMs: number;
+    /**
+     * **Test-only.** Per-event-name fault injection: when `attempts <= N`,
+     * the EventRouter throws a synthetic dispatch error to drive the retry /
+     * DLQ path. Used by the fault-injection E2E to prove the lease + retry
+     * loop dispatches a real run when the inner dispatch eventually
+     * succeeds, and lands the row in the DLQ when N exceeds
+     * `maxDispatchAttempts`.
+     *
+     * Only honoured when `KICI_TEST_MODE=1` is set at config-load time —
+     * production deployments never see this knob even if the env var is
+     * planted by accident. Source the value from
+     * `KICI_TEST_EVENT_FAIL_FIRST_N` (a JSON object literal).
+     */
+    debugFailFirstNAttemptsByEvent?: Record<string, number>;
 }
 /**
  * Reason an event landed in the DLQ.
@@ -54,6 +68,25 @@ export interface StoredEvent {
     dlqAt: Date | null;
     dlqReason: DlqReason | null;
 }
+/**
+ * Parse the `KICI_TEST_EVENT_FAIL_FIRST_N` JSON payload, gated by
+ * `KICI_TEST_MODE`. Returns the parsed map or `undefined` when:
+ *
+ * - `testMode` is false (the master switch). The JSON value is ignored
+ *   entirely; production deployments never see fault-injection even if
+ *   the per-event env var is accidentally planted.
+ * - the JSON value is absent / empty.
+ * - the JSON value is malformed or carries a wrong-shape entry. We
+ *   refuse to fall back to a partial map: a typo on one line silently
+ *   skipping that test would be confusing in CI logs.
+ *
+ * The accepted shape is `{ "<eventName>": <number> }`; non-string keys
+ * and non-number values are rejected. The numeric value is the inclusive
+ * upper bound of attempts to fail (so `1` fails the first attempt and
+ * succeeds on retry; `99` exceeds `maxDispatchAttempts` and lands the
+ * row in the DLQ).
+ */
+export declare function parseFaultInjectionMap(testMode: boolean, raw: string | undefined): Record<string, number> | undefined;
 /**
  * Default event router configuration.
  */

package/dist/metrics/scheduled-jobs.d.ts

@@ -1,18 +1,39 @@
-/** Success/failure counter for each tick of each scheduled job. */
+/**
+ * Success/failure counter for each tick of each scheduled job.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ * - result: success | failure
+ */
 export declare const jobRunsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
-/** Histogram of per-tick duration, seconds. */
+/**
+ * Histogram of per-tick duration, seconds.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ */
 export declare const jobDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
-/** Unix timestamp (seconds) of the most recent successful tick. */
+/**
+ * Unix timestamp (seconds) of the most recent successful tick.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ */
 export declare const jobLastSuccessTimestamp: {
     set(labels: Record<string, string>, value: number): void;
     reset(): void;
 };
-/** Unix timestamp (seconds) of the most recent failed tick. */
+/**
+ * Unix timestamp (seconds) of the most recent failed tick.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ */
 export declare const jobLastFailureTimestamp: {
     set(labels: Record<string, string>, value: number): void;
     reset(): void;
 };
-/** Count of consecutive failures since last success. Resets to 0 on success. */
+/**
+ * Count of consecutive failures since last success. Resets to 0 on success.
+ * Labels:
+ * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
+ */
 export declare const jobConsecutiveFailures: {
     set(labels: Record<string, string>, value: number): void;
     reset(): void;

package/dist/orchestrator-core.d.ts

@@ -27,7 +27,7 @@ import { ScalerManager } from './scaler/index.js';
 import type { ScalerConfig } from './scaler/index.js';
 import type { CacheStorage } from './storage/index.js';
 import { SourceCache, BuildCoordinator, DepCache, PendingBuildTracker, PendingInitTracker, PendingDynamicTracker } from './cache/index.js';
-import { CommitStatusReporter } from './reporting/commit-status.js';
+import { CheckRunReporter } from './reporting/check-run-reporter.js';
 import { StepLogBuffer } from './reporting/step-log-buffer.js';
 import { type LogStorage } from './reporting/log-storage.js';
 import { ExecutionTracker, type ExecutionTrackerDeps } from './reporting/execution-tracker.js';
@@ -39,10 +39,12 @@ import type { SecretStore } from '@kici-dev/engine';
 import type { AdminRouteDeps } from './routes/admin.js';
 import { AgentTokenStore } from './agent/token-store.js';
 import { OwnershipTracker } from './agent/ownership-tracker.js';
+import { EventStore } from './events/event-store.js';
 import { EventRouter } from './events/event-router.js';
 import { EventEmitter } from './events/event-emitter.js';
 import { TrustStore } from './events/trust-store.js';
 import { GenericSourceManager } from './webhook/generic-sources.js';
+import { GenericSourcesChangeListener } from './webhook/generic-sources-listener.js';
 import { RegistrationStore } from './registration/registration-store.js';
 import { RegistrationIndex } from './registration/registration-index.js';
 import { CronScheduler } from './cron/cron-scheduler.js';
@@ -72,7 +74,7 @@ export interface OrchestratorSubsystems {
     pendingBuilds: PendingBuildTracker | undefined;
     pendingInits: PendingInitTracker;
     pendingDynamics: PendingDynamicTracker;
-    commitStatusReporter: CommitStatusReporter;
+    checkRunReporter: CheckRunReporter;
     stepLogBuffer: StepLogBuffer;
     sourceLocationStore: SourceLocationStore;
     logStorage: LogStorage;
@@ -87,6 +89,12 @@ export interface OrchestratorSubsystems {
     lockFileCache: LockFileCache;
     dedup: DedupCache;
     eventRouter: EventRouter;
+    /**
+     * Event store for custom internal events (system + custom). Exposed
+     * here so the dashboard handler can serve the per-org DLQ surface
+     * (list / count / retry / discard) over the WS relay.
+     */
+    eventStore: EventStore;
     eventEmitter: EventEmitter;
     genericSourceManager: GenericSourceManager;
     trustStore: TrustStore;
@@ -107,6 +115,12 @@ export interface OrchestratorSubsystems {
     localConfigVersion: number;
     sourceStore: SourceStore;
     sourceManager: SourceManager;
+    /**
+     * Generic-webhook-source hot-reload listener. Exposed so the platform-mode
+     * boot can wire its `onChange` to re-push the full source list to the
+     * Platform when a generic source is added/removed at runtime.
+     */
+    genericSourcesChangeListener: GenericSourcesChangeListener;
     /** Inbound webhook delivery log writer (event_log table + object-storage payloads). */
     eventLogWriter: EventLogWriter;
     /** Access log writer (read + mutation attribution for dashboard + admin). */

package/dist/pipeline/processor.d.ts

@@ -26,7 +26,7 @@ import type { DepCache } from '../cache/index.js';
 import type { PendingBuildTracker } from '../cache/index.js';
 import type { PendingInitTracker } from '../cache/pending-inits.js';
 import type { PendingDynamicTracker } from '../cache/pending-dynamics.js';
-import type { CommitStatusReporter } from '../reporting/commit-status.js';
+import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
 import type { ExecutionTracker } from '../reporting/execution-tracker.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { RunCoordinator } from '../cluster/coordinator.js';
@@ -237,7 +237,7 @@ export interface ProcessingDeps {
     /** Pending dynamic tracker -- waits for agents to evaluate DynamicJobFn and return generated LockJob[]. */
     pendingDynamics?: PendingDynamicTracker;
     /** Commit status reporter for setting pending/success/failure/error on commits. Optional. */
-    commitStatusReporter?: CommitStatusReporter;
+    checkRunReporter?: CheckRunReporter;
     /** Execution tracker for DB persistence. Optional -- if not set, execution tracking is skipped. */
     executionTracker?: ExecutionTracker;
     /** Agent registry for determining execution target platform/arch. Optional -- if not set, defaults to linux/x64. */

package/dist/pipeline/rerun.d.ts

@@ -18,7 +18,7 @@ import type { Dispatcher } from '../agent/dispatcher.js';
 import type { ExecutionTracker } from '../reporting/execution-tracker.js';
 import type { JobQueue } from '../queue/job-queue.js';
 import type { PlatformClient } from '../ws/platform-client.js';
-import type { CommitStatusReporter } from '../reporting/commit-status.js';
+import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
 import type { RunCoordinator } from '../cluster/coordinator.js';
 import type { SecretResolver } from '../secrets/secret-resolver.js';
 import type { EventRouter } from '../events/event-router.js';
@@ -50,7 +50,7 @@ export interface RerunDeps {
     dispatcher: Dispatcher;
     jobQueue: JobQueue;
     platformClient: PlatformClient | null;
-    commitStatusReporter: CommitStatusReporter | null;
+    checkRunReporter: CheckRunReporter | null;
     coordinator: RunCoordinator | null;
     secretResolver: SecretResolver | null;
     eventRouter: EventRouter | null;

package/dist/pipeline/test-pipeline.d.ts

@@ -16,7 +16,7 @@
  */
 import type { LockFileCache } from '../lockfile-cache.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
-import type { CommitStatusReporter } from '../reporting/commit-status.js';
+import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
 import type { ExecutionTracker } from '../reporting/execution-tracker.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { ProviderRegistry } from '../provider-registry.js';
@@ -85,7 +85,7 @@ export interface TestPipelineDeps {
     lockFileCache: LockFileCache;
     dispatcher: Dispatcher;
     executionTracker?: ExecutionTracker;
-    commitStatusReporter?: CommitStatusReporter;
+    checkRunReporter?: CheckRunReporter;
     sourceCache?: SourceCache;
     buildCoordinator?: BuildCoordinator;
     depCache?: DepCache;

package/dist/policy/dashboard-write-policy.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Per-orchestrator policy controlling which dashboard.* write operations
+ * the orch accepts from Platform.
+ *
+ * Storage: a JSONB column on the existing `org_settings` table, keyed by
+ * `customer_id`. Empty object means every operation is enabled
+ * (permissive default at first-boot). Operators flip individual
+ * operations off via `kici-admin org-settings dashboard-writes set`.
+ *
+ * Three callers:
+ *   - The kici-admin CLI mutates via `setDashboardWritePolicy`.
+ *   - Mutating dashboard.* handlers check via `assertDashboardWriteAllowed`.
+ *   - The Platform-bound WS publisher reads the full map via
+ *     `getDashboardWritePolicy` to broadcast `orch.capabilities`.
+ *
+ * Reads are cached in-process (30 s TTL) — the policy changes
+ * infrequently and reading on every dashboard.* request is wasted IO.
+ * Writes invalidate the cache and emit a change event so the WS
+ * broadcaster can republish.
+ */
+import { EventEmitter } from 'node:events';
+import { type Kysely } from 'kysely';
+import { DashboardWriteOperation, type DashboardWritePolicyMap } from '@kici-dev/engine/protocol/dashboard-write-operations';
+import type { Database } from '../db/types.js';
+import type { ActorPrincipal } from '@kici-dev/engine';
+/**
+ * Event bus for policy-change notifications. The WS publisher subscribes
+ * to `'changed'` so it can broadcast a fresh `orch.capabilities` to
+ * Platform whenever the operator flips a switch.
+ */
+export declare const dashboardWritePolicyEvents: EventEmitter<[never]>;
+/**
+ * Error thrown by `assertDashboardWriteAllowed` when an operation is
+ * disabled. Carries the operation name + the descriptor's CLI hint so
+ * callers can surface a structured error to Platform / dashboard.
+ */
+export declare class DashboardWritePolicyDisabledError extends Error {
+    readonly operation: DashboardWriteOperation;
+    readonly cliEquivalent: string;
+    readonly code: "operation_disabled";
+    constructor(operation: DashboardWriteOperation, cliEquivalent: string);
+}
+/**
+ * Structured response envelope sent back to Platform when a mutating
+ * dashboard.* handler is rejected by the policy gate. Mirrors the
+ * Platform-side 403 body so the dashboard renders one consistent
+ * "operation disabled" affordance no matter which layer fires first.
+ */
+export declare function buildPolicyDeniedResponse(op: DashboardWriteOperation, responseType: string, requestId: string): Record<string, unknown>;
+/**
+ * Clear the cache. Public for tests and for the rare case where an
+ * operator wants to force a fresh read after manual DB surgery.
+ */
+export declare function invalidateDashboardWritePolicyCache(customerId?: string): void;
+/**
+ * Read the full policy map for a customer. Hits the in-process cache
+ * for 30 s after the first read; falls back to the DB on cache miss.
+ * Returns an empty map (everything enabled) when no `org_settings` row
+ * exists for the customer.
+ */
+export declare function getDashboardWritePolicy(db: Kysely<Database>, customerId: string): Promise<DashboardWritePolicyMap>;
+/**
+ * Single-operation check. Convenience wrapper around
+ * `getDashboardWritePolicy` + the engine-side resolver.
+ */
+export declare function isDashboardWriteEnabled(db: Kysely<Database>, customerId: string, op: DashboardWriteOperation): Promise<boolean>;
+/**
+ * Defense-in-depth gate for orch-side dashboard.* handlers. Throws
+ * `DashboardWritePolicyDisabledError` when the operation is disabled.
+ * Callers translate the error into the structured error envelope they
+ * send back to Platform.
+ */
+export declare function assertDashboardWriteAllowed(db: Kysely<Database>, customerId: string, op: DashboardWriteOperation): Promise<void>;
+/**
+ * Merge `updates` into the persisted policy and persist the result.
+ * Unknown keys in `updates` are rejected at the Zod schema layer
+ * before this function runs (kici-admin already validates). Any
+ * operation explicitly set to `true` is normalized away — the
+ * permissive default lives in the absence of the key, keeping the
+ * JSONB shape minimal.
+ *
+ * Each changed operation invokes the optional `onChange` callback
+ * once — the caller decides what to do with it (typically: write
+ * one `access_log` row per change).
+ *
+ * Emits `'changed'` on `dashboardWritePolicyEvents` with the new map
+ * so the WS publisher can rebroadcast capabilities.
+ */
+export declare function setDashboardWritePolicy(db: Kysely<Database>, customerId: string, updates: DashboardWritePolicyMap, options: {
+    actor: ActorPrincipal;
+    onChange?: (event: PolicyChangeEvent) => Promise<void>;
+}): Promise<DashboardWritePolicyMap>;
+/**
+ * Per-operation change event fired by `setDashboardWritePolicy` for
+ * each switch that actually flipped. The caller (admin HTTP route,
+ * test, future automation) decides what to do — typically writes one
+ * `access_log` row carrying `op`, `prior`, and `next` in `meta`.
+ */
+export interface PolicyChangeEvent {
+    actor: ActorPrincipal;
+    customerId: string;
+    op: DashboardWriteOperation;
+    prior: boolean;
+    next: boolean;
+}
+/**
+ * Reset to the permissive defaults (everything enabled). Useful for
+ * the `kici-admin org-settings dashboard-writes reset` subcommand.
+ */
+export declare function resetDashboardWritePolicy(db: Kysely<Database>, customerId: string, options: {
+    actor: ActorPrincipal;
+    onChange?: (event: PolicyChangeEvent) => Promise<void>;
+}): Promise<DashboardWritePolicyMap>;
+export { resolveFullPolicyView } from '@kici-dev/engine/protocol/dashboard-write-operations';
+//# sourceMappingURL=dashboard-write-policy.d.ts.map

package/dist/queue/job-queue.d.ts

@@ -298,8 +298,43 @@ export declare class JobQueue {
     /**
      * Mark a job as recovering (agent disconnected, within grace period).
      * Only transitions from 'dispatched' state for safety.
+     *
+     * When `deadline` and `agentId` are provided, persists them so a
+     * replacement coord on Raft leader switch can recreate the recovery
+     * timer (via `getRecoveringJobs()` on boot) or expire the row in
+     * the leader-gated sweep (`sweepExpiredRecoveries()`).
      */
-    markRecovering(jobId: string): Promise<void>;
+    markRecovering(jobId: string, deadline?: Date, agentId?: string): Promise<void>;
+    /**
+     * List every job currently in `recovering` state with its persisted
+     * recovery deadline. Used at coord boot (`Dispatcher.recoverState()`)
+     * to recreate the in-memory `recoveringJobs` Map with fresh timers.
+     *
+     * Returns rows whose `recovery_deadline` is non-null (the populated
+     * subset). Recovering rows from before the migration carry NULL and
+     * are handled by the leader-gated sweep on its next pass.
+     */
+    getRecoveringJobs(): Promise<Array<{
+        id: string;
+        runId: string;
+        agentId: string | null;
+        deadline: Date | null;
+    }>>;
+    /**
+     * Sweep every `recovering` row whose `recovery_deadline` is in the
+     * past, marking them `failed`. Returns the rows that flipped so the
+     * caller can fire the per-job `onRecoveryTimeout` hook in process.
+     *
+     * Intended for the leader-gated `Dispatcher.sweepExpiredRecoveries`
+     * tick — running on N coords would still be correct (the WHERE
+     * `status='recovering'` clause prevents double-failure) but only one
+     * needs to do the work.
+     */
+    sweepExpiredRecoveries(now: Date): Promise<Array<{
+        id: string;
+        runId: string;
+        agentId: string | null;
+    }>>;
     /**
      * Mark a job as failed only if it is still in 'recovering' state.
      * Uses optimistic concurrency to avoid failing jobs that were reclaimed.
@@ -321,6 +356,24 @@ export declare class JobQueue {
         runId: string;
         status: DispatchQueueStatus;
     } | null>;
+    /**
+     * HA-safe ownership check. Returns true if the DB shows that
+     * `agentId` previously held `jobId` according to any of:
+     *
+     *   - `status='dispatched'` AND the registry-managed bookkeeping
+     *     records the agent assignment (caller-side `agentJobs` map),
+     *   - `status='recovering'` AND `recovery_agent_id = <agent>` (so a
+     *     replacement coord still recognises in-flight chunks), OR
+     *   - the row is already terminal (`completed` / `failed` /
+     *     `expired`) — late `log.chunk` chunks from the agent's drain
+     *     window are accepted as benign duplicates rather than
+     *     rejected.
+     *
+     * Used by `OwnershipTracker.validateAsync` so a Raft leader switch
+     * doesn't turn the next 30s of legitimate per-job chunks into a
+     * stream of ownership violations.
+     */
+    hasAgentOwnedJob(agentId: string, jobId: string): Promise<boolean>;
     /**
      * Get all jobs matching a given status.
      * Used on startup to find 'dispatched' jobs from a previous instance for recovery.

package/dist/reporting/{commit-status.d.ts → check-run-reporter.d.ts}

@@ -12,7 +12,7 @@
  * Check run IDs are tracked in-memory after creation so that subsequent
  * updates (job complete, workflow complete) can reference them via checks.update().
  *
- * Enriched output (Phase 14):
+ * Enriched output:
  * - Live step progress with checklist-style updates (debounced at 5s)
  * - Failed check runs include step names, error messages, exit codes, and log context
  * - Check run annotations link failures to step source locations in workflow files (.kici/workflows/*.ts)
@@ -22,18 +22,19 @@
  * Note: The engine-level CheckStatusPoster interface (packages/engine/src/provider/check-status-poster.ts)
  * provides a provider-agnostic API for posting security-related check statuses (holds, approvals,
  * workflow modifications). The GitHub implementation is at packages/orchestrator/src/providers/github/check-status-poster.ts.
- * This CommitStatusReporter handles execution lifecycle checks (queued, in_progress, completed per job/workflow).
+ * This CheckRunReporter handles execution lifecycle checks (queued, in_progress, completed per job/workflow).
  * Future cleanup may unify both under CheckStatusPoster, but they serve different purposes today.
  */
 import { type GitHubAppConfig } from '../providers/github/auth.js';
 import type { ProviderRegistry } from '../provider-registry.js';
 import type { StepLogBuffer } from './step-log-buffer.js';
 import { type SourceLocationData } from './check-run-summary.js';
+import type { CheckRunTrackingStore } from './check-run-tracking-store.js';
 import { ExecutionJobStatus } from '@kici-dev/engine';
 /**
- * Dependencies for the CommitStatusReporter.
+ * Dependencies for the CheckRunReporter.
  */
-interface CommitStatusReporterDeps {
+interface CheckRunReporterDeps {
     /**
      * Provider registry for per-routing-key credential lookup.
      * When provided, the reporter resolves GitHub App credentials by routing key
@@ -48,6 +49,15 @@ interface CommitStatusReporterDeps {
     githubConfig?: GitHubAppConfig;
     /** Step log buffer for enriched failure summaries. */
     stepLogBuffer?: StepLogBuffer;
+    /**
+     * DB-backed tracking store. When provided, every per-key state mutation
+     * (check-run ID, step-progress array, build creation marker,
+     * in-progress-sent flag) is written through to the store so a replacement
+     * coord on Raft leader switch can recover the state. When omitted (the
+     * back-compat path used by unit tests that don't need HA correctness),
+     * the reporter operates entirely from in-memory `Map`s.
+     */
+    trackingStore?: CheckRunTrackingStore;
     /** Resolver for step source locations from the lock file (for annotations). */
     getStepSourceLocations?: (workflowName: string, jobName: string) => SourceLocationData[] | undefined;
     /**
@@ -196,19 +206,45 @@ interface UpdateStepProgressOptions {
  * All public methods are fire-and-forget: they return void immediately
  * and log errors internally without propagating them.
  */
-export declare class CommitStatusReporter {
+export declare class CheckRunReporter {
     private deps;
-    /** Map from composite key to check run ID for subsequent updates. */
+    /**
+     * L1 cache: composite key → check run ID.
+     *
+     * Backed by `check_run_tracking.check_run_id` when `deps.trackingStore`
+     * is wired. On a miss the cache falls through to the store; on a store
+     * miss the lookup returns undefined and the caller logs + skips.
+     *
+     * Without the store this Map IS the source of truth (single-coord
+     * deployments, unit tests).
+     */
     private readonly checkRunIds;
-    /** In-flight build check run creation promises, keyed by composite key. */
+    /**
+     * L1 cache: in-flight build-creation promises. The DB-backed counterpart
+     * lives in `check_run_tracking.build_creation_state`; this Map is needed
+     * locally so a same-process `setBuildComplete` can await the
+     * in-progress `setBuildPending` promise (the DB column is a state
+     * marker, not an awaitable).
+     */
     private readonly pendingBuildCreations;
-    /** Step progress entries per check run key. */
+    /** L1 cache: step-progress entries (synced to `check_run_tracking.step_progress_json`). */
     private readonly stepProgress;
-    /** Debounce timers for in_progress updates per check run key. */
+    /**
+     * L1 cache: per-key debounce timers. NOT persisted — on coord failover
+     * the next update either flushes immediately (because the DB row's
+     * `updated_at` is older than the debounce window) or starts a fresh
+     * timer.
+     */
     private readonly progressTimers;
-    /** Track whether the first in_progress transition has been sent per check run key. */
+    /** L1 cache: first in-progress sent flag (synced to `check_run_tracking.in_progress_sent_at`). */
     private readonly inProgressSent;
-    constructor(deps: CommitStatusReporterDeps);
+    /**
+     * L1 cache: runId → set of check-run composite keys. Synced to the
+     * indexed `check_run_tracking.run_id` column so a replacement coord can
+     * still find every key for a runId at cleanup time.
+     */
+    private readonly runIdToKeys;
+    constructor(deps: CheckRunReporterDeps);
     /**
      * Update the provider registry used for per-routing-key credential lookup.
      * Called after config reload when the provider registry is rebuilt.
@@ -298,14 +334,56 @@ export declare class CommitStatusReporter {
      */
     setBuildComplete(opts: SetBuildCompleteOptions): void;
     /**
-     * Clean up step progress entries and pending timers for a completed run.
-     * Called when execution tracker prunes a run from memory.
+     * Clean up step-progress entries, debounce timers, and DB rows for a
+     * completed run. Called when the execution tracker prunes the run.
+     *
+     * In-memory cleanup is synchronous; the DB cleanup is fire-and-forget
+     * because the caller (run-pruning hook) is on the response-shaping path
+     * and shouldn't block on a network round-trip. Failure logs but does
+     * not propagate.
      */
     cleanupRun(runId: string): void;
-    /** Map from runId to check run keys for cleanup. */
-    private readonly runIdToKeys;
+    /**
+     * Hydrate the L1 caches from the DB after a leader switch (or any
+     * boot-time recovery). Called once on coord become-leader so the
+     * runIdToKeys reverse map is populated for any future cleanupRun calls
+     * without requiring a DB round-trip per cleanup. If no store is wired,
+     * this is a no-op.
+     */
+    recoverState(): Promise<void>;
     /** Track a check run key associated with a runId for later cleanup. */
     private trackRunKey;
+    /**
+     * Parse a composite L1 cache key back into the (provider, owner, repo,
+     * sha, check_name) tuple used by the store. The key format is fixed by
+     * `checkRunKey()`; provider defaults to 'github' because today's
+     * reporter only writes check runs for GitHub.
+     */
+    private parseKey;
+    /**
+     * Write-through helper: persist a check-run ID to L1 + the store.
+     * Used by `setPending` / `setBuildPending` after a successful
+     * `checks.create()`.
+     */
+    private persistCheckRunId;
+    /**
+     * Read-through helper: look up a check-run ID. Checks L1 first, falls
+     * through to the store on miss, caches the result on hit. Returns
+     * undefined when neither layer has the ID — the caller logs + skips.
+     */
+    private resolveCheckRunId;
+    /**
+     * Write-through helper: persist updated step-progress entries.
+     */
+    private persistStepProgress;
+    /**
+     * Write-through helper: mark the first running-step transition as sent.
+     */
+    private persistInProgressSent;
+    /**
+     * Write-through helper: stamp `build_creation_state = 'pending'`.
+     */
+    private persistBuildCreationPending;
     /**
      * Resolve GitHub App credentials for a given routing key.
      *
@@ -379,4 +457,4 @@ export declare class CommitStatusReporter {
  */
 export declare function buildJobFailureDescription(data: Record<string, unknown>): string;
 export {};
-//# sourceMappingURL=commit-status.d.ts.map
+//# sourceMappingURL=check-run-reporter.d.ts.map