@kici-dev/orchestrator 0.9.1 → 0.11.0

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

@@ -16,7 +16,7 @@
  * 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 { AgentCapabilities, GlobalEvalCandidateResult, LockJobOrFactory, 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';
@@ -69,14 +69,29 @@ export interface GlobalEvalCandidate {
  * blank id still separates two workflows.
  */
 export declare function candidateKey(candidate: GlobalEvalCandidate): string;
+/**
+ * True for a `DynamicJobFn` entry the pre-run round runs: a generator with no
+ * upstream `needs`.
+ *
+ * A result-aware generator (`resultAware`, or any declared `needs`) reads its
+ * upstreams' outputs, which do not exist before the run starts. It runs on the
+ * run's deferred path instead, once those upstreams complete.
+ */
+export declare function isRoundGenerator(job: LockJobOrFactory): boolean;
+/** True for a `DynamicJobFn` entry that runs on the deferred path, never in the round. */
+export declare function isDeferredGenerator(job: LockJobOrFactory): boolean;
+/** True when the workflow carries at least one generator the round must NOT run. */
+export declare function hasDeferredGenerator(lockEntry: LockWorkflow): boolean;
 /**
  * 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.
+ * run the predicate) or carries a needs-free `DynamicJobFn` (only the agent may
+ * run the generator, and it depends on nothing the run produces). Everything
+ * else — static jobs, and result-aware generators the run evaluates later — is
+ * handed to the dispatch pipeline as declared, 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[];
@@ -119,6 +134,18 @@ export interface GlobalEvalAgentRegistry {
         arch: string;
         version?: string | null;
     }>;
+    /**
+     * Every registered agent, busy or idle. Optional so a test double can omit
+     * it; without it the up-front result-aware refusal never fires.
+     */
+    getAllEntries?(): Iterable<{
+        labels: ReadonlySet<string>;
+        platform: string;
+        arch: string;
+        version: string | null;
+        /** What the agent advertised on `agent.register`; `null` = supports nothing optional. */
+        capabilities: AgentCapabilities | null;
+    }>;
 }
 /**
  * First agent release whose job runner understands a `globalEvalRound`
@@ -162,6 +189,12 @@ export interface GlobalEvalRoundArgs {
     ref: string;
     dispatchBundle: ProviderBundle;
     dispatchCredentials: Record<string, unknown>;
+    /**
+     * The source `dispatchBundle` and `dispatchCredentials` belong to, when a
+     * cross-provider lock-file fallback made it a different source from
+     * `info.routingKey`. Absent means the inbound source.
+     */
+    dispatchRoutingKey?: string;
     /** Cluster defaults for the round budgets and the wait ceiling (`config.ts`). */
     config: {
         globalEvalRoundTimeoutMs: number;
@@ -192,6 +225,25 @@ export interface GlobalEvalRoundArgs {
  * timeout message that says nothing about agent versions.
  */
 export declare function unsupportedFleetReason(agentRegistry?: GlobalEvalAgentRegistry): string | null;
+/**
+ * Why a candidate with a result-aware generator is refused before any round.
+ *
+ * An agent without the capability runs every generator in the round, a
+ * result-aware one included; that generator sees no upstream outputs and
+ * returns the wrong jobs.
+ */
+export declare const RESULT_AWARE_UNSUPPORTED_REASON: string;
+/**
+ * Why no agent can run a round holding a result-aware generator, or `null`
+ * when one might.
+ *
+ * The same bar as {@link unsupportedFleetReason}: refused only on proof. That
+ * means init-runners ARE registered, every one reports a readable version, and
+ * none advertises the capability. An empty fleet, a busy capable agent, or an
+ * agent whose version cannot be read is not refused — the round queues on the
+ * agent-feature label, and a scaler or a registering agent can still serve it.
+ */
+export declare function resultAwareUnsupportedReason(agentRegistry?: GlobalEvalAgentRegistry): string | null;
 /**
  * Narrow one wire verdict into a value the dispatch path can trust.
  *

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

@@ -0,0 +1,41 @@
+import type { SimulatedEvent } from '@kici-dev/engine';
+import type { WebhookInfo } from '../webhook/handler.js';
+import type { ProviderBundle } from '../provider-registry.js';
+import type { TrustResolution } from '../security/trust-resolver.js';
+import type { TrustPolicyOutcome } from '../security/trust-policy-gate.js';
+import { type GlobalEvalCandidate } from './global-eval-round.js';
+import { type ProcessingDeps } from './processor.js';
+/** Inputs of one pass's held evaluation rounds. */
+export interface HoldGlobalEvalRoundsArgs {
+    info: WebhookInfo;
+    deps: ProcessingDeps;
+    event: SimulatedEvent;
+    /** The candidates that needed the round. */
+    candidates: readonly GlobalEvalCandidate[];
+    /** The source repository the event came from. */
+    repoIdentifier: string;
+    /** The event's commit SHA. */
+    ref: string;
+    resolvedOrgId: string;
+    /** Credentials the round would have run with, stored on the held row for its release. */
+    dispatchCredentials: Record<string, unknown>;
+    /** The source `dispatchCredentials` belongs to, when it is not the inbound one. */
+    dispatchRoutingKey?: string;
+    /** The inbound event's bundle and credentials: the security check lands on its repository. */
+    bundle?: ProviderBundle;
+    credentials?: Record<string, unknown>;
+    trustResolution: TrustResolution | undefined;
+    decision: Extract<TrustPolicyOutcome, {
+        action: 'hold';
+    }>;
+}
+/**
+ * Hold the evaluation round of every workflow repository among `candidates`.
+ * Returns the id of each held run, in workflow-repository order.
+ *
+ * One run per workflow repository, not per registered SHA: the release
+ * re-evaluates a whole workflow repository, so two rows for one repository would
+ * dispatch its workflows twice.
+ */
+export declare function holdGlobalEvalRounds(args: HoldGlobalEvalRoundsArgs): Promise<string[]>;
+//# sourceMappingURL=global-round-hold.d.ts.map

package/dist/pipeline/held-context-data.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Resolves a job's context data (variables, scoped secrets, container registry
+ * credentials) at dispatch, and again when a job stored as a pending dispatch
+ * context is dispatched later. A stored job keeps only what resolution needs
+ * ({@link DeferredContextResolution}), never a value, and both moments merge
+ * the result into the job config through {@link contextDataConfigFields}.
+ */
+import { z } from 'zod';
+import { type Context as EngineContext, type HostFacts, type LockJob, type TrustTier } from '@kici-dev/engine';
+import type { ContextStore } from '../contexts/context-store.js';
+import type { VariableStore } from '../contexts/variable-store.js';
+import type { JobDispatchContext } from '../contexts/protection/pipeline.js';
+import type { QueuedJobInput } from '../queue/job-queue.js';
+import type { SecretResolverApi } from '../secrets/secret-resolver.js';
+type LockContainer = NonNullable<LockJob['container']>;
+/** The context data a job config carries. */
+export interface ContextJobData {
+    contextVars?: Record<string, string>;
+    jobSecrets?: Record<string, string>;
+    jobNamespacedSecrets?: Record<string, Record<string, string>>;
+    containerRegistryAuth?: {
+        username: string;
+        password: string;
+        serveraddress: string;
+    };
+}
+/** The stores context-data resolution reads. */
+export interface ContextDataDeps {
+    contextStore?: ContextStore;
+    variableStore?: VariableStore;
+    secretResolver?: SecretResolverApi;
+}
+/** What a job's container registry credentials resolve against. */
+export interface RegistryAuthInputs {
+    container: LockContainer;
+    /** The dispatch facts the named context's protection rules evaluate. */
+    dispatchCtx: JobDispatchContext;
+    trustTier?: TrustTier;
+    /** Contexts already admitted to this job, whose rules are not re-run. */
+    admittedContextIds?: ReadonlySet<string>;
+    /**
+     * `omit`: a refusal (a context that does not admit the run, a missing
+     * secret, a malformed reference) leaves the job without registry
+     * credentials, as dispatch does. Only a store or resolver failure throws.
+     * `throw` (default): every failure throws, for a caller that catches.
+     */
+    onRefusal?: 'throw' | 'omit';
+}
+/**
+ * Stored with a job's pending dispatch context: everything resolution at its
+ * later dispatch needs, and no secret value.
+ */
+export declare const DeferredContextResolutionSchema: z.ZodObject<{
+    contexts: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    orgId: z.ZodString;
+    resolvesSecrets: z.ZodOptional<z.ZodBoolean>;
+    routingKey: z.ZodOptional<z.ZodString>;
+    hostCtx: z.ZodOptional<z.ZodObject<{
+        agentId: z.ZodString;
+        host: z.ZodString;
+        labels: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    registryAuth: z.ZodOptional<z.ZodObject<{
+        container: z.ZodCustom<LockContainer, LockContainer>;
+        dispatchCtx: z.ZodObject<{
+            branch: z.ZodString;
+            triggerType: z.ZodString;
+            repository: z.ZodString;
+            runId: z.ZodString;
+            jobId: z.ZodString;
+            internallyTriggered: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>;
+        trustTier: z.ZodOptional<z.ZodEnum<{
+            trusted: "trusted";
+            unknown: "unknown";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DeferredContextResolution = z.infer<typeof DeferredContextResolutionSchema>;
+/** Identity fields for log lines. */
+interface LogFields {
+    runId: string;
+    workflow: string;
+    job: string;
+}
+/**
+ * Resolve the merged variables and secrets of `entries`, then the container
+ * registry credentials, writing each onto `into` as soon as it resolves. A
+ * context that has no scope binding is named in a warning log line.
+ *
+ * Writing progressively keeps what already resolved when a later step throws,
+ * which is what the dispatch path's catch relies on.
+ */
+export declare function resolveContextJobData(args: {
+    deps: ContextDataDeps;
+    orgId: string;
+    entries: ReadonlyArray<{
+        name: string;
+        env: EngineContext;
+    }>;
+    hostCtx?: HostFacts;
+    routingKey?: string;
+    registryAuth?: RegistryAuthInputs;
+    log: LogFields;
+    into: ContextJobData;
+}): Promise<void>;
+/**
+ * The job-config fields a job's context data maps to.
+ *
+ * `runWideFlatSecrets` are layered over the context secrets so a run-wide value
+ * wins a key collision, and so they reach a job with no context at all.
+ */
+export declare function contextDataConfigFields(data: ContextJobData | undefined, runWideFlatSecrets: Record<string, string> | undefined): Record<string, unknown>;
+/**
+ * A job's dispatch input with its context data removed, for storing as a
+ * pending dispatch context. `runWideFlatSecrets` stay: they belong to the run,
+ * not to a context, and resolution at release layers them back on top.
+ */
+export declare function withoutContextData(jobInput: QueuedJobInput, runWideFlatSecrets: Record<string, string> | undefined): QueuedJobInput;
+/**
+ * Resolve a released job's context data and return its dispatch input with
+ * that data merged into `jobConfig`.
+ *
+ * The job's own contexts are not re-gated: it passed their rules, or its hold
+ * was released. Throws when the record is malformed, the stores are
+ * unavailable, a bound context is gone or replaced, or a lookup fails, so the
+ * caller fails the job rather than dispatching it without the secrets it was
+ * bound to. A registry-auth refusal leaves the job without registry
+ * credentials, as dispatch does.
+ */
+export declare function resolveReleasedJobInput(args: {
+    jobInput: QueuedJobInput;
+    jobName: string;
+    resolution: unknown;
+    deps: ContextDataDeps | undefined;
+}): Promise<QueuedJobInput>;
+/** Log a release-time resolution failure; the caller fails the job. */
+export declare function logReleaseResolutionFailure(jobInput: QueuedJobInput, err: unknown): string;
+export {};
+//# sourceMappingURL=held-context-data.d.ts.map

package/dist/pipeline/held-round-registrations.d.ts

@@ -0,0 +1,40 @@
+import type { RegisteredWorkflow } from '../registration/registration-index.js';
+import { type ProcessingDeps } from './processor.js';
+/** The held round's run row fields the release reads. */
+export interface HeldRoundRow {
+    customer_id: string;
+    workflow_sha: string | null;
+    workflow_branch: string | null;
+    trigger_decision: string | null;
+}
+/**
+ * The workflows the hold recorded the round as covering, or `undefined` for a
+ * row held before the record existed.
+ */
+export declare function heldRoundWorkflowsOf(triggerDecision: string | null): string[] | undefined;
+/**
+ * The workflow repository's organization-wide registrations for the held
+ * event, as they were at the held commit.
+ *
+ * Throws, naming the workflow repository and the workflows, when the release
+ * cannot run what the approver approved: the repository registers nothing any
+ * more, its lock file at the held commit cannot be read, a workflow the round
+ * covered has no live, enabled registration that still subscribes to the event,
+ * or the lock file at the held commit does not define it as an
+ * organization-wide workflow for the event. The release then fails the held run
+ * with that reason and dispatches nothing — never a partial round.
+ *
+ * Every live registration of a covered workflow is returned, one per source
+ * that registers it, as the pass the round was held from evaluates them.
+ *
+ * The covered set is the one the hold recorded. A row held before that record
+ * existed falls back to the held commit's round-shaped workflows, which cannot
+ * see a workflow whose registration vanished at an unchanged commit.
+ */
+export declare function registrationsAtHeldCommit(args: {
+    row: HeldRoundRow;
+    deps: Pick<ProcessingDeps, 'registrationIndex' | 'providerRegistry'>;
+    workflowRepo: string;
+    eventName: string;
+}): Promise<RegisteredWorkflow[]>;
+//# sourceMappingURL=held-round-registrations.d.ts.map

package/dist/pipeline/install-gate.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The workflow install gate: the protection rules of every context a
+ * workflow's `registries:` / `installEnv:` references name.
+ *
+ * Every context is evaluated before the gate decides, with the combination rule
+ * the job-level multi-context gate uses: a reject from any context rejects,
+ * whatever the others say. When none rejects and at least one holds, the gate
+ * raises ONE hold whose requirement aggregates every context's rules, most
+ * restrictive wins (`aggregateProtectionParams`): the reviewers of every held
+ * context must approve, the longest wait timer applies. That hold records which
+ * contexts held — its approval covers them — and which were admitted.
+ *
+ * The release gates again every context the approval did not cover, and
+ * refuses when any recorded context now matches a different row than the one
+ * the hold was raised against.
+ */
+import { z } from 'zod';
+import type { ProtectionGateResult } from '@kici-dev/engine';
+import type { TrustResolution } from '../security/trust-resolver.js';
+import type { Context as ContextRow } from '../db/types.js';
+import { type JobDispatchContext } from '../contexts/protection/pipeline.js';
+import { InstallSecretsDecisionReason } from '../metrics/prometheus.js';
+/** A context the install gate matched: the name the workflow used, and the row it matched. */
+export declare const InstallGateContextSchema: z.ZodObject<{
+    name: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+export type InstallGateContext = z.infer<typeof InstallGateContextSchema>;
+/**
+ * What an install-gate hold records about its contexts. Stored with the held
+ * dispatch, so the release knows which contexts the approval covers.
+ */
+export declare const InstallGateRecordSchema: z.ZodObject<{
+    held: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    admitted: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type InstallGateRecord = z.infer<typeof InstallGateRecordSchema>;
+/** The reject reasons the install gate reports, as its decision metric labels them. */
+export type InstallGateRejectReason = typeof InstallSecretsDecisionReason.EnvNotFound | typeof InstallSecretsDecisionReason.ProtectionRuleBlock;
+/** A gate verdict that holds the install. */
+export type InstallGateHoldResult = ProtectionGateResult & {
+    action: 'hold' | 'wait' | 'queue';
+};
+export type InstallGateOutcome = {
+    kind: 'pass';
+} | {
+    kind: 'reject';
+    reasonKind: InstallGateRejectReason;
+    reason: string;
+} | {
+    kind: 'hold';
+    /** The first held context in declaration order; it names the hold. */
+    primary: InstallGateContext;
+    result: InstallGateHoldResult;
+    record: InstallGateRecord;
+};
+interface GateInputs {
+    /** Every referenced context name, in declaration order, with the row it matched. */
+    matched: ReadonlyMap<string, ContextRow | null>;
+    trustResolution: TrustResolution | undefined;
+    protectionContext: JobDispatchContext;
+}
+/**
+ * Evaluate every referenced context's rules and decide the install gate.
+ *
+ * Reject wins over hold, as on the job-level gate. A hold aggregates the rules
+ * of every context, so its requirement is at least as strict as each held
+ * context's own, and its record lists which contexts held and which passed.
+ */
+export declare function gateInstall(inputs: GateInputs): Promise<InstallGateOutcome>;
+/**
+ * Decide the install gate for a dispatch resumed from a released hold.
+ *
+ * The contexts the hold recorded as held are covered by its approval and are
+ * not gated again: their reviewer and wait-timer rules are stateless and would
+ * hold the approved run once more. Every other context is gated again, and any
+ * verdict but pass rejects — a release never raises a second hold. A context
+ * the hold recorded must still match the row it matched then.
+ *
+ * `releasedHold` comes from stored JSON, so it is parsed here: an absent or
+ * malformed record covers no context, and every context is gated again.
+ */
+export declare function gateReleasedInstall(inputs: GateInputs & {
+    releasedHold: unknown;
+}): Promise<InstallGateOutcome>;
+export {};
+//# sourceMappingURL=install-gate.d.ts.map

package/dist/pipeline/install-secrets-resolver.d.ts

@@ -7,16 +7,20 @@
  * `<context>:<secret-name>` syntax. The resolver:
  *
  *   1. Parses every qualified ref and groups by context name.
- *   2. Fires the per-context protection-rule pipeline once per unique env
- *      (branch / trust / concurrency / reviewer / wait-timer). A `reject`
- *      result fails the whole workflow dispatch with a clear reason; a
- *      `hold` / `wait` / `queue` result returns a structured `hold` decision
- *      so the caller can pause the workflow dispatch as a workflow-scoped held
- *      run and resume it when the gate clears. On the resume path the caller
- *      sets `skipProtectionGate` so the gate (already satisfied) is bypassed
- *      and secrets are resolved directly.
- *   3. Resolves secrets per context via `secretResolver.resolveForJob`
- *      (which writes its own audit log lines).
+ *   2. Runs the install gate (`install-gate.ts`): every referenced context's
+ *      protection rules (branch / trust / concurrency / reviewer / wait-timer)
+ *      are evaluated before it decides. Any `reject` fails the whole workflow
+ *      dispatch with a clear reason; otherwise any hold returns ONE structured
+ *      `hold` decision, aggregated across the contexts, so the caller can
+ *      pause the workflow dispatch as a workflow-scoped held run and resume it
+ *      when the gate clears. The hold records which contexts held and which
+ *      passed. On the resume path the caller sets `skipProtectionGate` and
+ *      hands back that record: the contexts that held are covered by the
+ *      approval, every other context is gated again, and a context that now
+ *      matches a different row is refused.
+ *   3. Resolves secrets per context via `secretResolver.resolveForContext`
+ *      against the row step 2 gated (which writes its own audit log lines),
+ *      so a context whose name is a glob pattern delivers its own bindings.
  *   4. Validates each registry URL scheme: HTTPS always allowed; `http://`
  *      allowed only for loopback / `*.local` hosts OR when the org operator
  *      has flipped `org_settings.allow_http_npm_registries=true`.
@@ -33,7 +37,8 @@ import type { ApproverClause, LockRegistry } from '@kici-dev/engine';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 import type { ContextStore } from '../contexts/context-store.js';
-import { type JobDispatchContext } from '../contexts/protection/pipeline.js';
+import type { JobDispatchContext } from '../contexts/protection/pipeline.js';
+import { type InstallGateRecord } from './install-gate.js';
 /** Registry spec carried on the dispatch message (token already resolved). */
 export interface NpmRegistrySpec {
     url: string;
@@ -51,10 +56,18 @@ export interface ResolveInstallSecretsArgs {
     secretResolver: SecretResolverApi | undefined;
     protectionContext: JobDispatchContext;
     /**
-     * Resume path: skip the protection-rule gate (already satisfied) and resolve
-     * secrets directly. The untrusted-contributor strip still runs first.
+     * Resume path: the dispatch continues past a released install-gate hold. The
+     * gate runs only for the contexts `releasedHold` does not cover. The
+     * untrusted-contributor strip still runs first.
      */
     skipProtectionGate?: boolean;
+    /**
+     * Resume path: what the released hold recorded (`hold` decision's
+     * `record`). Its held contexts are covered by the approval; every recorded
+     * context must still match the same row. Read as stored JSON: absent or
+     * malformed, it covers no context.
+     */
+    releasedHold?: InstallGateRecord;
 }
 /** Normalized requirement carried on a `hold` decision. */
 export interface InstallHoldRequirement {
@@ -83,6 +96,8 @@ export type ResolveInstallSecretsResult = {
     holdType: string;
     queueType: 'context' | 'security';
     requirement: InstallHoldRequirement;
+    /** Which contexts held (the approval covers them) and which passed. */
+    record: InstallGateRecord;
 };
 /** Parse `<context>:<secret-name>`. Returns null on malformed input. */
 export declare function parseQualifiedSecretRef(ref: string): {

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

@@ -1,13 +1,14 @@
 /**
  * Multi-context resolution helpers for the dispatch path.
  *
- * A job binds an ordered list of contexts (`LockJob.contexts`). This
+ * A job binds an ordered list of contexts: the workflow-level names
+ * (`LockWorkflow.contexts`) first, then its own (`LockJob.contexts`). This
  * module resolves that list into concrete context names (static values
  * 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 Context, type HostFacts, type LockJob, type LockWorkflow } from '@kici-dev/engine';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 import type { VariableStore } from '../contexts/variable-store.js';
 /**
@@ -23,12 +24,25 @@ export interface ResolvedJobContexts {
     /** True when a dynamic element must be resolved by an agent init job. */
     needsInit: boolean;
 }
+/** One bound-context element, as a lock job carries it. */
+export type ContextRef = NonNullable<LockJob['contexts']>[number];
 /**
- * Resolve the ordered bound-context names from a lock job. Static elements
+ * The ordered context elements a job binds: the workflow-level names first,
+ * then the job's own. Placing the workflow names first means a job-level
+ * context wins a key collision, since later contexts override earlier ones.
+ *
+ * A workflow-level name the job also binds statically is dropped from the
+ * workflow part, so each context is gated and resolved once, at the job's own
+ * position. Every gating site reads its names through this function, so a
+ * workflow-level context passes the same gates a job-level one does.
+ */
+export declare function effectiveContextRefs(workflow: Pick<LockWorkflow, 'contexts'>, job: Pick<LockJob, 'contexts'>): ContextRef[];
+/**
+ * Resolve the ordered bound-context names from a lock job and its workflow. Static elements
  * use their value verbatim; a dynamic element is resolved by the agent's init
  * job and flags `needsInit`.
  */
-export declare function resolveJobContextNames(lockJob: LockJob): ResolvedJobContexts;
+export declare function resolveJobContextNames(workflow: Pick<LockWorkflow, 'contexts'>, lockJob: Pick<LockJob, 'contexts'>): ResolvedJobContexts;
 /**
  * Build the ordered bound-context display list for persistence at dispatch.
  * Unlike {@link resolveJobContextNames}, this never drops an unresolved
@@ -38,7 +52,7 @@ export declare function resolveJobContextNames(lockJob: LockJob): ResolvedJobCon
  * 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): string[];
+export declare function buildJobContextDisplayNames(workflow: Pick<LockWorkflow, 'contexts'>, lockJob: Pick<LockJob, 'contexts'>): string[];
 /** Merged secrets/variables across an ordered list of resolved contexts. */
 export interface MultiEnvMergedData {
     contextVars?: Record<string, string>;
@@ -52,7 +66,8 @@ export interface MultiEnvMergedData {
  * then folded in array order so a later context overrides an earlier key.
  * Secrets are also returned namespaced per context so qualified
  * `<env>:<secret>` references still resolve. `entries` carries the matched
- * `Context` for each name (in order); variables resolve by context id.
+ * `Context` for each name (in order); variables and secrets both resolve by the
+ * matched context's id, so a glob context contributes what its own row holds.
  */
 export declare function resolveMultiEnvMergedData(args: {
     deps: {

package/dist/pipeline/pending-workflow-context.d.ts

@@ -15,19 +15,31 @@
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { WorkflowDispatchContext } from './dispatch-matched-workflow.js';
+import { type SerializableGlobalDispatchIdentity } from './global-dispatch-identity.js';
 /**
  * The serializable subset of a `WorkflowDispatchContext` — everything except
  * the live `deps` and `bundle`, which are rebuilt on resume. Every field here
  * is JSON-safe (the event, payload, and lock file already ride the WS protocol
- * as JSON).
+ * as JSON). A global run's identity is stored without its workflow bundle and
+ * credentials, which the resume re-derives.
  */
-export type SerializableWorkflowDispatchInputs = Omit<WorkflowDispatchContext, 'deps' | 'bundle'>;
+export type SerializableWorkflowDispatchInputs = Omit<WorkflowDispatchContext, 'deps' | 'bundle' | 'global'> & {
+    global?: SerializableGlobalDispatchIdentity;
+};
+/** Stored inputs as a read returns them. */
+export type LoadedWorkflowDispatchInputs = SerializableWorkflowDispatchInputs & {
+    /**
+     * Set when the row's sealed secret fields could not be decrypted; the
+     * inputs then carry none of them, and the resume abandons the run.
+     */
+    secretsUnavailable?: string;
+};
 /** Extract the serializable inputs from a live dispatch context. */
 export declare function toSerializableInputs(ctx: WorkflowDispatchContext): SerializableWorkflowDispatchInputs;
 /** Persist the pending workflow context to the in-memory Map and the DB. */
 export declare function storePendingWorkflowContext(db: Kysely<Database> | undefined, inputs: SerializableWorkflowDispatchInputs): Promise<void>;
 /** Load the pending workflow context by run id (memory first, then DB). */
-export declare function loadPendingWorkflowContext(db: Kysely<Database> | undefined, runId: string): Promise<SerializableWorkflowDispatchInputs | null>;
+export declare function loadPendingWorkflowContext(db: Kysely<Database> | undefined, runId: string): Promise<LoadedWorkflowDispatchInputs | null>;
 /** Delete the pending workflow context from the in-memory Map and the DB. */
 export declare function deletePendingWorkflowContext(db: Kysely<Database> | undefined, runId: string): Promise<void>;
 /**

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

@@ -21,6 +21,7 @@ import type { LockFile as FullLockFile, SimulatedEvent } from '@kici-dev/engine'
 import type { OrchestratorMode } from '@kici-dev/engine';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
+import type { RegisteredWorkflow } from '../registration/registration-index.js';
 import { type TrustResolution } from '../security/trust-resolver.js';
 import { type ForkSwitchContext, type TrustPolicyOutcome } from '../security/trust-policy-gate.js';
 import { type WorkflowModification } from '../security/workflow-diff.js';
@@ -200,9 +201,16 @@ export declare function dispatchGlobalWorkflowsForOtherRepos(args: {
     ref: string;
     dispatchBundle: ProviderBundle;
     dispatchCredentials: Record<string, unknown>;
-    /** The inbound event's own bundle, used to post the globals-skipped check. */
+    /** The inbound event's own bundle + credentials, used to post the failed-round check. */
     bundle: ProviderBundle;
     credentials: Record<string, unknown>;
+    /** The event's trust resolution, recorded on each global run. */
+    trustResolution: TrustResolution | undefined;
+    /**
+     * The event's trust-policy verdict. It applies to each global run exactly as
+     * it applies to the per-repository ones: a `hold` parks the run in the
+     * security queue next to the pull request's own runs.
+     */
     securityDecision: TrustPolicyOutcome;
     /**
      * The source `dispatchCredentials` belongs to, when a cross-provider lock-file
@@ -216,6 +224,35 @@ export declare function dispatchGlobalWorkflowsForOtherRepos(args: {
      * the re-run of a failed evaluation round, which re-decides that round alone.
      */
     onlyWorkflowRepo?: string;
+    /**
+     * Dispatch only the candidates that need the evaluation round. Set by the
+     * re-evaluation of a failed or held round: the workflow repository's other
+     * candidates reached their outcome on the original delivery.
+     */
+    onlyRoundCandidates?: boolean;
+    /**
+     * Set with `onlyRoundCandidates` when the round being re-evaluated is a held
+     * round whose security hold was just approved. That hold also held every
+     * result-aware-only candidate of the repository, so the release dispatches
+     * them. A failed round's re-run leaves it unset: the delivery already
+     * dispatched those candidates.
+     */
+    releasedHold?: boolean;
+    /**
+     * Asked once the round has decided, before anything it admitted dispatches.
+     * Resolving false withdraws those verdicts: nothing the round admitted
+     * dispatches, and its workflow repositories are not reported as decided. Set
+     * by the release of a held round, whose run may have been cancelled while
+     * the round ran.
+     */
+    admitRoundVerdicts?: () => Promise<boolean>;
+    /**
+     * The global registrations to evaluate, in place of the ones the index holds
+     * for this event. Set by the release of a held round, which evaluates the
+     * workflow repository as it was at the commit the hold recorded: the round,
+     * its partition, and the dispatch after it all read these entries.
+     */
+    registrations?: readonly RegisteredWorkflow[];
 }): Promise<GlobalDispatchOutcome>;
 /**
  * Process a webhook through the complete pipeline, recording a `failed` event-log