@kici-dev/orchestrator 0.5.0 → 0.6.1

package/dist/__test-helpers__/fake-scaler-state-store.d.ts

@@ -0,0 +1,24 @@
+/**
+ * In-memory stand-in for the `scaler_pending_claims` half of `ScalerStateStore`.
+ *
+ * It reproduces the three properties the real table enforces in SQL — a claim
+ * is consumable exactly once, a consume past `expires_at` finds nothing, and a
+ * per-agent invalidation removes every row for that agent — against an injected
+ * clock. That lets a test drive the whole register → redeem round trip without a
+ * database, so the single-use and TTL properties are executed rather than
+ * hand-fed through a stubbed answer.
+ *
+ * Only the pending-claim methods are implemented. Reaching any other
+ * `ScalerStateStore` method is a `TypeError` at the call site, not a silent
+ * no-op.
+ */
+import type { ScalerStateStore } from '../scaler/scaler-state-store.js';
+/**
+ * Build an in-memory pending-claim store.
+ *
+ * @param now Clock (epoch ms) the TTL is evaluated against. Pass the same clock
+ *   the `ClaimStore` under test uses, or its `expiresAt` lands in a different
+ *   era than this store's `now()` and every redeem reads as expired.
+ */
+export declare function makeFakeScalerStateStore(now?: () => number): ScalerStateStore;
+//# sourceMappingURL=fake-scaler-state-store.d.ts.map

package/dist/__test-helpers__/mock-db-query.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Predicate + projection evaluation for the shared `createMockDb` harness.
+ *
+ * Kept BYTE-IDENTICAL in two places —
+ * `packages/orchestrator/src/__test-helpers__/mock-db-query.ts` and
+ * `packages/platform/src/__test-helpers__/mock-db-query.ts`. Each package owns an
+ * independent `createMockDb` builder and neither package may import the other, so
+ * the evaluator is duplicated rather than shared. `mock-db-mirror.test.ts` in both
+ * packages fails the moment the copies diverge.
+ *
+ * `createMockDb` used to return its configured rows verbatim, whatever the
+ * query asked for: a `.where(...)` or a `.select([...])` was recorded on a spy
+ * and then discarded. A test therefore observed only the rows it had itself
+ * configured, so dropping a filter or a projected column from the code under
+ * test changed nothing the test could see. This module is the evaluator that
+ * closes that: the mock now *applies* the query it was handed.
+ *
+ * Scope, stated precisely because the guarantee is partial by construction:
+ *
+ * - **Binary predicates are evaluated.** `.where(column, op, value)` for the
+ *   operators in {@link MockDbOperator}. That is the overwhelming majority of
+ *   the predicates this repo issues.
+ * - **Anything else is opaque and is NOT evaluated.** An expression-builder
+ *   callback (`.where((eb) => …)`) and a raw `sql` fragment carry their meaning
+ *   in code the mock cannot read, so they are recorded and skipped. A filter
+ *   written in one of those shapes is still unpinned.
+ * - **A predicate on a column the fixture row does not declare is NOT
+ *   evaluated.** The fixture, not the schema, is the source of truth here: a
+ *   test row is a partial literal, and a missing key means "this test did not
+ *   model that column", not "this column is NULL". Treating absence as NULL
+ *   would fail nearly every fixture in the repo for saying too little, while
+ *   catching nothing a fixture that *does* declare the column would not
+ *   already catch. The consequence is real and worth naming: to pin a filter,
+ *   a fixture row must mention the column that filter reads.
+ *
+ * Everything here is pure — no vitest, no chain state — so it is unit-tested
+ * directly in `mock-db-query.test.ts` rather than only through the mock.
+ */
+/** SQL comparison operators the mock evaluates. Anything else is opaque. */
+export declare enum MockDbOperator {
+    eq = "=",
+    neq = "!=",
+    neqAnsi = "<>",
+    lt = "<",
+    lte = "<=",
+    gt = ">",
+    gte = ">=",
+    in = "in",
+    notIn = "not in",
+    is = "is",
+    isNot = "is not",
+    like = "like",
+    notLike = "not like",
+    ilike = "ilike",
+    notILike = "not ilike"
+}
+/** A `.where(column, op, value)` predicate the mock can evaluate. */
+export interface BinaryPredicate {
+    kind: 'binary';
+    /** Column name with any `table.` qualifier stripped. */
+    column: string;
+    op: MockDbOperator;
+    value: unknown;
+}
+/** A predicate shape the mock cannot read (eb callback, raw sql, unknown op). */
+export interface OpaquePredicate {
+    kind: 'opaque';
+    /** Why it could not be parsed — surfaced in `explainSkippedPredicates`. */
+    reason: string;
+}
+export type MockDbPredicate = BinaryPredicate | OpaquePredicate;
+/** Drop a `table.` / `"table".` qualifier so a predicate keys into a flat row. */
+export declare function unqualify(column: string): string;
+/**
+ * Parse the arguments of one `.where(...)` call into a predicate.
+ *
+ * Only the 3-argument `(column, op, value)` form with a string column and a
+ * recognized operator is evaluable; everything else is opaque.
+ */
+export declare function parseWhereArgs(args: readonly unknown[]): MockDbPredicate;
+/**
+ * Evaluate one binary predicate against a row.
+ *
+ * Returns `undefined` when the predicate cannot be decided — the row does not
+ * declare the column, or the values are not comparable. An undecided predicate
+ * does not exclude the row (see the module docblock).
+ */
+export declare function evaluatePredicate(row: Record<string, unknown>, predicate: BinaryPredicate): boolean | undefined;
+/** True when the row satisfies every predicate the mock could decide. */
+export declare function rowMatches(row: unknown, predicates: readonly MockDbPredicate[]): boolean;
+/** Keep only the rows satisfying every decidable predicate. */
+export declare function filterRows<T>(rows: readonly T[], predicates: readonly MockDbPredicate[]): T[];
+/** One projected column: the row key read, and the key it is emitted under. */
+export interface ProjectedColumn {
+    source: string;
+    alias: string;
+}
+/**
+ * Parse `.select(...)` arguments into a projection.
+ *
+ * Returns `undefined` when the projection cannot be modelled — an aggregate
+ * expression, an `eb` callback, a raw `sql` fragment. An unmodelled projection
+ * leaves rows untouched rather than guessing at their shape.
+ */
+export declare function parseSelectArgs(args: readonly unknown[]): ProjectedColumn[] | undefined;
+/**
+ * Narrow a row to the projected columns.
+ *
+ * A projected column the fixture row does not declare is omitted rather than
+ * emitted as `undefined`, so `'key' in row` keeps meaning "the fixture modelled
+ * this" — the same convention {@link evaluatePredicate} reads.
+ *
+ * A column is read under its `source` name and, failing that, under its
+ * `alias`. Fixtures in this repo are written both ways — some model the raw
+ * table row (`storage_key`), others the row the aliased query returns
+ * (`storageKey`) — and the projection has to narrow both. Reading either name
+ * costs nothing: a column dropped from the projection disappears from the
+ * output under both conventions, which is the regression this exists to catch.
+ */
+export declare function projectRow<T>(row: T, columns: readonly ProjectedColumn[]): T;
+/** Narrow every row to the projected columns. */
+export declare function projectRows<T>(rows: readonly T[], columns: readonly ProjectedColumn[]): T[];
+/**
+ * Describe the predicates the mock recorded but could not evaluate.
+ *
+ * Exposed so a test that cares whether its filter was actually pinned can
+ * assert the mock understood it, instead of assuming it did.
+ */
+export declare function explainSkippedPredicates(predicates: readonly MockDbPredicate[]): string[];
+//# sourceMappingURL=mock-db-query.d.ts.map

package/dist/__test-helpers__/mock-db.d.ts

@@ -15,6 +15,29 @@
  *
  * Each test can configure return values via options and access the
  * underlying vi.fn() mocks for assertions via the `mocks` property.
+ *
+ * ## The select chain APPLIES the query (contract)
+ *
+ * A select chain does not return `selectRows` / `selectFirstRow` verbatim. It
+ * evaluates the `.where(...)` predicates and the `.select([...])` projection the
+ * code under test issued, so a test observes the query instead of restating it:
+ * dropping a filter or a projected column changes what the test sees.
+ *
+ * - **Per query, not per test.** Every `db.selectFrom(...)` builds a fresh chain
+ *   with its own predicate list, so two queries in one test cannot inherit each
+ *   other's filters. The `mocks.select*` spies stay shared across the whole
+ *   test, so existing clause assertions are unaffected.
+ * - **Only the shapes the evaluator reads.** `.where(column, op, value)` is
+ *   evaluated; an `eb` callback or a raw `sql` fragment is recorded and skipped.
+ *   `.select()` is applied only when every argument is a plain column string, so
+ *   an aggregate or `eb` projection leaves rows untouched.
+ * - **A predicate on a column the fixture omits does not exclude the row.** To
+ *   pin a filter, the fixture row must declare the column that filter reads.
+ * - **`executeTakeFirstOrThrow` yields `{}`** when the configured row does not
+ *   satisfy the query, rather than throwing as Kysely would.
+ *
+ * `mock-db-query.ts` holds the evaluator and states the same contract with its
+ * reasoning; `mock-db-query.test.ts` tests it directly.
  */
 import { vi } from 'vitest';
 export interface MockDbOptions {

package/dist/agent/dispatcher.d.ts

@@ -1,6 +1,7 @@
 import type { AgentRegistry } from './registry.js';
 import { type JobQueue, type QueuedJob, type QueuedJobInput } from '../queue/job-queue.js';
 import type { ScaleResult, ScalerRedispatchTrigger } from '../scaler/types.js';
+import type { ResolvedContainerSpawn } from '../scaler/types.js';
 import type { ResourceRequest } from '@kici-dev/engine';
 /**
  * Why a freed agent's queue drain claimed nothing.
@@ -80,24 +81,24 @@ type DispatchResult = {
     status: 'rejected';
     reason: string;
 };
-/**
- * Dispatch coordinator connecting the agent registry and job queue.
- *
- * Routes incoming jobs to matching agents based on label requirements,
- * falling back to the persistent queue when no agent is available.
- * Handles agent lifecycle events (connect, disconnect, job completion).
- *
- * The dispatcher does NOT directly access WebSocket connections --
- * it uses the onDispatch callback provided at construction. The caller
- * (app.ts or server.ts) provides an onDispatch that looks up the agent's
- * WS from the registry and sends the job.dispatch message.
- */
+export declare function containerSpawnFor(jobConfig: Record<string, unknown> | undefined): {
+    image: string;
+    authconfig?: {
+        username: string;
+        password: string;
+        serveraddress: string;
+    } | undefined;
+} | undefined;
 export declare class Dispatcher {
     private readonly registry;
     private readonly queue;
     private readonly metrics;
     private readonly onDispatch;
     private readonly onNoMatchingAgent?;
+    /** See the constructor dep of the same name. */
+    private readonly canPrespawnedAgentServe?;
+    /** See the constructor dep of the same name. */
+    private readonly isPrespawnedAgent?;
     /**
      * Single-flight guard for `retryPendingScaleRequests`. The capacity-freed
      * hook and the leader-gated sweep can both fire concurrently; this prevents
@@ -196,7 +197,34 @@ export declare class Dispatcher {
         /** Optional hook called when no agent matches the job's labels.
          *  When set, receives the per-job `resources` so the scaler can apply
          *  per-scaler / per-orchestrator / per-machine caps before spawning. */
-        onNoMatchingAgent?: (labels: string[], jobId: string, runId: string, excludeLabels: string[], resources?: ResourceRequest, orgId?: string) => Promise<ScaleResult>;
+        onNoMatchingAgent?: (labels: string[], jobId: string, runId: string, excludeLabels: string[], resources?: ResourceRequest, orgId?: string, 
+        /**
+         * The job's own container image plus registry credentials, already
+         * resolved at dispatch. Present means the backend spawns THAT image with
+         * the KiCI runtime injected instead of the pool's fixed agent image.
+         */
+        containerSpawn?: ResolvedContainerSpawn) => Promise<ScaleResult>;
+        /**
+         * Optional scaler predicate: may this pre-spawned (warm) agent serve this
+         * job? A warm agent is generic — started before the job existed, at the
+         * pool's shape and running the pool's image, both of which are fixed when
+         * it starts. When the predicate returns false the agent is skipped and the
+         * job falls through to `onNoMatchingAgent`, which spawns one that fits.
+         * Absent (no scaler) means every agent is eligible.
+         */
+        canPrespawnedAgentServe?: (agentId: string, job: {
+            resources?: ResourceRequest;
+            hasOwnContainerImage: boolean;
+        }) => boolean;
+        /**
+         * Whether this scaler pre-spawned the agent, i.e. whether
+         * `canPrespawnedAgentServe` can ever answer false for it. The queue drain
+         * (agent asks for work, rather than job looks for an agent) uses it to
+         * decide whether the suitability predicate is worth carrying into the
+         * claim: for every ordinary agent it is not, and the drain keeps its
+         * single-statement fast path.
+         */
+        isPrespawnedAgent?: (agentId: string) => boolean;
         /** Max reconnection delay from agent config (default 60s). Used to derive grace period. */
         maxReconnectDelayMs?: number;
         /** Callback fired when a job is permanently failed before/outside agent execution. */
@@ -285,6 +313,39 @@ export declare class Dispatcher {
      * that is about to reboot. No-op when no roster store is wired.
      */
     private filterRebootPending;
+    /**
+     * Drop pre-spawned (warm) agents that cannot serve this job. Sibling of
+     * {@link filterRebootPending}: both remove candidates `findAvailable` matched
+     * on labels but that are unusable for a reason labels cannot express.
+     *
+     * A warm agent's cpu, memory and container image are all set when it starts
+     * and cannot change afterwards, so a job asking for something else has to get
+     * an agent of its own. Dropping the candidate here is what sends it down the
+     * ordinary `onNoMatchingAgent` scale path. No-op when no scaler is wired.
+     */
+    private filterUnsuitablePrespawned;
+    /**
+     * The fit question for one job: the shape it declares, and whether it brings
+     * its own container image.
+     *
+     * The shape comes from `jobConfig.resources` when the typed `resources`
+     * mirror is absent, because the mirror is optional and several dispatch paths
+     * never fill it — a job reaching {@link dispatch} straight off the webhook
+     * pipeline or off a worker's reroute handler carries its declaration in
+     * `jobConfig` alone. Reading only the mirror there reports a job that
+     * declares nothing, which admits it onto a pre-spawned agent of some other
+     * size — the exact mismatch this gate exists to refuse.
+     */
+    private prespawnedFitFor;
+    /**
+     * The queue-drain half of {@link filterUnsuitablePrespawned}: a per-job
+     * predicate for one agent, or undefined when this agent needs no check.
+     *
+     * Undefined is the common answer — an ordinary agent is not pre-spawned, so
+     * the predicate could only ever say yes, and returning one would cost the
+     * drain its single-statement fast path for nothing.
+     */
+    private prespawnedFitFilterFor;
     /**
      * Release a reboot-pending host on its real reconnect (down-then-up). Clears
      * the persisted flag so the very next `onAgentAvailable` drain dispatches the
@@ -384,6 +445,13 @@ export declare class Dispatcher {
      * host-fanout child may run ONLY on its pinned agent — and `dequeueById`
      * ignores the pin — so a pinned job is routed to its own agent and never
      * offered to `findAvailable`, which would mis-deliver it to any label match.
+     *
+     * Reboot-pending gate: a host whose `restart` job just completed is still
+     * connected but about to reboot, so its held post-restart job must NOT be
+     * re-driven into the about-to-die box. This is the safety-net re-drive's
+     * counterpart of the same gate in `dispatch()` / `dispatchPinned` /
+     * `drainForAgent`; without it this path re-drives the held job onto the
+     * reboot-pending host and defeats the hold.
      */
     private selectConnectedTargetForPending;
     /**

package/dist/agent/host-roster.d.ts

@@ -77,6 +77,13 @@ export interface UpsertHostInput {
     agentId: string;
     tokenId: string | null;
     lifecycleClass: LifecycleClass;
+    /**
+     * True when an auto-scaler backend spawned this agent, so `runsOnAll`
+     * fan-out skips it. Derived from the scaler manager's registration lookup,
+     * never from `lifecycleClass` (which is `ephemeral` for every agent when the
+     * auth mode is `none`). Omitted ⇒ false.
+     */
+    scalerManaged?: boolean;
     labels: string[];
     hostname: string | null;
     platform: string;
@@ -176,13 +183,38 @@ export declare class HostRosterStore {
     getStagedVersion(agentId: string): Promise<string | null>;
     listAll(): Promise<HostRosterRow[]>;
     /**
-     * Resolve every roster host matching a `runsOnAll` predicate (OR-of-AND
-     * include groups, minus exclude labels), tagged with its derived status. This
-     * is the host-fanout resolver: it returns declared-but-absent static hosts
-     * (status `unreachable`) so the caller can apply `onUnreachable` — the live
-     * registry alone cannot name an expected-but-absent host.
+     * Resolve EVERY roster host matching a label predicate (OR-of-AND include
+     * groups, minus exclude labels), tagged with its derived status. Returns
+     * declared-but-absent static hosts (status `unreachable`) so a caller can
+     * apply `onUnreachable` — the live registry alone cannot name an
+     * expected-but-absent host.
+     *
+     * This is the INVENTORY query: it includes auto-scaler-spawned hosts, whose
+     * `lifecycleClass` is what the SDK's `ctx.kici.inventory` exposes to tell
+     * them apart. `runsOnAll` fan-out uses {@link findFanoutTargets} instead.
      */
     findMatching(include: readonly (readonly LabelMatcher[])[], exclude: readonly LabelMatcher[], graceMs: number): Promise<MatchedHost[]>;
+    /**
+     * Resolve the `runsOnAll` fan-out target set: {@link findMatching}, minus
+     * every auto-scaler-spawned host.
+     *
+     * Fan-out targets DECLARED fleet members. An auto-scaler agent is spawned to
+     * a pool's fixed shape, so a child pinned to one runs at that shape rather
+     * than its own — the same defect the dispatcher's warm-pool suitability gate
+     * removes, on the path a pin deliberately leaves ungated.
+     *
+     * Separate from `findMatching` on purpose: `findMatching` also backs the
+     * SDK's `inventory.query`, where a host the caller asked for must never go
+     * missing (a selector returning FEWER hosts than no selector at all).
+     */
+    findFanoutTargets(include: readonly (readonly LabelMatcher[])[], exclude: readonly LabelMatcher[], graceMs: number): Promise<MatchedHost[]>;
+    /**
+     * Shared row loop behind {@link findMatching} and {@link findFanoutTargets}.
+     * `excludeScalerManaged` stays private to the store — each public method
+     * names its own semantics, so a call site cannot silently pick the wrong
+     * population by passing a bare boolean.
+     */
+    private matchRows;
     /**
      * Map a roster row to the canonical {@link HostInventoryEntry} — the queryable
      * shape returned by the `inventory.query`/`inventory.get` RPC and typed on the

package/dist/agent/registry.d.ts

@@ -137,6 +137,8 @@ export interface RosterReconciler {
         agentId: string;
         tokenId: string | null;
         lifecycleClass: 'static' | 'ephemeral';
+        /** True when a scaler backend spawned this agent (kept out of `runsOnAll`). */
+        scalerManaged?: boolean;
         labels: string[];
         hostname: string | null;
         platform: string;

package/dist/app.d.ts

@@ -66,6 +66,8 @@ import type { RegistrationStore } from './registration/registration-store.js';
 import type { RegistrationIndex } from './registration/registration-index.js';
 import type { CronScheduler } from './cron/cron-scheduler.js';
 import { type ConfigRouteDeps } from './routes/admin-config.js';
+import type { ProcessingDeps } from './pipeline/processor.js';
+import type { InvokeGateDeps } from './pipeline/invoke-gate.js';
 import { WebhookIngestOutcome } from './pipeline/process-webhook.js';
 import type { IngestOverflowBuffer } from './webhook/ingest-overflow-buffer.js';
 import type { IngestOverflowReplayer } from './webhook/ingest-overflow-replayer.js';
@@ -85,9 +87,8 @@ import type { GenericSourceManager } from './webhook/generic-sources.js';
 import type { TrustStore } from './events/trust-store.js';
 import type { ContextStore } from './contexts/context-store.js';
 import type { VariableStore } from './contexts/variable-store.js';
-import type { HeldRunStore } from './contexts/held-runs.js';
+import type { HeldRunStore, ReleaseSignal } from './contexts/held-runs.js';
 import type { StepApprovalBridge } from './approvals/step-approval-bridge.js';
-import type { ContributorCache } from './security/contributor-cache.js';
 import { AgentMetricsAggregator } from './metrics/agent-metrics-aggregator.js';
 /**
  * All dependencies needed to create the orchestrator Hono app.
@@ -179,6 +180,14 @@ export interface AppDependencies {
      * is registered so `ctx.kici.oidc.token()` mints a `kici-local` dev token.
      */
     localOidcSigner?: LocalSigner;
+    /**
+     * Test-only fault-injection policy, threaded from a test-only entrypoint via
+     * `bootstrapOrchestrator`. Undefined in production. Consumed here only for the
+     * initial-mint provenance seam (`initialMintFault`); the other seams live in
+     * the composition root / server hooks. Type-only reference — the runtime
+     * module never enters the shipped bundle.
+     */
+    faultInjection?: import('./testing/fault-injection.js').OrchestratorFaultInjection;
     /**
      * Orchestrator-owned provenance signing (Phase 1 root of trust). Present when
      * `KICI_ORCHESTRATOR_PROVENANCE_ISSUER` is configured: the orchestrator mints +
@@ -257,6 +266,18 @@ export interface AppDependencies {
     configRouteDeps?: ConfigRouteDeps;
     /** Event router for internal event delivery. Optional -- if not set, event routing is inactive. */
     eventRouter?: EventRouter;
+    /** Invoke-gate dependencies (summon callback + chain-depth bound). Optional -- if not set, invoke gates fail loudly. */
+    invokeGateDeps?: InvokeGateDeps;
+    /**
+     * Late-binding handle the internal-event dispatch adapter reads to obtain the
+     * live `ProcessingDeps` bag. `createApp` populates it, because the bag can
+     * only be assembled here while the event router that dispatches internal
+     * events is constructed earlier in the bootstrap. Left unset by callers that
+     * never route internal events (tests constructing a bare app).
+     */
+    processingDepsRef?: {
+        current: (() => ProcessingDeps) | null;
+    };
     /** Event store. Optional -- mounted when admin DLQ admin route should be available. */
     eventStore?: EventStore;
     /** Event emitter for system events (workflow/job complete). Optional -- if not set, system events are skipped. */
@@ -297,6 +318,16 @@ export interface AppDependencies {
     heldRunStore?: HeldRunStore;
     /** Step-approval bridge — opens step-scoped holds and relays their resolution back to the waiting agent. Optional. */
     stepApprovalBridge?: StepApprovalBridge;
+    /**
+     * Re-dispatch a job whose hold was released. Supplied by both mode hooks
+     * through `appDepsExtras`; declared here so the admin held-run routes can
+     * read it type-safely rather than off an untyped spread. Optional — an app
+     * assembled without it mounts no local held-run decision surface, because a
+     * release that cannot dispatch is a row flip pretending to be a release.
+     */
+    onJobRelease?: (signal: ReleaseSignal) => Promise<void>;
+    /** Replay the stored dispatch context of a released workflow-scoped hold. Same provenance as `onJobRelease`. */
+    onWorkflowRelease?: (signal: ReleaseSignal) => Promise<void>;
     /** Global workflow policy for org-level permission enforcement. Optional -- if not set, global workflows are dispatched without permission checks. */
     globalWorkflowPolicy?: GlobalWorkflowPolicy;
     /** Inbound webhook delivery log writer. Optional -- if not set, deliveries are not persisted to event_log. */
@@ -330,10 +361,6 @@ export interface AppDependencies {
     coordinator?: RunCoordinator;
     /** Peer registry for aggregating infrastructure across cluster. Optional. */
     peerRegistry?: PeerRegistry;
-    /** Contributor permission cache. Optional -- threaded through from server.ts
-     *  so membership-related webhooks invalidate matching entries immediately
-     *  (instead of waiting for the 15-minute TTL). */
-    contributorCache?: ContributorCache;
     /**
      * Shared aggregator for agent-pushed metrics. When omitted, app.ts
      * constructs its own — kept optional so existing tests still work

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