@kici-dev/orchestrator 0.4.0 → 0.6.0

package/dist/providers/universal-git/config.d.ts

@@ -72,6 +72,7 @@ export declare const UniversalGitPayloadPathsSchema: z.ZodObject<{
     commitsAdded: z.ZodString;
     commitsModified: z.ZodString;
     commitsRemoved: z.ZodString;
+    commitMessage: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type UniversalGitPayloadPaths = z.infer<typeof UniversalGitPayloadPathsSchema>;
 /**
@@ -129,6 +130,7 @@ export declare const UniversalGitConfigSchema: z.ZodObject<{
         commitsAdded: z.ZodString;
         commitsModified: z.ZodString;
         commitsRemoved: z.ZodString;
+        commitMessage: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     eventMapping: z.ZodOptional<z.ZodObject<{
         push: z.ZodArray<z.ZodString>;

package/dist/providers/universal-git/index.d.ts

@@ -18,8 +18,17 @@
  *   - `UniversalGitRepoUrlBuilder` — substitutes `{owner}`/`{name}`/`{repo}`
  *     in the source's `gitUrlTemplate`.
  *
- * No `ContributorResolver` or `CheckStatusPoster` is wired for v1 — forge
- * API support for those is uneven and adding it is a separate phase.
+ * No `CheckStatusPoster` is wired for v1 — forge API support for it is uneven
+ * and adding it is a separate phase.
+ *
+ * The bundle also leaves `hasForkModel` unset. The normalizer does report an
+ * `isForkPR`, but it compares two repo names that `extractRepoFullName` reads
+ * from fixed keys (`repo.full_name`, then `full_name`) on the payload's `head`
+ * and `base` — keys many forges' PR payloads do not carry, and which no
+ * `payloadPaths` entry can redirect. It yields `false` whenever either is
+ * absent, so it fails toward trust. A pull-request event here therefore
+ * resolves no trust tier: it reads the base branch's lock file and writes an
+ * isolated cache scope, and the org fork policy never gates it.
  */
 import type { ProviderBundle } from '../../provider-registry.js';
 import type { GenericWebhookSource } from '../../db/types.js';

package/dist/providers/universal-git/normalizer.d.ts

@@ -84,6 +84,16 @@ export declare class UniversalGitWebhookNormalizer implements WebhookNormalizer
      * is safe to ship ahead of the interface change in Phase 3.
      */
     extractDefaultBranch(payload: unknown): string | null;
+    /**
+     * Text a `commitMessage` trigger filter is tested against.
+     *
+     * Push/tag reads the configured JSONPath, because forges genuinely differ on
+     * where the head commit lives. The PR read is STRUCTURAL rather than
+     * configured, matching how this normalizer already resolves base/head refs —
+     * `pull_request` on Gitea-family forges, `object_attributes` on GitLab, whose
+     * body field is spelled `description`.
+     */
+    private extractCommitMessage;
     /** Classify the raw event header against the source's eventMapping. */
     private classifyEvent;
 }

package/dist/queue/cleanup.d.ts

@@ -6,7 +6,7 @@ import type { CheckRunTrackingStore } from '../reporting/check-run-tracking-stor
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import type { LogStorage } from '../reporting/log-storage.js';
 import { JobQueue } from './job-queue.js';
-import { type CanRouteLabels } from './terminalize-unroutable.js';
+import { type CanRouteLabels, type TerminalizeDeps } from './terminalize-unroutable.js';
 /**
  * Optional cleanup dependencies + retention knobs. Present in platform/hybrid
  * mode (the only wiring site, `orchestrator-core`, always supplies them); the
@@ -67,6 +67,12 @@ export interface CleanupExtras {
      * safety: the job is terminal either way and the run fails either way.
      */
     canRouteLabels?: CanRouteLabels;
+    /**
+     * The Tier-2 global-eval tracker, forwarded to
+     * {@link terminalizeUnroutableJob} so a round job this sweep settles also
+     * settles the webhook request awaiting its verdict.
+     */
+    pendingGlobalEvals?: TerminalizeDeps['pendingGlobalEvals'];
 }
 /**
  * Run a single cleanup pass: remove expired dedup_cache entries and

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

@@ -180,6 +180,23 @@ export interface QueuedJob {
     /** For a runsOnAll host-fanout child: the agent this job is pinned to. */
     pinnedAgentId?: string;
 }
+/**
+ * The resource shape a job declares, read from the one location that always
+ * carries it.
+ *
+ * `jobConfig.resources` is where the declaration is stored and transported: it
+ * is what `job_config` holds across the DB round trip and what a worker
+ * receives over the wire. The typed `resources` field on {@link QueuedJobInput}
+ * and {@link QueuedJob} is a convenience mirror, and it is optional — several
+ * dispatch paths build their input without it (the worker's reroute handler and
+ * the webhook dispatch path among them). So a consumer that reads only the
+ * mirror sees a job that declares nothing, and a shape-sensitive decision made
+ * on that reading is wrong rather than merely unaware.
+ *
+ * Callers that hold a mirror still prefer it — it is the same value — and fall
+ * back here.
+ */
+export declare function resourcesFromJobConfig(jobConfig: Record<string, unknown> | undefined): ResourceRequest | undefined;
 /**
  * DB-backed FIFO job dispatch queue using Kysely (PostgreSQL only).
  * Uses SQL-based JSONB containment queries (@> operator) for label matching.
@@ -236,21 +253,69 @@ export declare class JobQueue {
      * @param agentLabels Labels the agent provides.
      * @param agentMandatoryLabels Mandatory labels the spawning scaler declared
      *   (empty for static / non-scaler agents).
+     * @param canServe Optional extra predicate applied to every candidate row
+     *   before it is claimed. Labels cannot express whether a pre-spawned agent's
+     *   fixed cpu / memory / image fit a job, so a caller that has to answer that
+     *   supplies it here — the row must never be claimed and put back, because a
+     *   claim-then-release both strands it as Dispatched for a window and burns a
+     *   dispatch attempt. Supplying it opts out of the single-statement fast
+     *   path, so pass it only for an agent that actually needs the check.
      * @returns The matching job, or null if none found.
      */
-    dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[], agentId?: string): Promise<QueuedJob | null>;
+    dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[], agentId?: string, canServe?: (job: QueuedJob) => boolean): Promise<QueuedJob | null>;
+    /**
+     * The column writes that constitute a claim. Identical to what
+     * {@link markDispatched} sets, so a claim and the caller's follow-up
+     * markDispatched are the same transition applied twice rather than two
+     * different half-transitions — and a row is never observable as Dispatched
+     * with no owner.
+     *
+     * `agentId` is optional only because `dequeueForLabels` accepts it optionally;
+     * every production caller supplies it.
+     */
+    private claimTransition;
+    /**
+     * Conditionally claim one row by id: flip Pending -> Dispatched, returning
+     * whether this caller won. The `status = Pending` guard is the arbiter — a
+     * loser updates zero rows and must treat that as "someone else took it",
+     * never as an error.
+     *
+     * Used by every claim path that has to run a JS post-filter before claiming
+     * (the regex matchers), since that filter runs after the SELECT's
+     * per-statement lock window has already closed.
+     */
+    private claimRowById;
     /**
      * Build the shared drain WHERE chain (status / expiry / exact-label @> /
      * exclude-label / pin / mandatory-label gate) common to both drain passes.
      * The pattern columns are NOT filtered here — each pass adds its own
      * pattern-free / pattern-bearing guard on top.
+     *
+     * No projection is attached: the pattern-free pass selects `id` alone (it
+     * embeds this as the sub-select of its claiming UPDATE), while the pattern
+     * pass selects every column so it can run the JS matcher post-filter.
      */
     private drainBaseQuery;
     /**
      * Fast path: claim the oldest pending pattern-free row. The
      * `runs_on_patterns = '[]' AND exclude_patterns = '[]'` guard restricts this
-     * pass to rows that need no JS post-filter, so the single-row atomic claim
-     * (FOR UPDATE SKIP LOCKED) keeps the original hot-path semantics intact.
+     * pass to rows that need no JS post-filter, which is what lets the whole
+     * claim be ONE statement.
+     *
+     * Selecting a row and transitioning it in two statements is not a claim.
+     * Outside an explicit transaction the `FOR UPDATE` lock lives only for the
+     * duration of its own SELECT, so a second agent arriving between the SELECT
+     * and the UPDATE reads the row still Pending, skips nothing, and dispatches
+     * the same job — which is one job executing twice on two agents, side effects
+     * and all.
+     *
+     * So the sub-select is embedded in the claiming UPDATE: its `FOR UPDATE SKIP
+     * LOCKED` row lock is now taken inside the UPDATE's own transaction and held
+     * until commit. That buys both halves at once — exactly one claimant can win
+     * a given row, and a concurrent claimant SKIPs the locked row and takes the
+     * *next* one instead of coming back empty-handed, which a select-then-claim
+     * retry loop would not preserve. The redundant outer `status = Pending` is
+     * belt-and-braces on the arbiter.
      */
     private claimPatternFree;
     /**
@@ -263,8 +328,29 @@ export declare class JobQueue {
      * Pending` makes exactly one of them win. The claim transitions the row to
      * Dispatched, matching the value the caller-side markDispatched would set
      * (which then re-sets it idempotently).
+     *
+     * Losing the claim continues to the next candidate rather than returning
+     * null, so a lost race costs this agent a candidate and not a whole drain.
      */
     private claimWithPatterns;
+    /**
+     * Both drain passes at once, with an extra JS predicate between the SELECT
+     * and the claim.
+     *
+     * Same shape as {@link claimWithPatterns} and for the same reason: the filter
+     * has to run BEFORE the row transitions, so the claim is a conditional
+     * `status = Pending` UPDATE by id rather than the embedded sub-select the
+     * fast path uses. Claiming first and releasing on a rejection is not an
+     * option — it strands the row as Dispatched for the width of the round trip
+     * and spends one of the job's bounded dispatch attempts every time an
+     * unsuitable agent polls.
+     *
+     * It covers pattern-free rows too, which the fast path would otherwise take
+     * first, so the predicate is applied to every candidate rather than to the
+     * pattern-bearing minority. Losing a claim continues to the next candidate,
+     * exactly as the pattern pass does.
+     */
+    private claimWithPostFilter;
     /**
      * Atomically claim the oldest pending job pinned to a specific agent. Used by
      * the eager pin drain when the pinned agent (re)registers or frees a slot —
@@ -276,6 +362,13 @@ export declare class JobQueue {
      * `runsOn`/`exclude` patterns no longer match the agent's current labels must
      * not be claimed. The single matching authority is the engine's
      * `matcherSatisfiedBy` (never a Postgres `~`).
+     *
+     * The claim is the conditional UPDATE, not the SELECT: the JS post-filter has
+     * to run first (claiming and then releasing a pattern-rejected row would
+     * strand it as Dispatched), which puts the filter outside the SELECT's
+     * per-statement lock window. Losing that claim returns null, and
+     * `onAgentAvailable` then falls through to the generic label drain — which
+     * also matches jobs pinned to this agent — so a lost race is not a stall.
      */
     dequeueByPinnedAgent(agentId: string, agentLabels?: string[]): Promise<QueuedJob | null>;
     /**
@@ -292,10 +385,22 @@ export declare class JobQueue {
      * spawned the agent and was reassigned to a different queued job).
      *
      * Returns null if the job is gone, no longer pending, expired, its label
-     * requirements are no longer satisfied by the agent, or the agent's gate
-     * is not satisfied by the job's `runsOn`.
-     */
-    dequeueById(jobId: string, agentLabels: string[], agentMandatoryLabels?: string[]): Promise<QueuedJob | null>;
+     * requirements are no longer satisfied by the agent, the agent's gate is not
+     * satisfied by the job's `runsOn`, or another claimant won the row first.
+     *
+     * That last case is the one this shares with every other claim path: the
+     * eager bound claim and the generic drain can target the same row moments
+     * apart, and a SELECT that returns the row still Pending lets both dispatch
+     * it. The conditional UPDATE below is the arbiter, and it runs after the JS
+     * post-filter so a pattern-rejected row is never claimed and stranded. A
+     * loser returns null, and `dispatchBoundJob` then falls back to the generic
+     * `onAgentAvailable` drain exactly as it does for an already-gone job.
+     *
+     * @param claimingAgentId Recorded as the row's durable owner as part of the
+     *   claim. Optional so existing 3-arg callers keep working; the caller's
+     *   markDispatched sets the same column immediately afterwards either way.
+     */
+    dequeueById(jobId: string, agentLabels: string[], agentMandatoryLabels?: string[], claimingAgentId?: string): Promise<QueuedJob | null>;
     /**
      * Insert a job directly with status='dispatched' (bypasses the queue).
      * Used when an agent is immediately available and the job doesn't need to wait.

package/dist/queue/terminalize-unroutable.d.ts

@@ -3,6 +3,7 @@ import { ExecutionJobStatus, type LabelMatcher } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
 import type { ExecutionTracker } from '../reporting/execution-tracker.js';
 import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
+import type { PendingGlobalEvalTracker } from '../cache/pending-global-evals.js';
 import type { ExpiredJobInfo } from './job-queue.js';
 /**
  * Whether ANYTHING could ever run a job with these selectors — a registered
@@ -23,6 +24,18 @@ export interface TerminalizeDeps {
     executionTracker: ExecutionTracker;
     checkRunReporter?: Pick<CheckRunReporter, 'updateJobStatus'>;
     canRouteLabels?: CanRouteLabels;
+    /**
+     * The Tier-2 global-eval tracker, so a round job settled here also settles
+     * the webhook request awaiting its verdict.
+     *
+     * A round job is the one queue entry with an in-process awaiter and no
+     * `execution_runs` row — the round decides whether any run exists at all —
+     * so the rest of this function skips it entirely and the awaiter would
+     * otherwise wait out its full ceiling for a job the queue has already
+     * declared dead. With the shipped defaults that is a 120s definitive
+     * fast-fail followed by a 240s wait, twice.
+     */
+    pendingGlobalEvals?: Pick<PendingGlobalEvalTracker, 'reject'>;
 }
 export declare function unroutableMessage(job: JobRoutingFacts): string;
 /**

package/dist/registration/extractor.d.ts

@@ -29,9 +29,9 @@ export declare function extractGlobalWorkflows(lockFile: LockFile): LockWorkflow
  * Extract workflows that have at least one registerable trigger, OR that
  * have repo patterns (global workflows).
  *
- * Since phase 28.5, Git-provider triggers (push, pr, tag, …) are ALSO
- * registerable so cross-source dispatch can resolve them via the registration
- * index when a generic webhook targets an externally-hosted repo. The
+ * Git-provider triggers (push, pr, tag, …) are ALSO registerable, so
+ * cross-source dispatch can resolve them via the registration index when a
+ * generic webhook targets an externally-hosted repo. The
  * per-event lock file pipeline remains the primary matching path for
  * same-source git events; registration is an additive index.
  *

package/dist/registration/registration-index.d.ts

@@ -21,6 +21,13 @@ export interface RegisteredWorkflow {
      */
     customerId: string;
     commitSha: string | null;
+    /**
+     * The repository's default branch at last registration. A `__schedule_fire`
+     * run executes this branch's lock file, so it is the branch such a run
+     * presents to a context's branch restrictions. `null` until the repo's next
+     * default-branch push populates it.
+     */
+    defaultBranch: string | null;
     sourceFile: string | null;
 }
 /**

package/dist/registration/registration-run-match.d.ts

@@ -0,0 +1,47 @@
+import type { ExpressionBuilder, ExpressionWrapper, SqlBool } from 'kysely';
+import type { Database } from '../db/types.js';
+/**
+ * Match `execution_runs` rows to the registrations that define their workflow.
+ *
+ * A registration always names the repository the workflow is DEFINED in. A run
+ * names two repositories: `repo_identifier` is the one it acted on and whose
+ * code its jobs checked out, and `workflow_repo_identifier` is the one that
+ * defines the workflow — recorded only when the two differ, which is exactly an
+ * organization-wide workflow dispatched against another repository.
+ *
+ * So the repository a registration must be matched on is
+ * `workflow_repo_identifier ?? repo_identifier`. Matching on `repo_identifier`
+ * alone is wrong in both directions at once: a global registration matches none
+ * of its own runs, and a same-named registration in the acted-on repository
+ * matches all of them.
+ *
+ * Both consumers — the "last triggered" enrichment and the delete path's
+ * in-flight cancellation — share this one predicate deliberately. Fixing one
+ * and not the other would leave the dashboard showing a global workflow as
+ * triggered while deleting it still cancelled nothing.
+ *
+ * A NULL marker is evidence of a per-repository run only because every
+ * recording site states which repository defines the workflow it is recording,
+ * and the sites narrow that to NULL exactly when it is the repository the run
+ * acted on. The predicate never infers the answer, and the recording sites do
+ * not leave it to a default: `recordInitFailureRun`, `recordRunHeld` and
+ * `recordGlobalEvalRoundFailureRun` take the defining repository as a required
+ * argument, and `WorkflowDispatchContext` carries it as a required field, so a
+ * dispatch path that does not state it does not compile. The one run-start
+ * recorder that takes it as a trailing positional, `onExecutionStarted`, is
+ * supplied by the global dispatch path — the only path where the two
+ * repositories differ.
+ */
+export declare function runsDefinedByRepos(eb: ExpressionBuilder<Database, 'execution_runs'>, repoIdentifiers: readonly string[]): ExpressionWrapper<Database, 'execution_runs', SqlBool>;
+/**
+ * The repository that defines the workflow a run executed — the read-side
+ * counterpart of {@link runsDefinedByRepos}, applied to a row the query
+ * returned. Selecting `workflow_repo_identifier` alongside `repo_identifier`
+ * and folding here keeps the grouping key the same expression the predicate
+ * filters on.
+ */
+export declare function definingRepoOfRun(row: {
+    repo_identifier: string;
+    workflow_repo_identifier: string | null;
+}): string;
+//# sourceMappingURL=registration-run-match.d.ts.map

package/dist/registration/registration-store.d.ts

@@ -24,6 +24,16 @@ export interface RegistrationRow {
      */
     customerId: string;
     commitSha: string | null;
+    /**
+     * The repository's default branch, captured from the push that last updated
+     * this registration. A `__schedule_fire` run executes this branch's lock
+     * file, so this is the branch such a run presents to a context's branch
+     * restrictions.
+     *
+     * `null` when the registration predates the column or the payload named no
+     * default branch — the run then presents no branch and the gate rejects.
+     */
+    defaultBranch: string | null;
     sourceFile: string | null;
     created_at: Date;
     updated_at: Date;
@@ -40,6 +50,18 @@ interface ReplaceAllOptions {
      */
     customerId: string;
     commitSha?: string;
+    /**
+     * The repository's default branch, read off the registering push's payload.
+     * Persisted so a `__schedule_fire` run can present it as its own branch.
+     *
+     * Three states, and the difference between the last two is load-bearing on an
+     * UPDATE: a string is written; `null` means the caller LOOKED and the payload
+     * named none, so the stored value is cleared; **omitting the field** means the
+     * caller does not know, and an already-captured branch is preserved. Only a
+     * default-branch push knows a repository's default branch, so a caller that
+     * is not one (the manual registration route) must not erase what one proved.
+     */
+    defaultBranch?: string | null;
     sourceFile?: string;
     /** Set of workflow names that should be marked as global */
     globalWorkflowNames?: Set<string>;

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

@@ -30,7 +30,7 @@ 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 { type TerminalJobStatus } from '@kici-dev/engine';
+import { CheckRunConclusion, type TerminalJobStatus } from '@kici-dev/engine';
 /**
  * Dependencies for the CheckRunReporter.
  */
@@ -87,6 +87,15 @@ interface SetPendingOptions {
     repo: string;
     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.
+     */
+    workflowRepoIdentifier?: string;
     jobNames: string[];
     installationId?: number;
     /** Routing key for per-app credential lookup (e.g., "github:12345"). */
@@ -105,6 +114,8 @@ interface SetBuildPendingOptions {
     repo: string;
     sha: string;
     workflowName: string;
+    /** See {@link SetPendingOptions.workflowRepoIdentifier}. */
+    workflowRepoIdentifier?: string;
     installationId?: number;
     /** Routing key for per-app credential lookup (e.g., "github:12345"). */
     routingKey?: string;
@@ -122,6 +133,8 @@ interface SetBuildCompleteOptions {
     repo: string;
     sha: string;
     workflowName: string;
+    /** See {@link SetPendingOptions.workflowRepoIdentifier}. */
+    workflowRepoIdentifier?: string;
     status: TerminalJobStatus;
     installationId?: number;
     /** Routing key for per-app credential lookup (e.g., "github:12345"). */
@@ -141,6 +154,8 @@ interface UpdateJobStatusOptions {
     repo: string;
     sha: string;
     workflowName: string;
+    /** See {@link SetPendingOptions.workflowRepoIdentifier}. */
+    workflowRepoIdentifier?: string;
     jobName: string;
     state: TerminalJobStatus;
     installationId?: number;
@@ -157,6 +172,15 @@ interface UpdateJobStatusOptions {
     runIdForLogs?: string;
     /** 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.
+     */
+    trustTier?: string;
+    lockFileSource?: string;
 }
 /**
  * Options for updateWorkflowStatus.
@@ -167,6 +191,8 @@ interface UpdateWorkflowStatusOptions {
     repo: string;
     sha: string;
     workflowName: string;
+    /** See {@link SetPendingOptions.workflowRepoIdentifier}. */
+    workflowRepoIdentifier?: string;
     overallStatus: TerminalJobStatus;
     installationId?: number;
     /** Routing key for per-app credential lookup (e.g., "github:12345"). */
@@ -176,6 +202,43 @@ interface UpdateWorkflowStatusOptions {
     requestId?: string;
     /** 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.
+     */
+    trustTier?: string;
+    lockFileSource?: string;
+}
+/**
+ * Options for completeUndispatchedCheckRuns.
+ */
+export interface CompleteUndispatchedCheckRunsOptions {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    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.
+     */
+    jobNames: string[];
+    installationId?: number;
+    /** Routing key for per-app credential lookup (e.g., "github:12345"). */
+    routingKey?: string;
+    /** Explicit requestId for trace context (falls back to AsyncLocalStorage context). */
+    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.
@@ -186,6 +249,8 @@ interface UpdateStepProgressOptions {
     repo: string;
     sha: string;
     workflowName: string;
+    /** See {@link SetPendingOptions.workflowRepoIdentifier}. */
+    workflowRepoIdentifier?: string;
     jobName: string;
     stepIndex: number;
     stepName: string;
@@ -257,7 +322,26 @@ export declare class CheckRunReporter {
      * still find every key for a runId at cleanup time.
      */
     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.
+     */
+    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
+     * 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.
@@ -301,6 +385,33 @@ export declare class CheckRunReporter {
      * Fire-and-forget: errors are logged but don't block the pipeline.
      */
     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.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    completeUndispatchedCheckRuns(opts: CompleteUndispatchedCheckRunsOptions): Promise<void>;
     /**
      * Clean up stale check runs left by a dead orchestrator.
      *
@@ -321,6 +432,8 @@ export declare class CheckRunReporter {
         repo: string;
         sha: string;
         workflowName: string;
+        /** See {@link SetPendingOptions.workflowRepoIdentifier}. */
+        workflowRepoIdentifier?: string;
         jobNames: string[];
     }): void;
     /**
@@ -337,7 +450,8 @@ export declare class CheckRunReporter {
      * 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
+     * Check run name format: kici/{workflowName}/setup — prefixed with the
+     * defining repository for a cross-repository global run, see `workflowLabel`.
      */
     setBuildPending(opts: SetBuildPendingOptions): void;
     /**
@@ -390,6 +504,13 @@ export declare class CheckRunReporter {
      * 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.
+     *
+     * 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.
      */
     private resolveCheckRunId;
     /**
@@ -425,6 +546,28 @@ export declare class CheckRunReporter {
      */
     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.
+     *
+     * 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.
+     */
+    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
@@ -468,6 +611,7 @@ export declare class CheckRunReporter {
      * Supports both 'completed' and 'in_progress' statuses.
      */
     private updateCheckRun;
+    private updateCheckRunLocked;
 }
 /**
  * Build a meaningful failure description from agent job status data.