@kici-dev/orchestrator 0.1.14 → 0.1.16

package/README.md

@@ -1 +1,13 @@
-TBD
+# @kici-dev/orchestrator
+
+Customer-deployable orchestrator for the KiCI CI/CD stack. Receives webhook events (directly or via the hosted relay), matches triggers against the lock file, and dispatches jobs to connected agents — including auto-scaled ephemeral agents (containers, bare-metal, micro-VMs).
+
+You normally don't install this package directly: deploy the orchestrator with the [`kici-admin`](https://www.npmjs.com/package/kici-admin) CLI (`kici-admin orchestrator install`) or run the published container image `quay.io/kici-dev/kici-orchestrator`.
+
+Part of [KiCI](https://kici.dev) — CI/CD workflows as TypeScript code: author them with full language power, dry-run them locally, and run them on your own infrastructure.
+
+## Links
+
+- Documentation: <https://docs.kici.dev/operator/orchestrator/getting-started/>
+- Source: <https://github.com/kici-dev/kici-public/tree/main/packages/orchestrator>
+- License: AGPL-3.0-only

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

@@ -28,6 +28,8 @@ export interface MockDbOptions {
     insertReturning?: unknown;
     /** Row returned by update chains ending in .returningAll().executeTakeFirstOrThrow() or executeTakeFirst(). Default: undefined */
     updatedRow?: unknown;
+    /** Row returned by update chains ending in .returning(...).executeTakeFirst(). Default: undefined */
+    updateReturning?: unknown;
     /** Result for update .execute() calls. Default: { numUpdatedRows: 0n } */
     updateResult?: {
         numUpdatedRows: bigint;

package/dist/agent/dispatcher.d.ts

@@ -71,10 +71,40 @@ export declare class Dispatcher {
     private graceCleanupTimer;
     /** Max reconnection delay from agent config, used to derive grace period. */
     private readonly maxReconnectDelayMs;
-    /** Callback when a recovery timer expires and the job is permanently failed. */
-    private readonly onRecoveryTimeout?;
+    /**
+     * Callback fired when a job reaches a permanent dispatch-side failure:
+     * recovery window expired, re-dispatch attempts exhausted, or a
+     * scaler-managed agent was destroyed mid-execution. The receiver marks
+     * the execution-tracker job failed with the given reason.
+     */
+    private readonly onJobFailedPermanently?;
     /** Callback when a job enters recovery (starts timer). */
     private readonly onRecoveryStarted?;
+    /** Fallback ack deadline when no getAckTimeoutMs dep is wired (tests). */
+    private static readonly DEFAULT_ACK_TIMEOUT_MS;
+    /**
+     * Pending dispatch acknowledgments: armed when a job.dispatch is sent,
+     * resolved by job.ack / job.reject / job.status running / disconnect
+     * triage. On expiry the dispatch is treated as lost: requeue + disconnect.
+     */
+    private readonly pendingAcks;
+    /**
+     * Acks that arrived before their pending-ack entry was armed (the agent
+     * answered faster than the orchestrator could resolve the timeout + stamp
+     * the deadline). Keyed by jobId -> the agent that acked. Consumed by
+     * `armAckDeadline`, which then skips arming.
+     */
+    private readonly earlyAcks;
+    /** Resolve the per-job ack deadline (per-org override / cluster default). */
+    private readonly getAckTimeoutMs;
+    /** Cancel + disconnect an agent whose dispatch ack deadline expired. */
+    private readonly onAckTimeout?;
+    /**
+     * Jobs that have reached agent-side execution (a `job.status: running`
+     * arrived). Disconnect triage treats never-started jobs as safely
+     * re-dispatchable; started jobs on destroyed agents fail fast.
+     */
+    private readonly startedJobs;
     /**
      * Per-job recovery timers for jobs in 'recovering' state.
      * When an agent disconnects with in-flight jobs, each job gets a timer.
@@ -94,10 +124,14 @@ export declare class Dispatcher {
         onNoMatchingAgent?: (labels: string[], jobId: string, runId: string, excludeLabels: string[], resources?: ResourceRequest) => Promise<ScaleResult>;
         /** Max reconnection delay from agent config (default 60s). Used to derive grace period. */
         maxReconnectDelayMs?: number;
-        /** Callback when a recovery timer expires and the job is permanently failed. */
-        onRecoveryTimeout?: (agentId: string, jobId: string, runId: string) => void;
+        /** Callback fired when a job is permanently failed before/outside agent execution. */
+        onJobFailedPermanently?: (agentId: string, jobId: string, runId: string, reason: string) => void;
         /** Callback when a job enters recovery (starts timer). */
         onRecoveryStarted?: (agentId: string, jobId: string) => void;
+        /** Resolve the per-job dispatch-ack deadline (ms). Defaults to 10s. */
+        getAckTimeoutMs?: (job: QueuedJob) => Promise<number>;
+        /** Cancel + disconnect an agent whose dispatch ack deadline expired. */
+        onAckTimeout?: (agentId: string, jobId: string, runId: string) => void;
     });
     /**
      * Dispatch a job to a matching agent, or queue it if none available.
@@ -132,6 +166,54 @@ export declare class Dispatcher {
      * calling onDispatch for each.
      */
     onAgentAvailable(agentId: string): Promise<void>;
+    /** Record that a job began executing on its agent. */
+    markJobStarted(jobId: string): void;
+    /**
+     * Arm the ack deadline for a just-sent dispatch (timer + persisted row).
+     *
+     * Resolving the timeout and persisting the deadline both touch the DB, so
+     * a fast agent's job.ack can arrive before this method registers its
+     * in-memory entry. `earlyAcks` records such an ack so this method skips
+     * arming entirely instead of starting a timer that has nothing to resolve
+     * it (which would expire a dispatch the agent actually accepted).
+     */
+    private armAckDeadline;
+    /**
+     * Consume a recorded early ack for `jobId` from `agentId`. Returns true if
+     * one was pending (and removes it).
+     */
+    private consumeEarlyAck;
+    /** Clear a pending ack (answered or otherwise settled). Idempotent. */
+    private resolvePendingAck;
+    /** Handle an explicit dispatch acknowledgment (`job.ack`) from an agent. */
+    onJobAcked(agentId: string, jobId: string): void;
+    /**
+     * The ack deadline expired: the dispatch is lost. Untrack the job, then
+     * remove the unresponsive agent from the registry BEFORE requeueing, so the
+     * redispatch cannot land the job back on the very agent we are tearing down.
+     * The job is already untracked when the WS close fires, so the disconnect
+     * triage finds nothing to double-handle.
+     */
+    private handleAckExpiry;
+    /**
+     * Handle an explicit dispatch rejection (`job.reject`) from an agent.
+     * Undoes the dispatch accounting and requeues the job for another agent.
+     */
+    onJobRejected(agentId: string, jobId: string, reason: string): Promise<void>;
+    /** Remove a job from all per-agent in-memory tracking. */
+    private untrackJob;
+    /**
+     * Requeue a dispatched job for re-delivery, or fail it permanently when
+     * its attempt budget is exhausted. Returns the outcome so disconnect
+     * triage can surface failed job IDs to the caller.
+     */
+    private requeueOrFail;
+    /**
+     * Try to deliver a requeued pending job: prefer an idle matching agent
+     * (atomic claim via dispatchBoundJob), otherwise consult the scaler so a
+     * fresh agent is spawned bound to this job.
+     */
+    private redispatch;
     /**
      * Handle agent disconnect. Starts per-job recovery timers instead of
      * immediately failing jobs, giving the agent a grace period to reconnect.
@@ -141,6 +223,19 @@ export declare class Dispatcher {
      * asynchronously when recovery timers expire).
      */
     onAgentDisconnect(agentId: string): Promise<string[]>;
+    /** Drop grace-window entries owned by an agent. */
+    private cleanupGraceEntriesForAgent;
+    /**
+     * Scaler-managed agent disconnected: requeue never-started jobs, fail
+     * started ones. Returns the permanently failed job IDs.
+     */
+    private triageScalerManagedDisconnect;
+    /**
+     * Static agent disconnected: start per-job recovery timers (the agent
+     * may reconnect and reclaim). Always returns [] — failures happen
+     * asynchronously when recovery timers expire.
+     */
+    private startRecoveryForDisconnect;
     /**
      * Called when an agent completes a job (success or failure).
      * Decrements active jobs and moves the job to the grace window
@@ -197,7 +292,9 @@ export declare class Dispatcher {
     getRecoveringJobsForAgent(agentId: string): string[];
     /**
      * Restore a reconciled job into the dispatcher's in-memory tracking.
-     * Called when an agent reconnects and claims a recovering job.
+     * Called when an agent reconnects and claims a recovering job. A
+     * reconnecting agent reporting the job in-flight means it had started,
+     * so mark it started for disconnect triage.
      */
     restoreJobForAgent(agentId: string, jobId: string): void;
     /**
@@ -221,10 +318,17 @@ export declare class Dispatcher {
      *     fast-failed by the sweep on its first run.
      */
     recoverState(): Promise<void>;
+    /**
+     * Leader-gated sweep: requeue every `dispatched` row whose ack deadline
+     * passed while no coord was watching (owning coord crashed before its
+     * in-memory timer fired). Requeue is atomic (WHERE status='dispatched'),
+     * so racing coords cannot double-requeue.
+     */
+    sweepExpiredAckDeadlines(): Promise<number>;
     /**
      * Leader-gated sweep: mark every `recovering` row whose
      * `recovery_deadline < now` as `failed` and fire the per-job
-     * `onRecoveryTimeout` hook. Intended to run on the Raft leader at a
+     * `onJobFailedPermanently` hook. Intended to run on the Raft leader at a
      * fixed interval so jobs whose owning coord crashed mid-recovery
      * still reach a terminal state.
      *

package/dist/agent/registry.d.ts

@@ -36,6 +36,14 @@ export interface AgentEntry {
      * agent's labels but does not satisfy the gate).
      */
     mandatoryLabels: Set<string>;
+    /**
+     * True when this agent was spawned by a scaler backend. Scaler-managed
+     * agents are single-use: the scaler destroys them on disconnect, so they
+     * can never reconnect to reclaim recovering jobs. The dispatcher uses
+     * this to triage disconnects (requeue / fail-fast) instead of starting a
+     * recovery window that cannot succeed.
+     */
+    scalerManaged: boolean;
     /** Number of jobs currently executing on this agent. */
     activeJobs: number;
     /** Maximum concurrent jobs this agent can handle (default 1). */
@@ -92,6 +100,12 @@ interface AgentMetadata {
      * `onAgentRegistered(...)` return value.
      */
     mandatoryLabels?: string[];
+    /**
+     * True when a scaler backend spawned this agent (single-use; destroyed
+     * on disconnect). Set by `agent-handler.ts` from the presence of the
+     * scaler registration metadata.
+     */
+    scalerManaged?: boolean;
 }
 export declare class AgentRegistry {
     /** Primary: agentId -> AgentEntry */

package/dist/app.d.ts

@@ -30,6 +30,8 @@ import type { ProviderRegistry } from './provider-registry.js';
 import type { SourceCache } from './cache/index.js';
 import type { BuildCoordinator } from './cache/index.js';
 import type { DepCache } from './cache/index.js';
+import type { UserCache } from './cache/index.js';
+import type { DispatchCacheRefTracker } from './cache/index.js';
 import type { PendingBuildTracker } from './cache/index.js';
 import type { PendingInitTracker } from './cache/index.js';
 import type { PendingDynamicTracker } from './cache/index.js';
@@ -46,6 +48,8 @@ import type { PeerToPeerMessage } from '@kici-dev/engine';
 import type { AgentTokenStore } from './agent/token-store.js';
 import type { OwnershipTracker } from './agent/ownership-tracker.js';
 import type { ObserverRegistry } from './ws/observer-registry.js';
+import type { FleetAgentCollector } from './ws/fleet-agent-collector.js';
+import type { FleetTopology } from './diagnostics/fleet-topology.js';
 import type { TokenManager } from './secrets/token-manager.js';
 import type { SecretResolver } from './secrets/secret-resolver.js';
 import { type AdminRouteDeps } from './routes/admin.js';
@@ -66,6 +70,7 @@ import type { TrustStore } from './events/trust-store.js';
 import type { EnvironmentStore } from './environments/environment-store.js';
 import type { VariableStore } from './environments/variable-store.js';
 import type { HeldRunStore } from './environments/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';
 /**
@@ -89,6 +94,15 @@ export interface AppDependencies {
     buildCoordinator?: BuildCoordinator;
     /** Dep cache for dependency tarballs. Optional — requires S3 storage. */
     depCache?: DepCache;
+    /** User-facing cache (ctx.cache / declarative job-step cache). Optional — requires cache storage. */
+    userCache?: UserCache;
+    /**
+     * Server-side jobId -> user-cache-namespace store. Written at dispatch time
+     * (orchestrator-core's buildOnDispatch); read by the agent-WS handler to
+     * resolve the cache ref for `cache.user.*` requests WITHOUT trusting the wire
+     * message. Optional — absent for modes that never serve the user cache.
+     */
+    dispatchCacheRefs?: DispatchCacheRefTracker;
     /** Cache storage backend (S3) for metadata operations on upload completion. */
     cacheStorage?: CacheStorage;
     /**
@@ -121,6 +135,11 @@ export interface AppDependencies {
     tokenStore?: AgentTokenStore;
     /** Job ownership tracker for validating agent messages. Optional — requires database. */
     ownershipTracker?: OwnershipTracker;
+    /**
+     * Orchestrator-scoped collector correlating fleet.logs.request with agents'
+     * chunked bundle responses. Shared with the fleet fan-out in orchestrator-core.
+     */
+    fleetAgentCollector?: FleetAgentCollector;
     /** Admin API route dependencies. Optional -- only mounted when secrets management is configured. */
     adminDeps?: AdminRouteDeps;
     /**
@@ -159,6 +178,8 @@ export interface AppDependencies {
     variableStore?: VariableStore;
     /** Held run store for persisting protection rule holds. Optional -- if not set, holds are not persisted. */
     heldRunStore?: HeldRunStore;
+    /** Step-approval bridge — opens step-scoped holds and relays their resolution back to the waiting agent. Optional. */
+    stepApprovalBridge?: StepApprovalBridge;
     /** 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. */
@@ -204,6 +225,21 @@ export interface AppDependencies {
      * can read the same store and Mimir gets agent metrics per-org.
      */
     agentMetricsAggregator?: AgentMetricsAggregator;
+    /**
+     * Fleet log-collection route backing. `getTopology` enumerates the cluster
+     * (no fan-out); `collectBundle` drives the recursive fan-out and returns the
+     * assembled ZIP. Mounted at /admin/fleet-topology + /admin/fleet-bundle.
+     */
+    fleetRoutes?: FleetRoutesDeps;
+}
+/** Backing for the /admin/fleet-* routes. */
+export interface FleetRoutesDeps {
+    getTopology: () => FleetTopology;
+    collectBundle: (opts: {
+        selectors: string[];
+        logWindowHours?: number;
+        timeoutSeconds?: number;
+    }) => Promise<Buffer>;
 }
 /**
  * In-memory cache for step source locations extracted from lock files.

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

@@ -0,0 +1,60 @@
+/**
+ * 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 { HeldRunStore, ReleaseSignal } from '../environments/held-runs.js';
+import { type TeamMembershipLookup } from './approval-resolver.js';
+/** Outcome of applying a decision. */
+export interface ApplyDecisionResult {
+    /** Whether the decision was accepted (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;
+    /** When ineligible/not-found, a reason for the caller to surface. */
+    reason?: string;
+    /** The release signal, when the element was released (for the caller to resume). */
+    release?: ReleaseSignal;
+}
+/** Dependencies injected into `applyDecision` (testable in isolation). */
+export interface ApplyDecisionDeps {
+    orgId: string;
+    store: HeldRunStore;
+    /** Team name → member user ids (from the Plan-1 trust-policy cache). */
+    teamMembershipLookup: TeamMembershipLookup;
+    /** Whether the run triggerer may self-approve (org_settings.allow_self_approval). */
+    allowSelfApproval: boolean;
+    /** Resolve the Keycloak sub of the user who triggered a run (for the self-approval gate). */
+    resolveTriggererSub: (runId: string) => Promise<string | undefined>;
+    /** Called when a job/workflow hold is released — re-dispatch the element. */
+    onJobRelease: (signal: ReleaseSignal) => Promise<void>;
+    /** Called when a step hold is released — notify the waiting agent (approved). */
+    onStepRelease?: (signal: ReleaseSignal) => Promise<void>;
+    /**
+     * Called when a step-scoped hold is rejected — notify the waiting agent so it
+     * fails the step instead of blocking until expiry. Carries the holdId.
+     */
+    onStepReject?: (heldRunId: string, reason?: string) => Promise<void> | void;
+}
+/** Apply a single approve/reject decision to a hold. */
+export declare function applyDecision(deps: ApplyDecisionDeps, args: {
+    heldRunId: string;
+    actorSub: string;
+    decision: ApprovalDecision;
+    reason?: string;
+}): Promise<ApplyDecisionResult>;
+//# sourceMappingURL=apply-decision.d.ts.map

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

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+import type { ApprovalRequirement, ApproverClause } from '@kici-dev/engine';
+/** A team name → set of member user ids (Keycloak subs). */
+export type TeamMembershipLookup = (team: string) => Set<string>;
+/** One recorded decision row (subset of `held_run_approvals`). */
+export interface RecordedDecision {
+    approver_user_id: string;
+    decision: 'approve' | 'reject';
+}
+/** Per-clause satisfaction detail for attribution + dashboard progress. */
+export interface PerClauseResult {
+    clause: ApproverClause;
+    satisfied: boolean;
+    /** The approver who satisfied this clause, if any. */
+    by?: string;
+}
+export interface EvaluationResult {
+    /** All clauses satisfied (AND). For empty clauses: any single approve. */
+    satisfied: boolean;
+    /** Any reject decision present → the element is rejected. */
+    rejected: boolean;
+    perClause: PerClauseResult[];
+}
+/**
+ * Is a single clause satisfied by any approve decision whose approver is
+ * eligible for the clause? Reject decisions 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)? */
+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).
+ */
+export declare function evaluate(requirement: ApprovalRequirement, decisions: RecordedDecision[], lookup: TeamMembershipLookup): EvaluationResult;
+export interface CanApproveContext {
+    /** The Keycloak sub of the user who triggered the run. */
+    triggererSub: string;
+    /** Whether the triggerer may self-approve their own held elements. */
+    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.
+ * - 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.
+ */
+export declare function canApprove(actorSub: string, requirement: ApprovalRequirement, decisions: RecordedDecision[], lookup: TeamMembershipLookup, ctx: CanApproveContext): boolean;
+//# sourceMappingURL=approval-resolver.d.ts.map

package/dist/approvals/step-approval-bridge.d.ts

@@ -0,0 +1,72 @@
+import type { HeldRunStore } from '../environments/held-runs.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+/** Outcome relayed back to the waiting agent. */
+export type StepApprovalOutcome = 'approved' | 'rejected' | 'expired';
+/** Arguments to open a step-scoped approval hold. */
+export interface StepApprovalRequest {
+    agentId: string;
+    runId: string;
+    jobId: string;
+    stepIndex: number;
+    stepName: string;
+    clauses: Array<{
+        team: string;
+    } | {
+        user: string;
+    }>;
+    reason: string;
+    /** Per-gate timeout (seconds); falls back to the org default. */
+    timeoutSeconds?: number;
+}
+/** Dependencies injected into the bridge. */
+export interface StepApprovalBridgeDeps {
+    store: HeldRunStore;
+    /**
+     * Resolve the orchestrator's tenant org id (same value the dashboard handler
+     * uses to read held_runs). A function because the org is resolved post-auth
+     * for sourceless orchestrators.
+     */
+    resolveOrgId: () => string;
+    /** Resolve the authoritative approval expiry (seconds) for an org. */
+    resolveExpirySeconds: (orgId: string) => Promise<number>;
+    /**
+     * Access-log writer for the orchestrator audit stream. Optional -- if not
+     * set, the step-hold creation audit row (`held_run.request`) is skipped.
+     */
+    accessLogWriter?: AccessLogWriter;
+    /** Routing key recorded on the audit row. Optional. */
+    routingKey?: string | null;
+}
+/**
+ * Owns the step-scoped held_runs rows and the map from holdId → the waiting
+ * agent's resolver. The only place that opens a step hold and the only place
+ * that settles a step-scoped wait.
+ */
+export declare class StepApprovalBridge {
+    private readonly deps;
+    private readonly pending;
+    constructor(deps: StepApprovalBridgeDeps);
+    /**
+     * Create a step-scoped hold and return a promise that settles when the hold
+     * is approved / rejected / expired (via {@link resolve}).
+     */
+    request(req: StepApprovalRequest): Promise<{
+        outcome: StepApprovalOutcome;
+        reason?: string;
+    }>;
+    /**
+     * Settle a step-scoped wait. Called by the approve/reject applier
+     * (`onStepRelease`) and by the stale detector (`expired`). A no-op when no
+     * agent is waiting on the hold (e.g. the agent already disconnected).
+     */
+    resolve(holdId: string, outcome: StepApprovalOutcome, reason?: string): boolean;
+    /**
+     * Reject every pending wait for a disconnected agent. The held_runs rows are
+     * left as-is (the stale detector will expire them) — only the in-memory
+     * resolver is dropped so the handler's relayed `ws.send` is skipped.
+     */
+    failAgent(agentId: string): void;
+    /** Number of in-flight step-approval waits (test/diagnostics). */
+    size(): number;
+}
+//# sourceMappingURL=step-approval-bridge.d.ts.map

package/dist/approvals/team-membership-lookup.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Read-only lookup over the team memberships pushed from the Platform via
+ * `trust_policy.update`. The orchestrator has no identity store, so this is the
+ * only source of "who is in team X" — the approval resolver uses it to satisfy
+ * `{team}` approver clauses.
+ */
+export interface TeamMembershipLookup {
+    /** Returns the set of member user ids for a team name (empty if unknown). */
+    getTeamMembers(name: string): Set<string>;
+}
+/** A lookup backed by no teams — the default before any push arrives. */
+export declare const EMPTY_TEAM_MEMBERSHIP_LOOKUP: TeamMembershipLookup;
+//# sourceMappingURL=team-membership-lookup.d.ts.map

package/dist/cache/agent-job-failed-error.d.ts

@@ -0,0 +1,13 @@
+import type { InitFailure } from '@kici-dev/engine';
+/**
+ * Reject reason for a pending init / dynamic-eval job the agent reported as
+ * failed. Carries the optional structured initFailure the agent attached to
+ * job.status.data so the orchestrator catch can record the correct category
+ * instead of collapsing everything to a string.
+ */
+export declare class AgentJobFailedError extends Error {
+    readonly initFailure?: InitFailure | undefined;
+    readonly name = "AgentJobFailedError";
+    constructor(message: string, initFailure?: InitFailure | undefined);
+}
+//# sourceMappingURL=agent-job-failed-error.d.ts.map

package/dist/cache/dispatch-cache-ref-tracker.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Server-side record of the user-cache namespacing for each dispatched job.
+ *
+ * The user-facing cache is namespaced by `{orgId, repoId, cacheRefScope, runId}`.
+ * Those values are decided by the orchestrator at dispatch time (lifted onto the
+ * `job.dispatch` message). The agent later sends `cache.user.*` requests that
+ * carry ONLY a `jobId` + `key` — never the namespacing — so the WS handler must
+ * resolve the namespace from a trusted server-side store keyed by jobId. This
+ * tracker is that store: a wire `cache.user.*` message can name a `jobId`, but it
+ * can never influence the org/repo/scope the orchestrator resolves for it.
+ *
+ * The map is written when a job is dispatched, read on every `cache.user.*`
+ * request, and deleted when the job completes or its agent disconnects (mirroring
+ * the dispatcher's own per-job cleanup lifecycle) so it cannot leak.
+ */
+import type { CacheRefScope } from '@kici-dev/engine';
+/** Cache namespacing recorded for a dispatched job. */
+export interface DispatchCacheRef {
+    /** Org that owns the run — the per-tenant cache isolation boundary. Absent for sourceless deploys. */
+    orgId?: string;
+    /** Repo identifier (e.g. "owner/repo") — second namespacing level. Absent for sourceless deploys. */
+    repoId?: string;
+    /** Write scope: `shared` (trusted ref) or `isolated` (untrusted ref, per-run scope). */
+    cacheRefScope?: CacheRefScope;
+    /** Run id — the per-run isolation namespace for `isolated`-scope writes. */
+    runId: string;
+}
+/**
+ * In-memory `jobId -> DispatchCacheRef` map populated at dispatch time and
+ * consumed by the agent WS handler to resolve a `UserCacheRef` server-side.
+ */
+export declare class DispatchCacheRefTracker {
+    private readonly refs;
+    /** Record the cache namespacing for a dispatched job. */
+    record(jobId: string, ref: DispatchCacheRef): void;
+    /** Resolve the cache namespacing for a job, or `undefined` if it was never dispatched / already cleaned up. */
+    get(jobId: string): DispatchCacheRef | undefined;
+    /** Drop a job's recorded ref (on completion or agent disconnect). */
+    delete(jobId: string): void;
+    /** Drop every recorded ref (test/teardown helper). */
+    clear(): void;
+    /** Number of currently-tracked dispatches (leak assertions in tests). */
+    get size(): number;
+}
+//# sourceMappingURL=dispatch-cache-ref-tracker.d.ts.map

package/dist/cache/index.d.ts

@@ -9,6 +9,8 @@
 export { SourceCache } from './source-cache.js';
 export { BuildCoordinator } from './build-coordinator.js';
 export { DepCache } from './dep-cache.js';
+export { UserCache, DEFAULT_USER_CACHE_QUOTA_BYTES, DEFAULT_USER_CACHE_TTL_MS, type UserCacheRef, type UserCacheRestoreResult, type UserCacheBeginSaveResult, type UserCacheOrgLimits, type UserCacheOrgLimitsReader, } from './user-cache.js';
+export { DispatchCacheRefTracker, type DispatchCacheRef } from './dispatch-cache-ref-tracker.js';
 export { PendingBuildTracker } from './pending-builds.js';
 export { PendingInitTracker } from './pending-inits.js';
 export type { InitResult } from './pending-inits.js';