@kici-dev/orchestrator 0.1.26 → 0.2.0

package/dist/worker/in-memory-job-queue.d.ts

@@ -20,9 +20,13 @@ export declare class InMemoryJobQueue {
     enqueue(input: QueuedJobInput): Promise<string>;
     /**
      * Returns a generated UUID for direct-dispatch tracking, or honors the
-     * caller's pre-allocated jobId when set (cluster reroute path).
+     * caller's pre-allocated jobId when set (cluster reroute path). The in-memory
+     * queue has no unique-key constraint, so an insert is always treated as new.
      */
-    insertDispatched(input: QueuedJobInput): Promise<string>;
+    insertDispatched(input: QueuedJobInput, _agentId: string): Promise<{
+        id: string;
+        inserted: boolean;
+    }>;
     /**
      * Dequeue the first pending job matching the given labels.
      *
@@ -111,12 +115,13 @@ export declare class InMemoryJobQueue {
     /** Always returns false. */
     markFailedIfRecovering(_jobId: string, _reason: string): Promise<boolean>;
     /** Always returns false. */
-    markDispatchedIfRecovering(_jobId: string): Promise<boolean>;
+    markDispatchedIfRecovering(_jobId: string, _agentId: string): Promise<boolean>;
     /** Always returns empty array. */
     getJobsByStatus(_status: DispatchQueueStatus): Promise<Array<{
         id: string;
         runId: string;
         status: DispatchQueueStatus;
+        agentId: string | null;
     }>>;
     /** No-op — nothing to expire. */
     markExpired(): Promise<number>;

package/dist/worker-core.d.ts

@@ -40,6 +40,7 @@ import { StepLogBuffer } from './reporting/step-log-buffer.js';
 import { ObserverRegistry } from './ws/observer-registry.js';
 import { ScalerManager } from './scaler/index.js';
 import type { ScalerConfig } from './scaler/index.js';
+import type { WorkerClusterSettings } from '@kici-dev/engine';
 /**
  * Subsystems available in worker mode.
  * Subset of OrchestratorSubsystems with in-memory replacements.
@@ -61,6 +62,15 @@ interface WorkerSubsystems {
     scalerManager: ScalerManager | null;
     scalerConfig: ScalerConfig | null;
 }
+/**
+ * Resolve the ephemeral agent-token TTL a worker-spawned agent should use:
+ * the fleet-wide `agent_token_ttl_ms` pulled from the leader when a snapshot has
+ * landed, otherwise the boot-time config default. This is the single seam the
+ * worker's three scaler backends read at spawn.
+ */
+export declare function resolveWorkerAgentTokenTtlMs(pushed: {
+    settings: WorkerClusterSettings;
+} | null, fallback: number): number;
 /**
  * Bootstrap the orchestrator in worker mode.
  *

package/dist/ws/agent-api-registry.d.ts

@@ -15,6 +15,26 @@
 export type ApiRole = 'read' | 'write';
 /** Handler function for an API method. */
 export type ApiHandler = (agentId: string, params: Record<string, unknown>) => Promise<unknown>;
+/**
+ * The caller named a method the registry does not know.
+ *
+ * A deliberate, bounded rejection: its message names only the method the caller
+ * itself sent, so the agent WS handler may forward it verbatim to the workflow
+ * author instead of replacing it with a safe fixed string.
+ */
+export declare class UnknownApiMethodError extends Error {
+    constructor(method: string);
+}
+/**
+ * The caller is not authorized for the role the requested method requires.
+ *
+ * A deliberate, bounded rejection: its message names only the caller's own
+ * method and roles, so the agent WS handler may forward it verbatim to the
+ * workflow author instead of replacing it with a safe fixed string.
+ */
+export declare class ApiRoleDeniedError extends Error {
+    constructor(method: string, requiredRole: ApiRole, allowedRoles: ApiRole[]);
+}
 /**
  * Registry for agent private API methods.
  *

package/dist/ws/agent-handler.d.ts

@@ -16,22 +16,24 @@
  * When agentAuthMode === 'none', the auth phase is skipped (legacy behavior).
  */
 import type { WSEvents } from 'hono/ws';
+import { LogStream } from '@kici-dev/engine';
 import type { RateLimiterConfig, AttestationVerifyStatus } from '@kici-dev/engine';
 import type { ProvenanceTrustRoot } from '../provenance/trust-root.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
-import type { AgentTokenStore } from '../agent/token-store.js';
+import { type AgentTokenStore } from '../agent/token-store.js';
 import type { OwnershipTracker } from '../agent/ownership-tracker.js';
 import type { SourceCache } from '../cache/source-cache.js';
 import type { DepCache } from '../cache/dep-cache.js';
 import type { UserCache } from '../cache/user-cache.js';
+import { type ArtifactStore } from '../artifacts/artifact-store.js';
 import type { DispatchCacheRefTracker } from '../cache/dispatch-cache-ref-tracker.js';
 import type { PendingBuildTracker } from '../cache/pending-builds.js';
 import type { PendingInitTracker } from '../cache/pending-inits.js';
 import type { PendingDynamicTracker } from '../cache/pending-dynamics.js';
 import type { CacheStorage } from '../storage/types.js';
 import type { AgentMetricsAggregator } from '../metrics/agent-metrics-aggregator.js';
-import type { AgentApiRegistry } from './agent-api-registry.js';
+import { type AgentApiRegistry } from './agent-api-registry.js';
 import type { FleetAgentCollector } from './fleet-agent-collector.js';
 /**
  * Run the three token-bound authorization gates against a wire-supplied
@@ -39,8 +41,9 @@ import type { FleetAgentCollector } from './fleet-agent-collector.js';
  * (Phase 2 / `pendingRegistration`) and on every subsequent re-register
  * arriving on the same registered WS — every code path that mutates the
  * registry's `agentId → entry` mapping for an authenticated WS MUST run
- * them, otherwise the §5.3 / §5.1 invariants only hold for the very first
- * register and a re-register can silently overwrite the authority.
+ * them, otherwise the token-scope and identity-binding invariants only
+ * hold for the very first register and a re-register can silently
+ * overwrite the authority.
  *
  * Gates:
  *  1. Token-scope subset — wire labels MUST be a subset of
@@ -59,7 +62,7 @@ import type { FleetAgentCollector } from './fleet-agent-collector.js';
  * case the caller MUST stop processing.
  */
 /**
- * WebSocket close reasons are capped at 123 UTF-8 bytes (RFC 6455 §5.5.1).
+ * WebSocket close reasons are capped at 123 UTF-8 bytes (RFC 6455, section 5.5.1).
  * A reason longer than that makes `ws.close()` throw a RangeError, which —
  * thrown from an async message handler — surfaces as an unhandled rejection
  * and skips the close entirely. Truncate on a byte boundary and drop any
@@ -88,6 +91,8 @@ export interface AgentWsHandlerDeps {
         stepIndex: number;
         lines: string[];
         timestamp: number;
+        /** Absent when the agent does not report a stream; read as `stdout`. */
+        stream?: LogStream;
     }) => void;
     /** Optional callback when agent sends step status updates. */
     onStepStatus?: (agentId: string, msg: {
@@ -141,7 +146,17 @@ export interface AgentWsHandlerDeps {
     }) => void;
     /** Optional callback when agent acknowledges config (for MMDS clearing in Firecracker). */
     onConfigAck?: (agentId: string) => void;
-    /** Optional callback when agent emits a custom event via ctx.emit(). */
+    /**
+     * Optional callback when agent emits a custom event via ctx.emit().
+     *
+     * A returned `error` is relayed to the agent verbatim, and the agent runs
+     * untrusted workflow code that persists it into the author's step logs — so
+     * an implementation may only return author-facing wording (an unknown job
+     * context). Raw exception text belongs in the implementation's own
+     * `logger.*`, with {@link AgentWsInternalFailure.eventEmitFailed} returned in
+     * its place; a thrown exception is already replaced with the same string
+     * here.
+     */
     onEventEmit?: (agentId: string, msg: {
         jobId: string;
         requestId: string;
@@ -185,6 +200,12 @@ export interface AgentWsHandlerDeps {
      * which org/repo/scope that job resolves to.
      */
     dispatchCacheRefs?: DispatchCacheRefTracker;
+    /**
+     * User-facing artifact store for serving `artifacts.*` upload/download
+     * requests from the sandbox. The org (`customer_id`) + runId are resolved
+     * server-side from the job's dispatch ref, NEVER from the wire body.
+     */
+    artifactStore?: ArtifactStore;
     /** Cache storage for setting metadata after upload completion. */
     cacheStorage?: CacheStorage;
     /**
@@ -253,7 +274,15 @@ export interface AgentWsHandlerDeps {
     }>) => Promise<void>;
     /** Agent metrics aggregator for receiving pushed metrics. */
     agentMetricsAggregator?: AgentMetricsAggregator;
-    /** Optional callback when agent reports a job belongs to a concurrency group. */
+    /**
+     * Optional callback when agent reports a job belongs to a concurrency group.
+     *
+     * A returned `reason` is relayed to the agent verbatim as the
+     * `job.concurrency.ack` reason, and the agent runs untrusted workflow code
+     * that persists it into the author's step logs — so an implementation may
+     * only return author-facing wording (the group the job queued behind). Raw
+     * exception text belongs in the implementation's own `logger.*`.
+     */
     onConcurrencyReport?: (agentId: string, msg: {
         runId: string;
         jobId: string;
@@ -271,6 +300,13 @@ export interface AgentWsHandlerDeps {
      * resolution back to the originating agent as a `step.approval-resolved`
      * message. The `agentId` lets the server drop the pending resolver when the
      * agent disconnects.
+     *
+     * The resolved `reason` is relayed to the agent verbatim, and the agent runs
+     * untrusted workflow code that persists it into the author's step logs — so
+     * an implementation may only resolve with author-facing wording (an
+     * approver's decline note, an invalid per-gate timeout). Raw exception text
+     * belongs in the implementation's own `logger.*`; a rejected promise is
+     * already replaced with {@link AgentWsInternalFailure.approvalFailed} here.
      */
     onStepApproval?: (agentId: string, msg: {
         runId: string;
@@ -309,5 +345,25 @@ export interface AgentWsHandlerDeps {
      */
     fleetAgentCollector?: FleetAgentCollector;
 }
+/**
+ * FAST PATH: Manual type guard for log.chunk messages.
+ *
+ * Skips Zod safeParse() on authenticated connections for this high-frequency message type.
+ *
+ * SYNC INVARIANT: This manual validator MUST match the Zod schema
+ * `agentLogChunkSchema` in packages/engine/src/protocol/messages/orchestrator-agent.ts.
+ * If you change the schema, update this validator in the same commit.
+ * See CLAUDE.md rule: "Zod fast-path sync invariant".
+ */
+export declare function isValidLogChunk(raw: unknown): raw is {
+    type: 'log.chunk';
+    messageId: string;
+    runId: string;
+    jobId: string;
+    stepIndex: number;
+    lines: string[];
+    timestamp: number;
+    stream?: LogStream;
+};
 export declare function createAgentWsHandler(deps: AgentWsHandlerDeps): WSEvents;
 //# sourceMappingURL=agent-handler.d.ts.map

package/dist/ws/bringup-api.d.ts

@@ -1,3 +1,5 @@
+import { AgentDeliveryMode, AgentPlatform } from '@kici-dev/shared';
+import { type AgentPackageDownloadStorage } from '../agent-packaging/download.js';
 import { type HostRosterStore } from '../agent/host-roster.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { AgentTokenStore } from '../agent/token-store.js';
@@ -21,6 +23,15 @@ export interface BringupApiDeps {
     resolveOrgId: () => string;
     /** Resolve the orchestrator WS URL the init-runner should dial. */
     resolveOrchestratorUrl: () => string;
+    /** Resolve the orchestrator's own version — the payload version to stage on bring-up. */
+    resolveVersion: () => string;
+    /**
+     * The cache-bucket agent-package store, present only when S3 cache storage is
+     * configured. Backs the `s3-direct` delivery mode: the handler mints a
+     * box-routable presigned download URL for a probed platform. Absent ⇒ every
+     * bring-up falls back to `ssh-push` and the presign RPC is refused.
+     */
+    agentPackages?: AgentPackageDownloadStorage;
 }
 /**
  * Reach the calling agent connects to + the resolved private key. Returned to
@@ -44,6 +55,15 @@ export interface EnsureInitRunnerResult {
     orchestratorUrl?: string;
     /** The init-runner label set the bootstrap token is bound to. */
     labels?: string[];
+    /** The orchestrator's own version — the self-contained payload version to stage. */
+    version?: string;
+    /**
+     * Per-host delivery mode the agent uses to stage the payload: `s3-direct` when
+     * the host is declared object-storage-reachable AND a cache store is
+     * configured, else `ssh-push`. The agent probes the platform then requests the
+     * presigned URL via `kici.presignAgentPackage` for the `s3-direct` case.
+     */
+    deliveryMode?: AgentDeliveryMode;
 }
 /** Result the agent receives for a `preBootSend` call. */
 export interface PreBootSendResult {
@@ -66,6 +86,85 @@ export declare class CapabilityDeniedError extends Error {
  * agent needs to drop + start the init-runner over SSH.
  */
 export declare function createEnsureInitRunnerHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<EnsureInitRunnerResult>;
+/** Result the agent receives for a `presignAgentPackage` call. */
+export interface PresignAgentPackageResult {
+    url: string;
+    /** The expected sha256 (hex), or null when the producer wrote no sidecar. */
+    sha256: string | null;
+}
+/**
+ * Build the `kici.presignAgentPackage` handler — the follow-up RPC the ops agent
+ * calls AFTER it probes the target platform (so the presign is keyed by the real
+ * platform). Same capability gate + access-log as the bring-up. Mints a
+ * box-routable presigned GET URL for the version-keyed payload from the
+ * orchestrator's own cache bucket; no standing S3 credential leaves the
+ * orchestrator. A missing payload object throws loudly (never a silent stale
+ * stage). Used by BOTH delivery paths: for `s3-direct` the URL goes to the box;
+ * for `ssh-push` the ops agent fetches it and streams the bytes onward.
+ */
+export declare function createPresignAgentPackageHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<PresignAgentPackageResult>;
+/** How the ops agent drains + restarts a re-staged host + where its install lives. */
+export interface AgentRestartSpec {
+    stop: string;
+    start: string;
+    installDir?: string;
+}
+/**
+ * Map a roster row's os/arch tokens to an {@link AgentPlatform}, or null when the
+ * host's platform is unknown / unsupported (so availability falls back to the
+ * whole bootstrap set). Accepts both `uname` (`x86_64`/`aarch64`) and Node
+ * (`x64`/`arm64`) arch spellings.
+ */
+export declare function archToAgentPlatform(platform: string | null, arch: string | null): AgentPlatform | null;
+/**
+ * Derive the drain/restart spec from a host's declared properties. Explicit
+ * stop/start commands win; otherwise a declared systemd service name maps to
+ * `systemctl --user stop|start <svc>`. Returns null when neither is declared —
+ * the orchestrator then cannot re-stage the host (it does not know how to
+ * restart it) and the caller refuses loudly.
+ */
+export declare function resolveRestartSpec(properties: Record<string, unknown>): AgentRestartSpec | null;
+/** Result the check-step receives for a `kici.agentVersionStatus` read. */
+export interface AgentVersionStatusResult {
+    /** The orchestrator's own version — the convergence target. */
+    targetVersion: string;
+    /** The version last staged onto the host, or null when never staged. */
+    stagedVersion: string | null;
+    /** True only when the target's payload objects exist for the host's platform. */
+    available: boolean;
+}
+/**
+ * Build the `kici.agentVersionStatus` read handler — the availability-gate probe
+ * the convergence check-step calls. Returns the target version, the host's
+ * recorded staged version, and whether the target's payloads are available for
+ * the host's platform (the whole bootstrap set when the platform is unknown). No
+ * SSH, no token — a pure read, but same capability gate + audit as the bring-up.
+ */
+export declare function createAgentVersionStatusHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<AgentVersionStatusResult>;
+/** Material the ops agent receives for a `kici.restageAgent` call. */
+export interface RestageAgentResult {
+    /** How to SSH to the target host. */
+    reach: BringupReach;
+    /** The resolved bring-up private key (custodied by the ops agent). */
+    privateKey: string;
+    /** The target version to converge onto (the orchestrator's own). */
+    version: string;
+    /** Per-host delivery mode (`s3-direct` when reachable + a store is configured). */
+    deliveryMode: AgentDeliveryMode;
+    /** How the ops agent drains + restarts the host after the install swap. */
+    restart: AgentRestartSpec;
+}
+/**
+ * Build the `kici.restageAgent` handler — the availability-gated, external-actor
+ * re-stage authorization. Gates on the caller's `ssh-transport` capability,
+ * REFUSES loudly when the target version's payloads are unavailable for the
+ * host's platform (belt-and-suspenders over the check-step gate — never a
+ * skew), resolves the host reach + SSH key + restart spec, records the staged
+ * version, audits, and returns the material the ops agent needs to swap + restart
+ * the target's agent over SSH. Mints NO token: the re-staged permanent agent
+ * reconnects on its own persistent credential (no self-update-handoff).
+ */
+export declare function createRestageAgentHandler(deps: BringupApiDeps): (callingAgentId: string, params: Record<string, unknown>) => Promise<RestageAgentResult>;
 /**
  * Build the `kici.preBootSend` handler. Gates on the caller's capability,
  * resolves the pre-boot input secret (e.g. a LUKS passphrase), audits, and

package/dist/ws/{dashboard-env-handler.d.ts → dashboard-context-handler.d.ts}

@@ -1,8 +1,8 @@
 /**
- * Dashboard environment handler for the orchestrator.
+ * Dashboard context handler for the orchestrator.
  *
- * Responds to dashboard.environments.* and dashboard.held-runs.* WS messages
- * from Platform by calling the appropriate stores (EnvironmentStore, VariableStore,
+ * Responds to dashboard.contexts.* and dashboard.held-runs.* WS messages
+ * from Platform by calling the appropriate stores (ContextStore, VariableStore,
  * BindingStore, PgSecretStore) and sending typed responses.
  *
  * Each handler:
@@ -11,30 +11,29 @@
  * 3. Returns a response message with requestId and data (or error)
  */
 import { type Kysely } from 'kysely';
-import type { HeldRunStore, ReleaseSignal } from '../environments/held-runs.js';
+import type { HeldRunStore, ReleaseSignal } from '../contexts/held-runs.js';
 import type { TeamMembershipLookup } from '../approvals/approval-resolver.js';
 import type { DashboardPlatformToOrchMessage } from '@kici-dev/engine';
-import type { EnvironmentStore } from '../environments/environment-store.js';
-import type { VariableStore } from '../environments/variable-store.js';
-import type { BindingStore } from '../environments/binding-store.js';
+import type { ContextStore } from '../contexts/context-store.js';
+import type { VariableStore } from '../contexts/variable-store.js';
+import type { BindingStore } from '../contexts/binding-store.js';
 import type { Database } from '../db/types.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
-/** Secret store interface (subset of PgSecretStore methods used here). */
-interface SecretStoreForDashboard {
-    listScopes(orgId: string): Promise<string[]>;
-    listKeys(orgId: string, scope: string): Promise<string[]>;
-    setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
-    deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
-    createScope?(orgId: string, scope: string): Promise<void>;
-    renameScope?(orgId: string, oldScope: string, newScope: string): Promise<void>;
-    deleteScope?(orgId: string, scope: string): Promise<void>;
-}
-export interface DashboardEnvHandlerDeps {
+import { type ScopedSecretStore } from '../secrets/scope-routing.js';
+import type { ResolvedDashboardEncryptionKey } from '../secrets/dashboard-encryption-key.js';
+/**
+ * Secret store interface (subset of PgSecretStore methods used here).
+ *
+ * Alias of the shared `ScopedSecretStore` so the WS plane and the HTTP admin
+ * plane route scopes against one contract.
+ */
+type SecretStoreForDashboard = ScopedSecretStore;
+export interface DashboardContextHandlerDeps {
     /** Organization ID for all operations. */
     orgId: string;
     /** Send a response message back to Platform over the WS connection. */
     send: (msg: unknown) => void;
-    environmentStore: EnvironmentStore;
+    contextStore: ContextStore;
     variableStore: VariableStore;
     bindingStore: BindingStore;
     secretStore: SecretStoreForDashboard;
@@ -54,6 +53,15 @@ export interface DashboardEnvHandlerDeps {
      * handlers fall back to the direct status flip.
      */
     approvals?: ApprovalHandlerDeps;
+    /**
+     * Dashboard-encryption key resolver. Present when KICI_SECRET_KEY is
+     * configured. Under the `encrypted` posture the secret/variable set handlers
+     * decrypt the browser-sealed envelope with the resolved private key. Absent ⇒
+     * `encrypted` writes fail closed (`encryption_unavailable`).
+     */
+    dashboardEncryption?: {
+        resolve: () => Promise<ResolvedDashboardEncryptionKey | null>;
+    };
 }
 /** Dependencies enabling the resolver-backed approve/reject + resume path. */
 export interface ApprovalHandlerDeps {
@@ -72,15 +80,15 @@ export interface ApprovalHandlerDeps {
     rejectWorkflow?: (runId: string) => Promise<void>;
 }
 /**
- * Handler for all dashboard environment and held run WS messages.
+ * Handler for all dashboard context and held run WS messages.
  *
  * Dispatches incoming messages by type and calls the appropriate store.
  */
-export declare class DashboardEnvHandler {
+export declare class DashboardContextHandler {
     private readonly deps;
     private routingKey;
     private readonly accessLog;
-    constructor(deps: DashboardEnvHandlerDeps);
+    constructor(deps: DashboardContextHandlerDeps);
     /** Update the orgId used for all operations (called when resolved from DB). */
     setOrgId(orgId: string): void;
     /** Update the routing key bound to access_log rows. */
@@ -92,6 +100,16 @@ export declare class DashboardEnvHandler {
      * sends a structured `operation_disabled` envelope back to Platform.
      */
     private enforcePolicy;
+    /**
+     * Resolve the plaintext value for a secret/variable set under the write
+     * policy. When the client sends a `sealed` envelope, decrypt it with the
+     * orchestrator's X25519 key (honored regardless of posture — the client chose
+     * to seal, so never expose that plaintext through the Platform). Otherwise,
+     * under the `encrypted` posture a plaintext `value` is refused (fail-closed);
+     * under `permissive` the plaintext `value` is used. Returns the plaintext or a
+     * structured error code the caller records + sends back.
+     */
+    private resolveWriteValue;
     /**
      * Write an access_log row for a handler invocation. Uses the handler's
      * bound orgId + routingKey, the msg.actor principal, and the handler-
@@ -105,8 +123,8 @@ export declare class DashboardEnvHandler {
     handleMessage(msg: DashboardPlatformToOrchMessage): Promise<boolean>;
     private handleEnvList;
     /**
-     * Map each environment id to the distinct secret key names reachable through
-     * its scope bindings. Joins `environment_bindings` → `scoped_secrets` on the
+     * Map each context id to the distinct secret key names reachable through
+     * its scope bindings. Joins `context_bindings` → `scoped_secrets` on the
      * scope pattern, excluding the `__empty__` sentinel. Returns key names only —
      * never values. Scoped to the caller-resolved org (the request's target org,
      * or the connection-level org on the legacy path).
@@ -159,4 +177,4 @@ export declare class DashboardEnvHandler {
     private sendError;
 }
 export {};
-//# sourceMappingURL=dashboard-env-handler.d.ts.map
+//# sourceMappingURL=dashboard-context-handler.d.ts.map

package/dist/ws/dashboard-run-state-handler.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Orchestrator-side handler for the `dashboard.run.state` system reconciliation
+ * read.
+ *
+ * The Platform's `RunMirrorReconciler` issues this request for a run that is
+ * stuck non-terminal in the Platform mirror to recover a terminal frame that was
+ * dropped on a live Platform↔orchestrator connection. It projects the current
+ * `execution_runs` + `execution_jobs` state for one run into the same
+ * `StateReplayRun` shape the reconnect `state.replay` push carries, so the
+ * Platform can drive it through the shared `upsertRunMirror` helper.
+ *
+ * Unlike the user-plane `dashboard.run.detail` read, this handler does NOT write
+ * an `access_log` row: it is a system reconciliation read (a `system` actor),
+ * not a user data access. The handler is pure (deps passed as arguments) so the
+ * WS wiring in `server.ts` stays a thin adapter and the logic is unit-testable
+ * without a live Platform connection.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import { type DashboardRunStateRequest, type DashboardRunStateResponse } from '@kici-dev/engine';
+export interface RunStateHandlerDeps {
+    db: Kysely<Database>;
+}
+/**
+ * Build the `StateReplayRun` projection for one run, or `null` when the
+ * orchestrator has no such run. Mirrors the DB-backed branch of
+ * `ExecutionTracker.getReplayDataWithDb` (jobs = id/name/status;
+ * `jobCount = jobs.length`; `triggerEvent`/`commitMessage` omitted — no columns).
+ */
+export declare function handleRunState(deps: RunStateHandlerDeps, req: DashboardRunStateRequest): Promise<DashboardRunStateResponse>;
+//# sourceMappingURL=dashboard-run-state-handler.d.ts.map

package/dist/ws/failure-messages.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Safe, fixed messages the orchestrator sends to the agent (and through it to
+ * the workflow author) when an agent-WS request fails for an internal reason.
+ *
+ * These are presentation strings, not a wire vocabulary: the protocol carries
+ * them in the free-text `reason` field of `step.approval-resolved` and in the
+ * free-text `error` field of `event.emit.response` / `agent.api.response`, so an
+ * orchestrator is free to reword them without any agent-side change. They live
+ * in one module — rather than inline at each send site — so the handler, its
+ * tests and the `onEventEmit` callback in `app.ts` cannot drift apart.
+ *
+ * Raw exception text is never one of these. Exceptions stay in the
+ * orchestrator's own logs; the author sees only "this is an orchestrator
+ * problem", never a database endpoint, a constraint name or a stack frame.
+ *
+ * Author-actionable failures do not come through here at all — they ride the
+ * callback's return value with its own safe wording (an unknown job context, an
+ * approval bridge's timeout reason), which stays specific enough to debug a bad
+ * workflow without operator log access.
+ */
+export declare const AgentWsInternalFailure: Readonly<{
+    /** The step-approval bridge rejected instead of resolving the hold. */
+    readonly approvalFailed: 'the orchestrator hit an internal error while resolving this approval';
+    /** The event router threw while emitting the agent's event. */
+    readonly eventEmitFailed: 'the orchestrator hit an internal error while emitting this event';
+    /** An agent private-API handler threw for a reason other than its two deliberate rejections. */
+    readonly agentApiFailed: 'the orchestrator hit an internal error while handling this API request';
+}>;
+//# sourceMappingURL=failure-messages.d.ts.map

package/dist/ws/oidc-token-relay.d.ts

@@ -1,6 +1,15 @@
 /**
  * Provenance ID-token relay (orchestrator side).
  *
+ * @deprecated The Platform-rooted identity mint is hard-deprecated in favor of
+ * orchestrator-owned signing (`oidc/orchestrator-mint.ts`). This relay is
+ * registered ONLY when the orchestrator has NO provenance signer configured
+ * (`selectOidcMintRegistration` prefers the orchestrator-owned mint whenever
+ * `KICI_ORCHESTRATOR_PROVENANCE_ISSUER` is set). It is kept wire-compatible for
+ * the mixed-version rollout window; the `oidc.mint.*` RPC shim is removed at
+ * v1.0. Existing Platform-signed bundles keep verifying forever (the Platform
+ * JWKS stays published). See docs/user/deprecations.md.
+ *
  * Backs the `oidc.token.request` agent.api method: an agent asks for a
  * short-lived OIDC ID token for a job it is running; the orchestrator verifies
  * the agent owns that job, resolves its runId from its own dispatch state, and
@@ -58,6 +67,12 @@ export interface OidcTokenHandlerDeps {
      * OIDC audience (config.testMintDeferAudience). Ignored unless `testMode`.
      */
     testMintDeferAudience?: string;
+    /**
+     * Test-only: force the *initial* agent mint to defer for this OIDC audience
+     * (config.testMintRejectAudience) so a pending row is created, which the
+     * retrier then terminally rejects. Ignored unless `testMode`.
+     */
+    testMintRejectAudience?: string;
 }
 /**
  * Build the agent.api handler for `OIDC_TOKEN_REQUEST_METHOD`. Validates the

package/dist/ws/ownership-gate.d.ts

@@ -0,0 +1,22 @@
+import type { OwnershipTracker } from '../agent/ownership-tracker.js';
+/** Whether a job-scoped agent frame may be handled. */
+export type OwnershipDecision = 'accept' | 'reject';
+/**
+ * Resolve whether `agentId` may act on `jobId`, in the two steps every
+ * job-scoped agent frame shares.
+ *
+ * 1. No tracker configured — ownership enforcement is off; accept.
+ * 2. The synchronous in-memory check hits — accept without touching the
+ *    database. This is the hot path: the owning coordinator answers from its
+ *    own `agentJobs` map.
+ * 3. Otherwise resolve asynchronously. `checkOwnership` returning false is
+ *    "not decided yet", not "refused", whenever a database fallback is
+ *    configured — so the caller must never treat step 2 as the verdict.
+ *
+ * A `reject` is final: the caller replies with the shared refusal wording (or,
+ * where the message has no reply, drops the frame). What it must never do is
+ * drop a frame that this function has not yet ruled on — an agent awaiting an
+ * acknowledgment would hang until its own deadline expired.
+ */
+export declare function gateOwnership(tracker: OwnershipTracker | undefined, agentId: string, jobId: string, messageType: string): Promise<OwnershipDecision>;
+//# sourceMappingURL=ownership-gate.d.ts.map