@kici-dev/orchestrator 0.3.0 → 0.5.0

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

@@ -13,8 +13,8 @@
  * 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 type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
@@ -55,6 +55,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;
@@ -74,6 +92,18 @@ 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;
     /**
@@ -91,13 +121,22 @@ 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.
      */
-    buildWindowTokenHeld?: boolean;
+    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.
+     */
+    runRegisteredBeforeDispatch?: boolean;
     /** Composite dedup key `${info.deliveryId}:${reg.id}` (cross-source only). */
     crossSourceDeliveryId?: string;
     /**
@@ -166,6 +205,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;
     /**
@@ -214,6 +261,116 @@ 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>>;
+    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;
+    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;
+}
+interface DispatchedJob {
+    jobId: string;
+    jobName: string;
+    runsOnLabels?: string[];
+    matrixValues?: Record<string, unknown>;
+    baseJobName?: string;
+    variantKind?: string;
+    variantLabel?: string;
+    /** Held by the rolling-wave gate (a fan-out child beyond maxParallel). */
+    waveGated?: boolean;
+    /** The base's wave width, stamped on every child of a bounded wave. */
+    waveMaxParallel?: number;
+    /** The base's failFast policy, stamped on every child of a bounded wave. */
+    waveFailFast?: boolean;
+    /** Ordered bound-context names persisted on the job row (multi-env jobs). */
+    contexts?: string[];
+    /** Bound contexts skipped on a test run (non-test / unconfigured). */
+    skippedContexts?: string[];
+    /** User-visible warning naming the skipped test-run contexts. */
+    envWarning?: string;
+}
 interface RejectedJob {
     jobId: string;
     jobName: string;
@@ -345,6 +502,77 @@ export declare function findInvalidApprovalTimeout(workflow: LockWorkflow): {
  * no host facts to scope by.
  */
 export declare function hostCtxFromMat(mat: MaterializedJob): HostFacts | undefined;
+/**
+ * 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>;
+/**
+ * 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: WorkflowDispatchContext;
+    dispatchedJobs: readonly DispatchedJob[];
+}): 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` is belt-and-braces. `evaluateJobContexts` gives a rejected or held job
+ * no init job in the first place, so this is unreachable today; if it ever
+ * becomes reachable, dispatching would mean going straight past a protection
+ * rule or an approval hold, which is the one outcome worth a redundant check.
+ *
+ * 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 +605,17 @@ 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: WorkflowDispatchContext, jobNames: readonly string[]): Promise<void>;
 /**
  * Dispatch a single matched workflow.
  *

package/dist/pipeline/global-eval-round.d.ts

@@ -0,0 +1,293 @@
+/**
+ * Tier-2 global eval round — orchestrator side.
+ *
+ * A global workflow can declare a `filter` predicate and `DynamicJobFn`
+ * generators, neither of which the orchestrator may run: author code never
+ * returns to this process. So the candidates that need either one are grouped by
+ * the workflow repo they live in and handed to ONE pre-run job per
+ * (event × workflow repo × registered SHA). That job checks out the workflow
+ * repo and the source repo once, runs every candidate's filter and then its
+ * generators, and reports a verdict per candidate.
+ *
+ * The round precedes any run row by design: its whole purpose is to decide which
+ * global workflows produce a run at all, so creating one up-front would defeat
+ * it.
+ *
+ * This module owns the partition, the grouping, and the dispatch-and-await. The
+ * caller decides what to do with the verdicts.
+ */
+import type { GlobalEvalCandidateResult, LockWorkflow, SimulatedEvent, WorkflowDecision } from '@kici-dev/engine';
+import { type GlobalEvalRoundCache } from '../cache/global-eval-round-cache.js';
+import type { PendingGlobalEvalTracker } from '../cache/pending-global-evals.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
+import type { ProviderBundle } from '../provider-registry.js';
+import type { QueuedJobInput } from '../queue/job-queue.js';
+import type { RegisteredWorkflow } from '../registration/registration-index.js';
+import type { WebhookInfo } from '../webhook/handler.js';
+/** Name prefix identifying a round job in the queue, logs, and the dashboard. */
+export declare const ROUND_JOB_PREFIX = "__globaleval__";
+/** Metric label values for a per-candidate round verdict. */
+export declare const GlobalEvalVerdictOutcome: {
+    /** The candidate's `filter` admitted it and its jobs are dispatching. */
+    readonly Run: 'run';
+    /** The candidate's `filter` returned false — a decided exclusion. */
+    readonly Filtered: 'filtered';
+    /** The round could not decide: it failed, breached a budget, or never reported. */
+    readonly Indeterminate: 'indeterminate';
+};
+export type GlobalEvalVerdictOutcome = (typeof GlobalEvalVerdictOutcome)[keyof typeof GlobalEvalVerdictOutcome];
+/** Metric label values for a dispatched round's outcome. */
+export declare const GlobalEvalRoundResultLabel: {
+    readonly Success: 'success';
+    readonly Error: 'error';
+};
+export type GlobalEvalRoundResultLabel = (typeof GlobalEvalRoundResultLabel)[keyof typeof GlobalEvalRoundResultLabel];
+/** Metric label values for one round-cache lookup. */
+export declare const GlobalEvalCacheLookupResult: {
+    readonly Hit: 'hit';
+    readonly Miss: 'miss';
+    /** The round input could not be serialized, so no key exists to look up. */
+    readonly Unkeyable: 'unkeyable';
+};
+export type GlobalEvalCacheLookupResult = (typeof GlobalEvalCacheLookupResult)[keyof typeof GlobalEvalCacheLookupResult];
+/** One matched global workflow the round may have to decide on. */
+export interface GlobalEvalCandidate {
+    reg: RegisteredWorkflow;
+    lockEntry: LockWorkflow;
+    /**
+     * The trigger-match decision this candidate came from, carried so the round's
+     * verdict can be appended to its trace. Optional because the round itself
+     * never reads it — only the caller that explains an exclusion does.
+     */
+    decision?: WorkflowDecision;
+}
+/**
+ * Stable identity for one candidate across a round's results.
+ *
+ * The registration id alone is unique, but the workflow name is appended so a
+ * lookup reads honestly at the call site and a malformed registration with a
+ * blank id still separates two workflows.
+ */
+export declare function candidateKey(candidate: GlobalEvalCandidate): string;
+/**
+ * Split matched global candidates into those that can dispatch straight away and
+ * those that must go through an eval round first.
+ *
+ * A candidate needs the round when it declares a `filter` (only the agent may
+ * run the predicate) or carries a `DynamicJobFn` (only the agent may run the
+ * generator). Everything else is fully described by the lock file, so routing it
+ * through a round would add a job dispatch and an agent round trip for nothing.
+ */
+export declare function partitionCandidates(candidates: readonly GlobalEvalCandidate[]): {
+    immediate: GlobalEvalCandidate[];
+    needsRound: GlobalEvalCandidate[];
+};
+/**
+ * Group by workflow repo, routing key, and registered SHA.
+ *
+ * All three parts are load-bearing. The repo identifier and the SHA together pin
+ * the exact tree the round checks out, so two registrations of one repo at
+ * different commits can never share a checkout; the routing key pins which
+ * provider bundle mints the clone credentials, so two providers owning the same
+ * repo path stay separate.
+ */
+export declare function groupCandidates(candidates: readonly GlobalEvalCandidate[]): Map<string, GlobalEvalCandidate[]>;
+/** Minimal dispatcher surface the round needs (the real one is the job dispatcher). */
+export interface GlobalEvalDispatcher {
+    dispatch(input: QueuedJobInput): Promise<{
+        status: string;
+        jobId: string;
+    }>;
+    /**
+     * Take a still-queued round job out of the queue when nobody is waiting for
+     * it any more. Optional so a test double can omit it.
+     */
+    cancelQueuedJob?(jobId: string, reason: string): Promise<void>;
+}
+/**
+ * Minimal provider-registry surface: resolving the bundle that owns a routing
+ * key. The round needs it because the workflow repo and the event's source repo
+ * can live behind different providers.
+ */
+export interface GlobalEvalProviderRegistry {
+    getByRoutingKey(routingKey: string): ProviderBundle | undefined;
+}
+/** Minimal agent-registry surface used to pick the round job's platform labels. */
+export interface GlobalEvalAgentRegistry {
+    findAvailable(labels: string[]): Array<{
+        platform: string;
+        arch: string;
+        version?: string | null;
+    }>;
+}
+/**
+ * First agent release whose job runner understands a `globalEvalRound`
+ * dispatch.
+ *
+ * Below it the agent has no round branch at all: the job falls through to the
+ * standard executor, whose `jobConfig` carries no `source.file`, so it either
+ * fails outright or reports success without the `globalEvalComplete` the
+ * orchestrator is waiting for. Either way the round never settles.
+ *
+ * Customers upgrade their orchestrator and their agents on their own schedule
+ * (`.claude/rules/compatibility.md`), so an orchestrator ahead of its fleet is
+ * a supported state and not an error — but it is one this module has to
+ * recognise, because the damage is not confined to the new feature. A global
+ * workflow that merely *contains* a generator now routes through the round, so
+ * an unrecognised round means static jobs that ran yesterday stop running.
+ */
+export declare const MIN_GLOBAL_EVAL_AGENT_VERSION = "0.5.0";
+export interface GlobalEvalRoundDeps {
+    dispatcher: GlobalEvalDispatcher;
+    pendingGlobalEvals: PendingGlobalEvalTracker;
+    /**
+     * Required, unlike the three optional deps below: it is what resolves the
+     * WORKFLOW repo's own provider bundle. Omitting it would leave the round with
+     * no clone URL for the workflow repo at all, so it is not a dep that can
+     * degrade quietly.
+     */
+    providerRegistry: GlobalEvalProviderRegistry;
+    clusterSettings?: ClusterSettingsReader;
+    globalEvalCache?: GlobalEvalRoundCache;
+    agentRegistry?: GlobalEvalAgentRegistry;
+}
+export interface GlobalEvalRoundArgs {
+    deps: GlobalEvalRoundDeps;
+    info: WebhookInfo;
+    event: SimulatedEvent;
+    candidates: readonly GlobalEvalCandidate[];
+    /** Source repo that triggered the event. */
+    repoIdentifier: string;
+    /** Source repo SHA the event lands on. */
+    ref: string;
+    dispatchBundle: ProviderBundle;
+    dispatchCredentials: Record<string, unknown>;
+    /** Cluster defaults for the round budgets and the wait ceiling (`config.ts`). */
+    config: {
+        globalEvalRoundTimeoutMs: number;
+        globalEvalCandidateTimeoutMs: number;
+        globalEvalWaitTimeoutMs: number;
+    };
+}
+/**
+ * Why a fleet cannot decide a round, or `null` when it might.
+ *
+ * Only ONE state is refused: every registered init-runner reports a version, and
+ * every one of them is below the minimum. Everything else returns `null`.
+ *
+ * An empty fleet is not refused — nothing is registered yet, an agent may
+ * register a second from now, and the queue's own unroutable handling already
+ * covers a round nobody picks up.
+ *
+ * A fleet containing even ONE agent whose version cannot be read is not refused
+ * either, and the bar is deliberately that strict rather than "all unknown".
+ * Refusing suppresses every global workflow for the delivery — the exact damage
+ * this function exists to prevent — so it must rest on proof, not on ignorance
+ * about part of the fleet. Getting it wrong in the other direction merely costs
+ * a slow failure with a less useful message.
+ *
+ * Refusing here rather than at dispatch is deliberate. A too-old fleet does not
+ * clear within a retry, so dispatching would spend two full wait ceilings of
+ * inline webhook latency to reach the same verdict — and reach it with a
+ * timeout message that says nothing about agent versions.
+ */
+export declare function unsupportedFleetReason(agentRegistry?: GlobalEvalAgentRegistry): string | null;
+/**
+ * Cap on the joined reason string a decided-nothing round reports.
+ *
+ * The reasons are authored by an agent running author code, so their combined
+ * length is unbounded — and this string travels verbatim into the commit
+ * check's `output.summary`, which GitHub caps at 65535 characters. An overflow
+ * is rejected with a 422 that the best-effort post swallows, so the check
+ * disappears in exactly the case it exists for. Realistic reasons are one short
+ * sentence each; this bound makes that structural instead of lucky.
+ */
+export declare const MAX_ROUND_REASON_CHARS = 4000;
+/**
+ * Truncate `text` to at most `max` UTF-16 code units, marking that it was cut.
+ *
+ * Two edges the naive slice gets wrong, both of which matter because the result
+ * is posted to an API with a hard character limit:
+ *
+ * - A `max` smaller than the marker would make `max - marker.length` negative,
+ *   and appending the marker to an empty slice then returns a string LONGER
+ *   than `max`. Such a `max` cannot carry both content and a marker, so the
+ *   marker itself is truncated instead.
+ * - Slicing at an arbitrary index can cut a surrogate pair in half, leaving a
+ *   lone surrogate that is not valid text. The cut backs off by one unit when
+ *   it lands between the halves of a pair.
+ */
+export declare function truncateReasonText(text: string, max: number): string;
+/**
+ * One round that produced no verdicts after every attempt, described well enough
+ * for the caller to record it.
+ *
+ * There is exactly one of these per failed round — never one per candidate. The
+ * round exists to collapse N candidate workflows into a single pre-run job, so
+ * fanning its failure back out into N run rows and N checks would undo the fan-out
+ * reduction the whole design is for. `workflowNames` is what makes the single
+ * record honest: it names every workflow the failure suppressed.
+ */
+export interface GlobalEvalRoundFailure {
+    /** The last attempt's round-job run id — what an errored run row is written under. */
+    runId: string;
+    /** Repo the suppressed workflows are authored in. */
+    workflowRepoIdentifier: string;
+    /** Every candidate workflow this round suppressed. */
+    workflowNames: string[];
+    /** The last attempt's error. */
+    error: string;
+    /** How many attempts were made before giving up. `0` ⇒ never dispatched. */
+    attempts: number;
+    /**
+     * True when the round itself completed and decided some candidates, leaving
+     * only {@link workflowNames} undecided.
+     *
+     * Recorded as its own record rather than folded into a total failure because
+     * the two read differently to an author: a total failure means nothing from
+     * this repo ran, a partial one means their workflow specifically could not be
+     * decided while its neighbours ran fine. Without it, whether a broken filter
+     * is visible at all depends on how many unrelated global workflows happen to
+     * share a workflow repo — a per-candidate budget breach in a group of one
+     * produces a check, and the identical fault in a group of two produces
+     * nothing.
+     */
+    partial?: boolean;
+}
+/** Every candidate's verdict, plus the rounds that produced none. */
+export interface GlobalEvalRoundsOutcome {
+    /** One verdict per candidate, keyed by {@link candidateKey}. */
+    verdicts: Map<string, GlobalEvalCandidateResult>;
+    /** One entry per round that failed outright — never one per candidate. */
+    failures: GlobalEvalRoundFailure[];
+}
+/**
+ * Run every eval round the candidate set needs and return one verdict per
+ * candidate, plus one failure record per round that produced none.
+ *
+ * Rounds run one group at a time: a group is one dual checkout on one agent, and
+ * a push touching several workflow repos is the uncommon case. A group whose
+ * round fails marks only its own candidates indeterminate — one unreachable
+ * workflow repo must not suppress the workflows living in another.
+ *
+ * The failures are returned rather than recorded here: this module owns the
+ * partition, the grouping, and the dispatch-and-await, and has neither a
+ * database handle nor the inbound provider bundle a commit check must be posted
+ * through.
+ */
+export declare function runGlobalEvalRounds(args: GlobalEvalRoundArgs): Promise<GlobalEvalRoundsOutcome>;
+/**
+ * Meter candidates a round never got to decide on.
+ *
+ * The caller's fail-closed paths — no pending-eval tracker, so a round could
+ * never settle — return before {@link runGlobalEvalRounds} is reached, and they
+ * suppress EVERY global workflow for that delivery. That is this subsystem's
+ * most severe outcome, and without this call it appeared in none of its
+ * metrics: one `logger.warn` was the whole record.
+ *
+ * Counted as `indeterminate` because that is exactly what happened — nothing
+ * evaluated the workflows — which also keeps `candidates` equal to the sum of
+ * the verdicts on every path.
+ */
+export declare function recordUnrunCandidates(count: number): void;
+//# sourceMappingURL=global-eval-round.d.ts.map

package/dist/pipeline/job-contexts.d.ts

@@ -3,43 +3,42 @@
  *
  * A job binds an ordered list of contexts (`LockJob.contexts`). This
  * module resolves that list into concrete context names (static values
- * verbatim, pure-inline dynamic elements evaluated against the event) and folds
- * the per-context secrets/variables last-wins. It keeps the heavy fold logic
+ * verbatim; every dynamic element is resolved by the agent's init job) and
+ * folds the per-context secrets/variables last-wins. It keeps the heavy fold logic
  * out of `dispatchMatchedWorkflow`, which must stay under the function-length cap.
  */
 import { type Context, type HostFacts, type LockJob } from '@kici-dev/engine';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 import type { VariableStore } from '../contexts/variable-store.js';
 /**
- * Placeholder written into the persisted bound-env list for an impure dynamic
- * element the orchestrator cannot resolve at dispatch. The agent's init eval
- * later overwrites the list with the resolved name.
+ * Placeholder written into the persisted bound-env list for a dynamic element
+ * the orchestrator does not resolve at dispatch. The agent's init eval later
+ * overwrites the list with the resolved name.
  */
 export declare const DYNAMIC_ENV_PLACEHOLDER = "(dynamic)";
 /** Ordered resolved context names plus whether any element still needs agent init. */
 export interface ResolvedJobContexts {
-    /** Resolved static + pure-inline names, in order. */
+    /** Resolved static names, in order. */
     names: string[];
-    /** True when an impure dynamic element must be resolved by an agent init job. */
+    /** True when a dynamic element must be resolved by an agent init job. */
     needsInit: boolean;
 }
 /**
  * Resolve the ordered bound-context names from a lock job. Static elements
- * use their value verbatim; pure-inline dynamic elements use the matching
- * pre-evaluated inline name (aligned by index); an impure dynamic element cannot
- * be resolved here and flags `needsInit`.
+ * use their value verbatim; any dynamic element (inline or impure) is resolved
+ * by the agent's init job and flags `needsInit`.
  */
-export declare function resolveJobContextNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): ResolvedJobContexts;
+export declare function resolveJobContextNames(lockJob: LockJob): ResolvedJobContexts;
 /**
  * Build the ordered bound-context display list for persistence at dispatch.
  * Unlike {@link resolveJobContextNames}, this never drops an unresolved
- * element: a static element uses its value, a pure-inline element uses its
- * resolved name when known, and any element the orchestrator cannot resolve at
- * dispatch (impure dynamic, or an unresolved pure-inline) becomes the
- * `(dynamic)` placeholder — so the persisted column reflects every declared
- * slot in order. Returns an empty array when the job binds no context.
+ * element: a static element uses its value, and any dynamic element (which the
+ * orchestrator no longer resolves at dispatch) becomes the `(dynamic)`
+ * placeholder — so the persisted column reflects every declared slot in order.
+ * The deferred-init flow-back overwrites the placeholder once the agent
+ * resolves the name. Returns an empty array when the job binds no context.
  */
-export declare function buildJobContextDisplayNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): string[];
+export declare function buildJobContextDisplayNames(lockJob: LockJob): string[];
 /** Merged secrets/variables across an ordered list of resolved contexts. */
 export interface MultiEnvMergedData {
     contextVars?: Record<string, string>;