@kici-dev/orchestrator 0.5.0 → 0.6.0

package/dist/scaler/warm-pool.d.ts

@@ -1,79 +1,182 @@
 /**
  * Warm pool manager for pre-provisioned idle agents.
  *
- * Tracks idle agents per label set, handles idle timeout expiry,
- * and triggers replenishment when a warm agent is consumed.
- * Uses callback pattern to avoid circular dependencies with ScalerManager.
+ * Each configured label set has a target `size`. On every tick the manager asks
+ * the agent registry how many agents could already serve a job with those
+ * labels, subtracts the spawns it has issued but not yet seen register, and
+ * starts the difference. It holds no list of its own: the agent registry is the
+ * single source of truth for what is ready, which is also what the dispatcher
+ * reads, so the two can never disagree.
+ *
+ * Uses a callback pattern to avoid circular dependencies with ScalerManager.
  */
 export interface WarmPoolCallbacks {
     /** Request the ScalerManager to spawn a new agent for the given label set */
     onSpawnRequest: (labelSet: string[], backendName: string) => Promise<void>;
     /** Request the ScalerManager to destroy an idle agent */
     onDestroyRequest: (managedId: string, backendName: string) => Promise<void>;
+    /**
+     * How many registered agents could serve a job with this label set right
+     * now. Backed by `AgentRegistry.findAvailable`, which is the same query the
+     * dispatcher uses — so the warm pool and the dispatcher can never disagree
+     * about what "ready" means.
+     *
+     * A static agent that matches the labels counts: it removes the need for a
+     * warm one just as well as a spawned agent does.
+     */
+    countAvailable: (labels: string[]) => number;
+    /**
+     * Agents this backend spawned that match the label set and have never run a
+     * job, with the timestamp they registered at. `registeredAt` doubles as
+     * "idle since": scaler agents are single-use, so an agent still registered
+     * with no active job has been idle since it came up.
+     *
+     * Scoped to the backend because the result feeds the reaper, and the reaper
+     * destroys what it is given. A static agent that happens to match the labels
+     * is ready capacity, not this pool's to tear down.
+     */
+    listIdle: (labels: string[], backendName: string) => Array<{
+        agentId: string;
+        registeredAt: number;
+    }>;
+    /**
+     * How many more agents this backend may still start before it reaches the
+     * scaler's `maxAgents` or the orchestrator's `globalMaxAgents`, whichever
+     * binds first. The deficit is clamped to it, so a pool that cannot reach its
+     * target stops asking instead of issuing a spawn the caps refuse every tick.
+     */
+    capacityRemaining: (backendName: string) => number;
+    /**
+     * Called at the end of each tick, once the reap and the deficit pass have
+     * run. The ScalerManager publishes the warm-pool gauges from it, so they
+     * follow the pool rather than the scrape.
+     */
+    onTick?: () => void;
+}
+/** One label set's fill state, as the warm-pool metrics report it. */
+export interface WarmPoolStats {
+    /**
+     * The pool's identity: its normalized DECLARED label set, which is the
+     * `configs` map key.
+     *
+     * This — not `labels` — is what a per-pool metric dimension keys on. Two
+     * pools on one scaler can widen to the SAME query set (one label set
+     * declaring the plain platform label the other only gets from the taint), so
+     * a dimension built from `labels` collapses them into one series and silently
+     * drops a pool's fill state.
+     */
+    key: string;
+    /** The widened query set the `ready` count was measured with. */
+    labels: string[];
+    backendName: string;
+    target: number;
+    ready: number;
+    inFlight: number;
 }
 export declare class WarmPoolManager {
     private readonly callbacks;
-    /** Pools of idle agents keyed by normalized label set string */
-    private readonly pools;
     /** Configuration per normalized label set */
     private readonly configs;
-    /** Periodic idle check interval */
+    /**
+     * Warm spawns issued but not yet registered, per normalized label set.
+     *
+     * Load-bearing: without it, two passes landing before the first spawn
+     * registers would each see the full deficit and issue `size` spawns apiece.
+     */
+    private readonly inFlight;
+    /** Periodic deficit + idle check interval */
     private idleCheckInterval;
     constructor(callbacks: WarmPoolCallbacks);
     /**
      * Configure the warm pool for a label set.
      * Called during ScalerManager initialization based on YAML config.
+     *
+     * `normalizedLabels` keys the pool by its DECLARED label set, which is what
+     * every in-flight release path normalizes back to.
      */
     configure(normalizedLabels: string, backendName: string, config: {
         size: number;
         idleTimeoutSeconds: number;
         labels: string[];
+        spawnLabels: string[];
     }): void;
     /**
-     * Add an agent to the warm pool.
-     * Called when a freshly spawned warm pool agent has registered but has no job.
-     */
-    addIdleAgent(normalizedLabels: string, managedId: string, backendName: string): void;
-    /**
-     * Consume an agent from the warm pool for the given label set.
-     * Returns the managedId (FIFO order) or null if pool is empty.
-     * After consuming, schedules replenishment on next tick.
+     * One deficit pass. For each configured label set, top the pool up to its
+     * target: `size - ready - inFlight`, clamped by the backend's remaining cap
+     * headroom.
+     *
+     * The per-backend budget is tracked across the whole pass: two label sets on
+     * one scaler draw from the same `maxAgents`, so clamping each against the
+     * same starting headroom would let them jointly overshoot it.
      */
-    consumeAgent(normalizedLabels: string): string | null;
+    evaluate(): void;
+    /** A warm spawn registered: release its in-flight slot. */
+    onWarmAgentRegistered(labels: string[]): void;
     /**
-     * Check if pool is below configured size and request spawns for the deficit.
+     * A warm spawn failed, timed out, or was pruned as never-registered: release
+     * its in-flight slot so the next pass retries it. Without this the slot is
+     * held forever and the pool sits permanently below target.
      */
-    replenish(normalizedLabels: string): void;
+    onWarmSpawnFailed(labels: string[]): void;
+    private releaseInFlight;
+    /** Per-label-set fill state, for the warm-pool metrics. */
+    getStats(): WarmPoolStats[];
     /**
-     * Start periodic idle check (every 30 seconds).
-     * Destroys agents that have been idle past their timeout.
+     * Start the periodic tick: reap surplus agents past their idle timeout, then
+     * top the pools back up.
+     *
+     * The first pass runs immediately rather than a tick later. Both hosts call
+     * this only after `ensureHostsReady()`, so spawning here is safe — and
+     * waiting would leave the pool empty for 30 seconds after every restart,
+     * which is precisely the cold start it exists to remove.
      */
     start(): void;
     /**
-     * Stop the periodic idle check interval.
+     * Stop the periodic tick.
      */
     stop(): void;
     /**
-     * Return current warm pool count for a label set.
-     */
-    getPoolSize(normalizedLabels: string): number;
-    /**
-     * Return total warm agents across all pools.
+     * Total ready agents across every configured pool. Surfaced by
+     * `getStatus().warmPoolCount`.
      */
     getTotalPoolSize(): number;
     /**
-     * Update configs. Drain excess agents from pools that shrunk.
-     * Does NOT remove agents from pools whose config was removed --
-     * let idle timeout handle that gracefully.
+     * Update configs. Destroy surplus agents in pools that shrunk, and drop
+     * pools whose config disappeared (the scaler was removed from the config,
+     * or its `warmPool.enabled` flipped to false) — a warm agent must not
+     * outlive the config that asked for it.
      */
     reload(newConfigs: Map<string, {
         backendName: string;
         size: number;
         idleTimeoutSeconds: number;
         labels: string[];
+        spawnLabels: string[];
     }>): void;
     /**
-     * Check for idle agents past their timeout and destroy them.
+     * Destroy this pool's idle agents beyond `keep`, oldest first.
+     *
+     * Oldest-first because the survivors are the ones with the most time left
+     * before the idle reaper takes them, which is the set an arriving job is
+     * most likely to find still ready.
+     */
+    private destroyIdle;
+    /**
+     * Destroy agents that are BOTH surplus to the pool's target AND idle past
+     * its timeout. `registeredAt` is the idle-since stamp: scaler agents are
+     * single-use, so an agent still registered with no active job has never run
+     * one.
+     *
+     * The target check is what stops the pool churning against itself. Reaping
+     * on age alone means a quiet pool destroys its own agent every
+     * `idleTimeoutSeconds` and immediately re-spawns it: the provisioning
+     * workflow runs forever on zero traffic, and — because an event-backend
+     * replacement takes minutes to boot — the pool is below target for much of
+     * every cycle. A warm pool that is cold most of the time is worse than none.
+     * So the timeout trims surplus only: a pool sitting at `size` never reaps.
+     *
+     * `size: 0` still drains, because then every ready agent is surplus.
+     *
      * Exposed for testing.
      */
     checkIdleTimeouts(): void;

package/dist/security/comment-handler.d.ts

@@ -5,9 +5,11 @@
  * approval/rejection of security holds. Verifies commenter identity
  * via the trust policy cache and checks ci_trust:write+ before acting.
  */
-import type { HeldRunStore } from '../contexts/held-runs.js';
-import { type IdentityLink, type PermissionLevel } from './trust-resolver.js';
-import type { CheckStatusPoster as EngineCheckStatusPoster } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type { HeldRunStore, ReleaseSignal } from '../contexts/held-runs.js';
+import type { Database, HeldRun } from '../db/types.js';
+import { type IdentityLink, type PermissionLevel } from './identity-link.js';
+import { type ResolveCheckStatusPoster } from '../pipeline/security-hold-check.js';
 /** Parsed /kici command from a comment body. */
 interface CommentCommand {
     action: 'approve' | 'reject';
@@ -19,9 +21,8 @@ export interface HandleApprovalCommentParams {
     commentBody: string;
     commenterUsername: string;
     /**
-     * Commenter immutable IDP-side numeric id from the webhook event. Used to
-     * match the identity link by id first, falling back to username during the
-     * backfill window (see trust-resolver.findIdentityLink).
+     * Commenter immutable IDP-side numeric id from the webhook event. The only
+     * field an identity link is matched on (see `identity-link.findIdentityLink`).
      */
     commenterUserId?: string;
     provider: string;
@@ -31,11 +32,49 @@ export interface HandleApprovalCommentParams {
     identityLinks: IdentityLink[];
     orgMemberPermissions: Map<string, PermissionLevel>;
     heldRunStore: HeldRunStore;
-    /** Check status poster for updating GitHub checks after approval/rejection. */
-    checkStatusPoster?: EngineCheckStatusPoster;
-    /** Commit SHA for the PR head (needed for check status updates). */
-    commitSha?: string;
-    credentials: unknown;
+    /**
+     * Orchestrator database, for resolving each ended hold's own commit and the
+     * other holds still pending on it. Optional so a store-less deployment still
+     * processes the command.
+     */
+    db?: Kysely<Database> | undefined;
+    /**
+     * Resolve the check poster of the provider bundle serving a routing key, so
+     * an ended hold's `KiCI Security` check can be terminalized on the commit the
+     * hold's own run acted on — which is not necessarily the PR head at comment
+     * time, and posting on the head would create a second check run there while
+     * leaving the real one pending.
+     */
+    resolvePoster?: ResolveCheckStatusPoster;
+    /**
+     * Resume a job whose security hold was just approved, by re-dispatching it.
+     *
+     * Approving must RUN the gated work, not merely flip the row and post a green
+     * check. The signal is routed through the same `routeRelease` the dashboard
+     * applier and the stale detector use, so a job-scoped hold lands here and a
+     * workflow-scoped one lands on `onWorkflowRelease`. Optional so an
+     * orchestrator without the dispatch wiring degrades to flip-and-report rather
+     * than failing the comment.
+     */
+    onJobRelease?: (signal: ReleaseSignal) => Promise<void>;
+    /**
+     * Resume a workflow-scoped hold that was just approved, by replaying its
+     * stored dispatch context. This is the path the org trust policy's PR-wide
+     * hold takes: it fires before any job is materialized, so there is no job to
+     * re-dispatch.
+     */
+    onWorkflowRelease?: (signal: ReleaseSignal) => Promise<void>;
+    /**
+     * Cancel a workflow-scoped hold that was just rejected, dropping its stored
+     * dispatch context. Without it a rejected PR-wide hold leaves its run alive in
+     * `held` forever and strands the context row that would have replayed it.
+     *
+     * It also completes the hold's `KiCI Security` check and resolves to whether
+     * it actually wrote one, so this handler reports only the holds no write
+     * covered — suppression bound to a check being written, not to a delegate
+     * resolving.
+     */
+    onWorkflowReject?: (hold: HeldRun, reason: string) => Promise<boolean>;
 }
 /** Result of handling a comment. */
 interface HandleApprovalResult {

package/dist/security/identity-link.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Identity-link lookup: map a provider identity from a webhook event onto the
+ * KiCI user the Platform linked it to.
+ *
+ * The comment-approval path uses this to decide whether a `/kici approve`
+ * commenter is a linked member with a high enough `ci_trust` level.
+ */
+import type { CiTrustLevel } from '@kici-dev/engine';
+/**
+ * RBAC permission levels from the Platform permission system.
+ *
+ * The same four values the wire schema carries for `memberCiTrustLevels`, so
+ * this aliases {@link CiTrustLevel} rather than restating them — a member's CI
+ * trust level IS the permission level this module's callers compare against.
+ */
+export type PermissionLevel = CiTrustLevel;
+/** Identity link mapping a provider identity to a KiCI user. */
+export interface IdentityLink {
+    userId: string;
+    provider: string;
+    providerUsername: string;
+    /**
+     * Immutable IDP-side numeric id (e.g. GitHub's `sender.id`). The only field
+     * a link is matched on; a link that carries no id can never match, so it
+     * grants nothing.
+     */
+    providerUserId?: string | null;
+}
+/**
+ * The provider username the org's identity directory links a KiCI user id to,
+ * or undefined when it names none unambiguously.
+ *
+ * The reverse of {@link findIdentityLink}: that maps a provider identity onto a
+ * KiCI user, this maps a KiCI user back onto a name a human recognises. Used
+ * where a decision made in the dashboard / CLI / MCP — which carries only the
+ * actor's opaque subject id — has to be attributed in copy a contributor reads
+ * on a public commit check.
+ *
+ * A user may hold links on several providers. When they agree on the username
+ * the answer is unambiguous; when they disagree there is no way to tell here
+ * which provider serves the commit, so this answers undefined rather than
+ * naming the wrong account. Undefined is a safe answer at every call site: the
+ * attribution is simply omitted, never replaced by the raw subject id.
+ */
+export declare function resolveLinkedUsername(identityLinks: IdentityLink[], userId: string): string | undefined;
+/**
+ * Match an identity link strictly by `(provider, providerUserId)`.
+ *
+ * Returns `null` whenever the numeric id is missing on either side or when no
+ * link's id matches the event's id. Matching by username is not supported, so
+ * renaming a provider account cannot be used to impersonate a linked member.
+ * A refused match is recorded under
+ * `kici_orch_trust_match_refused_no_id_total{reason}` so the rate of refusals
+ * stays observable.
+ *
+ * Pre-condition for callers: the Platform has filled `provider_user_id` for
+ * every row it pushes in `identity_links` — a row without one is inert here.
+ */
+export declare function findIdentityLink(identityLinks: IdentityLink[], provider: string, providerUsername: string, providerUserId: string | undefined): IdentityLink | null;
+//# sourceMappingURL=identity-link.d.ts.map

package/dist/security/lock-source.d.ts

@@ -4,11 +4,10 @@
  * For pull-request events, the orchestrator must decide whether to fetch
  * the workflow lock file from the PR head branch (the contributor's
  * proposed change) or from the base branch (the protected target). Only
- * trusted contributors get their HEAD lock evaluated; everyone else
+ * a trusted ref gets its HEAD lock evaluated; everything else
  * (unknown / known / undefined trust resolution) falls back to the base
- * branch's lock so an untrusted contributor cannot inject triggers,
- * jobs, or environment claims that the project's maintainers haven't
- * vetted.
+ * branch's lock so a fork ref cannot inject triggers, jobs, or
+ * environment claims that the project's maintainers haven't vetted.
  *
  * The default for non-PR events is HEAD, because there is no untrusted
  * "incoming" contribution to gate against — push events come directly
@@ -19,16 +18,15 @@ import type { TrustTier } from '@kici-dev/engine';
  * Select which branch's lock file to fetch.
  *
  * Invariant (customer-isolation): for any pull-request event, an
- * untrusted contributor (`tier === 'unknown' | 'known' | undefined`)
- * MUST NOT have their HEAD lock file evaluated by the orchestrator.
- * The base-branch lock — controlled by the project's trusted
- * maintainers — is the source of truth for trigger evaluation,
- * trust-tier-based environment access, and contributor-controlled
- * fields that downstream secret resolution depends on.
+ * untrusted ref (`tier === 'unknown' | 'known' | undefined`) MUST NOT
+ * have its HEAD lock file evaluated by the orchestrator. The
+ * base-branch lock — controlled by the project's trusted maintainers —
+ * is the source of truth for trigger evaluation, trust-tier-based
+ * environment access, and contributor-controlled fields that downstream
+ * secret resolution depends on.
  *
- * Only `tier === 'trusted'` (an identity-linked contributor with
- * provider write+ permission AND ci_trust write+ permission, per
- * `TrustResolver.resolveTrustTier`) can have their HEAD lock evaluated.
+ * Only `tier === 'trusted'` (a ref that lives in the base repo, per
+ * `resolveRefTrust`) can have its HEAD lock evaluated.
  */
 export declare function selectLockFileSource(isPREvent: boolean, tier: TrustTier | undefined): 'head' | 'base';
 //# sourceMappingURL=lock-source.d.ts.map

package/dist/security/reduced-privilege-note.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The one rendering of a run's reduced-privilege posture, for the provider
+ * checks a contributor reads on a pull request.
+ *
+ * It lives beside `trust-resolver.ts` and `lock-source.ts` — the two modules
+ * that decide the values it reads — rather than in the pipeline, because both
+ * the dispatch pipeline and the check-run reporter render it and
+ * `pipeline/processor.ts` already imports from `reporting/`.
+ */
+/**
+ * Lead-in of the reduced-privilege note. Exported so every surface that renders
+ * it, and their tests, name one string rather than a copy each.
+ */
+export declare const REDUCED_PRIVILEGE_MARKER = "**Reduced privileges (untrusted ref).**";
+/**
+ * The reduced-privilege posture of a run whose ref resolved to a tier other
+ * than `trusted`.
+ *
+ * Attach it only where the run the check describes actually executes. It is NOT
+ * attached to the trust-policy REJECTION: that run is never dispatched, so on
+ * that check the clauses below are vacuously true and read as a promise about a
+ * run that will not happen. The trust-policy HOLD does carry it — approving one
+ * replays the dispatch under the same trust resolution, so the reductions the
+ * clauses name are the ones the resumed run really runs under. Storing a resume
+ * context is not by itself the trigger: `holdWorkflowForInstallGate` stores one
+ * and posts no check at all, so it has nothing to attach the note to. See the
+ * call sites in `dispatch-matched-workflow.ts` for which checks a resuming hold
+ * actually posts.
+ *
+ * Returns null for a trusted ref and for a run whose trust never resolved. An
+ * absent tier is deliberately NOT treated as untrusted: `isUntrustedTier` in
+ * `install-secrets-resolver.ts` reads it leniently and leaves the install
+ * secrets in place, so a run with no tier has no withholding to report. The
+ * predicate for a resolved tier is "other than `trusted`", matching
+ * `isUntrustedTier` and `selectLockFileSource`. `deriveCacheRefScope` is
+ * stricter — it isolates an absent tier too — so an unresolved run's cache
+ * really is isolated while this note stays silent about it. Under-reporting is
+ * the safe direction: the note never claims a reduction that did not happen.
+ *
+ * Each clause names something already decided for THIS run rather than a
+ * mechanism:
+ *
+ * - `resolveInstallSecrets` returns `npmRegistries: undefined` and
+ *   `installEnvSecrets: undefined` for a resolved non-trusted tier, so the run
+ *   carries neither.
+ * - `deriveCacheRefScope` returns the isolated scope for the same tiers, and
+ *   `UserCache` confines WRITES to it; a restore still falls back to the shared
+ *   scope, so the clause is about what the run saves, not what it can read.
+ * - the base-branch clause is keyed on the run's recorded `lockFileSource`, not
+ *   on the tier: `selectLockFileSource` returns `base` only for a pull-request
+ *   event, and an untrusted tier also reaches an internal-event child run that
+ *   inherited it.
+ *
+ * Kept in step with the dashboard's reduced-privilege banner
+ * (`packages/dashboard/src/components/run-detail/degraded-run-banner.tsx`),
+ * which describes the same run and may be read beside these checks.
+ */
+export declare function buildReducedPrivilegeNote(tier: string | null | undefined, lockFileSource?: string | null): string | null;
+//# sourceMappingURL=reduced-privilege-note.d.ts.map