@kici-dev/orchestrator 0.4.0 → 0.6.0

package/dist/pipeline/dispatch-matched-workflow.d.ts

@@ -13,15 +13,17 @@
  * exported function is a narrative orchestrator that threads the typed
  * results through the pipeline.
  */
-import { ExecutionJobStatus, InitFailureCategory, CacheRefScope } from '@kici-dev/engine';
-import type { LabelMatcher, LockWorkflow, LockJob, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, HostFacts } from '@kici-dev/engine';
+import { ExecutionJobStatus, InitFailureCategory, CacheRefScope, HoldScope, TriggerSource } from '@kici-dev/engine';
+import type { LabelMatcher, LockWorkflow, LockJob, ApprovalRequirement, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, HostFacts } from '@kici-dev/engine';
 import { type HostRosterStore } from '../agent/host-roster.js';
+import { gatherInvokeResults } from '../orchestrator-core.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
 import type { QueuedJobInput } from '../queue/job-queue.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import type { TrustPolicyOutcome } from '../security/trust-policy-gate.js';
+import type { CreateHeldRunData } from '../contexts/held-runs.js';
 import { type ProcessingDeps } from './processor.js';
 /**
  * Trusted refs (write+ contributor, default-branch) get the org-shared cache
@@ -55,6 +57,24 @@ export interface WorkflowDispatchContext {
     bundle?: ProviderBundle;
     payload: unknown;
     repoIdentifier: string;
+    /**
+     * The repository that DEFINES the workflow being dispatched. `repoIdentifier`
+     * is the repository the run acts on; for an organization-wide workflow the
+     * two are different repositories, and every run row this dispatch writes has
+     * to say which one defined it.
+     *
+     * REQUIRED, for the same reason `securityDecision` is: a dispatch path that
+     * does not state it must not compile. Left optional, a new caller omits it
+     * silently and every row it records claims the workflow lives in the
+     * repository the run acted on — a null marker is read as that fact, not as
+     * "unknown" (`registration/registration-run-match.ts`).
+     *
+     * Every caller today states `repoIdentifier` or a value equal to it, because
+     * no cross-repository global dispatch enters this function — the global path
+     * builds its job inputs directly and dispatches them itself. The recording
+     * sites narrow, so stating the acted-on repository records nothing.
+     */
+    workflowRepoIdentifier: string;
     credentials: Record<string, unknown>;
     event: SimulatedEvent;
     eventWithFiles: SimulatedEvent;
@@ -67,6 +87,21 @@ export interface WorkflowDispatchContext {
         };
     };
     resolvedOrgId: string;
+    /**
+     * Siblings admitted against a context concurrency limit during THIS dispatch
+     * pass, keyed by {@link concurrencyAdmissionKey}.
+     *
+     * The gate's running count counts jobs whose status is already `running`, so
+     * it cannot see anything this pass has only just admitted. Without this tally
+     * every child of a fan-out is evaluated against that one blind value and all
+     * N are admitted against a single slot.
+     *
+     * Created lazily on first use and dropped with the ctx. It is per-pass state,
+     * never persisted and never shared between passes; two concurrent passes
+     * still race, which is accepted — this is a throughput control, not an
+     * isolation boundary.
+     */
+    concurrencyAdmissions?: Map<string, number>;
     workflow: LockWorkflow;
     decision: WorkflowDecision;
     runId: string;
@@ -74,8 +109,93 @@ export interface WorkflowDispatchContext {
     lockFileSource: string | undefined;
     /** True when this run executes an uploaded local working tree (CLI remote run). */
     localWorkingTree: boolean;
+    /**
+     * Identity that initiated this run, for `execution_runs.triggered_by`.
+     *
+     * Set by the CLI remote-run path, which knows its caller: the Platform relays
+     * the developer's actor on `test.relay.trigger` and the test pipeline renders
+     * it here. Undefined on the webhook path, where the initiator is a provider
+     * account rather than a KiCI principal — that attribution is carried by
+     * `triggerActorUsername` / `triggerActorUserId` instead.
+     */
+    triggeredBy?: string | null;
+    /** Agent provenance label when the run was initiated through an agent credential. */
+    triggeredByAgentLabel?: string | null;
     /** True only when invoked from the cross-source dispatch shell. */
     crossSource: boolean;
+    /**
+     * Trigger-event string for the run's `triggerEvent`, stated explicitly rather
+     * than derived from `event.type`.
+     *
+     * The internal-event adapter needs this because a user `kiciEvent()` renders
+     * two different values: `jobConfig.event.type` is the literal `kici_event`,
+     * while the run carries the raw event name. `event.type` carries the former,
+     * so the latter has to be stated.
+     *
+     * Absent ⇒ the value derived from the event, unchanged for the webhook,
+     * CLI-remote-run and resume callers.
+     */
+    triggerEventOverride?: string;
+    /**
+     * The exact `jobConfig.event` envelope to ship, stated explicitly instead of
+     * spreading the `SimulatedEvent` this dispatch matched against.
+     *
+     * Same reason as `triggerEventOverride`: the matcher's event shape and the
+     * shape user code observes are not the same object. `SimulatedEvent` requires
+     * `targetBranch` and carries `changedFiles`; the envelope omits both. An
+     * internally triggered run genuinely has no changed files, and its branch is
+     * provenance the orchestrator evaluates (the trigger matcher and the context
+     * branch gate) rather than a field user code asked for — the envelope becomes
+     * `RuleContext.event` on the agent and the `event` half of
+     * `buildConcurrencyGroupContext`, so publishing the branch would silently
+     * re-key the documented `ctx.event.targetBranch ?? 'default'` concurrency
+     * group of every existing internal workflow.
+     *
+     * Absent ⇒ the envelope derived from the event, unchanged for the webhook,
+     * CLI-remote-run and resume callers.
+     */
+    eventEnvelopeOverride?: Record<string, unknown>;
+    /**
+     * Chain depth to stamp on the started run. A run summoned by an invoke gate
+     * carries its summoner's depth + 1, which is what bounds the chain-depth
+     * circuit breaker. Absent ⇒ 0, the column default (a webhook-triggered run
+     * starts a chain).
+     *
+     * Threading this is load-bearing: the breaker fails OPEN if the value is
+     * lost, so an unbounded summon recursion would go undetected. It is stamped
+     * as soon as the run row exists, because `releaseInvokeGate` reads the column
+     * back at gate-release time — which happens inside this same dispatch.
+     */
+    chainDepth?: number;
+    /**
+     * Marks a run dispatched by a failure-lifecycle trigger, so its own
+     * completion is excluded from batch accumulation and a broken notifier
+     * cannot re-trigger itself (`EventRouter.isFailureLifecycleRun`).
+     *
+     * Persisted as a field INSIDE the `trigger_decision` JSON blob, merged onto
+     * the decision summary rather than replacing it.
+     */
+    dispatchedByFailureLifecycle?: boolean;
+    /**
+     * Marks a run the orchestrator triggered itself — a schedule fire, a
+     * workflow/job completion, a failure batch, a user `kiciEvent()`, or an
+     * invoke-gate summon — as opposed to one a provider webhook triggered.
+     *
+     * Read by the context branch gate, and by nothing else. Such a run usually
+     * carries a real branch in `event.targetBranch` — a schedule fire presents
+     * its registration's default branch, every other internal trigger inherits
+     * the branch of the run that emitted its event — and the gate matches it like
+     * any other run's. The flag singles out the runs whose `targetBranch` is
+     * EMPTY: a failure batch or a scaler event (many runs behind it, or none), a
+     * registration whose default branch has never been captured, an emitting run
+     * that is gone. The gate rejects those naming that cause, instead of quoting
+     * an empty value as though it were a branch name. It does NOT weaken the
+     * gate — a run with no branch cannot satisfy a restriction, `*` included.
+     *
+     * Absent ⇒ webhook-triggered, unchanged for the webhook, CLI-remote-run and
+     * resume callers.
+     */
+    internallyTriggered?: boolean;
     /**
      * Outcome of the org trust-policy gate for this PR event. `pass` dispatches
      * normally; `hold` parks the run in the security queue; `reject` fails it
@@ -91,13 +211,35 @@ export interface WorkflowDispatchContext {
      */
     securityDecision: TrustPolicyOutcome;
     /**
-     * Set when this dispatch call took a pending-jobs token for the source-pack
-     * build window. Tokens are fungible, so the `finally` must release only one
-     * it actually took — an unpaired release would consume a token held by a
-     * deferred init / dynamic task and un-hold the run while its jobs are still
-     * being registered.
+     * Set when this dispatch call took a pending-jobs token covering the window
+     * between registering the run and registering its jobs — the source-pack
+     * build window, or the plain dispatch window when there is no build. Tokens
+     * are fungible, so the `finally` must release only one it actually took — an
+     * unpaired release would consume a token held by a deferred init / dynamic
+     * task and un-hold the run while its jobs are still being registered.
+     */
+    dispatchWindowTokenHeld?: boolean;
+    /**
+     * Set when this dispatch call inserted the `execution_runs` row before
+     * handing the first job to an agent. A row that exists with zero jobs can
+     * never complete (`isRunComplete` ends `run.jobs.size > 0`) and no sweeper
+     * reaps it, so a throw inside that window has to terminalize the run
+     * explicitly rather than leave it `pending` forever.
      */
-    buildWindowTokenHeld?: boolean;
+    runRegisteredBeforeDispatch?: boolean;
+    /**
+     * Set once `setupDispatchContext` has posted this dispatch's queued
+     * `kici/<workflow>` check and one `kici/<workflow>/job/<name>` per static job.
+     *
+     * Those checks go up BEFORE anything decides whether the run will start, so
+     * every exit after setup owes them a conclusion. The named early exits each
+     * complete their own; a THROW does not, and nothing else can — the workflow
+     * check keys off a run whose jobs never registered, and the stale sweep only
+     * touches check runs already `in_progress`. Left alone they stay `queued`
+     * forever, which on a pull request is a check that never finishes and a
+     * branch-protection blocker.
+     */
+    pendingChecksPosted?: boolean;
     /** Composite dedup key `${info.deliveryId}:${reg.id}` (cross-source only). */
     crossSourceDeliveryId?: string;
     /**
@@ -154,6 +296,14 @@ export interface WorkflowDispatchContext {
      */
     dispatchInputs?: Record<string, unknown>;
 }
+/**
+ * The minimal slice of a dispatch context the needs catch-up + ready-recompute
+ * helpers read. Both the per-repository `WorkflowDispatchContext` and the
+ * global-workflow dispatch path (which builds its own inputs and never
+ * constructs a full `WorkflowDispatchContext`) can drive the needs scheduler
+ * through this narrow shape.
+ */
+export type NeedsSchedulingContext = Pick<WorkflowDispatchContext, 'deps' | 'runId'>;
 /**
  * Build the dispatch-envelope event, carrying the orchestrator's already-fetched
  * changed-files list + status from `eventWithFiles` as a fast-path (the agent
@@ -166,6 +316,14 @@ export interface DispatchMatchedWorkflowResult {
     dispatchedJobCount: number;
     /** Execution job ids of every dispatched/tracked job (root, gated, synthetic). */
     dispatchedJobIds: string[];
+    /**
+     * Jobs whose dispatch is deferred to the agent init round (a dynamic context
+     * or a deferred-init job) and therefore not yet in `dispatchedJobIds`. These
+     * still run — they are dispatched asynchronously by `startDeferredPhases` —
+     * so a caller must not treat a run with pending deferred work as "nothing
+     * dispatched". Absent/0 on the early-return paths.
+     */
+    deferredJobCount?: number;
     /** True when the workflow install gate paused the dispatch (held run). */
     held?: boolean;
     /**
@@ -182,8 +340,6 @@ export interface DispatchMatchedWorkflowOptions {
      * so secrets resolve directly and the dispatch flows into job dispatch.
      */
     skipInstallProtectionGate?: boolean;
-    /** The released held-run id being resumed (for logging / correlation). */
-    reuseHeldRunId?: string;
     /**
      * The run id whose `held` execution_runs row should be reused (flipped to
      * pending) instead of inserting a fresh row.
@@ -214,6 +370,120 @@ interface DispatchSetup {
      */
     checkMode: string | undefined;
 }
+interface BuildPrepResult {
+    sourceTarUrl: string | undefined;
+    sourceTarHash: string | undefined;
+    depsUrl: string | undefined;
+    depsHash: string | undefined;
+    contentHash: string | undefined;
+    lockfileHash: string | undefined;
+    hasDynamicEntries: boolean;
+    dynamicEntries: ReadonlyArray<Extract<LockWorkflow['jobs'][number], {
+        _type: 'dynamic';
+    }>>;
+    staticJobs: readonly LockJob[];
+    /**
+     * Static jobs expanded into dispatchable children (matrix fan-out). Non-matrix
+     * jobs pass through 1:1. Every dispatch phase iterates this list, keying by
+     * `expandedName`. Dynamic-matrix jobs are flagged `pendingDynamicMatrix`.
+     */
+    materializedJobs: readonly MaterializedJob[];
+    /** baseName -> expanded child names; drives needs-edge expansion. */
+    expansionMap: ReadonlyMap<string, readonly string[]>;
+    /** Jobs whose matrix could not be materialized (cap / zero-combination). */
+    matrixFailures: readonly RejectedJob[];
+    targetPlatform: string;
+    targetArch: string;
+    buildJobId: string | undefined;
+    buildJobName: string | undefined;
+    buildJobLabels: string[] | undefined;
+    buildJobTrackedEarly: boolean;
+    /** True when the build failed but dynamic entries can still proceed. */
+    buildFailed: boolean;
+    /**
+     * True when the helper has fully short-circuited the dispatch (build failed
+     * and no dynamic entries to fall back on, or build job rejected). Caller
+     * MUST early-return with `dispatchedJobCount: 0`.
+     */
+    abort: boolean;
+}
+interface JobEnvData {
+    contextName?: string;
+    /** Configured env id matched for the first declared context name. */
+    contextId?: string;
+    /**
+     * Ordered bound-context names persisted on the job row (`(dynamic)`
+     * placeholder for elements unresolved at dispatch; overwritten with the
+     * agent-resolved list for dynamic contexts). Empty/undefined = no binding.
+     */
+    contextNames?: string[];
+    contextVars?: Record<string, string>;
+    jobEnv?: Record<string, string>;
+    jobSecrets?: Record<string, string>;
+    jobNamespacedSecrets?: Record<string, Record<string, string>>;
+    /**
+     * Registry credentials for this job's container image, resolved from the
+     * secret NAMES the lock carries. Lifted to a top-level dispatch field (and
+     * stripped from jobConfig) before the message reaches the agent.
+     */
+    containerRegistryAuth?: {
+        username: string;
+        password: string;
+        serveraddress: string;
+    };
+    held?: boolean;
+    /**
+     * Pending approval hold for this job, set when a context policy or
+     * explicit lock `approval` requires human sign-off. The dispatch loop turns
+     * this into a `held_runs` row + a stored pending job context so `release()`
+     * can re-dispatch after approval.
+     */
+    approvalHold?: PendingApprovalHold;
+    /**
+     * A non-reviewer hold (security / wait-timer / concurrency-queue) decided by a
+     * context's protection rules. Carried rather than written on the spot so
+     * `holdJobForApproval` can create the row and the job's resume path in ONE
+     * transaction — the reviewer branch uses `approvalHold` for the same purpose.
+     */
+    nonApprovalHold?: CreateHeldRunData;
+    rejected?: boolean;
+    rejectReason?: string;
+    pendingInit?: boolean;
+    /** Bound contexts skipped on a test/local run because they disallow local execution. */
+    skippedEnvs?: string[];
+    /**
+     * User-visible warning set whenever any bound context was unavailable for
+     * a test run (non-test or unconfigured) and skipped — surfaced on the CLI run
+     * output and the dashboard run view.
+     */
+    envWarning?: string;
+}
+/** A resolved approval requirement awaiting hold creation in the dispatch loop. */
+interface PendingApprovalHold {
+    scope: HoldScope;
+    triggerSource: TriggerSource;
+    requirement: ApprovalRequirement;
+    contextId: string | null;
+    queueType: 'context' | 'security';
+}
+interface DeferredInitJob {
+    mat: MaterializedJob;
+    initJobInput: QueuedJobInput;
+}
+interface JobEnvEvalResult {
+    jobContextData: Map<string, JobEnvData>;
+    deferredInitJobs: DeferredInitJob[];
+    runContextName: string | undefined;
+    runContextId: string | undefined;
+}
+/**
+ * Synthetic job-id prefix every needs-gate site stamps on a job it holds back.
+ * The release path (`dispatchReadyJob` → `findSyntheticJobId` → `addJobsToRun`)
+ * keys on it, so it is load-bearing rather than cosmetic — which is what makes
+ * it a sound way to recover the gated set without threading a parallel list
+ * through both the single-orchestrator and cluster dispatch paths.
+ */
+export declare const NEEDS_PENDING_JOB_ID_PREFIX = "needs-pending-";
 interface RejectedJob {
     jobId: string;
     jobName: string;
@@ -227,6 +497,32 @@ interface RejectedJob {
      */
     terminalStatus?: ExecutionJobStatus;
 }
+/**
+ * Whether this dispatch must run a `__build__` job before its real jobs.
+ *
+ * Either cache missing is a reason to build. The two are keyed on different
+ * things — the source cache on the workflow source's contentHash, the dep cache
+ * on the lockfile hash — so they miss independently, and a dependency bump is
+ * exactly the case that leaves the source warm and the deps cold. Gating only on
+ * the source miss made that state permanent: no build job ran, so nothing ever
+ * uploaded the dep tarball, so every agent fell back to installing from the
+ * registry on every job — and an agent with no route to that registry (a
+ * cloud-hosted one-shot agent, an air-gapped runner) could not run the job at
+ * all. The `__build__` job already carries `buildSourceNeeded` /
+ * `buildDepsNeeded` separately and the agent already honors both, so a
+ * deps-only build was implemented and simply unreachable.
+ *
+ * A hash is required alongside its miss: with no hash there is no cache key to
+ * write, so building would produce an artifact nothing could ever look up.
+ */
+export declare function buildIsNeeded(args: {
+    /** False when there is nothing to cache into (no bundle, no coordinator, …). */
+    cacheInfraAvailable: boolean;
+    sourceHit: boolean;
+    contentHash: string | undefined;
+    depHit: boolean;
+    lockfileHash: string | undefined;
+}): boolean;
 /**
  * Build the QueuedJobInput for a synthetic `__bringup__` job: the orchestrator
  * dispatches one per declared-but-un-agented `includeUninitialized` child to an
@@ -278,6 +574,28 @@ export declare function runsOnSelectorsForLockJob(lockJob: {
     runsOn?: readonly LabelMatcher[];
     excludeLabels?: readonly LabelMatcher[];
 }): JobRoutingSelectors;
+/**
+ * Runtime facts a job's own shape demands of the host that runs it.
+ *
+ * Only a `container.dockerfile` job gets one. Building shells out to a
+ * `docker` / `podman` CLI, so a host without one cannot run the job at all, and
+ * the agent self-reports `kici:runtime:container-build` when it has one.
+ *
+ * A job that names a finalized `image` deliberately gets NOTHING added. Adding
+ * an implicit requirement to jobs that already work is how container jobs were
+ * stranded once before: they had been running fine, and a routing gate the
+ * orchestrator could not actually evaluate made them match nothing. A dockerfile
+ * job is new, so requiring the fact strands no existing workflow — and an agent
+ * old enough not to report the fact is an agent that cannot build anyway.
+ *
+ * Applied when matching REGISTERED agents (the dispatcher), and deliberately
+ * NOT when consulting the scaler. A scaler backend is chosen by exact label-set
+ * containment, so a required label the operator never wrote in a pool's label
+ * set matches no backend at all — the job would be stranded `queued-no-backend`
+ * rather than spawned. The pool's hosts are the operator's to describe; what an
+ * agent can actually do is known only once it registers and says so.
+ */
+export declare function requiredRuntimeLabelsFor(container: unknown): string[];
 /**
  * Resolve a generated job's single bare-`agentId` `runsOn` into a host pin.
  *
@@ -345,6 +663,187 @@ export declare function findInvalidApprovalTimeout(workflow: LockWorkflow): {
  * no host facts to scope by.
  */
 export declare function hostCtxFromMat(mat: MaterializedJob): HostFacts | undefined;
+/**
+ * Key for the in-pass admission tally.
+ *
+ * The org id is part of the key so the tally inherits the cross-tenant scoping
+ * the running-count query already enforces on `execution_runs.customer_id`: a
+ * context name shared across tenants must not leak concurrency between them.
+ * One dispatch pass carries a single `resolvedOrgId`, so the org component is a
+ * standing invariant rather than a live discriminator — it is here so a future
+ * pass dispatching for more than one org cannot silently merge two orgs'
+ * tallies. `JSON.stringify` over the pair is used rather than string
+ * concatenation so no separator character can make two different pairs collide.
+ */
+export declare function concurrencyAdmissionKey(orgId: string, concurrencyGroup: string): string;
+/**
+ * Phase D — evaluate static jobs' context data, queue deferred-init jobs
+ * for jobs with dynamic fields, and pick the first `runContextName` for
+ * the run.
+ */
+export declare function evaluateJobContexts(args: {
+    ctx: WorkflowDispatchContext;
+    setup: DispatchSetup;
+    buildPrep: BuildPrepResult;
+}): Promise<JobEnvEvalResult>;
+/**
+ * Refuse a Dockerfile build on an untrusted ref, unless the org opted in.
+ *
+ * A job may build its container image from a Dockerfile in the repository. That
+ * build runs arbitrary `RUN` commands on the agent host's daemon, OUTSIDE the
+ * hardened posture the job's own steps get — `docker build` cannot be
+ * capability-restricted the way a container run can. So an untrusted ref (a fork
+ * PR, an unresolved contributor, or an internally-triggered run without a
+ * trusted emitter — the same classification the user-cache write scope uses)
+ * reaches it only where the operator said so.
+ *
+ * "Without a trusted emitter" covers both halves of the internal case: a
+ * `kiciEvent()` subscriber that inherited a `known` / `unknown` tier, and one
+ * that inherited nothing at all (no emitting run, no persisted tier, a lookup
+ * that failed) — the strict fallback, which is not an "untrusted emitter".
+ *
+ * Enforced here, at dispatch, and nowhere else: the agent applies only what
+ * dispatch authorized, exactly as it does for the sandbox capability grant. Deny
+ * is loud and total — the build never starts.
+ */
+export declare function resolveWorkflowDockerfileBuilds(workflow: LockWorkflow, opts: {
+    scope: CacheRefScope;
+    allowUntrusted: boolean;
+}): {
+    allowed: true;
+} | {
+    denied: {
+        reason: string;
+    };
+};
+/**
+ * Post the pending `KiCI Security` status, and record on every hold that gates
+ * this commit's check that the commit now carries it.
+ *
+ * The record is what a settle reads to decide whether a hold has a check to
+ * terminalize. Deriving that from the row's shape instead answers what the code
+ * INTENDED, and `postCheckStatus` CREATES the named run when it finds none — so
+ * a post the provider refused left a shape saying "posted" and a settle that
+ * put a completed `KiCI Security` run on a commit which never had one.
+ *
+ * `heldRunIds` is plural because the commit carries ONE check run: a job held on
+ * two independent requirements has both of them gating it, and marking only the
+ * one whose summary was rendered would let the first to end resolve a check the
+ * other is still gating.
+ *
+ * Awaited, where the post used to be fire-and-forget: the record can only be
+ * written once the provider has accepted, and a record racing the settle is a
+ * record the settle may not see. A failed post is still swallowed — the dispatch
+ * loop is never blocked by a provider error — but the round-trip is now
+ * serial and inside the per-job loop, so N held jobs cost N of them.
+ *
+ * On success and then a failed record the commit keeps a pending check the
+ * settle will decline to close. That is the residue the fire-and-forget post
+ * could already leave, now narrowed to whatever can fail between the accepted
+ * post and ONE statement. The record is therefore retried
+ * {@link PENDING_CHECK_MARK_ATTEMPTS} times before it is given up on, which
+ * closes the half of that window the doc above names as reachable without a
+ * process dying — a lost connection, a statement timeout, a deadlock. What is
+ * left is a process death inside the retry window, and nothing in reach closes
+ * that: a sweeper would have to ask the provider whether the check exists, and
+ * `CheckStatusPoster` has no read method. Adding one means a new method on a
+ * compat-protected engine interface, every implementation and every hand-built
+ * bundle, to recover a window measured in milliseconds — against a recovery
+ * that already exists, since pushing a new commit re-posts. A sweeper without
+ * that read could only guess, and a wrong guess FABRICATES a check, which is
+ * the worse direction either way: a fabricated failing check on a pull request
+ * is worse than a stuck one.
+ *
+ * The record is one statement over every id, never one per id. A partial mark
+ * would leave an unmarked hold uncounted by the contention query, so the first
+ * hold to end would terminalize the shared check while the other still gates
+ * the job — a fabricated PASSING check, the worse direction, and reachable
+ * without any process dying. See `markPendingCheckPosted`.
+ */
+/**
+ * How many times {@link postPendingHoldCheck} tries to record an accepted post
+ * on the hold rows before giving up and leaving the check unclosable.
+ */
+export declare const PENDING_CHECK_MARK_ATTEMPTS = 3;
+/**
+ * Open the needs gate for any job whose upstreams already reached terminal
+ * before this run's edges existed.
+ *
+ * **The race this closes.** Root jobs are dispatched to agents inside the
+ * dispatch loop, but `execution_job_needs` is only written afterwards, here. An
+ * agent that reports a root job terminal in that window drives
+ * `evaluateDownstreams`, which reads zero edges, returns an empty result, and
+ * the gate never fires again — the downstream stays `pending` forever and the
+ * run hangs with no error anywhere. Nothing re-evaluates on its own: the
+ * scheduler is purely event-driven off job completion, and that event has
+ * already been consumed.
+ *
+ * The window is small (single-digit milliseconds) but entirely reachable: a job
+ * that fails immediately on arrival — a rejected dispatch, an init failure, a
+ * capability mismatch — reports terminal in about the time one DB write takes.
+ * It was invisible for as long as the webhook route answered only after the
+ * whole pipeline had run, because the caller could not learn a job had been
+ * dispatched until every edge was already committed.
+ *
+ * Recomputing here is the same guard the deferred result-aware eval registration
+ * already applies for its own edges, and it is safe to run unconditionally: the
+ * claim inside `recomputeNeedsSatisfied` is a conditional UPDATE, so a job the
+ * normal completion path already claimed is skipped rather than dispatched
+ * twice.
+ *
+ * Wave-held jobs share the synthetic-id prefix but are gated by the rolling-wave
+ * scheduler, not by needs, so they are excluded — opening their gate here would
+ * bypass the `maxParallel` window.
+ */
+export declare function catchUpNeedsGatedJobs(args: {
+    ctx: NeedsSchedulingContext;
+    dispatchedJobs: readonly {
+        jobId: string;
+        jobName: string;
+        waveGated?: boolean;
+    }[];
+}): Promise<void>;
+/** Why an init result must not lead to a dispatch. */
+export declare enum InitDispatchSuppression {
+    /** The workflow's own `filter` decided the workflow does not apply. */
+    Filter = "filter",
+    /** The job is already rejected by a context rule, or held for approval. */
+    Gated = "gated"
+}
+/**
+ * Decide whether an arrived init result may dispatch its job.
+ *
+ * `Filter` requires the workflow to actually declare a filter as well as the
+ * agent to have reported `false`: a buggy or rogue agent must not be able to
+ * suppress a filter-less workflow by inventing the field, and an agent that
+ * predates the filter reports no verdict at all — reading that absence as
+ * "suppress" would silently stop every dispatch it handles.
+ *
+ * `Gated` covers a job that is already rejected or held. Its two halves now have
+ * very different reachability, and saying so is the point of this paragraph:
+ *
+ * - **rejected** is live and load-bearing. The flow-back consumes it (that is
+ *   the `suppression === Gated && jobEnvData.rejected` branch) to stop a job its
+ *   context rules rejected from dispatching.
+ * - **held** is NOT consumed here any more. A held job deliberately DOES get an
+ *   init job — nothing else can resolve a dynamic value, so suppressing the
+ *   round would make the job undispatchable rather than merely gated. The
+ *   flow-back handles it after resolution instead, routing it to
+ *   `holdExecutionAfterInit` so the hold and its resolved dispatch context are
+ *   stored together.
+ *
+ * So do not read this as a guarantee that a held job cannot dispatch: that
+ * guarantee lives at the call site's `jobEnvData.held` branch, and — for the
+ * needs-scheduler and cluster paths, which reach a job by other routes — in
+ * `dispatchReadyJob`'s pending-hold check and the cluster path's own
+ * `holdJobForApproval` call.
+ *
+ * Exported for its own test: inline, the second branch could not be exercised at
+ * all, and an untestable security check is one nobody can prove still works.
+ */
+export declare function initDispatchSuppression(workflow: Pick<LockWorkflow, 'hasFilter'>, initResult: {
+    filterPassed?: boolean;
+}, jobEnvData: Pick<JobEnvData, 'rejected' | 'held'>): InitDispatchSuppression | null;
 export interface GeneratedJobConfig {
     /**
      * The generated lock job with its `name` and `needs` rewritten to expanded
@@ -377,6 +876,18 @@ export declare function partitionGeneratedConfigsByPin(configs: readonly Generat
     pinnedConfigs: GeneratedJobConfig[];
     unpinnedConfigs: GeneratedJobConfig[];
 };
+/**
+ * Recompute the needs gate for `jobNames` and act on whatever became ready:
+ * open the gate for a satisfied job, terminalize a job an upstream's status
+ * excluded.
+ *
+ * `recomputeNeedsSatisfied` claims each job with a conditional
+ * `needs_satisfied = false → true` UPDATE, so a job a concurrent
+ * `evaluateDownstreams` already claimed is not returned here and cannot be
+ * dispatched twice.
+ */
+export declare function recomputeAndApplyReady(ctx: NeedsSchedulingContext, jobNames: readonly string[]): Promise<void>;
+export { gatherInvokeResults };
 /**
  * Dispatch a single matched workflow.
  *
@@ -393,5 +904,4 @@ export declare function partitionGeneratedConfigsByPin(configs: readonly Generat
  *   J. deferred dynamic dispatch (fire-and-forget per dynamic entry)
  */
 export declare function dispatchMatchedWorkflow(ctx: WorkflowDispatchContext, opts?: DispatchMatchedWorkflowOptions): Promise<DispatchMatchedWorkflowResult>;
-export {};
 //# sourceMappingURL=dispatch-matched-workflow.d.ts.map