@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/agent/token-store.d.ts

@@ -1,41 +1,31 @@
 import { type Kysely } from 'kysely';
 import type { Database, AgentTokenRow } from '../db/types.js';
 /**
- * `created_by` marker prefix for single-use bootstrap (init-runner) tokens.
- * A bootstrap token stores `created_by: '<this prefix><targetAgentId>'` so the
- * register-time identity binding (agent-handler Gate 2) and the single-use
- * consume check can both recognize it and resolve the bound agent id.
+ * `created_by` prefix of single-use bootstrap (init-runner) tokens, stored as
+ * `'<this prefix><targetAgentId>'` so the register-time identity binding
+ * (agent-handler Gate 2) and the single-use consume check can resolve the
+ * bound agent id.
  */
 export declare const BOOTSTRAP_CREATED_BY_PREFIX = "bootstrap:";
 /**
  * Resolve the agent id an ephemeral token binds its holder to. Scaler tokens
- * store the id verbatim in `created_by`; bootstrap tokens store it behind
- * `BOOTSTRAP_CREATED_BY_PREFIX`. Returns the bare target agent id in both cases.
+ * store it verbatim in `created_by`; bootstrap tokens behind
+ * `BOOTSTRAP_CREATED_BY_PREFIX`.
  */
 export declare function boundAgentIdFromCreatedBy(createdBy: string): string;
-/**
- * Safe token row shape returned from list/validate (excludes token_hash).
- */
+/** Token row returned from list/validate, without token_hash. */
 export type SafeAgentTokenRow = Omit<AgentTokenRow, 'token_hash'>;
-/**
- * Manages agent authentication tokens.
- *
- * Tokens are kat_ + 64 hex chars (32 random bytes = 256 bits).
- * Only the SHA-256 hash is stored; the plaintext is returned once at generation time.
- */
 export declare class AgentTokenStore {
     private readonly db;
     constructor(db: Kysely<Database>);
     /**
-     * Create a static (long-lived) agent token.
+     * Create a static token: no expiry, for manually-registered agents.
      *
-     * Static tokens have no expiry and are intended for manually-registered agents.
-     *
-     * @param opts.labels - Optional agent labels this token is authorized for.
-     * @param opts.mandatoryLabels - Optional taint labels (a Kubernetes-taint-style
-     *   gate): a static agent registering with this token only accepts a job when
-     *   every label here appears in the job's required labels. Undefined = no taint.
-     * @param opts.createdBy - Optional creator identifier (e.g. "cli:admin").
+     * @param opts.labels - Agent labels this token is authorized for.
+     * @param opts.mandatoryLabels - Kubernetes-taint-style gate: an agent
+     *   registering with this token only accepts a job whose required labels
+     *   include every label here. Undefined = no taint.
+     * @param opts.createdBy - Creator identifier (e.g. "cli:admin").
      * @returns The plaintext token (shown once) and the DB row ID.
      */
     createStatic(opts: {
@@ -47,29 +37,22 @@ export declare class AgentTokenStore {
         id: string;
     }>;
     /**
-     * Create an ephemeral (short-lived) agent token.
-     *
-     * Ephemeral tokens are issued by the scaler for auto-provisioned agents
-     * and expire after the specified TTL.
+     * Create an ephemeral token, issued by the scaler for an auto-provisioned
+     * agent and expiring after `ttlMs`.
      *
-     * @param agentId - The agent ID this token is for (used as created_by).
-     * @param labels - Agent labels this token is authorized for.
-     * @param ttlMs - Time-to-live in milliseconds.
+     * @param agentId - Stored as created_by.
      * @returns The plaintext token (shown once).
      */
     createEphemeral(agentId: string, labels: string[], ttlMs: number): Promise<string>;
     /**
-     * Mint a single-use, short-TTL bootstrap token for an init-runner bring-up.
-     *
-     * The token is stored as `agent_type: 'ephemeral'` (so the existing expiry
-     * cleanup reaps it) and is bound to exactly the init-runner label set. It is
-     * single-use: `consumeBootstrapToken` sets `consumed_at` on first
-     * `agent.register`, and a second register is rejected. A leaked token is
-     * therefore inert after enrollment AND after its short TTL elapses.
+     * Mint a single-use, short-TTL bootstrap token for an init-runner bring-up,
+     * bound to exactly the init-runner label set. Stored as `agent_type:
+     * 'ephemeral'` so the expiry cleanup reaps it. `consumeBootstrapToken` sets
+     * `consumed_at` on first `agent.register` and a second register is rejected,
+     * so a leaked token is inert after enrollment AND after its TTL.
      *
      * @param targetAgentId - The agent id the init-runner will register as.
-     * @param ttlMs - Time-to-live in milliseconds (short, ~10 min).
-     * @param labels - The init-runner labels the token authorizes.
+     * @param ttlMs - Short, ~10 min.
      * @returns The plaintext token (shown once) and the DB row ID.
      */
     mintBootstrapToken(opts: {
@@ -81,58 +64,32 @@ export declare class AgentTokenStore {
         id: string;
     }>;
     /**
-     * Consume a single-use bootstrap token by id. Sets `consumed_at` only when it
-     * is currently null, so the first register wins and any subsequent attempt
-     * with the same token returns false (already consumed). Returns true when
-     * this call performed the consumption.
+     * Consume a bootstrap token. Sets `consumed_at` only while null, so the first
+     * register wins; returns true only when this call consumed it.
      */
     consumeBootstrapToken(id: string): Promise<boolean>;
     /**
-     * Validate a plaintext token against stored hashes.
-     *
-     * Checks that the token exists, is not revoked, and has not expired.
-     * On success, fires a non-blocking update to last_seen_at.
+     * Validate a plaintext token: exists, not revoked, not consumed, not expired.
+     * On success, fires a non-blocking last_seen_at update.
      *
-     * @param token - The plaintext token to validate.
      * @returns The token row (without hash) if valid, null otherwise.
      */
     validate(token: string): Promise<SafeAgentTokenRow | null>;
-    /**
-     * Revoke a token by ID.
-     *
-     * Sets revoked_at to now. Returns true if the token was revoked,
-     * false if it was already revoked or not found.
-     *
-     * @param id - The token row ID to revoke.
-     * @returns True if the token was newly revoked.
-     */
+    /** Revoke a token; false when it was already revoked or not found. */
     revoke(id: string): Promise<boolean>;
-    /**
-     * List all non-revoked tokens (excludes token_hash for security).
-     *
-     * @param opts.agentType - Optional filter by agent type ('static' | 'ephemeral').
-     * @returns Array of token rows without the hash field.
-     */
+    /** List non-revoked tokens, newest first, without token_hash. */
     list(opts?: {
         agentType?: string;
     }): Promise<SafeAgentTokenRow[]>;
     /**
-     * Clean up expired ephemeral tokens.
-     *
-     * Deletes rows where `expires_at < now()` and `agent_type = 'ephemeral'`.
-     * Called periodically by the orchestrator (every 60s) to keep the
-     * table from growing without bound.
+     * Delete expired ephemeral tokens. The orchestrator calls it every 60s so
+     * the table cannot grow without bound.
      *
-     * Optional `onBeforeDelete` callback is invoked once with the list
-     * of expired token IDs **before** the DELETE runs. The orchestrator
-     * uses this to call `agentRegistry.disconnectByTokenId(id)` for
-     * each expired row, so any in-flight WS that survived the
-     * per-token kick timer (e.g. across a process restart that wiped
-     * the in-memory `tokenExpiryTimers` map) is still kicked. Closes
-     * the sister gap to the revocation finding.
+     * `onBeforeDelete` gets the expired ids once, **before** the DELETE; the
+     * orchestrator calls `agentRegistry.disconnectByTokenId(id)` with each, so a
+     * WS that outlived the per-token kick timer (e.g. a restart wiped the
+     * in-memory `tokenExpiryTimers` map) is still kicked.
      *
-     * @param opts.onBeforeDelete - Optional sync/async callback invoked
-     *   with expired token IDs before the DELETE.
      * @returns Number of deleted rows.
      */
     cleanupExpired(opts?: {

package/dist/agent-packaging/availability.d.ts

@@ -1,12 +1,10 @@
 /**
  * Availability gate for version-keyed agent packages.
  *
- * The fleet auto-upgrade convergence NEVER rolls a host to a version whose
- * self-contained payload objects don't exist in the cache bucket — that would
- * stage stale/absent bytes (or leave the fleet at a version skew). This helper
- * `head`s each platform's payload object and reports which are missing, so the
- * caller can HOLD (the convergence gate) or skip re-producing (the upgrade
- * hook). It never throws — the caller decides hold-vs-alarm.
+ * Fleet auto-upgrade NEVER rolls a host to a version whose payload objects are
+ * absent from the cache bucket: that stages stale or absent bytes, or leaves a
+ * version skew. It never throws; the caller holds (convergence gate) or skips
+ * re-producing (upgrade hook).
  */
 import type { AgentPlatform } from '@kici-dev/shared';
 import { type AgentPackageDownloadStorage } from './download.js';
@@ -19,9 +17,8 @@ export interface PayloadAvailability {
 }
 /**
  * Check that a version's agent payloads exist for every requested platform.
- * Fail-closed by construction: an absent object lands in `missing`, so a caller
- * that gates on `available` can never converge onto a version whose bytes are
- * not present.
+ * Fail-closed: an absent object lands in `missing`, so gating on `available`
+ * never converges onto a version whose bytes are not present.
  */
 export declare function assertPayloadsAvailable(storage: AgentPackageDownloadStorage, version: string, platforms: AgentPlatform[]): Promise<PayloadAvailability>;
 //# sourceMappingURL=availability.d.ts.map

package/dist/agent-packaging/download.d.ts

@@ -1,9 +1,8 @@
 import type { AgentPlatform } from '@kici-dev/shared';
 /**
- * Read side of the cache-bucket agent-package store: mint a box-routable
- * presigned GET URL and read the payload's sha256 sidecar. Satisfied by the
- * orchestrator S3 cache storage client (`getUrl` presigns against the external,
- * container-routable endpoint; `get` reads the `.sha256` object).
+ * Read side of the cache-bucket agent-package store, satisfied by the orchestrator
+ * S3 cache storage client: `getUrl` presigns against the external,
+ * container-routable endpoint; `get` reads the `.sha256` sidecar.
  */
 export interface AgentPackageDownloadStorage {
     getUrl(key: string): Promise<string | null>;
@@ -15,11 +14,9 @@ export declare function agentPackageHashKey(version: string, platform: AgentPlat
 /** Parse a `sha256sum`-style `<hex>  <name>` sidecar into the leading hex token. */
 export declare function parseSha256Sidecar(contents: string): string | null;
 /**
- * Mint a presigned GET URL for a version-keyed agent payload and read its
- * sha256 sidecar. Returns null when the payload object is absent (an
- * unresolvable version) so the caller fails fast with a clear error rather than
- * staging stale bytes. The URL is box-routable (external endpoint); no standing
- * S3 credential ever leaves the orchestrator.
+ * Returns null when the payload object is absent (an unresolvable version), so
+ * the caller fails fast rather than staging stale bytes. The URL is box-routable
+ * (external endpoint); no standing S3 credential ever leaves the orchestrator.
  */
 export declare function presignAgentPackageDownload(storage: AgentPackageDownloadStorage, version: string, platform: AgentPlatform): Promise<{
     url: string;

package/dist/agent-packaging/install-closure.d.ts

@@ -7,24 +7,21 @@ export interface InstallClosureOptions {
     npmRegistry?: string;
 }
 /**
- * The `@kici-dev/agent@<spec>` argument for the install.
+ * The `@kici-dev/agent@<spec>` install argument.
  *
- * In production the agent is published to npm at the exact single-version, so we
- * pin it verbatim (`@kici-dev/agent@0.2.0`) — the payload is provably the version
- * the orchestrator runs. In development (`KICI_DEV=true`) the local Verdaccio
- * registry only carries prerelease builds (`<version>-<buildCounter>`), so we
- * match the current base version's prereleases instead — the same
- * prerelease-compatible resolution the rest of the dev tooling uses.
+ * In production it pins the exact single-version (`@kici-dev/agent@0.2.0`), so the payload is
+ * provably the version the orchestrator runs. In development (`KICI_DEV=true`) local Verdaccio
+ * carries only prereleases (`<version>-<buildCounter>`), so it matches the base version's
+ * prereleases, as the rest of the dev tooling does.
  */
 export declare function agentInstallSpec(version: string): string;
 /**
  * `npm install @kici-dev/agent@<version>` for the TARGET platform into prefixDir.
  *
- * `--cpu`/`--os` make npm resolve every transitive optional native binding (incl.
- * `@oxc-transform/binding-<platform>`) for the target platform, not the host —
- * the same mechanism `scripts/package.mjs` relies on for oxc. `--omit=dev` keeps
- * the closure to the runtime tree. When the published `@kici-dev/agent` ships an
- * `npm-shrinkwrap.json`, npm resolves the exact released + tested tree.
+ * `--cpu`/`--os` resolve every transitive optional native binding (incl.
+ * `@oxc-transform/binding-<platform>`) for the target, not the host, as `scripts/package.mjs`
+ * does for oxc. `--omit=dev` keeps the runtime tree only. A published `npm-shrinkwrap.json`
+ * pins the exact released + tested tree.
  */
 export declare function installAgentClosure(opts: InstallClosureOptions): Promise<void>;
 //# sourceMappingURL=install-closure.d.ts.map

package/dist/agent-packaging/node-binary.d.ts

@@ -11,16 +11,12 @@ export interface DownloadNodeOptions {
  * Download + SHASUMS256-verify the Node runtime for a glibc-Linux platform and
  * vendor `node` + `npm` into the payload.
  *
- * Fetches the release's SHASUMS256.txt, finds the entry for the target
- * platform's `.tar.gz`, downloads the archive, verifies its sha256 against that
- * entry, and extracts the runtime into `<prefix>/` (where `<prefix>` is the
- * grandparent of `destBinPath`): the `node` binary at `<prefix>/bin/node`, the
- * `bin/npm` + `bin/npx` launcher symlinks, and the bundled npm package under
- * `<prefix>/lib/node_modules/npm`. npm is required so the booted agent can
- * install a workflow's `.kici/` dependencies on a box with no system Node —
- * `resolveNpm()` finds it at `<nodeDir>/../lib/node_modules/npm/bin/npm-cli.js`.
- * The vendored Node is what the produced payload boots on — no system Node is
- * ever used.
+ * Extracts into `<prefix>/` (the grandparent of `destBinPath`): `bin/node`, the
+ * `bin/npm` + `bin/npx` launcher symlinks, and `lib/node_modules/npm`. npm is
+ * required so the booted agent can install a workflow's `.kici/` dependencies on
+ * a box with no system Node — `resolveNpm()` finds it at
+ * `<nodeDir>/../lib/node_modules/npm/bin/npm-cli.js`. The payload boots on the
+ * vendored Node; no system Node is ever used.
  */
 export declare function downloadNodeBinary(opts: DownloadNodeOptions): Promise<void>;
 //# sourceMappingURL=node-binary.d.ts.map

package/dist/agent-packaging/node-runtime-members.d.ts

@@ -1,12 +1,10 @@
 /**
  * The members of an official Node.js Linux or macOS archive that a KiCI payload
  * vendors, relative to the archive's `node-v<version>-<os>-<arch>/` directory:
- * the `node` binary, the `npm` and `npx` launchers, and the bundled npm package.
- * With them in place, the agent's `resolveNpm()` finds
- * `<nodeDir>/../lib/node_modules/npm/bin/npm-cli.js` beside the vendored `node`,
- * so the builder role needs no npm on the host.
+ * with them the agent's `resolveNpm()` finds npm beside the vendored `node`, so
+ * the builder role needs no npm on the host.
  *
- * This module has no imports so that repository tooling can read the list:
+ * No imports, so repository tooling can read the list:
  * `scripts/lib/node-dist.mjs` (the standalone package builder) keeps its own
  * copy, and its test pins the two lists equal.
  */

package/dist/agent-packaging/refresh.d.ts

@@ -1,12 +1,11 @@
 /**
- * Auto-refresh of version-keyed agent payloads on `orchestrator upgrade`.
+ * Auto-refresh of version-keyed agent payloads on `orchestrator upgrade`
+ * (auto-deploy ⟹ auto-upgrade ⟹ auto-package).
  *
- * The automation-completeness principle: auto-deploy ⟹ auto-upgrade ⟹
- * auto-package. After the orchestrator is upgraded to version V, this hook
- * produces + uploads `agent-packages/V/kici-agent-<platform>.tar.gz(.sha256)`
- * for the platforms the fleet already runs, so the convergence gate finds the
- * bytes it needs with no separate operator step. Idempotent: a platform whose
- * payload already exists for V is skipped, so a re-run is a no-op.
+ * After an upgrade to version V, produces + uploads
+ * `agent-packages/V/kici-agent-<platform>.tar.gz(.sha256)` for the fleet's platforms, so the
+ * convergence gate finds its bytes with no operator step. Idempotent: an existing payload for V
+ * is skipped.
  */
 import { AgentPlatform } from '@kici-dev/shared';
 import { type AgentPackageDownloadStorage } from './download.js';
@@ -31,18 +30,15 @@ export interface RefreshResult {
     skipped: AgentPlatform[];
 }
 /**
- * The platforms the fleet already has payloads for — the union across every
- * version present in the store EXCEPT `excludeVersion` (the just-upgraded
- * target, whose payloads we are about to (re)produce). Preserves the fleet's
- * arch coverage across an upgrade. Empty ⇒ the caller falls back to the
- * bootstrap default set.
+ * The platforms the fleet has payloads for: the union across every stored version EXCEPT
+ * `excludeVersion` (the target about to be (re)produced), preserving arch coverage across an
+ * upgrade. Empty ⇒ the caller falls back to the bootstrap default set.
  */
 export declare function discoverFleetPlatforms(storage: RefreshStorage, excludeVersion: string): Promise<AgentPlatform[]>;
 /**
- * Produce + upload the target version's payloads for the fleet's platform set,
- * skipping any already present (idempotent). Explicit `platforms` override the
- * discovery; otherwise the fleet's existing arch coverage is preserved, falling
- * back to the bootstrap default (`AgentPlatform.options`) on a fresh store.
+ * Produce + upload the target version's missing payloads. Explicit `platforms` override
+ * discovery; otherwise the fleet's arch coverage is kept, or the bootstrap default
+ * (`AgentPlatform.options`) on a fresh store.
  */
 export declare function refreshAgentPackages(storage: RefreshStorage, version: string, opts: {
     platforms?: AgentPlatform[];

package/dist/agent-packaging/store.d.ts

@@ -4,12 +4,11 @@ import type { AgentPackageDownloadStorage } from './download.js';
 /**
  * Resolve the agent-package store the bring-up presign handler reads from.
  *
- * Defaults to the orchestrator's OWN cache bucket (`cacheStorage`) — never a
- * vendor CDN. An `s3://bucket[/prefix]` override (`KICI_AGENT_BINARY_SOURCE`)
- * points the presign at another bucket on the SAME S3 endpoint (the customer
- * supply-chain mirror); the config schema already rejects an http(s) source so
- * no external HTTP default can slip in. Returns undefined when no cache storage
- * is configured and no override is set (the presign RPC then refuses loudly).
+ * Defaults to the orchestrator's OWN cache bucket, never a vendor CDN. An
+ * `s3://bucket[/prefix]` override (`KICI_AGENT_BINARY_SOURCE`) points at another
+ * bucket on the SAME S3 endpoint (a customer supply-chain mirror); the config
+ * schema rejects an http(s) source. Undefined when neither is set, so the
+ * presign RPC refuses loudly.
  */
 export declare function resolveAgentPackageStore(config: AppConfig, cacheStorage: CacheStorage | undefined): AgentPackageDownloadStorage | undefined;
 //# sourceMappingURL=store.d.ts.map

package/dist/agent-packaging/upload.d.ts

@@ -8,10 +8,9 @@ export declare const AGENT_PACKAGES_PREFIX = "agent-packages/";
 /** Cache-bucket key for a version-keyed agent payload. */
 export declare function agentPackageKey(version: string, platform: AgentPlatform): string;
 /**
- * Parse an `agent-packages/<version>/kici-agent-<platform>.tar.gz` key back into
- * its version + platform, or null when the key is not a payload tarball (e.g. a
- * `.sha256` sidecar or an unrelated key). Used to discover the fleet's platform
- * set from the store on upgrade.
+ * Parse a payload key back into its version and platform; null for any other key
+ * (a `.sha256` sidecar, an unrelated key). Discovers the fleet's platform set
+ * from the store on upgrade.
  */
 export declare function parseAgentPackageKey(key: string): {
     version: string;

package/dist/app.d.ts

@@ -91,9 +91,6 @@ import type { VariableStore } from './contexts/variable-store.js';
 import type { HeldRunStore, ReleaseSignal } from './contexts/held-runs.js';
 import type { StepApprovalBridge } from './approvals/step-approval-bridge.js';
 import { AgentMetricsAggregator } from './metrics/agent-metrics-aggregator.js';
-/**
- * All dependencies needed to create the orchestrator Hono app.
- */
 export interface AppDependencies {
     config: AppConfig;
     db: Kysely<Database>;

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

@@ -4,28 +4,23 @@ import { HoldOutcome } from '../pipeline/security-hold-check.js';
 import type { HeldRunStore, ReleaseSignal } from '../contexts/held-runs.js';
 import { type TeamMembershipLookup } from './approval-resolver.js';
 /**
- * The access-log action a held-run decision is audited under.
- *
- * A `kici run --approve-all` breakglass approval audits as
- * `held_run.auto_approve`, so the trail shows "auto-approved by the dispatcher"
- * apart from an interactive approve. The marker only renames the record:
- * eligibility is enforced the same way for both. It never applies to a reject.
- * Every approving surface takes its action from here, so the Platform-relayed
- * and the direct admin-route approvals cannot audit the same act two ways.
+ * The access-log action a held-run decision is audited under. A
+ * `kici run --approve-all` breakglass approval audits as `held_run.auto_approve`
+ * to set it apart from an interactive approve; eligibility is enforced the same
+ * for both, and a reject never gets it. Every approving surface takes its action
+ * from here, so Platform-relayed and admin-route approvals audit one act one way.
  */
 export declare function heldRunDecisionAction(decision: ApprovalDecision, autoApprove: boolean): AccessLogAction;
 /** 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. */
+    /** False when a step of the consequence chain 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). */
+    /** Whether the decision was recorded. */
     accepted: boolean;
-    /** Human-readable status: 'released' | 'rejected' | 'pending' | 'ineligible' | 'not-found'. */
     status: 'released' | 'rejected' | 'pending' | 'ineligible' | 'not-found';
     /** When still pending, how many clauses remain unsatisfied. */
     remainingClauses?: number;
@@ -34,26 +29,20 @@ export interface ApplyDecisionResult {
     /** 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`).
+     * The post-commit consequence — already running, deliberately not awaited.
+     * Present on `released` and `rejected`; absent when nothing changed.
      *
-     * 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.
+     * It NEVER rejects: a throw is logged and surfaces as `{ ok: false, error }`,
+     * so a caller may leave it unawaited. A caller answering a waiting client
+     * answers first and attaches its audit record to this, so the record carries
+     * the real outcome rather than a guess. A test or 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.
+     * Awaiting it made an approve spend nine-plus seconds behind a ten-second
+     * relay budget and answer 504 on an approval that had landed. Awaiting adds no
+     * strength: the resume is the same dispatch the original webhook ran with no
+     * client waiting, `dispatchMatchedWorkflow` returning means only that jobs
+     * were routed, and `resumeWorkflow` reports its own failures on the run row
+     * and the provider's check runs.
      */
     consequence?: Promise<DecisionConsequenceResult>;
 }
@@ -83,34 +72,28 @@ export interface ApplyDecisionDeps {
     onStepReject?: (heldRunId: string, reason?: string) => Promise<void> | void;
     /**
      * 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 pending workflow context. The rejecter's reason becomes the run's
+     * cancellation reason: this serves the install gate, the trust policy's
+     * PR-wide hold and the SDK's workflow `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.
+     * The row tells those apart: only some posted a pending `KiCI Security` check.
+     * Resolves to whether a terminal security check was WRITTEN, so this applier
+     * suppresses its own post only when one 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
+     * Terminalize the `KiCI Security` check of every hold this applier ends that
+     * `onWorkflowReject` did not already report. Without it a job-scoped hold
+     * answered from the dashboard strands its check: the row leaves `pending`, so
+     * the stale detector's pending-only approval-window sweep never reaches 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.
+     * `actorSub` is an opaque subject id a contributor cannot read; the wiring
+     * site resolves it to a display name (or drops it), since only it holds the
+     * org's identity directory. Omitted where the summary must match one a
+     * delegate built without it; see the reject arm below.
      */
     settleSecurityCheck?: (args: {
         hold: HeldRun;

package/dist/approvals/approval-resolver.d.ts

@@ -1,14 +1,9 @@
 /**
- * Pure approval-clause evaluator. No DB access, no I/O — given a requirement,
- * a team-membership lookup, the recorded decisions, and (for eligibility) the
- * run's triggerer + the self-approval policy, it answers:
- *
- * - `evaluate` — is the requirement satisfied (all clauses ANDed), and was it
- *   rejected (any single reject decision)?
- * - `canApprove` — may a given actor cast an approve decision right now?
- *
- * Both the dashboard handler and the CLI HTTP route funnel through these so the
- * authorization story is identical regardless of the surface.
+ * Pure approval-clause evaluator (no DB, no I/O). `evaluate` answers whether a
+ * requirement is satisfied (all clauses ANDed) or rejected (any reject);
+ * `canApprove` whether an actor may cast an approve now. The dashboard handler
+ * and the CLI HTTP route both funnel through these, so authorization is
+ * identical on every surface.
  */
 import type { ApprovalRequirement, ApproverClause } from '@kici-dev/engine';
 /** A team name → set of member user ids (Keycloak subs). */
@@ -32,16 +27,11 @@ export interface EvaluationResult {
     rejected: boolean;
     perClause: PerClauseResult[];
 }
-/**
- * Is a single clause satisfied by any approve decision whose approver is
- * eligible for the clause? Reject decisions never satisfy.
- */
+/** Satisfied by any approve from an eligible approver; rejects never satisfy. */
 export declare function isClauseSatisfied(clause: ApproverClause, decisions: RecordedDecision[], lookup: TeamMembershipLookup): boolean;
-/** Does an actor satisfy/qualify for a clause (team membership or exact user)? */
+/** Team membership or exact user match. */
 export declare function isActorEligibleForClause(actorSub: string, clause: ApproverClause, lookup: TeamMembershipLookup): boolean;
 /**
- * Evaluate a requirement against the recorded decisions.
- *
  * - A single reject decision sets `rejected` (the caller fails the element).
  * - Empty clauses ⇒ satisfied by ANY single approve decision.
  * - Non-empty clauses ⇒ satisfied iff every clause is satisfied (AND).
@@ -54,13 +44,11 @@ export interface CanApproveContext {
     allowSelfApproval: boolean;
 }
 /**
- * May `actorSub` cast an approve decision on this requirement right now?
- *
- * - Self-approval gate: when `allowSelfApproval` is false and the actor is the
- *   run's triggerer, they may never approve.
+ * - Self-approval gate: when `allowSelfApproval` is false, the run's triggerer
+ *   may never approve.
  * - Eligibility: the actor must qualify for at least one still-UNSATISFIED
- *   clause. (Approving a clause that is already satisfied adds nothing.) For an
- *   empty-clause requirement, any non-triggerer-blocked actor qualifies.
+ *   clause (approving a satisfied clause adds nothing). For an empty-clause
+ *   requirement, any actor the self-approval gate passes qualifies.
  */
 export declare function canApprove(actorSub: string, requirement: ApprovalRequirement, decisions: RecordedDecision[], lookup: TeamMembershipLookup, ctx: CanApproveContext): boolean;
 //# sourceMappingURL=approval-resolver.d.ts.map