@kici-dev/orchestrator 0.4.0 → 0.6.0

package/dist/approvals/apply-decision.d.ts

@@ -1,22 +1,15 @@
-/**
- * Shared approve/reject applier — the single code path behind both the
- * dashboard WS handler and the `kici` CLI HTTP route, so the authorization +
- * resume story is identical regardless of the surface.
- *
- * Flow for an approve:
- *   1. Load the hold + its recorded decisions.
- *   2. Build the team-membership lookup and run `canApprove` (eligibility +
- *      self-approval gate). Ineligible actors are rejected with a clear reason.
- *   3. Record the decision in `held_run_approvals`.
- *   4. Re-evaluate. If all clauses are satisfied, `release()` the hold and
- *      resume the element (re-dispatch for job/workflow; the agent bridge for
- *      step scope — wired by the caller via `onStepRelease`).
- *
- * A reject records the decision and `reject()`s the hold (failing the element).
- */
 import { ApprovalDecision } from '@kici-dev/engine';
+import type { HeldRun } from '../db/types.js';
+import { HoldOutcome } from '../pipeline/security-hold-check.js';
 import type { HeldRunStore, ReleaseSignal } from '../contexts/held-runs.js';
 import { type TeamMembershipLookup } from './approval-resolver.js';
+/** Whether a decision's post-commit consequence ran to completion. */
+export interface DecisionConsequenceResult {
+    /** True when the whole consequence chain ran; false when a step of it threw. */
+    ok: boolean;
+    /** The failure message, when `ok` is false. */
+    error?: string;
+}
 /** Outcome of applying a decision. */
 export interface ApplyDecisionResult {
     /** Whether the decision was accepted (recorded). */
@@ -29,6 +22,29 @@ export interface ApplyDecisionResult {
     reason?: string;
     /** The release signal, when the element was released (for the caller to resume). */
     release?: ReleaseSignal;
+    /**
+     * The decision's post-commit consequence — already running, deliberately not
+     * awaited by the applier. Present on `released` and `rejected`, absent on
+     * every outcome that changed nothing (`pending`, `ineligible`, `not-found`).
+     *
+     * It NEVER rejects: a throw anywhere in the chain is logged and surfaces as
+     * `{ ok: false, error }`, so a caller may drop it on the floor without
+     * risking an unhandled rejection. A caller that answers a waiting client
+     * answers without awaiting this, and attaches its audit record to it instead
+     * — the record then carries the consequence's real outcome rather than a
+     * guess. A caller that needs the consequence finished before it continues
+     * (a test, a sequential sweep) awaits it.
+     *
+     * The consequence is where an approve was spending nine-plus seconds behind a
+     * ten-second relay budget, answering 504 on an approval that had already
+     * landed. It is not a stronger answer for having been awaited: the resume it
+     * runs is the same dispatch the original webhook delivery ran without any
+     * client waiting on it, `dispatchMatchedWorkflow` returning says only that
+     * jobs were routed rather than that any of them ran, and `resumeWorkflow`
+     * already reports its own failures on the run row and on the provider's check
+     * runs rather than through this return value.
+     */
+    consequence?: Promise<DecisionConsequenceResult>;
 }
 /** Dependencies injected into `applyDecision` (testable in isolation). */
 export interface ApplyDecisionDeps {
@@ -55,10 +71,42 @@ export interface ApplyDecisionDeps {
      */
     onStepReject?: (heldRunId: string, reason?: string) => Promise<void> | void;
     /**
-     * Called when a workflow-scoped hold is rejected (install gate rejected) —
-     * cancel the run and drop the pending workflow context. Carries the runId.
+     * Called when a workflow-scoped hold is rejected — cancel the run and drop
+     * the pending workflow context. Carries the whole hold row and the rejecter's
+     * own reason, which becomes the run's cancellation reason: the callers serve
+     * the install gate, the org trust policy's PR-wide hold and the SDK's
+     * workflow-level `requireApproval` alike, so a reason invented at the wiring
+     * site would misattribute one of them.
+     *
+     * The row is what tells those apart — only some of them posted a pending
+     * `KiCI Security` check, and only those have one to complete. Resolves to
+     * whether a terminal security check was WRITTEN, so this applier suppresses
+     * its own post only when one actually landed.
+     */
+    onWorkflowReject?: (hold: HeldRun, reason?: string) => Promise<boolean>;
+    /**
+     * Terminalize the `KiCI Security` check a just-ended hold posted, for every
+     * hold this applier ends that `onWorkflowReject` did not already report.
+     *
+     * Without it a job-scoped security hold answered from the dashboard strands
+     * its check forever: the row leaves `pending`, so the stale detector's
+     * approval-window sweep — which only ever sees pending rows — can no longer
+     * reach it. Optional so an orchestrator with no provider wiring degrades to
+     * flip-and-resume rather than failing the decision.
+     *
+     * `actorSub` is the deciding actor's opaque subject id, which is what this
+     * applier has and NOT something a contributor can read. Resolving it to a
+     * display name — or dropping the attribution when it resolves to none — is
+     * the wiring site's job, because only that site holds the org's identity
+     * directory. Omitted entirely where the summary must match one a delegate
+     * built without it; see the reject arm below.
      */
-    onWorkflowReject?: (runId: string) => Promise<void>;
+    settleSecurityCheck?: (args: {
+        hold: HeldRun;
+        outcome: HoldOutcome;
+        actorSub?: string | undefined;
+        reason?: string | undefined;
+    }) => Promise<boolean>;
 }
 /** Apply a single approve/reject decision to a hold. */
 export declare function applyDecision(deps: ApplyDecisionDeps, args: {

package/dist/approvals/held-run-release-wiring.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The release wiring the local (`kici-admin`) held-run decision surface runs on.
+ *
+ * `createApp` composes this for every mode. It lives here rather than inline in
+ * that composition root because the defect it guards against is a MISSING
+ * field, not a wrong algorithm: a release path that flips the `held_runs` row
+ * without dispatching looks like it works and does nothing. A factory can be
+ * constructed by a test and its fields asserted; an object literal buried in
+ * `createApp` cannot.
+ *
+ * It returns `undefined` when there is no job-release callback, so an app
+ * assembled without one mounts no decision route at all rather than one whose
+ * approves are silent no-ops.
+ *
+ * Every callback reads the LIVE processing-deps bag at call time rather than
+ * capturing one: the provider registry is swapped whenever sources reload, and
+ * a captured bag would resolve a check poster from a registry that no longer
+ * serves the routing key.
+ */
+import type { ReleaseSignal } from '../contexts/held-runs.js';
+import type { ProcessingDeps } from '../pipeline/processor.js';
+import type { HeldRunReleaseWiring } from '../routes/admin-held-runs.js';
+/** The subset of `createApp`'s deps this factory reads. */
+export interface HeldRunReleaseInputs {
+    /**
+     * Re-dispatch a released job-scoped hold. Supplied by both mode hooks through
+     * `appDepsExtras`; its absence is what makes the whole surface absent.
+     */
+    onJobRelease?: ((signal: ReleaseSignal) => Promise<void>) | undefined;
+    /** Replay the stored dispatch context of a released workflow-scoped hold. */
+    onWorkflowRelease?: ((signal: ReleaseSignal) => Promise<void>) | undefined;
+    /** The live processing-deps bag, assembled per call. */
+    buildProcessingDeps: () => ProcessingDeps;
+}
+/**
+ * The reason a workflow-scoped hold rejected through this surface records on the
+ * run it cancels, when the operator supplied none.
+ *
+ * Scope-neutral on purpose: the install gate, the org trust policy's PR-wide
+ * hold and an SDK workflow-level `requireApproval` all arrive here, so a
+ * reason naming one of them would mislabel the other two.
+ */
+export declare const DEFAULT_LOCAL_REJECT_REASON = "Workflow hold rejected by the orchestrator operator";
+export declare function buildHeldRunRelease(inputs: HeldRunReleaseInputs): HeldRunReleaseWiring | undefined;
+//# sourceMappingURL=held-run-release-wiring.d.ts.map

package/dist/approvals/independent-wiring.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The approval subsystem an INDEPENDENT orchestrator runs on.
+ *
+ * `server.ts` composes this inline for the three Platform-attached modes. An
+ * independent orchestrator has no Platform and therefore none of that hook, so
+ * every gate that raises a hold was inert there: a fork PR the org policy said
+ * to HOLD was dropped instead of held, an SDK `requireApproval` job ran
+ * UNGATED (the dispatch site logged an error and dispatched anyway), and the
+ * stale detector had no store through which to expire an overdue hold,
+ * terminalize its `KiCI Security` check, or drop the pending dispatch context
+ * it would have replayed.
+ *
+ * It lives here rather than inside `standalone.ts` because that module is an
+ * entry point: it runs `guardStartup` at import time, so nothing can construct
+ * its wiring in a test. A factory can be constructed, and the fields it
+ * produces can be asserted — which is the whole point, since every defect this
+ * closes was a missing field rather than a wrong algorithm.
+ *
+ * What it deliberately does NOT produce is a `stepApprovalBridge`. A
+ * step-scoped hold is opened by the agent WS `onStepApproval` seam and answered
+ * by the dashboard applier, which is Platform-relayed and has no
+ * independent-mode equivalent — so wiring the bridge would let an agent open a
+ * hold nothing could resolve short of expiry.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import { HeldRunStore, type ReleaseSignal } from '../contexts/held-runs.js';
+import { type ProcessingDeps, type ReadyDispatchContextRow } from '../pipeline/processor.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+import type { RunCoordinator } from '../cluster/coordinator.js';
+import type { InvokeGateDeps } from '../pipeline/invoke-gate.js';
+/** The subsystem fields the composition reads. A subset of `OrchestratorSubsystems`. */
+export interface IndependentApprovalSubsystems {
+    db: Kysely<Database>;
+    dispatcher: Dispatcher;
+    executionTracker?: ExecutionTracker | undefined;
+    coordinator?: RunCoordinator | undefined;
+    invokeGateDeps?: InvokeGateDeps | undefined;
+    /**
+     * The live direct-ingress deps bag. Read lazily inside the release callbacks:
+     * it is populated by `createApp`, which runs after the mode hook, and reading
+     * it at wiring time throws.
+     */
+    buildProcessingDeps: () => ProcessingDeps;
+}
+/** What the independent mode hook merges into `appDepsExtras`. */
+export interface IndependentApprovalExtras {
+    heldRunStore: HeldRunStore;
+    onWorkflowRelease: (signal: ReleaseSignal) => Promise<void>;
+    onJobRelease: (signal: ReleaseSignal) => Promise<void>;
+    matchContext: (orgId: string, name: string) => Promise<ReadyDispatchContextRow | null>;
+}
+export declare function createIndependentApprovalExtras(sub: IndependentApprovalSubsystems): IndependentApprovalExtras;
+//# sourceMappingURL=independent-wiring.d.ts.map

package/dist/approvals/resume-router.d.ts

@@ -0,0 +1,9 @@
+import type { ReleaseSignal } from '../contexts/held-runs.js';
+/** The three resume paths a released hold can take. */
+export interface ResumeHandlers {
+    onStepRelease?: (signal: ReleaseSignal) => Promise<void>;
+    onWorkflowRelease?: (signal: ReleaseSignal) => Promise<void>;
+    onJobRelease: (signal: ReleaseSignal) => Promise<void>;
+}
+export declare function routeRelease(signal: ReleaseSignal, handlers: ResumeHandlers): Promise<void>;
+//# sourceMappingURL=resume-router.d.ts.map

package/dist/approvals/triggerer-subject.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The `service:` namespace both approving surfaces use for a non-human
+ * principal: `kici-admin`'s token identity (its only subject), and the
+ * dashboard's rendering of a `service_account` actor.
+ */
+export declare const SERVICE_SUBJECT_PREFIX = "service:";
+/** Render an admin-token user id in the shared `service:` namespace. */
+export declare function adminActorSub(tokenUserId: string): string;
+/**
+ * Resolve the subject of whoever triggered a run, in the approver vocabulary.
+ *
+ * | `triggered_by` | Returns | Why |
+ * |---|---|---|
+ * | `user:<sub>` | `<sub>` | what a `{user}` clause and both surfaces' own subject use |
+ * | `platform_operator:<sub>` | `<sub>` | same Keycloak subject as a `user` |
+ * | `service_account:<id>` | `service:<id>` | the namespace {@link adminActorSub} and the dashboard both produce |
+ * | `system:<component>` | `system:<component>` | the dashboard renders a system actor with its prefix intact |
+ * | `api_key:<keyId>` | `<keyId>` | see the residual below |
+ * | anything else | unchanged | no other actor type reaches these surfaces |
+ *
+ * The agent suffix is stripped first. `stringifyActor` renders a `user` or
+ * `api_key` who acted through an agent as `user:<sub> via agent:<label>`, and a
+ * reader splitting on the first colon gets `<sub> via agent:<label>` — which
+ * matches no live subject, so the gate was inert for every agent-mediated
+ * trigger. That is the `user` case, i.e. the common one.
+ *
+ * **Residual: `api_key`.** A key's persisted identifier is its `keyId`, while
+ * both surfaces render a live `api_key` actor as its owner's Keycloak subject
+ * (`ownerSub`). Those are different identifiers for the same principal and no
+ * string transform bridges them — closing it needs a keyId → ownerSub lookup,
+ * which is a store this pure function does not have. So an owner approving a
+ * hold on a run their own key triggered is still admitted. Recorded rather than
+ * papered over: returning the bare keyId is at least honest about what was
+ * stored.
+ */
+export declare function triggererSubjectFor(triggeredBy: string | null | undefined): string | undefined;
+//# sourceMappingURL=triggerer-subject.d.ts.map

package/dist/cache/dep-cache.d.ts

@@ -1,14 +1,40 @@
 /**
  * Dependency-specific cache layer wrapping CacheStorage.
  *
- * Stores and retrieves dependency tarballs keyed by lockfileHash + platform + arch.
- * Shared CacheStorage backend with SourceCache (same S3 bucket).
- * Refreshes TTL on reads (touch-on-read).
+ * Stores dependency tarballs under their own content hash, with a small pointer
+ * resolving lockfileHash + platform + arch to that hash. Shared CacheStorage
+ * backend with SourceCache (same S3 bucket). Refreshes TTL on reads
+ * (touch-on-read).
  *
- * Cache key format: deps/{platform}-{arch}/{lockfileHash}.tar.gz
+ * Keys: `deps/{platform}-{arch}/{depsHash}.tar.gz` (immutable) and
+ * `deps/{platform}-{arch}/{lockfileHash}.hash` (the pointer).
  */
 import type { CacheStorage } from '../storage/types.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
+/**
+ * Cache key for a dependency tarball, addressed by the tarball's OWN content
+ * hash: `deps/{platform}-{arch}/{depsHash}.tar.gz`.
+ *
+ * Content-addressing is what makes a mismatched pair unrepresentable. When the
+ * tarball lived at a lockfile-derived name, it and its companion `.hash` were
+ * two independently-written objects under keys that any two builds sharing a
+ * lockfile + platform + arch also share — so concurrent builders could leave the
+ * `.tar.gz` from one and the `.hash` from the other, and the reader failed
+ * verification durably. Naming the object by its own hash means every pair a
+ * reader can observe is self-consistent, and the bytes at a given key can never
+ * change after a URL is signed for it.
+ */
+export declare function depTarballKey(depsHash: string, platform: string, arch: string): string;
+/**
+ * Cache key for the pointer that resolves a lockfile to the content hash of the
+ * tarball built from it: `deps/{platform}-{arch}/{lockfileHash}.hash`.
+ *
+ * This is the one mutable object in the scheme. A concurrent write replaces a
+ * pointer wholesale — there is no window in which it is half-written — so the
+ * worst a racing pair of builders can do is leave whichever pointer landed last,
+ * and both tarballs remain valid and fetchable.
+ */
+export declare function depPointerKey(lockfileHash: string, platform: string, arch: string): string;
 export declare class DepCache {
     private readonly storage;
     private readonly maxTarballBytes;
@@ -30,7 +56,17 @@ export declare class DepCache {
      * `cache_ttl_days` change takes effect on the next lookup.
      */
     private resolveTtlMsOverride;
-    /** Check if a dep tarball exists in cache. */
+    /**
+     * Resolve a lockfile to the content hash of the tarball built from it, or
+     * null when no pointer exists. The single place the indirection is read.
+     */
+    private resolvePointer;
+    /**
+     * Check if a dep tarball exists in cache.
+     *
+     * Both halves must be present: a pointer whose tarball has aged out is a miss,
+     * not a hit, or the caller skips a rebuild and dispatches a URL that 404s.
+     */
     has(lockfileHash: string, platform: string, arch: string): Promise<boolean>;
     /**
      * Get a pre-signed download URL for the dep tarball (for agent delivery).
@@ -38,9 +74,10 @@ export declare class DepCache {
      */
     getUrl(lockfileHash: string, platform: string, arch: string): Promise<string | null>;
     /**
-     * Get a pre-signed download URL and the tarball content hash (if available).
-     * Returns null on cache miss. Hash may be undefined for old entries stored
-     * before integrity tracking was added.
+     * Get a pre-signed download URL and the tarball content hash.
+     *
+     * Returns null on cache miss — including an entry with no pointer, which is
+     * unverifiable and so is deliberately not served.
      */
     getUrlAndHash(lockfileHash: string, platform: string, arch: string): Promise<{
         url: string;
@@ -49,7 +86,14 @@ export declare class DepCache {
     /**
      * Get a pre-signed upload URL for direct agent-to-S3 upload.
      */
-    getUploadUrl(lockfileHash: string, platform: string, arch: string): Promise<string>;
+    getUploadUrl(depsHash: string, platform: string, arch: string): Promise<string>;
+    /**
+     * Publish the pointer that makes an uploaded tarball discoverable by lockfile.
+     *
+     * Called only after the agent confirms its upload completed. Publishing before
+     * the bytes land would let a reader follow the pointer to a missing object.
+     */
+    publishPointer(lockfileHash: string, platform: string, arch: string, depsHash: string): Promise<void>;
     /**
      * Store a dep tarball in cache.
      * Throws if tarball exceeds max size (per user decision).
@@ -60,7 +104,7 @@ export declare class DepCache {
      * Used by build agents to compute the hash for depsHash protocol field.
      */
     static computeHash(data: Buffer): string;
-    /** Remove a dep tarball from cache. */
+    /** Remove a dep tarball and its pointer from cache. */
     remove(lockfileHash: string, platform: string, arch: string): Promise<boolean>;
 }
 //# sourceMappingURL=dep-cache.d.ts.map

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

@@ -0,0 +1,95 @@
+/**
+ * LRU for completed Tier-2 global eval round results.
+ *
+ * **This cache only helps webhook redelivery and same-input re-deliveries.** Its
+ * key pins the source commit and a digest of the whole round input, and every
+ * real push carries a new source SHA — so a developer pushing twice gets two
+ * rounds, by design. Read it as a duplicate-delivery guard, never as a
+ * steady-state optimization: sizing it up buys nothing, and a hit rate near zero
+ * on a healthy cluster is the expected shape, not a defect.
+ *
+ * There is deliberately no TTL. A round verdict is a pure function of its
+ * inputs, and {@link globalEvalRoundCacheKey} covers all of them, so an entry
+ * cannot go stale within its own key — the same content-addressable argument the
+ * lock-file and content caches make for their SHA-keyed entries, without their
+ * branch-name escape hatch.
+ */
+import type { GlobalEvalRoundResult } from '@kici-dev/engine';
+/**
+ * Key one round over **every input its verdict depends on**.
+ *
+ * The three SHAs are not enough, and the gap is a wrong-answer bug rather than a
+ * missed-hit one. `createFilterContext` and `buildGeneratorContext` both receive
+ * the whole event, so a filter can branch on `event.type`, `targetBranch`,
+ * `changedFiles`, or anything in the raw payload. A push to `main` at commit X
+ * and a pull-request synchronize whose head is commit X share all three SHAs and
+ * genuinely deserve different verdicts: their events differ, and their
+ * changed-file sets are computed over different ranges. Two branches pointing at
+ * one commit collide the same way. `workflowRoutingKey` is in the key for the
+ * reason `groupCandidates` keeps it in the group key — it selects the provider
+ * bundle that mints the clone credentials.
+ *
+ * `sourceRepoIdentifier` is its own component, placed next to `sourceSha` so the
+ * source repo and its commit stay adjacent. Every event already carries its
+ * source repo, so the event digest covers it too — but keying it explicitly
+ * makes that coverage structural rather than incidental: an event shape that
+ * stopped carrying the source repo could otherwise collide two repos' rounds.
+ *
+ * The candidate list and the event are folded in as a SHA-256 digest of their
+ * JSON, so the key stays a bounded string no matter how large a payload is. Both
+ * are rebuilt by the same code from the same delivery, so a genuine redelivery
+ * reproduces the digest; anything else is a miss, which costs a round rather
+ * than a wrong verdict.
+ *
+ * Returns `null` when the inputs cannot be serialized. A round that cannot be
+ * keyed is simply not cached — never keyed on a partial input, which is how a
+ * cache starts answering questions it was not asked.
+ */
+export declare function globalEvalRoundCacheKey(args: {
+    workflowRepoIdentifier: string;
+    workflowSha: string;
+    workflowRoutingKey: string;
+    sourceRepoIdentifier: string;
+    sourceSha: string;
+    /** The exact per-candidate payload the round job carries. */
+    candidates: unknown;
+    /** The exact event the round job carries. */
+    event: unknown;
+}): string | null;
+/**
+ * A round that left ANY candidate undecided is not a result worth replaying.
+ *
+ * An agent-side budget breach reports `success` with the affected candidates
+ * marked indeterminate — the whole round on a round-budget breach, one workflow
+ * on a candidate-budget breach. Caching either turns one slow round into a
+ * permanently replayed failure for the whole key: a webhook redelivery, which
+ * is exactly when an operator is retrying, would be served the stored failure
+ * instead of running again, and the round's own retry sits behind this cache
+ * read so a stored breach short-circuits that too.
+ *
+ * Requiring EVERY candidate to be decided costs almost no hit rate — an
+ * indeterminate verdict is the exceptional path — and buys a guarantee that is
+ * easy to state: nothing a redelivery replays was ever undecided.
+ *
+ * An empty candidate list is not cacheable either. For a non-empty group it
+ * means every candidate is about to be recorded as "no verdict", which is the
+ * same failure by another route.
+ */
+export declare function isCacheableRoundResult(result: GlobalEvalRoundResult): boolean;
+export declare class GlobalEvalRoundCache {
+    private readonly cache;
+    private hits;
+    private misses;
+    constructor(options: {
+        max: number;
+    });
+    get(key: string): GlobalEvalRoundResult | undefined;
+    set(key: string, value: GlobalEvalRoundResult): void;
+    /** Hit/miss counters for metrics and debugging. */
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+    };
+}
+//# sourceMappingURL=global-eval-round-cache.d.ts.map

package/dist/cache/index.d.ts

@@ -15,4 +15,7 @@ export { PendingBuildTracker } from './pending-builds.js';
 export { PendingInitTracker } from './pending-inits.js';
 export type { InitResult } from './pending-inits.js';
 export { PendingDynamicTracker } from './pending-dynamics.js';
+export { PendingGlobalEvalTracker } from './pending-global-evals.js';
+export { GlobalEvalRoundCache, globalEvalRoundCacheKey, isCacheableRoundResult, } from './global-eval-round-cache.js';
+export { parseGlobalEvalResult } from './pending-global-evals.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cache/pending-global-evals.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pending tracker for the Tier-2 global eval round.
+ *
+ * The orchestrator dispatches one round job per (event × workflow repo) and
+ * waits for the agent to return a verdict per candidate workflow. The
+ * underlying tracker logic lives in `PendingTracker<GlobalEvalRoundResult>`;
+ * this subclass wires the round-specific logger prefix and disconnect error.
+ *
+ * Unlike the dynamic-eval and init trackers, this round runs BEFORE any run row
+ * exists: its whole purpose is to decide which global workflows produce a run at
+ * all, so creating one up-front would defeat it.
+ */
+import { type GlobalEvalRoundResult } from '@kici-dev/engine';
+import { PendingTracker } from './pending-tracker.js';
+/**
+ * Validate the round result carried on a `job.status` message before it reaches
+ * the tracker.
+ *
+ * **This is the one place the round's wire payload is validated.** The status
+ * message's `data` field is `z.record(z.string(), z.unknown())`, so nothing
+ * upstream checks `globalEvalResult` against its schema — a cast at the message
+ * handler would be a type assertion over an arbitrary agent-supplied value, and
+ * any agent that owns the round job can send one. Parsing here keeps the
+ * "typed but unvalidated" boundary at a single named function instead of spread
+ * across every consumer.
+ *
+ * The parsed value is widened back to {@link GlobalEvalRoundResult}: the schema
+ * is deliberately loose about `jobs` (the lock-job shape has no Zod mirror), and
+ * the dispatch path re-checks every generated job before it builds anything from
+ * one.
+ */
+export declare function parseGlobalEvalResult(raw: unknown): {
+    ok: true;
+    value: GlobalEvalRoundResult;
+} | {
+    ok: false;
+    error: string;
+};
+export declare class PendingGlobalEvalTracker extends PendingTracker<GlobalEvalRoundResult> {
+    constructor();
+}
+//# sourceMappingURL=pending-global-evals.d.ts.map

package/dist/cache/pending-inits.d.ts

@@ -18,6 +18,16 @@ export interface InitResult {
      * function. The dispatch path re-materializes these into N execution jobs.
      */
     matrixValues?: Array<Record<string, string | undefined>>;
+    /**
+     * Verdict of the workflow-level `filter`, reported only when the init job was
+     * asked to evaluate one. `false` means the workflow does not apply to this
+     * event and its job must not be dispatched.
+     *
+     * Optional on purpose: an agent that predates the filter never sends it, so
+     * absence means "no verdict was reported" and dispatch proceeds — only an
+     * explicit `false` suppresses.
+     */
+    filterPassed?: boolean;
 }
 export declare class PendingInitTracker extends PendingTracker<InitResult> {
     constructor();

package/dist/cli/api-client.d.ts

@@ -84,6 +84,24 @@ export interface GenericSourceResponse {
  * print an empty one.
  */
 export declare function firstCauseMessage(err: unknown): string;
+/**
+ * True when a rejected `fetch` failed at the transport layer, as opposed to
+ * failing while the request was still being built.
+ *
+ * `fetch` uses a `TypeError` for both, so they are easy to conflate — but only
+ * a transport failure means the orchestrator was actually dialled. Measured
+ * against Node 24's undici:
+ *
+ *   closed port    → TypeError('fetch failed')                       cause: Error(ECONNREFUSED)
+ *   invalid header → TypeError('Headers.append: … invalid header …') cause: undefined
+ *   invalid URL    → TypeError('Failed to parse URL from …')         cause: Error(ERR_INVALID_URL)
+ *
+ * The discriminator is therefore the message, NOT the presence of a `cause`:
+ * the invalid-URL case carries one. undici uses exactly `fetch failed` for a
+ * transport failure and a descriptive message for everything it rejects before
+ * opening a connection.
+ */
+export declare function isTransportFailure(err: unknown): boolean;
 export declare function fetchAdminApi(url: string, init: RequestInit, baseUrl: string): Promise<Response>;
 export declare class AdminApiClient {
     private readonly baseUrl;

package/dist/cli/commands/cluster-settings.d.ts

@@ -25,14 +25,63 @@ interface StringKnobSpec {
     expects: string;
     validate: (value: string) => boolean;
 }
+/**
+ * One boolean knob. A third spec type for the same reason {@link StringKnobSpec}
+ * is separate from {@link KnobSpec}: the value parser, the PATCH body type, and
+ * the `show` formatter all differ. A boolean also has no bounds to validate —
+ * only two accepted spellings.
+ */
+interface BooleanKnobSpec {
+    field: string;
+    flag: string;
+    label: string;
+}
 /** camelCase → value (null clears the override). */
-type PatchBody = Record<string, number | string | null>;
-/** Parse an integer CLI flag with a minimum, exiting with an error on failure. */
-export declare function parseKnobValue(flag: string, value: string, min: number): number;
+type PatchBody = Record<string, number | string | boolean | null>;
+/**
+ * Parse an integer CLI flag against its knob's bounds, exiting on failure.
+ *
+ * `max` is optional because most knobs have no meaningful ceiling; the ones
+ * that do carry a hard boot-safety bound (see {@link KnobSpec.max}).
+ */
+export declare function parseKnobValue(flag: string, value: string, min: number, max?: number): number;
 /** Validate a text CLI flag against its knob's shape, exiting on failure. */
 export declare function parseStringKnobValue(knob: StringKnobSpec, value: string): string;
+/**
+ * Parse a boolean CLI flag, exiting on failure.
+ *
+ * Accepts only the exact strings `true` and `false`. A permissive parser (any
+ * non-empty string is true) would read `--global-workflows-enabled no` as an
+ * enable, which for this knob turns a typo into a security posture change.
+ */
+export declare function parseBooleanKnobValue(knob: BooleanKnobSpec, value: string): boolean;
 /** Assemble the PATCH body from provided `set` flags (exits if none given). */
 export declare function buildClusterPatch(opts: Record<string, string | undefined>): PatchBody;
+/**
+ * Warn when only one of the two ordered global-eval timeouts is being set.
+ *
+ * The orchestrator's wait ceiling must exceed the agent's round budget — the
+ * agent's budget starts only once the round job is RUNNING, so a lower ceiling
+ * fires on every round that merely waited for a free agent, failing every round
+ * silently. The server rejects the pair outright when BOTH effective values are
+ * stored, but it cannot compare against a column left NULL: NULL means "the
+ * orchestrator's configured default applies", and the route does not know that
+ * number. Setting one alone is exactly that blind spot, so warn here.
+ *
+ * Returns the lines rather than printing them so the check is unit-testable.
+ */
+export declare function unpairedEvalTimeoutWarnings(patch: PatchBody): string[];
+/**
+ * Warn for every deprecated knob the patch sets.
+ *
+ * The set still goes through — the column and the route field are a released
+ * operator surface and keep accepting writes — so the warning says what the
+ * stored value now does, which is nothing.
+ *
+ * Returns the lines rather than printing them so the check is unit-testable,
+ * matching {@link unpairedEvalTimeoutWarnings}.
+ */
+export declare function deprecatedKnobWarnings(patch: PatchBody): string[];
 /** Build the reset PATCH body: all knobs → null, or just the flagged ones. */
 export declare function buildClusterReset(opts: Record<string, boolean | undefined>): PatchBody;
 /**

package/dist/cli/commands/diagnose.d.ts

@@ -11,5 +11,11 @@
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
+/**
+ * Width of the table's Message column. A check message is cut at this many
+ * characters, so anything a check wants an operator to see in the default
+ * (non-`--json`) output has to fit inside it.
+ */
+export declare const DIAGNOSE_TABLE_MESSAGE_WIDTH = 42;
 export declare function registerDiagnoseCommand(program: Command, getClient: () => AdminApiClient): void;
 //# sourceMappingURL=diagnose.d.ts.map