@kici-dev/orchestrator 0.4.0 → 0.5.0

package/dist/pipeline/process-webhook.d.ts

@@ -30,10 +30,17 @@ import { type ProcessingDeps } from './processor.js';
  * ingress route return `{ duplicate: true }` to GitHub's Recent Deliveries
  * panel; `skipped` covers unknown provider / unknown event / no-repo paths;
  * `processed` means the pipeline matched and dispatched (or recorded a run).
+ *
+ * `queued` means the delivery is durably stored and its pipeline will run after
+ * the response — the direct-ingress accept path's success outcome. It maps to
+ * the same 202 `processed` always did, because from the sender's side both mean
+ * "accepted, nothing more to do"; the distinction exists so the accept path can
+ * be asserted on directly rather than through the HTTP status.
  */
 export declare const WebhookIngestOutcome: z.ZodEnum<{
     duplicate: "duplicate";
     processed: "processed";
+    queued: "queued";
     shed: "shed";
     skipped: "skipped";
 }>;

package/dist/pipeline/processor.d.ts

@@ -18,6 +18,7 @@ import type { WebhookInfo } from '../webhook/handler.js';
 import type { DedupCache } from '../webhook/dedup.js';
 import type { ProviderRegistry, ProviderBundle } from '../provider-registry.js';
 import type { LockFileCache } from '../lockfile-cache.js';
+import type { ContentRequirementsCache } from '../content-requirements-cache.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
 import type { PlatformClient } from '../ws/platform-client.js';
 import type { QueuedJobInput } from '../queue/job-queue.js';
@@ -27,6 +28,8 @@ 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 { PendingGlobalEvalTracker } from '../cache/pending-global-evals.js';
+import type { GlobalEvalRoundCache } from '../cache/global-eval-round-cache.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';
@@ -35,6 +38,7 @@ import type { RunCoordinator } from '../cluster/coordinator.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import type { TeamMembershipLookup } from '../approvals/team-membership-lookup.js';
 import type { LogStorage } from '../reporting/log-storage.js';
+import type { LogWriter } from '../reporting/log-writer.js';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 import type { ContributorCache } from '../security/contributor-cache.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
@@ -228,8 +232,12 @@ export declare function buildTriggerEvent(event: string, action: string | null |
  */
 export declare function extractInboundRepoIdentifier(payload: unknown): string | null;
 /**
- * Extract the first line of the commit message from a webhook payload.
- * Handles push (head_commit.message) and PR (pull_request.title) events.
+ * Extract the first line of the commit message from a webhook payload, for run
+ * display. Handles push (head_commit.message), PR (pull_request.title) and
+ * issue_comment (issue.title) events.
+ *
+ * The Tier-0 `commitMessage` trigger filter deliberately reads a DIFFERENT text
+ * (the full message, and PR title + body) — see `githubFilterText`.
  */
 export declare function extractCommitMessage(event: string, payload: unknown): string | undefined;
 /**
@@ -267,7 +275,31 @@ export declare function summarizeApprovalClauses(clauses: ReadonlyArray<{
 export interface ProcessingDeps {
     dedup: DedupCache;
     providerRegistry: ProviderRegistry;
+    /**
+     * Re-register the provider bundle for a generic routing key from server
+     * truth, returning true when a bundle is now present.
+     *
+     * The registry is an in-memory CACHE of `generic_webhook_sources`, populated
+     * by three independent paths (startup enumeration, the admin write handler,
+     * and the LISTEN/NOTIFY drain). None of them can guarantee the entry is
+     * present for a delivery that arrives at an arbitrary moment, and a miss is
+     * not benign: `getByRoutingKey` used to substitute an unrelated `generic:`
+     * bundle whose normalizer reports "this payload has no repository", so the
+     * delivery was discarded with nothing above `debug` to say why.
+     *
+     * Optional — hand-built test deps and wirings with no generic-source manager
+     * keep the previous behaviour (a miss stays a miss, reported loudly).
+     */
+    ensureProviderBundle?: (routingKey: string) => Promise<boolean>;
     lockFileCache: LockFileCache;
+    /**
+     * Cache for the Tier-1 `requires` static content filter (source-file bytes at
+     * a ref, keyed by (repo, sha, path)). Optional so hand-built test deps and
+     * independent deployments that never use `requires` keep working; when absent,
+     * a candidate carrying `requires` is dropped fail-visible rather than
+     * dispatched unfiltered (see content-filter.ts).
+     */
+    contentRequirementsCache?: ContentRequirementsCache;
     dispatcher: Dispatcher;
     /** Null/undefined in Independent mode. send() buffers when disconnected. */
     platformClient?: PlatformClient;
@@ -285,6 +317,21 @@ export interface ProcessingDeps {
     pendingInits?: PendingInitTracker;
     /** Pending dynamic tracker -- waits for agents to evaluate DynamicJobFn and return generated LockJob[]. */
     pendingDynamics?: PendingDynamicTracker;
+    /** Pending global-eval tracker -- waits for the pre-run round that decides which global workflows apply. */
+    pendingGlobalEvals?: PendingGlobalEvalTracker;
+    /** Round-result cache for the pre-run global eval round. Optional -- if not set, every round re-runs. */
+    globalEvalCache?: GlobalEvalRoundCache;
+    /** Cluster default for the whole-round budget handed to the eval agent (ms).
+     *  The live per-cluster override is `cluster_settings.global_eval_round_timeout_ms`. */
+    globalEvalRoundTimeoutMs?: number;
+    /** Cluster default for the per-candidate budget handed to the eval agent (ms).
+     *  The live per-cluster override is `cluster_settings.global_eval_candidate_timeout_ms`. */
+    globalEvalCandidateTimeoutMs?: number;
+    /** Cluster default for the orchestrator's own ceiling on awaiting a round (ms).
+     *  Unlike the two budgets above, this one is enforced here rather than by the
+     *  agent, so it also bounds a round no agent ever picked up. The live
+     *  per-cluster override is `cluster_settings.global_eval_wait_timeout_ms`. */
+    globalEvalWaitTimeoutMs?: number;
     /** Commit status reporter for setting pending/success/failure/error on commits. Optional. */
     checkRunReporter?: CheckRunReporter;
     /** Execution tracker for DB persistence. Optional -- if not set, execution tracking is skipped. */
@@ -321,6 +368,13 @@ export interface ProcessingDeps {
     secretKey?: string;
     /** Log storage backend for persisting webhook payloads. Optional -- if not set, payload storage is skipped. */
     logStorage?: LogStorage;
+    /**
+     * Durable step-log writer. Optional -- when present, the deferred-init path
+     * uses it to surface a post-init env warning on the run's log stream so a
+     * blocking `kici run remote` test run prints it (the accept response has
+     * already been returned by the time the init round resolves).
+     */
+    logWriter?: Pick<LogWriter, 'appendChunk' | 'drain'>;
     /** Context store for looking up deployment contexts. Optional -- if not set, context features are inactive. */
     contextStore?: ContextStore;
     /** Variable store for resolving context variables. Optional -- if not set, context vars are not merged. */

package/dist/pipeline/route-or-dispatch-jobs.d.ts

@@ -19,6 +19,12 @@ export interface DispatchedJobEntry {
     jobName: string;
     matrixValues?: Record<string, unknown>;
     runsOnLabels?: string[];
+    /**
+     * The unexpanded job name a materialized child came from. Persisted to
+     * `execution_jobs.base_job_name`, which is the key the rolling-wave scheduler
+     * groups a wave's children by — a NULL there makes the wave gate bail.
+     */
+    baseJobName?: string;
 }
 export interface RejectedJobEntry {
     jobId: string;

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

@@ -22,6 +22,7 @@
  * - direct workflow execution (bypass trigger matching) is supported.
  */
 import { type ProcessingDeps } from './processor.js';
+import { type ActorPrincipal } from '@kici-dev/engine';
 import type { CheckMode, HostTargetSelector } from '@kici-dev/engine';
 /**
  * Input for a test trigger request.
@@ -58,6 +59,17 @@ export interface TestTriggerInput {
     };
     /** Request trace ID from the HTTP request. */
     requestId: string;
+    /**
+     * The principal that initiated this run, relayed by the Platform on
+     * `test.relay.trigger` (where the wire schema has always required it).
+     *
+     * Required rather than optional: the relay handler is the only production
+     * caller, so there is no path that legitimately lacks an actor, and an
+     * optional field would let a future caller silently drop attribution — which
+     * is exactly how `execution_runs.triggered_by` stayed NULL for every remote
+     * test run while the column claimed to hold the initiator.
+     */
+    actor: ActorPrincipal;
     /** JSON-stringified lock file content for local repos with no remote. */
     inlineLockFile?: string;
     /** When true, repo has no remote -- skip provider lookup, skip clone. */

package/dist/pipeline/webhook-payload-store.d.ts

@@ -0,0 +1,20 @@
+import type { LogStorage } from '../reporting/log-storage.js';
+/**
+ * Object-storage key holding the webhook payload for a run. Shared by the
+ * writers and by the re-run path that copies a payload forward, so the layout
+ * is stated once.
+ */
+export declare function webhookPayloadPath(runId: string): string;
+/**
+ * Store a run's triggering webhook payload, best-effort.
+ *
+ * A failure is logged and swallowed: the payload is a debugging aid, and losing
+ * it must never cost the run that was about to execute. A no-op when the
+ * orchestrator has no object storage configured.
+ */
+export declare function storeWebhookPayload(args: {
+    logStorage: LogStorage | undefined;
+    runId: string;
+    payload: unknown;
+}): Promise<void>;
+//# sourceMappingURL=webhook-payload-store.d.ts.map

package/dist/provenance/backfill-run.d.ts

@@ -6,6 +6,12 @@ export interface BackfillRunRow {
     status: string;
     routing_key: string | null;
     repo_identifier: string | null;
+    /**
+     * The repository that DEFINES the workflow, recorded only when it differs
+     * from `repo_identifier`. A cross-repository global run backfilled without it
+     * lands in the Platform mirror as an ordinary per-repository run.
+     */
+    workflow_repo_identifier: string | null;
     provider: string | null;
     local_working_tree: boolean | null;
     sha: string | null;
@@ -33,7 +39,10 @@ export interface BackfillRunDeps {
 }
 /**
  * Send one `execution.status` (terminal) followed by one `job.status.forward`
- * per job, populating exactly the fields the Platform's `handler.ts` upserts.
+ * per job, populating the run and job fields the Platform's `handler.ts` upserts
+ * that the local rows can answer for (the trigger metadata a live run carries in
+ * memory — trigger event, commit message, re-run lineage — has no column here
+ * and is left to the live path).
  * Ordered execution.status FIRST so the run row exists before the job rows
  * reference it. A no-op (throws) when the run is not found locally — the caller
  * leaves the pending row `deferred` with a clear error.

package/dist/provider-registry.d.ts

@@ -12,7 +12,7 @@
  * webhook normalization, lock file fetching, changed files retrieval,
  * clone token creation, and URL building.
  */
-import type { WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster, ProviderType } from '@kici-dev/engine';
+import type { WebhookNormalizer, LockFileFetcher, FileContentsFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster, ProviderType } from '@kici-dev/engine';
 /**
  * Complete set of provider capabilities.
  *
@@ -24,6 +24,23 @@ import type { WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, CloneToke
 export interface ProviderBundle {
     normalizer: WebhookNormalizer;
     lockFileFetcher?: LockFileFetcher;
+    /**
+     * Fetches arbitrary file contents at a ref (content-match triggers). Unlike
+     * the other fetchers, a GitHub instance is scoped to one installation, so the
+     * per-delivery installation id must be known to construct it -- it is wired
+     * where that id is in scope, not in the source-level bundle build. Providers
+     * that can prebuild one (no per-delivery credential) may set this directly;
+     * providers scoped per installation supply {@link fileContentsFetcherFactory}
+     * instead.
+     */
+    fileContentsFetcher?: FileContentsFetcher;
+    /**
+     * Builds a per-delivery {@link FileContentsFetcher} from the event
+     * credentials (e.g. a GitHub installation id). Returns undefined when the
+     * credentials do not carry what the provider needs. The webhook pipeline
+     * calls this once per delivery, where the credentials are already resolved.
+     */
+    fileContentsFetcherFactory?: (credentials: Record<string, unknown>) => FileContentsFetcher | undefined;
     changedFilesFetcher?: ChangedFilesFetcher;
     cloneTokenProvider?: CloneTokenProvider;
     repoUrlBuilder?: RepoUrlBuilder;
@@ -79,12 +96,30 @@ export declare class ProviderRegistry {
      * prefix. For multi-app, use getByRoutingKey() instead.
      */
     get(type: ProviderType): ProviderBundle | undefined;
+    /**
+     * Whether a bundle is registered at EXACTLY this routing key.
+     *
+     * `getByRoutingKey` cannot answer this: it falls back to a provider-type
+     * lookup, so it returns a bundle for a key it has never seen. A caller that
+     * needs to know whether the source's OWN bundle is present — rather than
+     * whether some bundle can be produced — has to ask here.
+     */
+    hasExact(routingKey: string): boolean;
     /**
      * Get the provider bundle by routing key.
      * Routing keys have the format "{provider}:{id}" (e.g., "github:12345").
      *
-     * Falls back to get(providerType) if exact key is not found,
-     * for backward compatibility with single-app registration.
+     * Falls back to get(providerType) if the exact key is not found, for
+     * backward compatibility with single-app registration.
+     *
+     * The fallback is deliberately narrower for a `generic:` key. Such a key is
+     * fully qualified (`generic:{orgId}:{sourceId}`), so the type-prefix scan in
+     * `get()` cannot be a "the single configured app" shortcut the way it is for
+     * `github:` — it returns whichever `generic:`-prefixed bundle happens to sit
+     * first in insertion order, which may belong to a different source, or to a
+     * different ORGANIZATION. Only the shared default bundle (`generic:default`,
+     * the one that genuinely stands in for every plain generic source) is an
+     * acceptable stand-in, so that is the only fallback offered here.
      */
     getByRoutingKey(routingKey: string): ProviderBundle | undefined;
     /**

package/dist/providers/github/check-status-poster.d.ts

@@ -5,11 +5,13 @@
  * - Security holds (pending): "KiCI Security" — "Held for approval"
  * - Workflow modifications (neutral): "KiCI: Workflow changes"
  * - Org globals skipped by the trust policy (neutral): "KiCI: Organization workflows"
+ * - Org global evaluation failed (failure): "KiCI: Organization workflow evaluation"
  * - Approved runs (success) / Rejected/expired runs (failure)
  *
- * `postWorkflowModificationCheck` and `postGlobalWorkflowsSkippedCheck` are
- * interface-backed (the `CheckStatusPoster` contract in `@kici-dev/engine`) and
- * post on their own check names so neither overwrites the security-hold check.
+ * `postWorkflowModificationCheck`, `postGlobalWorkflowsSkippedCheck`, and
+ * `postGlobalEvalFailedCheck` are interface-backed (the `CheckStatusPoster`
+ * contract in `@kici-dev/engine`) and post on their own check names so none of
+ * them overwrites the security-hold check.
  *
  * Reuses the Octokit infrastructure from auth.ts via createInstallationOctokit.
  * Uses a fixed check name per category so that subsequent updates (approve/reject)
@@ -47,5 +49,22 @@ export declare class GitHubCheckStatusPoster implements CheckStatusPoster {
      * while the run is still held. Always posted as neutral/completed.
      */
     postGlobalWorkflowsSkippedCheck(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
+    /**
+     * Post the check recording that the pre-run evaluation of the organization's
+     * global workflows failed, so none of the workflows it was deciding on ran.
+     *
+     * Its own check name ("KiCI: Organization workflow evaluation") for the same
+     * reason as the notice above: the security-hold check is a single named run
+     * per commit which a hold posts as pending and approve / reject later
+     * complete, so writing this through `postCheckStatus` would resolve a
+     * still-held run's check and unblock a branch protection rule that requires
+     * it.
+     *
+     * Posted as a failure, not a neutral: work the organization asked for did not
+     * run, and the reader has to be able to tell that from a clean commit. The
+     * name is new, so no existing branch protection rule requires it — a rule
+     * only requires check names it was configured with.
+     */
+    postGlobalEvalFailedCheck(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
 }
 //# sourceMappingURL=check-status-poster.d.ts.map

package/dist/providers/github/commit-message.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Where the commit message lives in a GitHub webhook payload, and the two
+ * different readings of it.
+ *
+ * They differ deliberately. `githubFilterText` feeds the Tier-0 `commitMessage`
+ * trigger filter, so it must be the WHOLE message — truncating to the subject
+ * line would make a `[skip ci]` marker written in the body invisible to a filter
+ * that names it. `githubDisplayMessage` feeds run-display metadata, where a
+ * one-line summary is the point.
+ */
+/** Full text a `commitMessage` trigger filter is tested against; undefined when the payload carries none. */
+export declare function githubFilterText(event: string, payload: unknown): string | undefined;
+/**
+ * One-line message for run display: the subject (first line) of a push's
+ * head-commit message, the PR title, or the issue title. This is the reading
+ * run-display metadata uses, distinct from the full text `githubFilterText`
+ * feeds the Tier-0 filter.
+ */
+export declare function githubDisplayMessage(event: string, payload: unknown): string | undefined;
+//# sourceMappingURL=commit-message.d.ts.map

package/dist/providers/github/file-contents.d.ts

@@ -0,0 +1,40 @@
+/**
+ * GitHub file contents fetcher.
+ *
+ * Implements the FileContentsFetcher interface from @kici-dev/engine for GitHub.
+ * Fetches an arbitrary file's contents from a GitHub repository at a specific
+ * ref via the Contents API, so the orchestrator can evaluate content-match
+ * triggers without cloning the repo.
+ */
+import type { FileContentsFetcher } from '@kici-dev/engine';
+import { type GitHubAppConfig } from './auth.js';
+/**
+ * GitHub-specific implementation of FileContentsFetcher.
+ *
+ * The installation id is baked in at construction because the
+ * FileContentsFetcher interface is credential-less at call time -- a fetcher
+ * instance is scoped to one GitHub App installation.
+ */
+export declare class GitHubFileContentsFetcher implements FileContentsFetcher {
+    private readonly config;
+    private readonly installationId;
+    readonly provider: 'github';
+    constructor(config: GitHubAppConfig, installationId: number);
+    /**
+     * Fetch a file's contents from a GitHub repository at a specific ref.
+     *
+     * @param owner - Repository owner (e.g. "my-org")
+     * @param repo - Repository name (e.g. "my-app")
+     * @param path - Repo-relative file path (e.g. ".kici/workflows/ci.ts")
+     * @param ref - Git ref (branch, tag, or SHA)
+     * @returns `{ present: false }` on 404 / directory; `{ present: true, bytes }`
+     *          when inline content is returned; `{ present: true }` (no bytes)
+     *          when the file exists but GitHub omits inline content (files over
+     *          1 MiB).
+     */
+    getFileContents(owner: string, repo: string, path: string, ref: string): Promise<{
+        present: boolean;
+        bytes?: string;
+    }>;
+}
+//# sourceMappingURL=file-contents.d.ts.map

package/dist/providers/github/index.d.ts

@@ -4,6 +4,7 @@
  * Each class implements a corresponding interface from @kici-dev/engine:
  * - GitHubWebhookNormalizer -> WebhookNormalizer
  * - GitHubLockFileFetcher -> LockFileFetcher
+ * - GitHubFileContentsFetcher -> FileContentsFetcher
  * - GitHubChangedFilesFetcher -> ChangedFilesFetcher
  * - GitHubCloneTokenProvider -> CloneTokenProvider
  * - GitHubRepoUrlBuilder -> RepoUrlBuilder
@@ -11,6 +12,7 @@
  */
 export { GitHubWebhookNormalizer } from './normalizer.js';
 export { GitHubLockFileFetcher } from './lock-file.js';
+export { GitHubFileContentsFetcher } from './file-contents.js';
 export { GitHubChangedFilesFetcher } from './changed-files.js';
 export { GitHubCloneTokenProvider, createInstallationOctokit } from './auth.js';
 export type { GitHubAppConfig, GitHubCredentials } from './auth.js';

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/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

@@ -239,18 +239,59 @@ export declare class JobQueue {
      * @returns The matching job, or null if none found.
      */
     dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[], agentId?: string): 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,6 +304,9 @@ 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;
     /**
@@ -276,6 +320,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 +343,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/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