@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/reporting/check-run-reporter.d.ts

@@ -1,78 +1,52 @@
 /**
- * GitHub check run integration module.
+ * GitHub Checks API integration for the execution lifecycle.
  *
- * Creates and updates check runs at key lifecycle points using the Checks API.
- * Per locked decisions:
- * - Check runs created (queued) at trigger match time (before agent picks up the job)
- * - Both per-job AND overall workflow check runs: kici/{workflow} and kici/{workflow}/job/{job}
- * - Success ONLY if ALL jobs pass
- * - Cancelled/timed-out use 'cancelled' conclusion
+ * - Check runs are created (queued) at trigger match time, before an agent picks up the job
+ * - Per-job AND overall check runs: kici/{workflow} and kici/{workflow}/job/{job}
+ * - Success ONLY if ALL jobs pass; cancelled/timed-out use the 'cancelled' conclusion
  * - All API calls are fire-and-forget (non-blocking)
  *
- * Check run IDs are tracked in-memory after creation so that subsequent
- * updates (job complete, workflow complete) can reference them via checks.update().
+ * Check run IDs are tracked after creation so later updates can call checks.update().
+ * Output carries live step progress (debounced at 5s), failure details (step names, errors,
+ * exit codes, log context) and annotations pointing at step source locations in
+ * `.kici/workflows/*.ts`. GitHub-only: other providers are a logged no-op.
  *
- * 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)
- *
- * Currently GitHub-only. Non-GitHub providers are handled gracefully (no-op with log).
- *
- * 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 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.
+ * Security check statuses (holds, approvals, workflow modifications) go through the separate
+ * engine `CheckStatusPoster` (packages/engine/src/provider/check-status-poster.ts; GitHub impl
+ * in packages/orchestrator/src/providers/github/check-status-poster.ts) — the two serve
+ * different purposes today.
  */
 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 { CheckRunConclusion, type TerminalJobStatus } from '@kici-dev/engine';
-/**
- * Dependencies for the CheckRunReporter.
- */
 interface CheckRunReporterDeps {
-    /**
-     * Provider registry for per-routing-key credential lookup: the reporter
-     * resolves GitHub App credentials by routing key from the registry's
-     * CloneTokenProvider config.
-     */
+    /** Resolves GitHub App credentials by routing key from its CloneTokenProvider config. */
     providerRegistry?: ProviderRegistry;
-    /** Step log buffer for enriched failure summaries. */
+    /** Feeds log context into 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.
+     * When provided, every per-key state mutation (check-run ID, step progress, build creation
+     * marker, in-progress-sent flag) is written through so a replacement coord on Raft leader
+     * switch can recover it. When omitted (unit tests that don't need HA correctness), state
+     * lives only in the in-memory `Map`s.
      */
     trackingStore?: CheckRunTrackingStore;
-    /** Resolver for step source locations from the lock file (for annotations). */
+    /** Step source locations from the lock file, for annotations. */
     getStepSourceLocations?: (workflowName: string, jobName: string) => SourceLocationData[] | undefined;
     /**
-     * Base URL of the user-facing dashboard (e.g.
-     * `https://dashboard.example.com/dashboard`). When set AND
-     * `getOrgPublicAlias()` returns an alias, the reporter populates
-     * `details_url = <dashboardUrl>/r/orgs/<alias>/runs/<runId>` on
-     * every check-run create/update. When unset, no `details_url` is
-     * emitted (preserving today's behavior).
+     * Dashboard base URL (e.g. `https://dashboard.example.com/dashboard`). When set AND
+     * `getOrgPublicAlias()` returns an alias, every check-run create/update carries
+     * `details_url = <dashboardUrl>/r/orgs/<alias>/runs/<runId>`; otherwise no `details_url`.
      */
     dashboardUrl?: string;
     /**
-     * Resolver for the orchestrator's owning org public alias. Typically
-     * wired to `PlatformClient.getOrgPublicAlias()`. Returns the
-     * `oal_<12-char>` alias supplied by Platform on `auth.success`, or
-     * `undefined` before auth completes.
+     * Typically `PlatformClient.getOrgPublicAlias()`: the `oal_<12-char>` alias the Platform
+     * supplies on `auth.success`, or `undefined` before auth completes.
      */
     getOrgPublicAlias?: () => string | undefined;
 }
-/**
- * Options for setPending.
- */
 interface SetPendingOptions {
     provider: string;
     owner: string;
@@ -80,12 +54,10 @@ interface SetPendingOptions {
     sha: string;
     workflowName: string;
     /**
-     * The repository that DEFINES the workflow, when that is not the repository
-     * the run acted on — an organization-wide workflow dispatched against
-     * another repository. Qualifies the check-run name so the run cannot share a
-     * check run with a same-named workflow of the acted-on repository; see
-     * `workflowLabel`. Passing the acted-on repository here is a no-op, so a
-     * caller cannot change a per-repository run's name by accident.
+     * The repository that DEFINES the workflow when it differs from the acted-on one (an
+     * organization-wide workflow). Qualifies the check-run name so the run cannot share a check
+     * run with a same-named workflow of the acted-on repository; see `workflowLabel`. Passing
+     * the acted-on repository is a no-op, so a per-repository run's name cannot change by accident.
      */
     workflowRepoIdentifier?: string;
     jobNames: string[];
@@ -97,9 +69,6 @@ interface SetPendingOptions {
     /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
     runId?: string;
 }
-/**
- * Options for setBuildPending.
- */
 interface SetBuildPendingOptions {
     provider: string;
     owner: string;
@@ -116,9 +85,6 @@ interface SetBuildPendingOptions {
     /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
     runId?: string;
 }
-/**
- * Options for setBuildComplete.
- */
 interface SetBuildCompleteOptions {
     provider: string;
     owner: string;
@@ -137,9 +103,6 @@ interface SetBuildCompleteOptions {
     /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
     runId?: string;
 }
-/**
- * Options for updateJobStatus.
- */
 interface UpdateJobStatusOptions {
     provider: string;
     owner: string;
@@ -165,18 +128,13 @@ interface UpdateJobStatusOptions {
     /** Job ID for StepLogBuffer lookup. */
     jobId?: string;
     /**
-     * The run's resolved trust tier and lock-file branch. When the tier is
-     * anything other than `trusted`, the completion summary leads with the
-     * reduced-privilege note so a contributor reading a failed job on a fork pull
-     * request can see which parts of the build environment the run did not have.
-     * Both absent for a run whose trust never resolved.
+     * The run's resolved trust tier and lock-file branch. For any tier other than `trusted`, the
+     * completion summary leads with the reduced-privilege note so a contributor reading a failed
+     * fork-PR job can see what the build environment lacked. Both absent when trust never resolved.
      */
     trustTier?: string;
     lockFileSource?: string;
 }
-/**
- * Options for updateWorkflowStatus.
- */
 interface UpdateWorkflowStatusOptions {
     provider: string;
     owner: string;
@@ -195,17 +153,13 @@ interface UpdateWorkflowStatusOptions {
     /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
     runId?: string;
     /**
-     * The run's resolved trust tier and lock-file branch, same contract as
-     * {@link UpdateJobStatusOptions}. The roll-up check carries the note too: a
-     * contributor who reads only `kici/<workflow>` — the one branch protection
-     * usually requires — would otherwise see a run fail with no explanation.
+     * Same contract as {@link UpdateJobStatusOptions}. The roll-up check carries the note too: a
+     * contributor who reads only `kici/<workflow>` — the one branch protection usually requires —
+     * would otherwise see a run fail with no explanation.
      */
     trustTier?: string;
     lockFileSource?: string;
 }
-/**
- * Options for completeUndispatchedCheckRuns.
- */
 export interface CompleteUndispatchedCheckRunsOptions {
     provider: string;
     owner: string;
@@ -214,11 +168,7 @@ export interface CompleteUndispatchedCheckRunsOptions {
     workflowName: string;
     /** See {@link SetPendingOptions.workflowRepoIdentifier}. */
     workflowRepoIdentifier?: string;
-    /**
-     * The job names `setPending` / `setPendingAwait` created a check run for.
-     * Pass the same list that call used, or the names will not match the check
-     * runs on the commit.
-     */
+    /** Pass the exact list `setPending` / `setPendingAwait` used, or names miss the check runs. */
     jobNames: string[];
     installationId?: number;
     /** Routing key for per-app credential lookup (e.g., "github:12345"). */
@@ -227,14 +177,10 @@ export interface CompleteUndispatchedCheckRunsOptions {
     requestId?: string;
     /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
     runId?: string;
-    /** The conclusion to complete each check run with. */
     conclusion: CheckRunConclusion;
     /** The check-run output body. The title stays the standard `KiCI: <label>` form. */
     summary: string;
 }
-/**
- * Options for updateStepProgress.
- */
 interface UpdateStepProgressOptions {
     provider: string;
     owner: string;
@@ -255,167 +201,121 @@ interface UpdateStepProgressOptions {
     runId?: string;
 }
 /**
- * Reports check run status to Git hosting providers.
+ * Reports check run status via the GitHub Checks API (checks.create / checks.update).
+ * Non-GitHub providers are a no-op with a warning log.
  *
- * Currently supports GitHub via the Checks API (checks.create / checks.update).
- * Non-GitHub providers are handled gracefully (no-op with warning log).
- *
- * All public methods are fire-and-forget: they return void immediately
- * and log errors internally without propagating them.
+ * All public methods are fire-and-forget: they return void immediately and log errors
+ * internally without propagating them.
  */
 export declare class CheckRunReporter {
     private deps;
     /**
-     * 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).
+     * L1 cache: composite key → check run ID, backed by `check_run_tracking.check_run_id` when
+     * `deps.trackingStore` is wired (miss → store; store miss → undefined, caller logs + skips).
+     * Without the store this Map IS the source of truth (single-coord deployments, unit tests).
      */
     private readonly checkRunIds;
     /**
-     * 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).
+     * L1 cache: in-flight build-creation promises. Needed locally even with the DB-backed
+     * `check_run_tracking.build_creation_state`, so a same-process `setBuildComplete` can await
+     * the in-progress `setBuildPending` (the DB column is a state marker, not an awaitable).
      */
     private readonly pendingBuildCreations;
     /** L1 cache: step-progress entries (synced to `check_run_tracking.step_progress_json`). */
     private readonly stepProgress;
     /**
-     * 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.
+     * L1 cache: per-key debounce timers. NOT persisted — on coord failover the next update
+     * either flushes immediately (the DB row's `updated_at` is older than the debounce window)
+     * or starts a fresh timer.
      */
     private readonly progressTimers;
     /** L1 cache: first in-progress sent flag (synced to `check_run_tracking.in_progress_sent_at`). */
     private readonly inProgressSent;
     /**
-     * Keys whose job check run has already been completed.
-     *
-     * Makes the check run's status monotonic: once a `completed` update is
-     * issued, no later step-progress update may push it back to `in_progress`.
-     * Cancelling the pending debounce timer at completion time is not sufficient
-     * on its own — a step status that arrives after the completion schedules a
-     * FRESH timer, which then fires and leaves the check run showing
-     * `status: in_progress` with a terminal `conclusion` already attached. That
-     * is the permanently-unresolved state check-run completion exists to prevent,
-     * so the guard is on the write itself rather than on the timer.
+     * Keys whose job check run has been completed. Makes status monotonic: after a `completed`
+     * update, no step-progress update may push it back to `in_progress`. Cancelling the debounce
+     * timer at completion is not enough — a step status arriving later schedules a FRESH timer,
+     * which would leave `status: in_progress` with a terminal `conclusion` attached, the
+     * permanently-unresolved state completion exists to prevent. So the guard is on the write
+     * itself, not on the timer.
      */
     private readonly terminalSent;
     /**
-     * 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.
+     * L1 cache: runId → check-run composite keys. Synced to the indexed
+     * `check_run_tracking.run_id` column so a replacement coord can find every key at cleanup.
      */
     private readonly runIdToKeys;
     /**
-     * Per-key serialization of GitHub check-run PATCHes. Two updates for one
-     * check run must never be in flight at GitHub simultaneously: the terminal
-     * `completed` write and an earlier `in_progress` write race last-write-wins,
-     * and if the `in_progress` PATCH lands second it reopens the check run to the
-     * permanently-unresolved `{ status: in_progress, conclusion: <terminal> }`
-     * state. The `terminalSent` re-check inside `updateCheckRun` cannot help once
-     * an `in_progress` PATCH has passed it and is awaiting the network — it is a
-     * check-then-await. Chaining every PATCH for a key through this map makes the
-     * re-check and the PATCH atomic relative to the completion write.
+     * Per-key serialization of GitHub check-run PATCHes. Two updates for one check run must never
+     * be in flight at once: the terminal `completed` write and an earlier `in_progress` write race
+     * last-write-wins, and an `in_progress` landing second reopens the check run to the
+     * permanently-unresolved `{ status: in_progress, conclusion: <terminal> }` state. The
+     * `terminalSent` re-check in `updateCheckRun` is a check-then-await and cannot stop a PATCH
+     * already on the network; chaining every PATCH for a key makes re-check + PATCH atomic
+     * relative to the completion write.
      */
     private readonly updateLocks;
     constructor(deps: CheckRunReporterDeps);
     /**
-     * Run `fn` after every previously-queued check-run PATCH for `key` has
-     * settled, so all updates to one check run execute strictly in order. The
-     * chain swallows prior errors (each is surfaced to its own caller) so one
+     * Run `fn` after every queued PATCH for `key` has settled, so updates to one check run run
+     * strictly in order. The chain swallows prior errors (each surfaces to its own caller) so one
      * failed PATCH does not wedge the key.
      */
     private runUpdateExclusive;
-    /**
-     * Update the provider registry used for per-routing-key credential lookup.
-     * Called after config reload when the provider registry is rebuilt.
-     */
+    /** Called after config reload rebuilds the provider registry. */
     updateRegistry(newRegistry: ProviderRegistry): void;
     /**
-     * Late-bind the public-alias resolver. Called from `server.ts` /
-     * `standalone.ts` after `PlatformClient` is constructed so the reporter
-     * can pull the freshly-authenticated org's alias when building
-     * `details_url`. orchestrator-core can't pass it at construction time
-     * because the platform client is created later (after the HTTP server
-     * starts).
+     * Late-bound from `server.ts` / `standalone.ts` once `PlatformClient` exists: orchestrator-core
+     * can't pass it at construction because the platform client is created after the HTTP server
+     * starts.
      */
     setOrgPublicAliasResolver(resolver: () => string | undefined): void;
     /**
-     * Set pending (queued) check runs for a workflow and all its jobs.
-     * Called at trigger match time (before agent picks up the job).
-     * Fire-and-forget: errors are logged but don't block the pipeline.
-     *
-     * Creates check runs via checks.create with status 'queued'.
-     * Per locked decision: both per-job AND overall workflow check runs.
-     * Name format: kici/{workflow-name}, kici/{workflow-name}/job/{job-name}
+     * Create queued check runs for a workflow (kici/{workflow-name}) and each job
+     * (kici/{workflow-name}/job/{job-name}) at trigger match time, before an agent picks up the job.
+     * Fire-and-forget.
      */
     setPending(opts: SetPendingOptions): void;
     /**
-     * Same as setPending but returns a Promise that resolves when check runs
-     * are created. Used by the RunCoordinator for rerouted jobs where the
-     * check runs MUST exist before job dispatch to ensure updates work.
+     * Awaitable setPending. The RunCoordinator uses it for rerouted jobs, whose check runs MUST
+     * exist before dispatch for updates to work.
      */
     setPendingAwait(opts: SetPendingOptions): Promise<void>;
-    /**
-     * Update a specific job's check run.
-     * Called when a job reaches a terminal state.
-     * Fire-and-forget: errors are logged but don't block the pipeline.
-     */
+    /** Called when a job reaches a terminal state. Fire-and-forget. */
     updateJobStatus(opts: UpdateJobStatusOptions): void;
     /**
-     * Update the overall workflow check run.
-     * Called when ALL jobs in a workflow reach terminal state.
-     * Per locked decision: success ONLY if ALL jobs pass.
-     * Fire-and-forget: errors are logged but don't block the pipeline.
+     * Called when ALL jobs in a workflow reach a terminal state; success ONLY if ALL jobs pass.
+     * Fire-and-forget.
      */
     updateWorkflowStatus(opts: UpdateWorkflowStatusOptions): void;
     /**
      * Complete the queued check runs of a workflow that never dispatched a job.
      *
-     * `setPendingAwait` creates `kici/<workflow>` and one
-     * `kici/<workflow>/job/<name>` per static job before the pipeline knows
-     * whether the workflow will run. When the workflow then ends without
-     * dispatching one — a hold rejected or expired, or any pre-dispatch init
-     * failure — none of these names ever reaches a job or run record, so
-     * `updateJobStatus` and `updateWorkflowStatus` are never called for them, and
-     * `doCleanupStaleCheckRuns` skips them because that sweep only updates check
-     * runs whose status is `in_progress`. They stay `queued` on the commit, which
-     * on a pull request reads as a check that never finishes and blocks branch
-     * protection.
+     * `setPendingAwait` creates `kici/<workflow>` and one `kici/<workflow>/job/<name>` per static
+     * job before the pipeline knows whether the workflow runs. When it ends without dispatching
+     * (a hold rejected or expired, any pre-dispatch init failure), no job or run record carries
+     * these names, so `updateJobStatus` / `updateWorkflowStatus` never fire, and
+     * `doCleanupStaleCheckRuns` skips them (it only updates `in_progress` check runs). They would
+     * stay `queued` — on a PR, a never-finishing check that blocks branch protection.
      *
-     * Completes only the check runs this reporter can resolve an id for (L1 cache
-     * or the `check_run_tracking` row), and skips a key already latched terminal.
+     * Completes only check runs whose id resolves (L1 or the `check_run_tracking` row), skipping
+     * keys already latched terminal.
      *
-     * The build check `kici/<workflow>/setup` is deliberately not in the set,
-     * because that latch does not reliably cover it. `setBuildComplete` stamps
-     * `terminal_sent_at` on the row but adds nothing to the in-process
-     * `terminalSent` set, and `resolveCheckRunId` returns on an L1 hit without
-     * reading the row — so a build check this process completed a moment ago
-     * resolves with no latch, and completing it again would overwrite a real
-     * build conclusion. An unreadable row is the harmless direction: it yields
-     * no id and the name is skipped.
+     * The build check `kici/<workflow>/setup` is deliberately excluded: the latch does not
+     * reliably cover it. `setBuildComplete` stamps `terminal_sent_at` on the row but not the
+     * in-process `terminalSent` set, and `resolveCheckRunId` returns on an L1 hit without reading
+     * the row — so a just-completed build check resolves unlatched, and completing it again would
+     * overwrite a real build conclusion. An unreadable row is harmless: no id, name skipped.
      */
     completeUndispatchedCheckRuns(opts: CompleteUndispatchedCheckRunsOptions): Promise<void>;
     /**
      * Clean up stale check runs left by a dead orchestrator.
      *
-     * Unlike updateJobStatus/updateWorkflowStatus (which rely on in-memory checkRunId),
-     * this method discovers check runs via the GitHub API by listing check runs for the
-     * commit SHA and matching on the `kici/` name prefix. This allows a replacement
-     * orchestrator to clean up check runs it didn't create.
-     *
-     * Uses the GitHub App to look up the installation for each repo, then lists and
-     * updates any stuck "in_progress" check runs with a "timed_out" conclusion.
-     *
-     * Fire-and-forget: errors are logged but don't block.
+     * Unlike updateJobStatus/updateWorkflowStatus (which rely on in-memory checkRunId), this lists
+     * the commit's check runs via the GitHub API and matches the `kici/` prefix, so a replacement
+     * orchestrator can clean up check runs it didn't create. Looks up each repo's installation via
+     * the GitHub App, then completes stuck "in_progress" check runs as "timed_out".
+     * Fire-and-forget.
      */
     cleanupStaleCheckRuns(opts: {
         provider: string;
@@ -429,140 +329,87 @@ export declare class CheckRunReporter {
         jobNames: string[];
     }): void;
     /**
-     * Update live step progress for a job's check run.
-     * Called each time a step starts, completes, or fails.
-     * The first 'running' step triggers an immediate in_progress transition.
-     * Subsequent updates are debounced (5 seconds) to prevent API rate limiting.
-     * Fire-and-forget: errors are logged but don't block the pipeline.
+     * Called each time a step starts, completes, or fails. The first 'running' step triggers an
+     * immediate in_progress transition; later updates are debounced (5 seconds) to avoid API rate
+     * limiting. Fire-and-forget.
      */
     updateStepProgress(opts: UpdateStepProgressOptions): void;
     /**
-     * Set a build check run to pending (queued).
-     * Called when a build job is dispatched for dependency installation and/or bundle compilation.
-     * Separate from execution check runs so users see build progress independently.
-     * Fire-and-forget: errors are logged but don't block the pipeline.
-     *
-     * Check run name format: kici/{workflowName}/setup — prefixed with the
-     * defining repository for a cross-repository global run, see `workflowLabel`.
+     * Queue the build check run when a build job (dependency install and/or bundle compilation) is
+     * dispatched — separate from execution check runs so users see build progress independently.
+     * Name: kici/{workflowName}/setup, prefixed with the defining repository for a
+     * cross-repository global run (see `workflowLabel`). Fire-and-forget.
      */
     setBuildPending(opts: SetBuildPendingOptions): void;
-    /**
-     * Update a build check run to completed.
-     * Called when the build job finishes (success, failure, or cancellation).
-     * Fire-and-forget: errors are logged but don't block the pipeline.
-     */
+    /** Called when the build job finishes (success, failure, or cancellation). Fire-and-forget. */
     setBuildComplete(opts: SetBuildCompleteOptions): void;
     /**
-     * Clean up step-progress entries and debounce timers for a completed run.
-     * Called when the execution tracker prunes the run.
+     * Drop a run's in-memory state when the execution tracker prunes it.
      *
-     * In-memory only. Database rows are owned by the retention sweep in
-     * `queue/cleanup.ts`, which deletes on inactivity age rather than on run
-     * completion. Deleting here would strand a late terminal update: a check-run
-     * status PATCH that arrives after the prune resolves its check-run ID by
-     * loading through to this row, and a deleted row makes that lookup fail.
+     * In-memory only: DB rows belong to the retention sweep in `queue/cleanup.ts`, which deletes
+     * on inactivity age, not run completion. Deleting here would strand a late terminal PATCH,
+     * which resolves its check-run ID by loading through to the row.
      */
     cleanupRun(runId: string): void;
     /**
-     * Mark the reporter as DB-backed after a leader switch (or any boot-time
-     * recovery). Called once on coord become-leader. If no store is wired,
-     * this is a no-op.
+     * Called once on coord become-leader (or any boot-time recovery); no-op without a store.
      *
-     * Nothing is hydrated up front — the table can be large across many shas —
-     * so check-run IDs load through on demand inside `resolveCheckRunId`. The
-     * `runIdToKeys` reverse map is rebuilt only from this coord's own writes,
-     * so a run whose keys all predate the switch leaves `cleanupRun` nothing to
-     * evict. That is harmless: the L1 caches it clears are equally empty on a
-     * fresh coord, and the DB rows belong to the retention sweep rather than to
-     * run prune.
+     * Nothing is hydrated up front — the table can be large across many shas — so IDs load
+     * through on demand in `resolveCheckRunId`. `runIdToKeys` is rebuilt only from this coord's
+     * writes, so a run whose keys predate the switch leaves `cleanupRun` nothing to evict. That is
+     * harmless: those L1 caches are equally empty on a fresh coord, and DB rows belong to the
+     * retention sweep, not run prune.
      */
     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.
+     * Inverse of `checkRunKey()`. Provider is always 'github': the reporter only writes GitHub
+     * check runs.
      */
     private parseKey;
-    /**
-     * Write-through helper: persist a check-run ID to L1 + the store.
-     * Used by `setPending` / `setBuildPending` after a successful
-     * `checks.create()`.
-     */
+    /** Write-through to L1 + store 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.
+     * Read-through: L1, then the store (cached on hit); undefined when neither has it — the caller
+     * logs + skips.
      *
-     * The same row also rehydrates the `terminalSent` latch. Both L1 entries are
-     * dropped together by `cleanupRun`, and only one of them used to come back:
-     * the id reloaded from here while the latch did not, which is exactly the
-     * pair that lets a late step-progress update resolve a check run and PATCH
-     * `status: in_progress` over its completion. Reading `terminal_sent_at` off
-     * the row this query already selects costs nothing and closes that gap.
+     * The same row also rehydrates the `terminalSent` latch. `cleanupRun` drops both L1 entries
+     * together; reloading the id without the latch would let a late step-progress update PATCH
+     * `status: in_progress` over the completion. `terminal_sent_at` is on the row already
+     * selected, so this costs nothing.
      */
     private resolveCheckRunId;
-    /**
-     * Write-through helper: persist updated step-progress entries.
-     */
     private persistStepProgress;
-    /**
-     * Write-through helper: mark the first running-step transition as sent.
-     */
+    /** Mark the first running-step transition as sent. */
     private persistInProgressSent;
-    /**
-     * Write-through helper: stamp `build_creation_state = 'pending'`.
-     */
+    /** Stamp `build_creation_state = 'pending'`. */
     private persistBuildCreationPending;
-    /**
-     * Resolve GitHub App credentials for a given routing key from the bundle's
-     * CloneTokenProvider `getAppConfig()`. Returns undefined when no routing key,
-     * registry, bundle or GitHub provider is available.
-     */
+    /** Via the CloneTokenProvider `getAppConfig()` (only GitHubCloneTokenProvider has it). */
     private resolveGithubConfig;
-    /**
-     * Resolve trace IDs for check run summaries.
-     * Priority: explicit option value > AsyncLocalStorage context > 'N/A'
-     */
+    /** Priority: explicit option value > AsyncLocalStorage context > 'N/A'. */
     private resolveTraceIds;
-    /**
-     * Append trace IDs to a check run summary string.
-     */
     private appendTraceIds;
     private checkRunKey;
     /**
      * The workflow label every check-run name and title is built from.
      *
-     * A check run's identity is `(owner, repo, sha, check name)` — on the
-     * provider, in `check_run_tracking`'s primary key, and in this class's L1
-     * keys. There is no run id anywhere in it. Two per-repository runs cannot
-     * collide on that identity, because one lock file cannot define a workflow
-     * name twice. An organization-wide workflow can: it is defined in ANOTHER
-     * repository, so its name is free to equal a workflow name of the repository
-     * it was dispatched against, and on the same commit the two runs then resolve
-     * to one check run. The global run's conclusion would complete the acted-on
-     * repository's check — the signal branch protection reads — and point its
-     * `details_url` at the wrong run, while `cleanupRun` would evict the other
-     * run's check-run id and terminal latch on prune.
+     * A check run's identity is `(owner, repo, sha, check name)` — on the provider, in
+     * `check_run_tracking`'s primary key, and in the L1 keys — with no run id. Per-repository runs
+     * cannot collide (one lock file cannot define a workflow name twice), but an
+     * organization-wide workflow, defined in ANOTHER repository, can share a name with the
+     * acted-on repository's workflow and resolve to one check run on the same commit. Its
+     * conclusion would then complete the acted-on check — the signal branch protection reads —
+     * with the wrong `details_url`, and `cleanupRun` would evict the other run's id and latch.
      *
-     * Qualifying the label with the defining repository keeps them apart. The
-     * "differs from the acted-on repository" narrowing lives here rather than at
-     * the call sites, so a per-repository run's name — which is customer-visible
-     * and may sit in a branch-protection required-check list — cannot move
-     * because a caller passed the field where it did not apply.
+     * Qualifying with the defining repository keeps them apart. The "differs from the acted-on
+     * repository" narrowing lives here, not at call sites, so a per-repository run's name
+     * (customer-visible, possibly a branch-protection required check) cannot move because a caller
+     * passed the field where it did not apply.
      */
     private workflowLabel;
     /**
-     * Build the `details_url` for a check run pointing at the dashboard's
-     * public-alias resolver (`/r/orgs/<oal_xxx>/runs/<runId>`). Returns
-     * `undefined` when either the dashboard URL or the alias is missing,
-     * or when the runId is the synthetic `'N/A'` sentinel from
-     * `resolveTraceIds` (no real run to link to). Strips any trailing
-     * slash on `dashboardUrl` so the concatenation produces a single
-     * separator.
+     * Dashboard public-alias link (`/r/orgs/<oal_xxx>/runs/<runId>`). Undefined when the
+     * dashboard URL or alias is missing, or runId is the `'N/A'` sentinel from `resolveTraceIds`.
      */
     private buildDetailsUrl;
     private doSetPending;
@@ -570,41 +417,20 @@ export declare class CheckRunReporter {
     private doUpdateWorkflowStatus;
     private doCleanupStaleCheckRuns;
     private doUpdateStepProgress;
-    /**
-     * Flush pending progress update to GitHub.
-     */
     private flushProgress;
     private doSetBuildPending;
     private doSetBuildComplete;
-    /**
-     * Map internal build status to GitHub Checks conclusion and description.
-     */
     private mapBuildConclusion;
-    /**
-     * Map internal job state to GitHub Checks conclusion and description.
-     */
     private mapJobConclusion;
-    /**
-     * Map internal workflow state to GitHub Checks conclusion and description.
-     */
     private mapWorkflowConclusion;
-    /**
-     * Create a check run via the GitHub Checks API.
-     * Returns the check run ID on success, or undefined on failure.
-     */
+    /** Returns the check run ID, or undefined on failure. */
     private createCheckRun;
-    /**
-     * Update an existing check run via the GitHub Checks API.
-     * Supports both 'completed' and 'in_progress' statuses.
-     */
     private updateCheckRun;
     private updateCheckRunLocked;
 }
 /**
- * Build a meaningful failure description from agent job status data.
- *
- * Examines `stepResults` for the first failed step, falling back to
- * `data.error`, and finally to a generic "Job failed" message.
+ * Failure description from agent job status data: the first failed step in `stepResults`,
+ * else `data.error`, else a generic "Job failed".
  */
 export declare function buildJobFailureDescription(data: Record<string, unknown>): string;
 export {};