@kici-dev/orchestrator 0.16.0 → 0.18.0

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

@@ -8,10 +8,8 @@
  * for jobs with dynamic fields, and deferred dynamic-job-fn dispatch for
  * `_type:'dynamic'` lock entries.
  *
- * Splits the historic 2438-line `dispatchMatchedWorkflow` into typed phase
- * helpers so each piece can be reasoned about independently. The main
- * exported function is a narrative orchestrator that threads the typed
- * results through the pipeline.
+ * The exported `dispatchMatchedWorkflow` threads typed phase-helper results
+ * through the pipeline.
  */
 import { ExecutionJobStatus, InitFailureCategory, CacheRefScope, HoldScope, TriggerSource } from '@kici-dev/engine';
 import type { LabelMatcher, LockWorkflow, LockJob, ApprovalRequirement, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, UpstreamSnapshot, HostFacts } from '@kici-dev/engine';
@@ -40,44 +38,31 @@ import { type ProcessingDeps } from './processor.js';
  */
 export declare function deriveCacheRefScope(trust: TrustResolution | undefined): CacheRefScope;
 /**
- * Context for dispatching a single matched workflow.
- *
- * Captures every per-workflow closure dependency so the dispatch body is
- * callable from BOTH the same-source path AND the cross-source delegation
- * shell. `crossSource` is the discriminator the helper uses to override the
- * dispatch `deliveryId` so fan-out targets land on their composite dedup
- * slot (`${inbound.deliveryId}:${reg.id}`) instead of the inbound delivery
- * id.
+ * Context for dispatching a single matched workflow, from both the same-source
+ * path and the cross-source delegation shell. `crossSource` overrides the
+ * dispatch `deliveryId` so fan-out targets land on their composite dedup slot
+ * (`${inbound.deliveryId}:${reg.id}`).
  */
 export interface WorkflowDispatchContext {
     info: WebhookInfo;
     deps: ProcessingDeps;
     /**
-     * Provider bundle for the matched source. Undefined for local-repo test runs
-     * (`kici run` against an inline lock file with no remote provider): in that
-     * mode there is no clone-url builder / check-status poster / clone-token
-     * provider, and `repoUrl` falls back to `''` (the agent treats a missing url
-     * as a local/`fullRepo` clone). The webhook adapter always passes a defined
-     * bundle, so its dispatch behavior is unchanged.
+     * Undefined only for local-repo test runs (`kici run` with an inline lock
+     * file and no remote provider): no clone-url builder, check poster or
+     * clone-token provider, and `repoUrl` is `''`, which the agent treats as a
+     * local/`fullRepo` clone. The webhook adapter always passes one.
      */
     bundle?: ProviderBundle;
     payload: unknown;
     repoIdentifier: string;
     /**
-     * The repository that defines the workflow. Equals `repoIdentifier` unless
-     * `global` is set.
-     *
-     * 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
+     * The repository that defines the workflow; equals `repoIdentifier` unless
+     * `global` is set. REQUIRED so a dispatch path that omits it does not
+     * compile: a null marker is read as "the repository the run acted on", not
      * "unknown" (`registration/registration-run-match.ts`).
      */
     workflowRepoIdentifier: string;
-    /**
-     * Set when the workflow is defined in another repository; `repoIdentifier`
-     * is then the event's source repository.
-     */
+    /** Set when another repository defines the workflow; `repoIdentifier` is then the event's source. */
     global?: GlobalDispatchIdentity;
     credentials: Record<string, unknown>;
     event: SimulatedEvent;
@@ -94,24 +79,19 @@ export interface WorkflowDispatchContext {
     };
     resolvedOrgId: string;
     /**
-     * The NAMES of the jobs this dispatch pass has admitted against a context
-     * concurrency limit, keyed by {@link concurrencyAdmissionKey}.
+     * NAMES of the jobs this pass admitted against a context concurrency limit,
+     * keyed by {@link concurrencyAdmissionKey}. The DB count cannot see a job
+     * just admitted, so without it every fan-out child is admitted against one
+     * slot.
      *
-     * The database count cannot see a job this pass has only just admitted, so
-     * 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.
+     * Names, not a counter, so the two terms stay DISJOINT: the count query
+     * excludes exactly these names ({@link countOccupyingJobs}). A counter summed
+     * with a count that already sees the row double-counts a sibling on the
+     * deferred-init path and spuriously holds a job.
      *
-     * Names rather than a counter, because the two terms have to be DISJOINT: the
-     * count query excludes exactly the names held here (see
-     * {@link countOccupyingJobs}), so a job whose row has already landed
-     * contributes its tally entry and nothing else. A counter cannot express that
-     * exclusion, and summing it with a count that already sees the row is how the
-     * deferred-init path double-counts a sibling and spuriously holds a job.
-     *
-     * Created lazily on first use and dropped with the ctx. It is per-pass state,
-     * never persisted and never shared between passes; two actors arriving in the
-     * same millisecond still race between the count and the insert, which is
-     * accepted — this is a throughput control, not an isolation boundary.
+     * Lazy, per-pass, never persisted or shared. Two actors in the same
+     * millisecond still race between count and insert — accepted, as this is a
+     * throughput control, not an isolation boundary.
      */
     concurrencyAdmissions?: Map<string, Set<string>>;
     workflow: LockWorkflow;
@@ -122,117 +102,83 @@ export interface WorkflowDispatchContext {
     /** 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.
+     * `execution_runs.triggered_by`. Set by the CLI remote-run path from the
+     * actor the Platform relays on `test.relay.trigger`. Undefined on the webhook
+     * path, whose provider-account initiator is in `triggerActorUsername` /
+     * `triggerActorUserId`.
      */
     triggeredBy?: string | null;
     /** Agent provenance label when the run was initiated through an agent credential. */
     triggeredByAgentLabel?: string | null;
     /**
-     * Re-run lineage for `execution_runs.parent_run_id` / `original_run_id`: the
-     * run this one re-runs and the root of its re-run chain. Set by the re-run of
-     * an organization-wide run; absent for every first run.
+     * `execution_runs.parent_run_id` / `original_run_id`. Set by the re-run of an
+     * organization-wide run; absent for every first run.
      */
     rerunLineage?: RerunLineage;
     /**
-     * The trigger event the run's OIDC subject derives from, when it is not the
-     * run's own `triggerEvent`. A re-run records `rerun` as its trigger event,
-     * which carries no pull-request dimension, so it states the original run's
-     * event here to keep the subject a re-run of a fork pull request presents.
+     * The trigger event the OIDC subject derives from, when not the run's own.
+     * A re-run records `rerun`, which has no pull-request dimension, so it
+     * states the original event here to keep a fork pull request's subject.
      */
     subjectTriggerEvent?: string;
     /** 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.
+     * The run's `triggerEvent`, stated instead of derived from `event.type`. A
+     * user `kiciEvent()` has `event.type` = `kici_event` while the run carries
+     * the raw event name. Absent ⇒ derived from the event.
      */
     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.
+     * The exact `jobConfig.event` envelope, instead of spreading the matched
+     * `SimulatedEvent`. The envelope omits `targetBranch` and `changedFiles`: an
+     * internal run has no changed files, and its branch is provenance for the
+     * trigger matcher and context branch gate. The envelope becomes
+     * `RuleContext.event` and the `event` half of `buildConcurrencyGroupContext`,
+     * so publishing the branch would silently re-key the documented
+     * `ctx.event.targetBranch ?? 'default'` group of every internal workflow.
+     * Absent ⇒ derived from the event.
      */
     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).
+     * Chain depth to stamp: an invoke-gate summon carries its summoner's depth +
+     * 1, which bounds the chain-depth circuit breaker. Absent ⇒ 0.
      *
-     * 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.
+     * Load-bearing: the breaker fails OPEN if this is lost. Stamped as soon as
+     * the run row exists, because `releaseInvokeGate` reads it back 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.
+     * cannot re-trigger itself (`EventRouter.isFailureLifecycleRun`). Persisted
+     * as a field merged INTO the `trigger_decision` JSON blob.
      */
     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.
+     * Marks a run the orchestrator triggered itself (schedule fire, workflow/job
+     * completion, failure batch, user `kiciEvent()`, invoke-gate summon). Absent
+     * ⇒ 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.
+     * Read only by the context branch gate. Such a run usually has a real
+     * `targetBranch` (a schedule's registration default branch, or the emitting
+     * run's branch) and is matched normally. The flag lets the gate name the
+     * cause when `targetBranch` is EMPTY (failure batch, scaler event, uncaptured
+     * default branch, emitting run gone) instead of quoting an empty branch. It
+     * does NOT weaken the gate: a run with no branch satisfies no restriction,
+     * `*` included.
      */
     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
-     * before any job starts. Computed once per PR event in the webhook pipeline
-     * and threaded down; the dispatch gate acts on it directly, see
-     * `holdRunForSecurityPolicy` / `rejectRunForSecurityPolicy`.
+     * Org trust-policy gate outcome for this PR event: `pass` dispatches, `hold`
+     * parks the run in the security queue, `reject` fails it before any job
+     * starts (`holdRunForSecurityPolicy` / `rejectRunForSecurityPolicy`).
+     * Computed once per PR event in the webhook pipeline.
      *
-     * REQUIRED: a dispatch path that does not state a decision must not compile.
-     * This field was optional once and the gate read `if (!decision) return
-     * null`, so forgetting to thread it meant the run passed the security gate —
-     * fail-open by omission inside a fail-closed control. A `pass` is stated
-     * explicitly.
+     * REQUIRED so a path that omits it does not compile: an optional field read
+     * as `if (!decision) return null` passes the gate on omission — fail-open
+     * inside a fail-closed control. A `pass` is stated explicitly.
      */
     securityDecision: TrustPolicyOutcome;
     /**
@@ -253,139 +199,110 @@ export interface WorkflowDispatchContext {
      */
     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.
+     * Set once `setupDispatchContext` posted the queued `kici/<workflow>` check
+     * and one `kici/<workflow>/job/<name>` per static job. They go up BEFORE the
+     * start decision, so every exit owes them a conclusion. Named early exits
+     * complete their own; a THROW does not, and nothing else can (the stale
+     * sweep only touches `in_progress` checks), so they stay `queued` forever —
+     * a branch-protection blocker on a pull request.
      */
     pendingChecksPosted?: boolean;
     /** Composite dedup key `${info.deliveryId}:${reg.id}` (cross-source only). */
     crossSourceDeliveryId?: string;
     /**
-     * Routing key to use for dispatched QueuedJobInput + log / tracker rows.
-     * Same-source: equal to `info.routingKey`. Cross-source: equal to
-     * `reg.routingKey` (the registration's owning source, NOT the inbound
-     * generic routing key).
+     * Routing key for dispatched jobs and log / tracker rows: `info.routingKey`
+     * same-source; `reg.routingKey` cross-source (the registration's owning
+     * source, NOT the inbound generic key).
      */
     effectiveRoutingKey?: string;
     /**
-     * Provider identifier to use for dispatched QueuedJobInput + tracker rows.
-     * Same-source: equal to `info.provider`. Cross-source: equal to
-     * `regBundle.normalizer.provider` (the registration's provider type,
-     * e.g. 'github').
+     * Provider for dispatched jobs and tracker rows: `info.provider`
+     * same-source; `regBundle.normalizer.provider` cross-source.
      */
     effectiveProvider?: string;
     /**
-     * Extra jobConfig fields merged into every dispatched QueuedJobInput by
-     * this helper. Cross-source callers use this to inject provenance fields
-     * (`crossSource: true`, `inboundRoutingKey`, `inboundEventName`,
-     * `workflowRepoUrl`, `workflowRef`, `workflowSha`,
-     * `workflowRepoIdentifier`) that downstream agents / dashboards need for
-     * correct clone + logging.
+     * jobConfig fields merged into every dispatched job. Cross-source callers
+     * inject provenance (`crossSource: true`, `inboundRoutingKey`,
+     * `inboundEventName`, `workflowRepoUrl`, `workflowRef`, `workflowSha`,
+     * `workflowRepoIdentifier`) that agents and dashboards need to clone and log.
      */
     extraJobConfig?: Record<string, unknown>;
     /**
-     * Test-run provenance. Present only for `kici run` / test-trigger dispatches.
-     * When set, `recordRunStart` stamps `is_test_run = true` and
-     * `fixture_id = testRun.fixtureId` on the `execution_runs` row. Undefined for
-     * webhook runs (the stamp block is skipped).
+     * Set only for `kici run` / test-trigger dispatches: `recordRunStart` stamps
+     * `is_test_run = true` and `fixture_id` on the `execution_runs` row.
      */
     testRun?: {
         fixtureId: string;
     };
     /**
-     * Run-wide flat secrets layered onto EVERY dispatched job's `jobConfig.secrets`
-     * (env-declaring or not). Used by the test path to deliver `kici run --secret`
-     * / `--env` CLI flat secrets, which must reach a job regardless of whether it
-     * declares an `context:`. Merged UNDER the per-job env-resolved secrets so
-     * the CLI value wins on a key collision (matching the prior B1-env -> A-CLI
-     * precedence). Undefined for webhook runs.
+     * `kici run --secret` / `--env` flat secrets, layered onto EVERY job's
+     * `jobConfig.secrets` whether or not it declares a `context:`. The CLI value
+     * wins on a key collision with per-job context secrets. Undefined for webhook
+     * runs.
      */
     runWideFlatSecrets?: Record<string, string>;
     /**
-     * Runtime host narrowing from `kici run --target` (Ansible `--limit`). Applied
-     * as a post-filter over each runsOnAll job's matched roster: effective hosts =
-     * runsOnAll ∩ target. Narrow-only. Undefined for webhook runs (no narrowing).
+     * `kici run --target` (Ansible `--limit`): narrow-only post-filter, effective
+     * hosts = runsOnAll ∩ target. Undefined for webhook runs.
      */
     target?: HostTargetSelector;
     /**
-     * Resolved (coerced + defaulted + validated) workflow-dispatch inputs from
-     * `kici run --input`. Carried onto every dispatched job's request so the agent
-     * exposes them as `ctx.dispatchInputs`. Undefined for webhook runs.
+     * Resolved (coerced, defaulted, validated) `kici run --input` values, exposed
+     * to every job as `ctx.dispatchInputs`. Undefined for webhook runs.
      */
     dispatchInputs?: Record<string, unknown>;
     /**
-     * What the workflow install gate recorded when it held this dispatch: the
-     * contexts that held, which the hold's approval covers, and the ones it
-     * admitted. Stored with the held dispatch and read by its release, which
-     * gates every context the approval did not cover. Unset on any other
-     * dispatch.
+     * Set only on an install-gate-held dispatch: the contexts that held (covered
+     * by the hold's approval) and the ones admitted. Its release gates every
+     * context the approval did not cover.
      */
     installGateRecord?: InstallGateRecord;
 }
 /**
- * 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.
+ * The slice the needs catch-up and ready-recompute helpers read, so the
+ * global-workflow path (which never builds a full `WorkflowDispatchContext`)
+ * can drive the needs scheduler too.
  */
 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
- * recomputes from the clone when status !== 'fetched', so this only forfeits the
- * optimization when a path is missed — correctness comes from the agent).
+ * The dispatch-envelope event, carrying the already-fetched changed files as a
+ * fast path. The agent recomputes from the clone when status !== 'fetched', so
+ * correctness comes from the agent.
  */
 export declare function envelopeEvent(baseEvent: SimulatedEvent, eventWithFiles: SimulatedEvent): SimulatedEvent;
 export interface DispatchMatchedWorkflowResult {
-    /** Number of jobs successfully dispatched (non-rejected). */
+    /** Non-rejected jobs dispatched. */
     dispatchedJobCount: number;
-    /** Execution job ids of every dispatched/tracked job (root, gated, synthetic). */
+    /** Every dispatched/tracked job id (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.
+     * Jobs deferred to the agent init round, not yet in `dispatchedJobIds`. They
+     * still run (`startDeferredPhases`), so a run with deferred work is not
+     * "nothing dispatched". Absent/0 on early returns.
      */
     deferredJobCount?: number;
-    /** True when the workflow install gate paused the dispatch (held run). */
+    /** True when the workflow install gate held the run. */
     held?: boolean;
     /**
-     * User-visible warnings aggregated from dispatched jobs — today, one per job
-     * whose bound test-run context(s) were unavailable and skipped. Surfaced
-     * on the accepted trigger response so the CLI can print them.
+     * One warning per job whose bound test-run contexts were skipped, surfaced
+     * on the trigger response for the CLI to print.
      */
     envWarnings?: string[];
 }
 /** Options controlling a (re-)dispatch of a matched workflow. */
 export interface DispatchMatchedWorkflowOptions {
-    /**
-     * Resume path: skip the workflow install protection gate (already satisfied)
-     * so secrets resolve directly and the dispatch flows into job dispatch.
-     */
+    /** Resume path: the install protection gate is already satisfied. */
     skipInstallProtectionGate?: boolean;
-    /**
-     * The run id whose `held` execution_runs row should be reused (flipped to
-     * pending) instead of inserting a fresh row.
-     */
+    /** Run id whose `held` row is flipped to pending instead of inserting a new one. */
     reuseRunId?: string;
 }
 type DispatchFn = (input: QueuedJobInput) => ReturnType<Dispatcher['dispatch']>;
 interface DispatchSetup {
-    /** Wrapped dispatcher that injects ctx.extraJobConfig into every dispatch. */
+    /** Injects ctx.extraJobConfig into every dispatch. */
     dispatcher: {
         dispatch: DispatchFn;
     };
-    /** WebhookInfo overlaid with effective routing key + provider. */
+    /** Overlaid with the effective routing key and provider. */
     info: WebhookInfo;
     /** Composite delivery id on cross-source, otherwise info.deliveryId. */
     effectiveDeliveryId: string;
@@ -395,11 +312,9 @@ interface DispatchSetup {
     } | undefined;
     workflowTimeoutMs: number | undefined;
     /**
-     * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`),
-     * carried on `ctx.extraJobConfig` by the test-trigger / `kici run --check`
-     * path. Persisted onto the `execution_runs` row so `computeRunStatus` can
-     * fail a `check-fail-on-drift` run that detected drift. Undefined for the
-     * default apply-mode webhook path.
+     * Idempotent-step mode (`apply` | `check` | `check-fail-on-drift`) from the
+     * `kici run --check` path; persisted so `computeRunStatus` fails a
+     * `check-fail-on-drift` run with drift. Undefined for apply-mode webhooks.
      */
     checkMode: string | undefined;
 }
@@ -417,9 +332,9 @@ interface BuildPrepResult {
     }>>;
     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`.
+     * Static jobs after matrix fan-out (non-matrix 1:1), keyed by
+     * `expandedName` in every phase. Dynamic-matrix jobs carry
+     * `pendingDynamicMatrix`.
      */
     materializedJobs: readonly MaterializedJob[];
     /** baseName -> expanded child names; drives needs-edge expansion. */
@@ -432,12 +347,11 @@ interface BuildPrepResult {
     buildJobName: string | undefined;
     buildJobLabels: string[] | undefined;
     buildJobTrackedEarly: boolean;
-    /** True when the build failed but dynamic entries can still proceed. */
+    /** 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`.
+     * Dispatch short-circuited (build failed with no dynamic entries, or build
+     * job rejected). Caller MUST return `dispatchedJobCount: 0`.
      */
     abort: boolean;
 }
@@ -446,9 +360,8 @@ interface JobEnvData {
     /** 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.
+     * Ordered bound-context names for the job row; `(dynamic)` marks an element
+     * the agent resolves later, which then overwrites the list.
      */
     contextNames?: string[];
     contextVars?: Record<string, string>;
@@ -456,9 +369,9 @@ interface JobEnvData {
     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.
+     * Container registry credentials resolved from the lock's secret NAMES;
+     * lifted to a top-level dispatch field (stripped from jobConfig) before the
+     * agent sees it.
      */
     containerRegistryAuth?: {
         username: string;
@@ -467,24 +380,21 @@ interface JobEnvData {
     };
     held?: boolean;
     /**
-     * Set when the job's bound contexts admitted its reject rules: what a later
-     * dispatch resolves the context data from when the job is stored as a
-     * pending dispatch context (held, waiting on upstream jobs, or outside its
-     * wave window) instead of dispatching now. Carries no secret value.
+     * Set when the bound contexts admitted the job's reject rules: what a later
+     * dispatch resolves context data from when the job is stored pending (held,
+     * awaiting upstream, outside its wave). Carries no secret value.
      */
     contextResolution?: DeferredContextResolution;
     /**
-     * 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.
+     * Set when a context policy or lock `approval` needs sign-off; the dispatch
+     * loop turns it into a `held_runs` row plus a stored pending job context so
+     * `release()` can re-dispatch.
      */
     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.
+     * A non-reviewer hold (security / wait-timer / concurrency-queue) from
+     * protection rules. Carried, not written on the spot, so
+     * `holdJobForApproval` creates the row and resume path in ONE transaction.
      */
     nonApprovalHold?: CreateHeldRunData;
     rejected?: boolean;
@@ -492,11 +402,7 @@ interface JobEnvData {
     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.
-     */
+    /** Warning naming test-run contexts skipped as non-test or unconfigured; shown in CLI and dashboard. */
     envWarning?: string;
 }
 /** A resolved approval requirement awaiting hold creation in the dispatch loop. */
@@ -518,14 +424,11 @@ interface JobEnvEvalResult {
     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.
- *
- * Re-exported from `db/synthetic-job-ids.ts`, which owns it so the concurrency
- * sweep in `contexts/` can exclude these rows without importing this module.
+ * Synthetic job-id prefix every needs-gate site stamps on a held-back job. The
+ * release path (`dispatchReadyJob` → `findSyntheticJobId` → `addJobsToRun`)
+ * keys on it, so it soundly recovers the gated set without threading a parallel
+ * list through both the single-orch and cluster paths. Owned by `db/synthetic-job-ids.ts` so the `contexts/`
+ * concurrency sweep need not import this module.
  */
 export { NEEDS_PENDING_JOB_ID_PREFIX };
 interface RejectedJob {
@@ -535,29 +438,19 @@ interface RejectedJob {
     /** Explicit init-failure category override; inferred from reason when absent. */
     category?: InitFailureCategory;
     /**
-     * Terminal status to record for this job. Defaults to `failed`. A zeroed
-     * `runsOnAll` that intentionally narrowed to no hosts is recorded as `skipped`
-     * (no init-failure) so its downstreams' `when` sets govern propagation.
+     * Default `failed`. A `runsOnAll` deliberately narrowed to no hosts records
+     * `skipped` (no init-failure) so downstream `when` sets govern propagation.
      */
     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 unreachable.
+ * Whether a `__build__` job must run first. Either cache missing is a reason:
+ * source (keyed on contentHash) and deps (keyed on lockfile hash) miss
+ * independently, and a dependency bump leaves source warm and deps cold.
+ * Gating on the source miss alone never uploads the dep tarball, so agents
+ * with no registry route (cloud one-shot, air-gapped) cannot run at all.
  *
- * 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.
+ * A miss counts only with its hash: no hash means no cache key to write.
  */
 export declare function buildIsNeeded(args: {
     /** False when there is nothing to cache into (no bundle, no coordinator, …). */
@@ -568,13 +461,11 @@ export declare function buildIsNeeded(args: {
     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
- * agent holding `kici:capability:ssh-transport`, which runs the agent-side
- * `ensureInitRunner(targetAgentId)` over SSH. The init-runner then connects
- * under `targetAgentId`, and the child's pinned-hold (already queued with that
- * pin) drains its bootstrap steps onto it. The bring-up job clones nothing and
- * runs no sandbox (`bringupOnly`).
+ * A synthetic `__bringup__` job, one per un-agented `includeUninitialized`
+ * child, sent to a `kici:capability:ssh-transport` agent that runs
+ * `ensureInitRunner(targetAgentId)` over SSH. The init-runner connects under
+ * `targetAgentId` and the child's pinned hold drains onto it. Clones nothing,
+ * no sandbox (`bringupOnly`).
  */
 export declare function buildBringupJobInput(args: {
     ctx: WorkflowDispatchContext;
@@ -582,23 +473,10 @@ export declare function buildBringupJobInput(args: {
     targetAgentId: string;
 }): QueuedJobInput;
 /**
- * Phase B orchestrator: probe caches, dispatch the build job (if needed),
- * and surface enough state for downstream phases to skip / continue
- * appropriately.
- */
-/**
- * Materialize each static job's matrix into dispatchable children. A job whose
- * matrix is invalid (zero combinations / over the cap) is dropped from the
- * dispatch list and recorded as a `matrix_expansion` matrix failure so the run's
- * other jobs still proceed. Dynamic-matrix jobs pass through with a
- * `pendingDynamicMatrix` marker for the eval flow.
- */
-/**
- * Resolve a `runsOnAll` lock job against the declared host roster and partition
- * the matched hosts into the target set per the `onUnreachable` policy (R2):
- * `ready` hosts always run; unreachable durable (`static`) hosts hold / fail /
- * skip; stale ephemeral hosts are always skipped. Throws {@link FanoutError}
- * when the run can't proceed (fail policy with an absent host, or zero targets).
+ * Resolve a `runsOnAll` job against the host roster and apply `onUnreachable`:
+ * `ready` hosts run; unreachable `static` hosts hold / fail / skip; stale
+ * ephemeral hosts are skipped. Throws {@link FanoutError} when the run cannot
+ * proceed (fail policy with an absent host, or zero targets).
  */
 export declare function resolveHostFanoutTargets(lockJob: LockJob, deps: ProcessingDeps, target?: HostTargetSelector): Promise<ResolvedHostAgent[]>;
 /** Exact labels + regex patterns partitioned from a lock job's selectors. */
@@ -608,64 +486,44 @@ interface JobRoutingSelectors {
     excludeLabels: string[];
     excludePatterns: LabelMatcher[];
     /**
-     * The `runsOn` exact values exactly as the lock file spells them, before the
-     * canonical fold `partitionMatchers` applies.
-     *
-     * Only {@link resolveRosterAgentPin} reads this. A bare agent id in `runsOn`
-     * is the documented inventory fan-out pattern (`runsOn: [h.agentId]`), and an
-     * agent id is not a label: `host_roster.agent_id` is case-sensitive, so the
-     * folded form misses every host whose id carries a capital.
+     * `runsOn` exact values as spelled, before `partitionMatchers` folds them.
+     * For {@link resolveRosterAgentPin} only: `host_roster.agent_id` is
+     * case-sensitive, so the folded form misses ids with a capital.
      */
     runsOnExactRaw: string[];
 }
 /**
- * Partition a lock job's runsOn / excludeLabels matchers into exact labels (SQL
- * `@>` prefilter + registry index) and regex patterns (JS post-filter). A
- * `runsOnAll` host-fanout job has no `runsOn`; its pinned children carry no
- * routing (the pin targets the resolved agent directly).
+ * Partition runsOn / excludeLabels into exact labels (SQL `@>` prefilter +
+ * registry index) and regex patterns (JS post-filter). A `runsOnAll` job has
+ * no `runsOn`; its children route by pin.
  */
 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.
+ * Runtime labels a job's shape demands of its host. Only a
+ * `container.dockerfile` job gets one: building needs a `docker` / `podman`
+ * CLI, which the agent self-reports as `kici:runtime:container-build`.
  *
- * 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.
+ * A finalized `image` job deliberately gets NOTHING: an implicit requirement
+ * on working jobs strands them. An agent too old to report the label 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.
+ * Applied to REGISTERED agents only, NOT the scaler: backends match by exact
+ * label-set containment, so a label absent from the pool's set strands the job
+ * `queued-no-backend`. What an agent can do is known once it registers.
  */
 export declare function requiredRuntimeLabelsFor(container: unknown): string[];
 /**
- * Resolve a generated job's single bare-`agentId` `runsOn` into a host pin.
- *
- * The documented inventory fan-out pattern is `runsOn: [h.agentId]`. A bare
- * agentId is not a label any agent advertises, so the normal label path leaves
- * the job `queued-no-backend`. When the single exact label names a known roster
- * host, resolve it to a `pinnedAgentId` dispatch (+ the host's coordinator for
- * cross-cluster reroute) — exact parity with how `runsOnAll` children pin. Any
- * other shape (multi-label, a regex pattern, a non-roster label, or no roster
- * store) returns null and the caller keeps normal label routing.
- *
- * `runsOnExact` takes the values the lock file spells, NOT the canonical labels
- * every other routing path uses: this looks the value up as an agent id, and
- * agent ids are case-sensitive. Handing it folded labels strands every host
- * whose id carries a capital on the normal label path, where a bare agent id
- * matches nothing.
+ * Resolve the documented inventory pattern `runsOn: [h.agentId]` into a host
+ * pin. A bare agentId is no advertised label, so label routing leaves it
+ * `queued-no-backend`. When the single exact label names a roster host, pin it
+ * (plus its coordinator for reroute), as `runsOnAll` children pin. Any other
+ * shape returns null and keeps label routing.
+ *
+ * `runsOnExact` takes the lock's spelling, NOT folded labels: agent ids are
+ * case-sensitive.
  */
 export declare function resolveRosterAgentPin(args: {
     runsOnExact: string[];
@@ -686,19 +544,18 @@ export interface WavePlan {
     }>;
 }
 /**
- * Compute the rolling-wave plan for a materialized job set.
- *
- * For each base job declaring `maxParallel` whose fan-out produced more than one
- * child, children are ordered deterministically by `fanoutIndex` (the
- * agentId / variant-label rank assigned at materialization; falling back to
- * `expandedName` for children with no index) and every child at index `>=
- * maxParallel` is held (`wave_gated=true`). The first `maxParallel` dispatch
- * immediately; held children release one-per-terminal via the wave-scheduler.
- * Every child of a bounded-wave base — held or not — gets a `policy` entry so
- * the wave-scheduler can read the width/failFast at terminal time. A non-fan-out
- * job (single child) or one without `maxParallel` contributes nothing.
+ * Rolling-wave plan. For a `maxParallel` base with more than one child,
+ * children sort by `fanoutIndex` (else `expandedName`) and index `>=
+ * maxParallel` is held (`wave_gated=true`); held children release
+ * one-per-terminal via the wave-scheduler. Every child of a bounded base gets
+ * a `policy` entry for the scheduler to read at terminal time.
  */
 export declare function computeWavePlan(materializedJobs: readonly MaterializedJob[]): WavePlan;
+/**
+ * Materialize each static job's fan-out. An invalid fan-out (zero combinations,
+ * over the cap) is recorded as a failure so the run's other jobs proceed.
+ * Dynamic-matrix jobs pass through marked `pendingDynamicMatrix`.
+ */
 export declare function materializeStaticJobsSafe(staticJobs: readonly LockJob[], deps: ProcessingDeps, target?: HostTargetSelector): Promise<{
     materializedJobs: MaterializedJob[];
     expansionMap: Map<string, readonly string[]>;
@@ -707,10 +564,9 @@ export declare function materializeStaticJobsSafe(staticJobs: readonly LockJob[]
 /** The `paths` lists this workflow's matching left to the agent, or undefined. */
 export declare function deferredPathsOf(ctx: Pick<WorkflowDispatchContext, 'decision'>): string[][] | undefined;
 /**
- * Scan a lock workflow's always-mode approval timeouts (workflow-level +
- * each static job) for a non-positive / non-finite `timeoutSeconds`. Returns the
- * first offender or null. Step-scope approvals ride the validated
- * `step.approval-request` wire schema and are not checked here.
+ * First workflow- or job-level approval with an invalid `timeoutSeconds`, or
+ * null. Step-scope approvals are validated by the `step.approval-request`
+ * wire schema instead.
  */
 export declare function findInvalidApprovalTimeout(workflow: LockWorkflow): {
     scope: 'workflow' | 'job';
@@ -718,30 +574,21 @@ export declare function findInvalidApprovalTimeout(workflow: LockWorkflow): {
     value: number;
 } | null;
 /**
- * Build the per-host secret-resolution context for a materialized child. A
- * `runsOnAll` host child carries its identity on `mat.agent` (preferred) or
- * `mat.pinnedAgentId`/`mat.host`; a non-host child (matrix/static) has none, so
- * resolution stays fleet-wide (`'**'`-only). Returns `undefined` when there are
- * no host facts to scope by.
+ * Per-host secret-resolution facts for a host child (`mat.agent` preferred,
+ * else `pinnedAgentId`/`host`). Undefined for a non-host child, whose
+ * resolution stays fleet-wide (`'**'`-only).
  */
 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.
+ * In-pass admission tally key. The org id mirrors the count query's
+ * `customer_id` scoping so a shared context name never leaks concurrency
+ * across tenants — a standing invariant, since one pass has one org.
+ * `JSON.stringify`, not concatenation, so no separator makes 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.
+ * Phase D — evaluate static jobs' context data, queue deferred-init jobs for
+ * dynamic fields, and pick the run's `runContextName`.
  */
 export declare function evaluateJobContexts(args: {
     ctx: WorkflowDispatchContext;
@@ -749,24 +596,15 @@ export declare function evaluateJobContexts(args: {
     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 an `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.
+ * Refuse a Dockerfile build on an untrusted ref unless the org opted in. The
+ * build runs arbitrary `RUN` commands on the host daemon, OUTSIDE the hardened
+ * posture (`docker build` cannot be capability-restricted). Untrusted = fork
+ * PR, unresolved contributor, or internal run without a trusted emitter (the
+ * user-cache write-scope classification) — including a `kiciEvent()`
+ * subscriber that inherited an `unknown` tier or nothing at all.
+ *
+ * Enforced only here, at dispatch; the agent applies what dispatch authorized,
+ * as for sandbox grants. Deny is loud and total.
  */
 export declare function resolveWorkflowDockerfileBuilds(workflow: LockWorkflow, opts: {
     scope: CacheRefScope;
@@ -778,55 +616,37 @@ export declare function resolveWorkflowDockerfileBuilds(workflow: LockWorkflow,
         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;
+/**
+ * Post the pending `KiCI Security` status, then record on every hold gating
+ * this commit's check that the commit carries it.
+ *
+ * A settle reads the record, not the row's shape, to decide whether there is a
+ * check to terminalize: `postCheckStatus` CREATES a missing run, so a shape
+ * saying "posted" after a refused post put a completed check on a commit that
+ * never had one.
+ *
+ * `heldRunIds` is plural because the commit carries ONE check run: with two
+ * requirements gating a job, marking one lets the first to end resolve a check
+ * the other still gates. Marked in one statement, never per id — a partial
+ * mark lets the contention query miss a hold and fabricate a PASSING check
+ * (`markPendingCheckPosted`).
+ *
+ * Awaited so the record lands before a settle can race it; a failed post is
+ * swallowed so the dispatch loop never blocks, at one serial round-trip per
+ * held job.
+ *
+ * A failed record after a successful post leaves a pending check no settle
+ * closes; retried {@link PENDING_CHECK_MARK_ATTEMPTS} times to cover a lost
+ * connection, statement timeout or deadlock. A process death mid-retry stays
+ * open: a sweeper would need a read on `CheckStatusPoster`, a compat-protected
+ * engine interface, to recover milliseconds that a new commit already
+ * recovers — and guessing FABRICATES checks, worse than a stuck one.
+ */
 export declare function postPendingHoldCheck(args: {
     poster: NonNullable<NonNullable<WorkflowDispatchContext['bundle']>['checkStatusPoster']>;
     store: NonNullable<ProcessingDeps['heldRunStore']>;
@@ -842,34 +662,15 @@ export declare function postPendingHoldCheck(args: {
     postFailureMessage: string;
 }): Promise<void>;
 /**
- * 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.
+ * Open the needs gate for jobs whose upstreams went terminal before the edges
+ * existed. Edges are written after the loop; a root job terminal on arrival
+ * drives `evaluateDownstreams` against zero edges, and the event-driven
+ * scheduler never re-fires, so the downstream stays `pending` forever.
+ *
+ * The same guard the deferred result-aware eval registration applies for its own
+ * edges. Safe unconditionally: `recomputeNeedsSatisfied` claims with a conditional
+ * UPDATE, so an already-claimed job is not dispatched twice. Wave-held jobs
+ * share the prefix but are excluded, or the `maxParallel` window is bypassed.
  */
 export declare function catchUpNeedsGatedJobs(args: {
     ctx: NeedsSchedulingContext;
@@ -889,40 +690,25 @@ export declare enum InitDispatchSuppression {
     Gated = "gated"
 }
 /**
- * Decide whether an arrived init result may dispatch its job.
+ * Whether an arrived init result may dispatch its job.
  *
- * `Paths` is checked first: a workflow whose deferred `paths` did not match
- * never triggered, whatever its filter says. Only an explicit `false`
- * suppresses — an agent that predates deferred paths reports no verdict, and
- * that absence dispatches.
+ * `Paths` first: unmatched deferred `paths` never triggered, whatever the
+ * filter says. Only an explicit `false` suppresses; an older agent's missing
+ * verdict dispatches.
  *
- * `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.
+ * `Filter` needs both a declared filter and a reported `false`: a rogue agent
+ * cannot suppress a filter-less workflow, and an older agent's missing verdict
+ * must not stop every dispatch.
  *
- * `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:
+ * `Gated`: **rejected** is load-bearing — the flow-back's
+ * `suppression === Gated && jobEnvData.rejected` branch stops it. **held** is
+ * NOT consumed here: a held job gets its init round (only it resolves dynamic
+ * values) and the flow-back routes it to `holdExecutionAfterInit`. The no-
+ * dispatch guarantee for a held job lives at the call site's `held` branch,
+ * `dispatchReadyJob`'s pending-hold check, and the cluster path's
+ * `holdJobForApproval`.
  *
- * - **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.
+ * Exported so the security check is testable.
  */
 export declare function initDispatchSuppression(workflow: Pick<LockWorkflow, 'hasFilter'>, initResult: {
     filterPassed?: boolean;
@@ -930,43 +716,34 @@ export declare function initDispatchSuppression(workflow: Pick<LockWorkflow, 'ha
 }, jobEnvData: Pick<JobEnvData, 'rejected' | 'held'>): InitDispatchSuppression | null;
 export interface GeneratedJobConfig {
     /**
-     * The generated lock job with its `name` and `needs` rewritten to expanded
-     * matrix-child names (identical to the base job for non-matrix generated
-     * jobs). Downstream dispatch / needs-edge / tracking code keys on this name.
+     * `name` and `needs` rewritten to expanded matrix-child names; dispatch,
+     * needs edges and tracking key on this name.
      */
     genJob: LockJob;
     genJobConfig: Record<string, unknown>;
     runsOnLabels: string[];
-    /** Regex matchers the agent's labels must satisfy (JS post-filter). */
+    /** JS post-filter. */
     runsOnPatterns: LabelMatcher[];
-    /** Exact labels the dispatched agent must NOT have. */
     excludeLabels: string[];
-    /** Regex matchers that disqualify an agent (JS post-filter). */
+    /** JS post-filter. */
     excludePatterns: LabelMatcher[];
-    /** Host-fanout pin: when runsOn resolved to a roster host, route only to it. */
+    /** Set when runsOn resolved to a roster host. */
     pinnedAgentId?: string;
-    /** The host's current coordinator (cross-cluster reroute hint); null = not connected. */
+    /** Cross-cluster reroute hint; null = not connected. */
     connectedInstanceId?: string | null;
-    /** The matrix combination for this child; absent for non-matrix generated jobs. */
     matrixValues?: Record<string, unknown>;
     /**
-     * The `gitCredentials` map the generator's LOCK entry declared, inherited by
-     * this child. Persisted to `execution_jobs.git_credentials` at every dispatch
-     * site below, which is what the credential relay authorizes a request against.
+     * Inherited from the generator's LOCK entry; persisted to
+     * `execution_jobs.git_credentials` at every dispatch site for the relay.
      */
     gitCredentials?: Readonly<Record<string, Readonly<Record<string, string>>>>;
-    /**
-     * What a later dispatch resolves the job's context data from, when the job
-     * binds a context. A generated job stored as a pending dispatch context
-     * carries no context data at rest.
-     */
+    /** Context-data source for a later dispatch; no context data rests in storage. */
     contextResolution?: DeferredContextResolution;
 }
 /**
- * Split generated configs into pinned (host-pin dispatch) and unpinned (normal
- * label routing). A pinned config always rides the dispatcher pin path because
- * the coordinator's `JobToRoute` shape carries no pin field — routing it via the
- * coordinator would silently drop the pin.
+ * Split generated configs into pinned and unpinned. Pinned always use the
+ * dispatcher pin path: `JobToRoute` has no pin field, so the coordinator would
+ * silently drop it.
  */
 export declare function partitionGeneratedConfigsByPin(configs: readonly GeneratedJobConfig[]): {
     pinnedConfigs: GeneratedJobConfig[];
@@ -982,42 +759,33 @@ interface ResolveGeneratedJobConfigsArgs {
     installEnvSecrets: Record<string, string> | undefined;
     generatedJobs: LockJob[];
     dynamicEntry: BuildPrepResult['dynamicEntries'][number];
-    /** Frozen upstream snapshot threaded into each generated job's dynamicSource for re-eval. */
+    /** Threaded into each job's dynamicSource for re-eval. */
     upstreamSnapshot?: UpstreamSnapshot;
 }
-/** A generated job its contexts' protection gates held, with the hold they decided. */
+/** A generated job its contexts' gates held. */
 export interface HeldGeneratedJob {
     config: GeneratedJobConfig;
     envData: JobEnvData;
 }
 /**
- * The generated jobs split by their context gate verdict. A job the gates
- * rejected, or whose resolution threw, appears in neither list: it is recorded
- * on the run as failed.
+ * Generated jobs by gate verdict. Rejected or thrown jobs are in neither list;
+ * they are recorded on the run as failed.
  */
 export interface GeneratedJobResolution {
-    /** Jobs cleared to dispatch, carrying their resolved context data. */
+    /** Carrying their resolved context data. */
     dispatchable: GeneratedJobConfig[];
-    /** Jobs to hold; their context secrets are not resolved. */
+    /** Context secrets not resolved. */
     held: HeldGeneratedJob[];
 }
 /**
- * Gate each generated job on its bound contexts and build the job configs.
- *
- * A job the context rules reject is recorded on the run as failed and returned
- * in neither list. A job whose resolution throws is recorded on the run as
- * failed too, and dropped from both lists.
+ * Gate each generated job and build its config. Rejected or thrown jobs are
+ * recorded on the run as failed and returned in neither list.
  */
 export declare function resolveGeneratedJobConfigs(args: ResolveGeneratedJobConfigsArgs): Promise<GeneratedJobResolution>;
 /**
- * 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.
+ * Recompute the needs gate for `jobNames`: open satisfied jobs, terminalize
+ * excluded ones. The conditional `needs_satisfied = false → true` claim means
+ * a job a concurrent `evaluateDownstreams` claimed is never dispatched twice.
  */
 export declare function recomputeAndApplyReady(ctx: NeedsSchedulingContext, jobNames: readonly string[]): Promise<void>;
 export { gatherInvokeResults };
@@ -1041,11 +809,7 @@ export declare function buildSecurityHoldData(runId: string, decision: Extract<T
     triggerSource: "context";
 };
 /**
- * Dispatch a single matched workflow.
- *
- * Narrative orchestrator: each phase is a typed helper that returns a typed
- * result the next phase consumes. The function reads top-to-bottom as the
- * pipeline:
+ * Dispatch a single matched workflow, phase by phase:
  *   A. setup → wrapped dispatcher + overlaid info
  *   B. cache + build → buildPrep with cache URLs and build-job state
  *   C. workflow secrets + ephemeral key → secret bundle