@kici-dev/orchestrator 0.1.27 → 0.3.0

package/dist/app.d.ts

@@ -10,7 +10,7 @@
  * - Request ID and logging middleware
  * - 25MB body size limit
  *
- * Pattern follows packages/platform/src/app.ts: returns { app, injectWebSocket }.
+ * Pattern follows packages/platform/src/app.ts: returns { app, wss }.
  */
 import type { Kysely } from 'kysely';
 import type pg from 'pg';
@@ -21,6 +21,7 @@ import type { Database } from './db/types.js';
 import type { AgentRegistry } from './agent/registry.js';
 import type { Dispatcher } from './agent/dispatcher.js';
 import type { RunCoordinator } from './cluster/coordinator.js';
+import type { ClusterSettingsReader } from './cluster/cluster-settings-reader.js';
 import type { PeerRegistry } from './cluster/peer-registry.js';
 import type { JobQueue } from './queue/job-queue.js';
 import type { DedupCache } from './webhook/dedup.js';
@@ -32,6 +33,7 @@ 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 { ArtifactStore } from './artifacts/artifact-store.js';
 import type { DispatchCacheRefTracker } from './cache/index.js';
 import type { PendingBuildTracker } from './cache/index.js';
 import type { PendingInitTracker } from './cache/index.js';
@@ -39,7 +41,7 @@ import type { PendingDynamicTracker } from './cache/index.js';
 import type { CacheStorage } from './storage/types.js';
 import type { ProvenanceTrustRoot } from './provenance/trust-root.js';
 import type { LocalSigner } from './oidc/local-dev-signer.js';
-import { type CheckRunReporter } from './reporting/check-run-reporter.js';
+import type { CheckRunReporter } from './reporting/check-run-reporter.js';
 import type { ExecutionTracker } from './reporting/execution-tracker.js';
 import type { LogWriter } from './reporting/log-writer.js';
 import type { LogStorage } from './reporting/log-storage.js';
@@ -62,6 +64,12 @@ import type { RegistrationStore } from './registration/registration-store.js';
 import type { RegistrationIndex } from './registration/registration-index.js';
 import type { CronScheduler } from './cron/cron-scheduler.js';
 import { type ConfigRouteDeps } from './routes/admin-config.js';
+import { WebhookIngestOutcome } from './pipeline/process-webhook.js';
+import type { IngestOverflowBuffer } from './webhook/ingest-overflow-buffer.js';
+import { type OverflowDelivery } from './webhook/ingest-overflow-types.js';
+import type { IngestAdmissionController } from './webhook/ingest-admission.js';
+import type { OrgIngestCapReader } from './webhook/org-ingest-cap-reader.js';
+import type { SandboxAllowListReader } from './pipeline/sandbox-allowlist-reader.js';
 import type { ConcurrencyGroupTracker } from './concurrency/group-tracker.js';
 import type { ConcurrencyQueueManager } from './concurrency/queue-manager.js';
 import type { EventRouter } from './events/event-router.js';
@@ -85,6 +93,8 @@ export interface AppDependencies {
     config: AppConfig;
     db: Kysely<Database>;
     pool: pg.Pool;
+    /** Fleet-wide settings reader; threads the live lock-file cap into warm-added universal-git sources. */
+    clusterSettings?: ClusterSettingsReader;
     registry: AgentRegistry;
     /**
      * Warmth latch surfaced on `GET /ready`. Returns `true` only once the
@@ -100,6 +110,22 @@ export interface AppDependencies {
     lockFileCache: LockFileCache;
     providerRegistry: ProviderRegistry;
     platformClient?: PlatformClient;
+    /**
+     * Webhook-ingest admission controller (shared with the WS relay path). When
+     * present, the HTTP ingest closure admits before running the pipeline and
+     * sheds (429 + Retry-After) when the controller is saturated.
+     */
+    ingestController?: IngestAdmissionController;
+    /** Resolves the fairness key + per-org cap for a routing key (cached, DB-degraded). */
+    ingestCapReader?: OrgIngestCapReader;
+    /** Reads the per-org container-sandbox escape-hatch allow-list at dispatch (uncached, DB-degraded). */
+    sandboxAllowListReader?: SandboxAllowListReader;
+    /**
+     * Durable overflow buffer (capture side). When present and
+     * `config.ingestOverflowEnabled`, a shed HTTP delivery is additively persisted
+     * for later replay; absent → capture disabled.
+     */
+    ingestOverflowBuffer?: IngestOverflowBuffer;
     /**
      * Fulfil deferred attestations on demand (mints in this process, which owns
      * the Platform WS). Backs `POST /api/v1/admin/attestations/retry`. Wired only
@@ -122,6 +148,8 @@ export interface AppDependencies {
     depCache?: DepCache;
     /** User-facing cache (ctx.cache / declarative job-step cache). Optional — requires cache storage. */
     userCache?: UserCache;
+    /** User-facing artifact store (ctx.artifacts). Optional — requires cache storage + DB. */
+    artifactStore?: ArtifactStore;
     /**
      * Server-side jobId -> user-cache-namespace store. Written at dispatch time
      * (orchestrator-core's buildOnDispatch); read by the agent-WS handler to
@@ -140,6 +168,29 @@ export interface AppDependencies {
      * is registered so `ctx.kici.oidc.token()` mints a `kici-local` dev token.
      */
     localOidcSigner?: LocalSigner;
+    /**
+     * Orchestrator-owned provenance signing (Phase 1 root of trust). Present when
+     * `KICI_ORCHESTRATOR_PROVENANCE_ISSUER` is configured: the orchestrator mints +
+     * signs identity tokens locally with its own ES256 key, and serves its own
+     * OIDC discovery + JWKS + native verify endpoint. `resolveOrchestratorSigner`
+     * lazily reconciles the active signing key (leader-election-race-safe); the
+     * repo backs the `.well-known` + verify routes.
+     */
+    provenanceSigning?: {
+        issuer: string;
+        resolveSigner: () => Promise<import('./oidc/signer.js').Signer | null>;
+        repo: import('./db/repos/signing-keys-repo.js').OrchestratorSigningKeyRepo;
+    };
+    /**
+     * Dashboard-encryption (X25519) key custody. Present whenever KICI_SECRET_KEY
+     * is configured. `repo` backs the JWKS enc-key publication; `resolve` lazily
+     * reconciles the active key (leader-election-race-safe) for the WS decrypt
+     * handler.
+     */
+    dashboardEncryption?: {
+        repo: import('./db/repos/dashboard-encryption-keys-repo.js').DashboardEncryptionKeyRepo;
+        resolve: () => Promise<import('./secrets/dashboard-encryption-key.js').ResolvedDashboardEncryptionKey | null>;
+    };
     /**
      * Filesystem cache backend handle. Only set when KICI_STORAGE_TYPE is
      * `filesystem`. Drives the /api/v1/cache/blob/* HTTP route that serves and
@@ -300,11 +351,12 @@ export declare class SourceLocationStore {
  * Create Hono application with all routes and middleware.
  *
  * @param deps - Application dependencies (injected for testability)
- * @returns Object with Hono app instance and injectWebSocket function
+ * @returns Object with Hono app instance and the configured WebSocket server
  */
 export declare function createApp(deps: AppDependencies): {
     app: import("hono/hono-base").HonoBase<import("hono/types").BlankEnv, import("hono/types").BlankSchema, string, string>;
-    injectWebSocket: (server: import("http").Server | import("http2").Http2Server | import("http2").Http2SecureServer) => void;
+    wss: import("ws").Server<typeof import("ws").WebSocket, typeof import("http").IncomingMessage>;
+    reinjectDirect: (d: OverflowDelivery) => Promise<WebhookIngestOutcome>;
     onSourceLocationsExtracted: (workflowName: string, jobName: string, locations: Array<{
         file: string;
         line: number;

package/dist/artifacts/artifact-store.d.ts

@@ -0,0 +1,233 @@
+import type { Kysely } from 'kysely';
+import type { ArtifactRejectReason } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+import type { CacheStorage } from '../storage/types.js';
+/**
+ * The presigned PUT never landed an object, so there is nothing to record.
+ * Distinct from a transient storage/DB error: a caller retrying the commit
+ * would keep finding the object absent, so this failure is terminal and is
+ * reported straight back to the agent (which fails the workflow step).
+ */
+export declare class ArtifactObjectMissingError extends Error {
+    readonly storageKey: string;
+    constructor(storageKey: string);
+}
+/**
+ * The requested artifact name violates the shared name contract. Terminal: the
+ * name is fixed for the life of the request, so a retry would fail identically.
+ */
+export declare class ArtifactInvalidNameError extends Error {
+    constructor(detail: string);
+}
+/**
+ * Map a `completeUpload` failure onto a message safe to send to the agent — which
+ * runs untrusted workflow code, so the reason reaches the workflow author and its
+ * step logs.
+ *
+ * An invalid-name error already carries a safe message: its constructor formats
+ * the schema's own fixed detail, so it passes through unchanged. An object-missing
+ * error is a genuinely actionable terminal case and keeps its own category, but
+ * the storage key its message embeds does not travel. Anything else is an internal
+ * failure the author cannot act on, so it collapses to one literal; the raw
+ * exception stays in the orchestrator's own log line.
+ */
+export declare function classifyArtifactCommitFailure(err: unknown): string;
+/** Cluster-wide default per-org artifact byte quota: 20 GiB. */
+export declare const DEFAULT_ARTIFACT_QUOTA_BYTES: number;
+/** Cluster-wide default per-artifact TTL: 30 days. */
+export declare const DEFAULT_ARTIFACT_TTL_MS: number;
+/** Cluster-wide default per-artifact size cap: 1 GiB. */
+export declare const DEFAULT_ARTIFACT_MAX_BYTES: number;
+/** Cluster-wide default per-run artifact count cap. */
+export declare const DEFAULT_ARTIFACT_MAX_PER_RUN = 50;
+/**
+ * Storage key for a run's named artifact.
+ *
+ * Injective over names: distinct names always produce distinct keys, so a
+ * second upload can never silently overwrite the first while both rows keep
+ * their own hash.
+ *
+ * The trailing discriminator is a hash of the exact name, and it is what keeps
+ * the keys apart on a CASE-INSENSITIVE object namespace — the filesystem
+ * backend on a macOS or Windows host. There `bundle` and `Bundle` would
+ * otherwise be two keys resolving to one file; because their discriminators
+ * differ, the keys differ by more than case and stay two objects. That is why
+ * the discriminator is wide (see `KEY_DISCRIMINATOR_LENGTH`): under case
+ * folding it carries the whole separation on its own. The readable stem is kept
+ * so an operator browsing the bucket can still tell which artifact an object
+ * is.
+ *
+ * Hashing the EXACT name rather than the sanitized one is deliberate:
+ * sanitizing is many-to-one, so a discriminator over its output would fold
+ * `a/b` and `a_b` back together.
+ *
+ * Changing this format does not strand existing artifacts — the key is
+ * persisted in `artifacts.storage_key` and the download paths read that column
+ * rather than re-deriving. Only the grant and commit paths derive, and both do
+ * so at upload time.
+ */
+export declare function artifactStorageKey(runId: string, name: string): string;
+/**
+ * Per-org override of the artifact limits, read from `org_settings`. Each field
+ * is optional; an undefined field falls back to the cluster-wide default.
+ */
+export interface ArtifactOrgLimits {
+    quotaBytes?: number;
+    ttlMs?: number;
+    maxBytes?: number;
+    maxPerRun?: number;
+}
+/** Resolves the per-org artifact limits (e.g. an `org_settings` read). */
+export type ArtifactOrgLimitsReader = (customerId: string) => Promise<ArtifactOrgLimits>;
+/** Outcome of a begin-upload grant request. */
+export interface ArtifactBeginUploadResult {
+    outcome: 'granted' | 'rejected';
+    uploadUrl?: string;
+    storageKey?: string;
+    reason?: ArtifactRejectReason;
+    /**
+     * Free-text rejection detail carried when no enforcement `reason` applies —
+     * today, a name that violates the artifact-name contract.
+     */
+    error?: string;
+}
+/** Outcome of a download lookup. */
+export interface ArtifactDownloadResult {
+    outcome: 'found' | 'not_found';
+    downloadUrl?: string;
+    sizeBytes?: number;
+    sha256?: string;
+}
+/** A run's artifact as surfaced to the dashboard. */
+export interface ArtifactListEntry {
+    name: string;
+    jobId: string;
+    sizeBytes: number;
+    sha256: string;
+    createdAt: string;
+    /**
+     * Presigned GET for the backing object. Present on the run-detail listing
+     * (`listForRunWithUrls`); omitted when the object could not be resolved
+     * (expired / gone).
+     */
+    downloadUrl?: string;
+}
+export declare class ArtifactStore {
+    private readonly storage;
+    private readonly db;
+    private readonly defaultQuotaBytes;
+    private readonly defaultTtlMs;
+    private readonly maxBytes;
+    private readonly maxPerRun;
+    private readonly orgLimitsReader?;
+    constructor(opts: {
+        storage: CacheStorage;
+        db: Kysely<Database>;
+        /** Cluster-wide default quota (env default). */
+        quotaBytes?: number;
+        /** Cluster-wide default TTL (env default). */
+        ttlMs?: number;
+        /** Per-artifact size cap. */
+        maxBytes?: number;
+        /** Per-run artifact count cap. */
+        maxPerRun?: number;
+        /** Per-org override reader (org_settings). When unset, defaults apply. */
+        orgLimitsReader?: ArtifactOrgLimitsReader;
+    });
+    /**
+     * Resolve the effective quota, TTL, per-artifact size cap, and per-run count
+     * cap for an org. Each value is the per-org `org_settings` override when set,
+     * otherwise the cluster-wide default.
+     */
+    private resolveLimits;
+    /** ISO cutoff for TTL filtering: rows created before this are expired. */
+    private cutoff;
+    /**
+     * Grant or refuse a presigned PUT for a named artifact. Order: name contract →
+     * resolve limits → size cap → duplicate name → per-run count cap → org quota.
+     * The size cap and per-run count cap are the resolved per-org override when
+     * set, otherwise the cluster-wide default. No presigned URL is minted for a
+     * request that would violate any gate.
+     *
+     * The name is checked first, and here rather than only in the SDK, because the
+     * agent runs untrusted customer workflow code: a name that bypassed the SDK
+     * check would be sanitized onto another name's storage key, letting a second
+     * upload overwrite the first object while both rows keep their own hash. A
+     * contract violation is not an enforcement rejection, so it carries a
+     * free-text `error` and no `reason`.
+     */
+    beginUpload(args: {
+        customerId: string;
+        runId: string;
+        name: string;
+        declaredSizeBytes: number;
+    }): Promise<ArtifactBeginUploadResult>;
+    /**
+     * Commit a completed upload: write the object metadata sidecar, then insert
+     * the DB row. The `UNIQUE (run_id, name)` constraint (via onConflict-do-nothing)
+     * is the immutability backstop for a racing duplicate that slipped past the
+     * pre-mint check.
+     *
+     * Neither agent-supplied value is trusted: the storage key is re-derived from
+     * the server-resolved `runId` + `name`, and the recorded size is the real byte
+     * size of the stored object read back from the storage backend. Agents run
+     * untrusted customer workflow code, so an echoed key could otherwise point a
+     * row at another tenant's object, and a declared size could under-account the
+     * per-org quota (a presigned PUT does not bind content length).
+     *
+     * The name is re-validated here, not only at `beginUpload`: a commit is its
+     * own inbound message, so an agent can send one for a name it never got a
+     * grant for. Without the check, a non-conforming name would derive the
+     * storage key of a *different*, already-committed artifact and record a second
+     * row against that same object with its own hash.
+     *
+     * Throws when the commit cannot be recorded — `ArtifactInvalidNameError` for a
+     * name that violates the contract, `ArtifactObjectMissingError` when the
+     * presigned PUT never landed an object, or the underlying storage / DB error
+     * otherwise. The caller reports the failure back to the agent, which fails the
+     * workflow step rather than leaving a green run with no artifact.
+     */
+    completeUpload(args: {
+        customerId: string;
+        runId: string;
+        jobId: string;
+        name: string;
+        /** Agent-declared size. Advisory — the stored object is stat'd instead. */
+        sizeBytes: number;
+        sha256: string;
+        /** Agent-echoed key. Ignored — the key is re-derived server-side. */
+        storageKey: string;
+    }): Promise<void>;
+    /** Load a single artifact row (any TTL state) for a run + name. */
+    private loadRow;
+    private isExpired;
+    /**
+     * Resolve a named artifact of a run to a presigned GET + its size/sha256, or
+     * `not_found` when the name was never uploaded, has expired, or its backing
+     * object is gone.
+     */
+    download(args: {
+        customerId: string;
+        runId: string;
+        name: string;
+    }): Promise<ArtifactDownloadResult>;
+    /** ISO string for a row's created_at (Date or already-string). */
+    private createdAtIso;
+    /** Load a run's non-expired artifact rows, newest first, given the org TTL. */
+    private loadRunRows;
+    /**
+     * List a run's non-expired artifacts with a presigned GET per entry, newest
+     * first — the shape the dashboard run-detail panel renders. Resolves the org
+     * TTL once, then mints one presigned URL per row; a row whose backing object
+     * is gone lists its metadata with `downloadUrl` omitted rather than being
+     * dropped. Also reports the presigned-URL expiry (seconds) — the storage
+     * backend's `getUrl` signature TTL, NOT the artifact-retention `ttlMs` — so
+     * the dashboard can refresh a rendered `downloadUrl` before its signature
+     * expires.
+     */
+    listForRunWithUrls(customerId: string, runId: string): Promise<{
+        artifacts: ArtifactListEntry[];
+        downloadUrlExpiresInSeconds: number;
+    }>;
+}
+//# sourceMappingURL=artifact-store.d.ts.map

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

@@ -0,0 +1,46 @@
+/**
+ * Safe, fixed messages the orchestrator sends to the agent (and through it to
+ * the workflow author) when a user-artifact request is refused for something
+ * other than an enforcement gate or a genuine lookup miss — an internal failure,
+ * or a request that violates the artifact-name contract.
+ *
+ * These are presentation strings, not a wire vocabulary: the protocol carries
+ * them in the free-text `error` field of `artifacts.upload.response` /
+ * `artifacts.download.response` and in the free-text `reason` field of
+ * `artifacts.upload.complete.ack`, so an orchestrator is free to reword them
+ * without any agent-side change. They live here — rather than inline at each
+ * send site — so the handler and its tests share one definition.
+ *
+ * Raw exception text is never one of these. Exceptions stay in the
+ * orchestrator's own logs; the author sees only "this is an orchestrator or
+ * configuration problem", never a database endpoint or a stack frame.
+ */
+export declare const ArtifactInternalFailure: Readonly<{
+    /** Upload requested but the orchestrator has no artifact store configured. */
+    readonly uploadNotConfigured: 'artifact uploads are not configured on this orchestrator';
+    /** Download requested but the orchestrator has no artifact store configured. */
+    readonly downloadNotConfigured: 'artifact downloads are not configured on this orchestrator';
+    /** The job's run could not be resolved server-side (upload and download). */
+    readonly unresolvableRun: 'the run for this job could not be resolved on the orchestrator';
+    /** `beginUpload` threw. */
+    readonly uploadFailed: 'the orchestrator hit an internal error while starting the upload';
+    /** `download` threw. */
+    readonly downloadFailed: 'the orchestrator hit an internal error while resolving the download';
+    /** `completeUpload` threw with no more specific classification. */
+    readonly commitFailed: 'the orchestrator hit an internal error while committing the upload';
+    /** The uploaded object was absent from storage at commit time. */
+    readonly commitObjectMissing: 'the uploaded artifact object was not found in storage — the upload may not have completed';
+}>;
+/**
+ * The artifact-name rejection prefix and message builder are defined in
+ * `@kici-dev/engine`, beside `ArtifactNameSchema` itself, so the orchestrator and
+ * the agent sandbox render one wording. Such a rejection is neither an
+ * enforcement gate (nothing about the org's usage refuses it) nor an internal
+ * failure — the sandbox validates the same contract at the call site, so a name
+ * only reaches this path from an agent that bypassed or predates that check.
+ *
+ * Re-exported here because this module is where the orchestrator's artifact
+ * failure messages live — callers keep their existing import path.
+ */
+export { ARTIFACT_INVALID_NAME_PREFIX, artifactInvalidNameError } from '@kici-dev/engine';
+//# sourceMappingURL=failure-messages.d.ts.map

package/dist/audit/access-log.d.ts

@@ -1,4 +1,4 @@
-import type { Kysely } from 'kysely';
+import type { Kysely, Transaction } from 'kysely';
 import { type ColdStore } from '@kici-dev/shared';
 import { type AccessLogAction, type AccessLogItem, type AccessLogOutcome, type AccessLogRateLimiter, type AccessLogSource, type AccessLogTargetType, type ActorPrincipal, type ActorType } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
@@ -70,6 +70,23 @@ export declare class AccessLogWriter {
      */
     setColdStore(coldStore: ColdStore | null): void;
     record(entry: AccessLogRecord): Promise<void>;
+    /**
+     * Transactional variant: writes the row through the caller's executor so it
+     * commits or rolls back with the mutation it audits.
+     *
+     * Unlike `record`, failures PROPAGATE. The best-effort swallow exists so a
+     * broken `access_log` cannot take down dashboard reads; a caller that opted
+     * into a transaction is asserting the opposite — the mutation must not land
+     * unaudited — so the error has to reach the transaction and abort it.
+     *
+     * The per-action `POLICY_BY_ACTION` gate still applies, so a `sample` /
+     * `rate_limit` action would be dropped here silently and the caller's
+     * mutation would commit unaudited after all. Callers must therefore use an
+     * action whose policy is `always` — which is why `trust_policy.updated` is
+     * one.
+     */
+    recordInTransaction(executor: Kysely<Database> | Transaction<Database>, entry: AccessLogRecord): Promise<void>;
+    private insert;
     /**
      * Phase D: delegates to `loadAccessLogRange` so cold-store rows are
      * merged transparently when pagination crosses the warm cutoff. The

package/dist/cache/dep-cache.d.ts

@@ -8,13 +8,28 @@
  * Cache key format: deps/{platform}-{arch}/{lockfileHash}.tar.gz
  */
 import type { CacheStorage } from '../storage/types.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 export declare class DepCache {
     private readonly storage;
     private readonly maxTarballBytes;
+    private readonly cacheTtlDaysFallback;
+    private readonly clusterSettings?;
     constructor(options: {
         storage: CacheStorage;
         maxTarballBytes?: number;
+        /** Cluster default for the dependency-cache entry TTL, in days. */
+        cacheTtlDaysFallback?: number;
+        /** Reader for the fleet-wide `cache_max_tarball_bytes` / `cache_ttl_days` overrides. */
+        clusterSettings?: ClusterSettingsReader;
     });
+    /**
+     * Resolve the live dependency-cache entry TTL as a per-operation override
+     * (ms) from `cluster_settings.cache_ttl_days`, falling back to the cluster
+     * default. `undefined` when no reader is wired, so the storage backend uses
+     * its own configured TTL. Passed to read/expiry operations so an operator's
+     * `cache_ttl_days` change takes effect on the next lookup.
+     */
+    private resolveTtlMsOverride;
     /** Check if a dep tarball exists in cache. */
     has(lockfileHash: string, platform: string, arch: string): Promise<boolean>;
     /**

package/dist/cache/user-cache.d.ts

@@ -88,7 +88,44 @@ export declare class UserCache {
     private writePrefix;
     /** Namespace prefixes the ref may READ, in priority order. Isolated reads its own run scope, then shared. */
     private readPrefixes;
+    /**
+     * Object key for a committed cache entry.
+     *
+     * The trailing discriminator is a hash of the EXACT cache key, and it is what
+     * keeps `build` and `Build` apart on a case-insensitive namespace — the
+     * filesystem backend on a macOS or Windows host, where the two would
+     * otherwise resolve to one object and a restore could return the other key's
+     * tarball.
+     *
+     * It is deliberately a SUFFIX: `restoreByPrefix` matches `restoreKeys` by
+     * string prefix, so appending leaves those semantics untouched. The only
+     * parse that has to know about it is the `matchedKey` slice.
+     */
     private finalKey;
+    /**
+     * The pre-discriminator object key.
+     *
+     * @deprecated Read-only compatibility path for entries written before the key
+     * carried a discriminator. Nothing writes this format; it is removed at the
+     * next major, by which point every such entry has aged out of the cache TTL.
+     */
+    private legacyFinalKey;
+    /**
+     * Restore an entry still stored in the pre-discriminator key format.
+     *
+     * Two gates, and BOTH are load-bearing — dropping either re-creates the
+     * wrong-cache-hit this change fixes:
+     *
+     * 1. `unambiguousLegacyKey` statically rules out any key that could have
+     *    collided with a case variant in the old format.
+     * 2. The listed name must match byte-exactly. A case-insensitive backend
+     *    resolves `getUrl('build')` to an object created as `Build`, but its
+     *    *listing* reports the real created name — so comparing against the
+     *    listing is what detects that the object is not really ours.
+     *
+     * @deprecated Removed at the next major; see `legacyFinalKey`.
+     */
+    private restoreLegacyExact;
     /** Restore: try the exact key across read prefixes, then restoreKeys prefix scan (newest wins). */
     restore(ref: UserCacheRef & {
         key: string;

package/dist/cancel/cancel-run.d.ts

@@ -41,6 +41,11 @@ export interface CancelRunResult {
     agentsNotified: number;
     /** Number of pending/queued execution_jobs rows marked cancelled. */
     pendingCancelled: number;
+    /**
+     * True when the run was already in a terminal status, so the cancel was a
+     * no-op: no agent was notified and no row was written.
+     */
+    alreadyTerminal: boolean;
 }
 /**
  * Cancel a whole run, recording `reason` on its cancelled jobs and (if not
@@ -50,9 +55,11 @@ export interface CancelRunResult {
  * the run to its terminal status immediately so the run does not linger in
  * `cancelling`.
  *
- * Idempotent against terminal runs: callers should pre-check terminal state
- * (the cancel route returns 409); the underlying UPDATEs are status-guarded so
- * a double-call is harmless.
+ * A cancel targeting a run that is already terminal is a no-op: the run's
+ * status is read first and, when terminal, the function returns
+ * `alreadyTerminal: true` having written nothing. Entry points map that to
+ * their own convention (the operator route answers 409; the dashboard/MCP path
+ * returns a structured already-terminal result).
  */
 export declare function cancelRunWithReason(deps: CancelRunDeps, runId: string, reason: string, options?: CancelRunOptions): Promise<CancelRunResult>;
 //# sourceMappingURL=cancel-run.d.ts.map

package/dist/cancel/dashboard-cancel-handler.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The cancel handler behind the dashboard, the `kici runs cancel` CLI, and the
+ * MCP `cancel_run` tool.
+ *
+ * It delegates to `cancelRunWithReason` so the customer-facing cancel follows
+ * the same mechanics as the operator-facing one: an already-terminal run is a
+ * no-op, only OPEN agent sockets are notified, queued dispatch rows are
+ * cancelled, pending jobs are marked cancelled, and a run with no outstanding
+ * agent work is driven terminal.
+ *
+ * `cancelledJobs` counts notified agents plus pending/queued job rows marked
+ * cancelled, matching the operator route.
+ */
+import { type CancelRunDeps } from './cancel-run.js';
+export declare function createDashboardCancelHandler(deps: CancelRunDeps): (runId: string, cancelledBy: string | null, cancelledByAgentLabel: string | null, force?: boolean) => Promise<{
+    cancelledJobs: number;
+    alreadyTerminal: boolean;
+}>;
+//# sourceMappingURL=dashboard-cancel-handler.d.ts.map

package/dist/cli/api-client.d.ts

@@ -63,6 +63,28 @@ export interface GenericSourceResponse {
     /** Universal-git config; raw JSON string or parsed object (pg driver dependent). */
     git_config?: string | GenericSourceGitConfigPayload | null;
 }
+/**
+ * `fetch` rejects with a bare `TypeError: fetch failed` when it cannot reach the
+ * host — it names neither the address dialled nor the knob that sets it. Printed
+ * through the CLI's `Error: ${message}` handler that becomes `Error: fetch
+ * failed`, which reads like a fault in the subcommand rather than a misaddressed
+ * client, and sends the operator debugging the wrong thing.
+ *
+ * The trap is sharpened by two details of this CLI. The base URL comes from
+ * `KICI_ADMIN_URL`, not the `KICI_ORCHESTRATOR_URL` an operator is likelier to
+ * have exported; and subcommands accepting `--database-url` fall back to direct
+ * DB access, so on a host with `KICI_DATABASE_URL` set they keep working while
+ * the HTTP-only ones fail — making it look like specific subcommands are broken.
+ *
+ * So: name the address, name the variable, and name the near-miss.
+ */
+/**
+ * Best-effort one-line detail from a rejected `fetch`. Returns '' when nothing
+ * useful is available, so the caller can omit the parenthetical rather than
+ * print an empty one.
+ */
+export declare function firstCauseMessage(err: unknown): string;
+export declare function fetchAdminApi(url: string, init: RequestInit, baseUrl: string): Promise<Response>;
 export declare class AdminApiClient {
     private readonly baseUrl;
     private readonly token;
@@ -106,7 +128,14 @@ export declare class AdminApiClient {
         logWindowHours?: number;
         timeoutSeconds?: number;
     }, outPath: string): Promise<void>;
-    listScopes(orgId: string): Promise<{
+    /**
+     * List secret scopes for an org.
+     *
+     * @param allBackends - Aggregate every registered backend and return scopes
+     *   in qualified `<backend>:<path>` form. Default (false) returns the bare,
+     *   pg-only listing; that default flips at v1.0.0.
+     */
+    listScopes(orgId: string, allBackends?: boolean): Promise<{
         scopes: string[];
     }>;
     listKeys(orgId: string, scope: string): Promise<{
@@ -150,6 +179,8 @@ export declare class AdminApiClient {
         reEncrypted: number;
         reEncryptedConfigs: number;
         skippedConfigs: number;
+        reEncryptedBackends: number;
+        skippedBackends: number;
     }>;
     createGenericSource(data: {
         orgId: string;
@@ -223,6 +254,8 @@ export declare class AdminApiClient {
         label: string;
         role: string;
         routingKey?: string;
+        /** Optional absolute expiry as an ISO datetime string. */
+        expiresAt?: string;
     }): Promise<{
         token: string;
         id: string;
@@ -294,6 +327,16 @@ export declare class AdminApiClient {
         version?: number;
         errors?: string[];
     }>;
+    /** Flip the coordinator drain flag on ('drain') or off ('resume'). */
+    drain(action: 'drain' | 'resume'): Promise<{
+        draining: boolean;
+        jobsRunning: number;
+    }>;
+    /** Report the coordinator's current drain state without changing it. */
+    drainStatus(): Promise<{
+        draining: boolean;
+        jobsRunning: number;
+    }>;
     createApiKey(opts: {
         label?: string;
         routingKeys?: string[];