@kici-dev/orchestrator 0.5.0 → 0.6.1

package/dist/pipeline/security-hold-check.d.ts

@@ -0,0 +1,217 @@
+import { type CheckStatus, type CheckStatusPoster } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/** Resolve the check poster of the provider bundle a routing key is served by. */
+export type ResolveCheckStatusPoster = (routingKey: string) => CheckStatusPoster | undefined;
+/**
+ * The `held_runs` columns this module reads. A full `HeldRun` row satisfies it,
+ * so every caller passes the row it already loaded rather than a projection.
+ */
+export interface SecurityCheckHold {
+    id: string;
+    org_id: string;
+    run_id: string;
+    job_id: string;
+    hold_scope: string;
+    hold_type: string;
+    approval_requirement: unknown;
+    /**
+     * Whether the pending post reached the provider. Required rather than
+     * optional so a query that projects columns by name cannot omit it and fall
+     * back to the shape derivation without the compiler saying so.
+     */
+    posted_pending_check: boolean | null;
+}
+/** How a hold ended, which decides the conclusion, title and summary. */
+export declare enum HoldOutcome {
+    /** Released to run — an approver satisfied it. */
+    Approved = "approved",
+    /** Refused by an approver. */
+    Rejected = "rejected",
+    /** Nobody answered inside the approval window. */
+    Expired = "expired"
+}
+/** Why {@link settleSecurityHoldCheck} did or did not write the check. */
+export declare enum SecurityCheckSettlement {
+    /** A terminal status was written. */
+    Posted = "posted",
+    /** This hold posted no pending check, so it has none to terminalize. */
+    NotOwned = "not-owned",
+    /** The caller already wrote this commit's check earlier in the same pass. */
+    AlreadySettled = "already-settled",
+    /** Another pending hold on the same commit still owns the check. */
+    Contended = "contended",
+    /** The hold's run row is gone, so the commit cannot be named. */
+    NoCommit = "no-commit",
+    /** No provider bundle serves the run's routing key any more. */
+    NoPoster = "no-poster",
+    /**
+     * The settlement could not complete — the provider refused the write, or the
+     * hold row did not carry the columns the ownership predicate reads.
+     */
+    Failed = "failed"
+}
+export interface SettleSecurityCheckResult {
+    outcome: SecurityCheckSettlement;
+    /** Whether a terminal status actually reached the provider. */
+    posted: boolean;
+    /** `owner/repo@sha`, once the hold's commit resolved. */
+    commit?: string;
+}
+/**
+ * Whether this hold put a pending `KiCI Security` check on its commit, and so
+ * has one to terminalize when it ends.
+ *
+ * `posted_pending_check` is the answer whenever the row carries one: it is
+ * written `true` only after the provider accepted the post, so it records what
+ * HAPPENED. Everything below records what the code INTENDED, which is a
+ * different question and answers the wrong way twice — a post the provider
+ * refused, and a hold reached with no check poster in `ctx.bundle`, both leave
+ * a shape that says "posted" and a commit that has nothing. Terminalizing then
+ * CREATES the check run, so the mirror of the stuck-check leak is a fabricated
+ * failing check on a pull request.
+ *
+ * The shape derivation stays for `null` — a row written before the column
+ * existed, for which no fact was recorded and an inference is all there is.
+ *
+ * Three sites post that pending status, and the derivation is read off them
+ * rather than off the queue type — which cannot make the distinction, because a
+ * workflow install gate whose context protection rule is security-typed carries
+ * `queue_type = 'security'` and posts nothing at all.
+ *
+ * | Hold | Written by | Posts pending? | Recognised here by |
+ * |---|---|---|---|
+ * | org trust policy's PR-wide hold | `holdRunForSecurityPolicy` | yes | `job_id` is a `SECURITY_HOLD_JOB_IDS` sentinel |
+ * | workflow install gate | `holdWorkflowForInstallGate` | no | `job_id` is `installGateJobId(name)` |
+ * | SDK workflow `requireApproval` | `holdJobForApproval` | yes | carries an `approval_requirement` |
+ * | context reviewer hold | `holdJobForApproval` | yes | carries an `approval_requirement` |
+ * | SDK job `requireApproval` | `holdJobForApproval` | yes | carries an `approval_requirement` |
+ * | context security hold | the per-env gate | yes | job scope + `hold_type = security` |
+ * | wait-timer / concurrency hold | the per-env gate | no | none of the above matches |
+ * | step approval | `StepApprovalBridge.request` | no | step scope |
+ *
+ * `approval_requirement` is what `createHold` writes and `create` does not, so
+ * it identifies exactly the rows `holdJobForApproval` wrote through the
+ * approval path — the site whose post is guarded by `if (hold && …)`. The two
+ * other `createHold` callers are excluded above it: the install gate by its job
+ * id, the step bridge by its scope.
+ */
+export declare function postedPendingSecurityCheck(hold: SecurityCheckHold): boolean;
+/**
+ * The terminal summary for a hold that ended, in the one vocabulary both check
+ * families use: `cancelled` for a rejection, `timed_out` for an elapsed window,
+ * `success` for an approval.
+ *
+ * The subject follows the hold's scope on every outcome, because the same event
+ * means different things at each: a workflow-scoped hold owns the whole run,
+ * while a job-scoped one owns one job and says nothing about the run's other
+ * jobs — including a step-approval hold that is still pending, which a run-wide
+ * "no longer waiting for approval" would contradict.
+ *
+ * `actor` names whoever ended the hold, on an approve and on a reject alike.
+ * Only an expiry has none: nobody answered, which is what expiry means. A
+ * rejecter whose surface already writes its own attribution into `reason` (the
+ * `/kici reject` handler builds "Rejected by alice via /kici reject") passes no
+ * `actor`, so the sentence lands once rather than twice.
+ *
+ * **`actor` is a display name, and it is published verbatim on a public commit
+ * check.** It must never be an opaque identity-provider subject id: a surface
+ * that holds one — the dashboard / CLI / MCP applier, which decides by KiCI
+ * user id — resolves it against the org's identity directory first and passes
+ * nothing when that resolves to no single name. Omitting the attribution reads
+ * as "an approver"; leaking the subject reads as `Approved by
+ * 8f3a-…-uuid`, on a pull request anyone can open.
+ *
+ * `reason` is normalized to end in terminal punctuation — a rejecter's own
+ * sentence carries none, and without one it runs straight into what follows.
+ */
+export declare function buildHoldEndedSummary(args: {
+    outcome: HoldOutcome;
+    scope: string;
+    reason?: string | undefined;
+    actor?: string | undefined;
+    via?: string | undefined;
+}): string;
+/**
+ * Terminalize the `KiCI Security` check of a hold that just ended, choosing the
+ * conclusion, title and summary from {@link HoldOutcome}.
+ *
+ * The single entry point for every surface that ends a hold — the `/kici`
+ * comment handler, the dashboard / CLI / MCP applier, and the stale detector's
+ * approval-window sweep — so those surfaces cannot render one event three ways.
+ */
+export declare function settleSecurityCheckForOutcome(args: {
+    db: Kysely<Database> | undefined;
+    resolvePoster: ResolveCheckStatusPoster | undefined;
+    hold: SecurityCheckHold;
+    outcome: HoldOutcome;
+    reason?: string | undefined;
+    actor?: string | undefined;
+    via?: string | undefined;
+    excludeHoldIds?: readonly string[] | undefined;
+    skipCommits?: ReadonlySet<string> | undefined;
+}): Promise<SettleSecurityCheckResult>;
+/**
+ * The dashboard / CLI / MCP applier's entry point into
+ * {@link settleSecurityCheckForOutcome}.
+ *
+ * That applier decides by KiCI user id, so the only actor it holds is an opaque
+ * identity-provider subject — and this summary is published verbatim on a public
+ * commit check. `resolveDisplayName` maps the subject onto the account name the
+ * org's identity directory links it to; when it names none, the attribution is
+ * DROPPED rather than falling back to the subject. So an approve reads
+ * "Approved by an approver" at worst, never "Approved by 8f3a-…-uuid".
+ *
+ * Separate from its caller so the resolve-or-drop step is a unit under test
+ * rather than a line in the composition root.
+ */
+export declare function settleSecurityCheckForDecision(args: {
+    db: Kysely<Database> | undefined;
+    resolvePoster: ResolveCheckStatusPoster | undefined;
+    /** Subject id → the linked account name, or undefined for no single name. */
+    resolveDisplayName: (actorSub: string) => string | undefined;
+    hold: SecurityCheckHold;
+    outcome: HoldOutcome;
+    /** Omitted where the summary must match one another writer built without it. */
+    actorSub?: string | undefined;
+    reason?: string | undefined;
+}): Promise<SettleSecurityCheckResult>;
+/**
+ * Terminalize the `KiCI Security` check of a hold that just ended, under a
+ * caller-supplied status and copy.
+ *
+ * Used directly where one summary has to reach BOTH check families — a rejected
+ * workflow-scoped hold reports the same sentence on `KiCI Security` and on the
+ * `kici/…` runs of the same event, and that sameness is asserted rather than
+ * assumed. Everything else goes through {@link settleSecurityCheckForOutcome}.
+ *
+ * Call it AFTER the hold's own row has left `pending` (every caller does: the
+ * applier flips inside `recordAndReject` / `recordAndRelease`, the comment
+ * handler inside `reject` / `approveByQueueType`) — and, on an approve, BEFORE
+ * the resume, so a replayed dispatch that holds again overwrites this terminal
+ * status with its own pending one rather than the other way round. The ending
+ * hold's own id is excluded from the contention query regardless, so a sweep
+ * that has not yet flipped its batch can name it in `excludeHoldIds`.
+ *
+ * Never throws: terminalizing a check run is a reporting courtesy on a path
+ * whose real job is to terminalize the hold, and a provider error must not stop
+ * that. The returned `posted` is what a caller binds its own suppression to —
+ * it says a check was written, not merely that a delegate resolved.
+ */
+export declare function settleSecurityHoldCheck(args: {
+    db: Kysely<Database> | undefined;
+    resolvePoster: ResolveCheckStatusPoster | undefined;
+    hold: SecurityCheckHold;
+    status: CheckStatus;
+    title: string;
+    summary: string;
+    excludeHoldIds?: readonly string[] | undefined;
+    /**
+     * Commits this caller already wrote in the same pass. A sweep that ends
+     * several holds on one commit shares one check run between them, and every
+     * hold in it carries the same conclusion and summary — so the second write
+     * would be a byte-identical provider round-trip.
+     */
+    skipCommits?: ReadonlySet<string> | undefined;
+}): Promise<SettleSecurityCheckResult>;
+//# sourceMappingURL=security-hold-check.d.ts.map

package/dist/pipeline/undispatched-hold-checks.d.ts

@@ -0,0 +1,23 @@
+import { type CheckRunConclusion } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
+/**
+ * Complete the check runs of `runId`'s stored workflow dispatch, if it has one.
+ *
+ * A run with no pending workflow context never held at workflow scope (or its
+ * context was already consumed by a resume), so there is nothing to close and
+ * this is a no-op. Call it BEFORE `deletePendingWorkflowContext` — the context
+ * is the only place the check-run names can still be derived from.
+ *
+ * Never throws: closing a check run is a reporting courtesy on a path whose real
+ * job is to terminalize the run, and a provider error must not stop that.
+ */
+export declare function completeUndispatchedHoldChecks(args: {
+    db: Kysely<Database> | undefined;
+    checkRunReporter: CheckRunReporter | undefined;
+    runId: string;
+    conclusion: CheckRunConclusion;
+    summary: string;
+}): Promise<void>;
+//# sourceMappingURL=undispatched-hold-checks.d.ts.map

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

@@ -0,0 +1,62 @@
+/**
+ * Cross-coordinator propagation of dashboard-write policy changes.
+ *
+ * Sister to `GenericSourcesChangeListener`
+ * (`packages/orchestrator/src/webhook/generic-sources-listener.ts`), which
+ * owns the `generic_sources_change` channel. This listener owns
+ * `dashboard_write_policy_change` — the channel `setDashboardWritePolicy`
+ * emits from inside its own write transaction.
+ *
+ * The problem it solves: `dashboardWritePolicyEvents` is a per-process
+ * `EventEmitter`, so only the coordinator that served the `kici-admin`
+ * write learned about a flip. Its siblings kept serving a stale cached map
+ * from their own policy gate for up to the cache TTL, and — worse — kept
+ * advertising the stale map to the control plane indefinitely, because
+ * capabilities are pushed on change and on reconnect, never polled. The
+ * control plane caches capabilities per orchestrator connection and resolves
+ * a cluster name to whichever of its connections it finds first, so a policy
+ * flip could be invisible to the dashboard for as long as the cluster stayed
+ * up.
+ *
+ * On NOTIFY:
+ *   1. Queue the affected `customer_id` (the channel payload).
+ *   2. Debounce 200 ms so rapid flips coalesce into one drain pass.
+ *   3. For each queued customer: drop the cached map, re-read the
+ *      authoritative one from the database, and emit `'changed'` on
+ *      `dashboardWritePolicyEvents`. The platform-mode boot already
+ *      subscribes to that event and re-broadcasts `orch.capabilities`.
+ *
+ * The payload is the customer id alone: every coordinator shares one
+ * orchestrator database, so re-reading is both cheap and authoritative,
+ * and no wire copy of the map can go stale in flight.
+ *
+ * The writing coordinator receives its own NOTIFY too. That is deliberate
+ * and harmless — it already emitted the event in-process, and the second
+ * emit produces an identical capability broadcast.
+ */
+import type pg from 'pg';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+export interface DashboardWritePolicyChangeListenerOptions {
+    /** Raw pg pool — a dedicated PoolClient is checked out for LISTEN. */
+    pool: pg.Pool;
+    /** Used to re-read the authoritative policy map on each NOTIFY. */
+    db: Kysely<Database>;
+    /** Coalesce window for rapid NOTIFYs against the same customer. Default 200 ms. */
+    debounceMs?: number;
+}
+export declare class DashboardWritePolicyChangeListener {
+    private readonly opts;
+    private client;
+    private readonly pending;
+    private debounceTimer;
+    private readonly debounceMs;
+    constructor(opts: DashboardWritePolicyChangeListenerOptions);
+    /** Open the dedicated client and subscribe. */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private scheduleDrain;
+    /** Visible for tests — drain the queued customer ids synchronously. */
+    drain(): Promise<void>;
+}
+//# sourceMappingURL=dashboard-write-policy-listener.d.ts.map

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

@@ -23,10 +23,24 @@ import { type Kysely } from 'kysely';
 import { DashboardWriteOperation, type DashboardWritePolicyMap, type DashboardWritePolicyState } from '@kici-dev/engine/protocol/dashboard-write-operations';
 import type { Database } from '../db/types.js';
 import type { ActorPrincipal } from '@kici-dev/engine';
+/**
+ * Postgres `LISTEN/NOTIFY` channel carrying policy changes across the
+ * cluster. The payload is the `customer_id` alone — every coordinator
+ * shares one orchestrator database, so each listener re-reads the
+ * authoritative map for itself rather than trusting a wire copy.
+ *
+ * `DashboardWritePolicyChangeListener` (`./dashboard-write-policy-listener.ts`)
+ * is the consumer.
+ */
+export declare const DASHBOARD_WRITE_POLICY_CHANNEL = "dashboard_write_policy_change";
 /**
  * Event bus for policy-change notifications. The WS publisher subscribes
  * to `'changed'` so it can broadcast a fresh `orch.capabilities` to
  * Platform whenever the operator flips a switch.
+ *
+ * The emitter is per-process, so it carries a change only to the peer that
+ * served the admin write. The NOTIFY channel above is what reaches the other
+ * coordinators, whose listeners then emit this same event locally.
  */
 export declare const dashboardWritePolicyEvents: EventEmitter<[never]>;
 /**

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, FileContentsFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster, ProviderType } from '@kici-dev/engine';
+import type { WebhookNormalizer, LockFileFetcher, FileContentsFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, CheckStatusPoster, ProviderType } from '@kici-dev/engine';
 /**
  * Complete set of provider capabilities.
  *
@@ -44,7 +44,15 @@ export interface ProviderBundle {
     changedFilesFetcher?: ChangedFilesFetcher;
     cloneTokenProvider?: CloneTokenProvider;
     repoUrlBuilder?: RepoUrlBuilder;
-    contributorResolver?: ContributorResolver;
+    /**
+     * This provider has a fork model: a head ref can live outside the base repo,
+     * so the fork trust policy applies to its pull-request events. True for
+     * GitHub. Absent for providers whose trust boundary is something else — a
+     * generic source's verification secret, a local source's on-disk ownership —
+     * and for universal-git, which reports an `isForkPR` signal that must not
+     * gate it.
+     */
+    hasForkModel?: boolean;
     checkStatusPoster?: CheckStatusPoster;
     /**
      * Local `file://` in-place profile: this bundle's `repoBasePath` is the

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

@@ -66,5 +66,16 @@ export declare class GitHubCheckStatusPoster implements CheckStatusPoster {
      * only requires check names it was configured with.
      */
     postGlobalEvalFailedCheck(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
+    /**
+     * Post the success conclusion on the organization-workflow-evaluation check
+     * after a re-run of a failed round completed cleanly.
+     *
+     * Deliberately the SAME check name the failure posts: GitHub keys a check run
+     * by its name on a commit, so writing the success under that name is what
+     * turns the red check green on the original commit. A second, differently
+     * named green check would leave the red one standing and keep a branch
+     * protection rule blocked with no way to clear it short of a new commit.
+     */
+    postGlobalEvalSucceededCheck(repoIdentifier: string, commitSha: string, summary: string, credentials: unknown): Promise<void>;
 }
 //# sourceMappingURL=check-status-poster.d.ts.map

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

@@ -8,7 +8,6 @@
  * - GitHubChangedFilesFetcher -> ChangedFilesFetcher
  * - GitHubCloneTokenProvider -> CloneTokenProvider
  * - GitHubRepoUrlBuilder -> RepoUrlBuilder
- * - GitHubContributorResolver -> ContributorResolver
  */
 export { GitHubWebhookNormalizer } from './normalizer.js';
 export { GitHubLockFileFetcher } from './lock-file.js';
@@ -17,6 +16,5 @@ export { GitHubChangedFilesFetcher } from './changed-files.js';
 export { GitHubCloneTokenProvider, createInstallationOctokit } from './auth.js';
 export type { GitHubAppConfig, GitHubCredentials } from './auth.js';
 export { GitHubRepoUrlBuilder } from './repo-url.js';
-export { GitHubContributorResolver } from './contributor-resolver.js';
 export { GitHubCheckStatusPoster } from './check-status-poster.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -74,8 +74,9 @@ export declare class GitHubWebhookNormalizer implements WebhookNormalizer {
      */
     extractCredentials(payload: unknown): Record<string, unknown>;
     /**
-     * Map GitHub membership-related webhook events to ContributorCache
-     * invalidations. See WebhookNormalizer.getAccessCacheInvalidations.
+     * Map GitHub membership-related webhook events to permission-cache
+     * invalidations. See WebhookNormalizer.getAccessCacheInvalidations, which is
+     * deprecated and has no caller.
      *
      * Covered event types:
      *

package/dist/providers/local/normalizer.d.ts

@@ -70,8 +70,9 @@ export declare class LocalWebhookNormalizer implements WebhookNormalizer {
      */
     normalizeEvent(eventType: string, _action: string | null, payload: unknown): SimulatedEvent | null;
     /**
-     * Map membership-related local-source webhook events to ContributorCache
-     * invalidations.
+     * Map membership-related local-source webhook events to permission-cache
+     * invalidations. See WebhookNormalizer.getAccessCacheInvalidations, which is
+     * deprecated and has no caller.
      *
      * Local-source payloads are GitHub-shaped by design, so the mapping
      * mirrors the GitHub normalizer exactly:
@@ -80,9 +81,6 @@ export declare class LocalWebhookNormalizer implements WebhookNormalizer {
      * - `organization`: user-in-org
      * - `membership`: user-in-org
      * - `team` (repo-scoped actions only): repo
-     *
-     * This lets membership-invalidation paths be exercised through
-     * `sendLocalWebhook()` without requiring a real GitHub App.
      */
     getAccessCacheInvalidations(eventType: string, _action: string | null, payload: unknown): AccessCacheInvalidation[];
 }

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/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,9 +253,16 @@ 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
@@ -309,6 +333,24 @@ export declare class JobQueue {
      * 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 —

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