@kici-dev/orchestrator 0.10.0 → 0.12.0

package/dist/queue/job-queue.d.ts

@@ -612,12 +612,12 @@ export declare class JobQueue {
      * declared failed, so any dispatch_queue row still in `Pending`,
      * `Recovering`, or `Dispatched` is by definition orphaned and must
      * also be moved to `Failed` — leaving a `Dispatched` row in place
-     * keeps the row in a non-terminal state forever, which the build-timeout
-     * E2E (and any operator query for "is this run actually done") relies
-     * on never happening. The complementary {@link markCompleted} status
-     * guard ensures a late `job.complete` from the agent that was still
-     * working when the run was declared failed cannot flip the row back
-     * to `Completed`.
+     * keeps the row in a non-terminal state forever, which any caller
+     * polling for a terminal state (and any operator query for "is this
+     * run actually done") relies on never happening. The complementary
+     * {@link markCompleted} status guard ensures a late `job.complete` from
+     * the agent that was still working when the run was declared failed
+     * cannot flip the row back to `Completed`.
      *
      * @returns Number of affected rows.
      */

package/dist/queue/scheduled-job.d.ts

@@ -1,19 +1,17 @@
 /**
  * Orchestrator scheduled-job wrapper.
  *
- * Mirrors `packages/platform/src/queue/scheduled-job.ts` in observable
+ * Mirrors the Platform's scheduled-job wrapper in observable
  * surface (5 Prometheus metrics + structured logs + audit row on
  * failure) but uses `setInterval` instead of pg-boss — the orchestrator
  * has no pg-boss dependency and we're not adding one.
  *
- * All future orchestrator periodic jobs MUST use this wrapper — per
- * CLAUDE.md "no workarounds", the legacy setInterval call sites in
- * queue/cleanup.ts and secrets/cleanup.ts migrate in the same phase
- * they'd otherwise be updated.
+ * Every orchestrator periodic job MUST use this wrapper, as the cleanup
+ * jobs in queue/cleanup.ts and secrets/cleanup.ts do.
  *
  * `triggerNow()` on the returned handle forces one off-cadence tick
  * (used by the admin `/api/v1/admin/scheduled-jobs/:name/trigger`
- * endpoint and by E2E harnesses). It does NOT reset the interval
+ * endpoint and by tests). It does NOT reset the interval
  * timer — a real tick still fires at the scheduled cadence after.
  */
 import { z } from 'zod';
@@ -60,7 +58,7 @@ export interface OrchestratorScheduledJobHandle {
     stop(): void;
     /**
      * Force one off-cadence tick and await it (success or failure).
-     * Returns the tick's outcome so E2E and admin routes can report it.
+     * Returns the tick's outcome so callers such as the admin route can report it.
      */
     triggerNow(): Promise<{
         ok: boolean;

package/dist/registration/extractor.d.ts

@@ -5,7 +5,7 @@ import type { LockFile, LockTrigger, LockWorkflow } from '@kici-dev/engine';
  * Non-Git-provider triggers (kici_event, schedule, webhook, …) live in the
  * registration table because they have no per-repo lock file pipeline to
  * fall back to. Git-provider triggers (push, pr, tag, …) ALSO live in the
- * registration table so that the cross-source dispatch path (phase 28.5)
+ * registration table so that the cross-source dispatch path
  * can resolve them by (customer_id, repo_identifier) when a generic webhook
  * targets an externally-hosted repo. The per-event lock file pipeline still
  * handles same-source dispatch for git triggers; registration is an additive

package/dist/registration/registration-index.d.ts

@@ -73,7 +73,7 @@ export declare class RegistrationIndex {
     private byOrgAndEvent;
     /**
      * Quinary index: registrations keyed by `${customerId}|${repoIdentifier}`.
-     * Drives the cross-source repo lookup (phase 28.5): when a generic webhook
+     * Drives the cross-source repo lookup: when a generic webhook
      * carries a repository identifier in its payload, the dispatcher looks up
      * registrations for that (org, repo) pair across ALL routing keys and uses
      * each registration's stored `providerContext` + `routingKey` to reach the

package/dist/reporting/execution-tracker.d.ts

@@ -716,7 +716,7 @@ export declare class ExecutionTracker {
      */
     private runInvokeGateAggregationHook;
     /**
-     * Phase 9: stuck-jobs invariant check ( Layer 3).
+     * Phase 9: stuck-jobs invariant check (Layer 3).
      * Before declaring a run complete, verify no stuck jobs exist. If any are
      * found, fail them via recursive onJobStatus calls and signal the caller to
      * stop (returns true) — the recursive calls will re-enter and re-check
@@ -786,8 +786,8 @@ export declare class ExecutionTracker {
      * Create a failed execution run when the build timed out before onExecutionStarted
      * had a chance to insert the row (buildJobTrackedEarly was false).
      *
-     * Inserts a minimal execution_runs row with status='failed' directly so the E2E
-     * test (and dashboard) can observe the failure instead of a missing run.
+     * Inserts a minimal execution_runs row with status='failed' directly so the
+     * dashboard (and any run query) can observe the failure instead of a missing run.
      *
      * The fifth pre-dispatch recording site, and the third that writes the row and
      * returns. Its row is terminal with no resume path, so no invoke gate ever

package/dist/routes/admin-access-log.d.ts

@@ -4,7 +4,7 @@
  * Operator-facing read access to read + orchestrator-admin mutation attempts
  * captured with ActorPrincipal attribution. Mirrors the dashboard's
  * dashboard.access-log.list WS handler but exposed over HTTP + Bearer auth
- * so operators can dogfood from the CLI without going through the dashboard.
+ * so operators can read it from the CLI without going through the dashboard.
  *
  *   GET /api/v1/admin/access-log
  *     Filters: orgId, actorType, actorId, action, source, outcome,

package/dist/routes/admin-auth.d.ts

@@ -26,8 +26,8 @@ import type { Role } from '../secrets/rbac.js';
  * The three admin-auth response bodies.
  *
  * A single map rather than string literals repeated across every admin router:
- * the 401 wordings are observed by operators and by E2E assertions, so they are
- * pinned in exactly one place.
+ * the 401 wordings are observed by operators and asserted on by tests, so they
+ * are pinned in exactly one place.
  */
 export declare const AUTH_ERROR: {
     readonly missing: 'Missing authorization';

package/dist/routes/admin-contexts.d.ts

@@ -11,6 +11,12 @@
  *   GET    /api/v1/admin/contexts/:name/variables?orgId=<id>         — list org-level variables
  *   PUT    /api/v1/admin/contexts/:name/variables/:key?orgId=<id>    — upsert variable
  *   DELETE /api/v1/admin/contexts/:name/variables/:key?orgId=<id>    — delete variable
+ *   GET    /api/v1/admin/contexts/:name/source-overrides?orgId=<id>[&routingKey=<k>]
+ *                                                                    — list per-source overrides
+ *   PUT    /api/v1/admin/contexts/:name/source-overrides/:routingKey/:key?orgId=<id>
+ *                                                                    — upsert a source override
+ *   DELETE /api/v1/admin/contexts/:name/source-overrides/:routingKey/:key?orgId=<id>
+ *                                                                    — delete a source override
  *
  * Backs the `kici-admin context` dual-mode CLI. Offline (direct-DB) mode
  * bypasses this router entirely — the CLI calls `*Direct` helpers from

package/dist/routes/admin-event-log.d.ts

@@ -4,7 +4,7 @@
  * Operator-facing read access to the per-delivery records the orchestrator
  * persists for every inbound webhook. Mirrors the dashboard's WS handler
  * (`DashboardHandler.handleEventLogList/Detail`) but is exposed over HTTP +
- * Bearer auth so operators can dogfood from the CLI without going through
+ * Bearer auth so operators can read it from the CLI without going through
  * the dashboard.
  *
  *   GET /api/v1/admin/event-log
@@ -28,7 +28,7 @@ export interface AdminEventLogRoutesDeps {
     logStorage: LogStorage;
     tokenManager: TokenManager;
     rbac: RbacEnforcer;
-    /** Phase E: optional cold-store for archived event_log rows. */
+    /** Optional cold-store for archived event_log rows. */
     coldStore?: ColdStore;
 }
 type AdminEnv = {

package/dist/routes/admin-registrations.d.ts

@@ -1,8 +1,8 @@
 /**
  * Admin API routes for workflow registration management.
  *
- * Provides endpoints for listing, inspecting, refreshing, and deleting
- * workflow registrations. All routes are protected by Bearer token
+ * Provides endpoints for listing, inspecting, refreshing, disabling and
+ * deleting workflow registrations. All routes are protected by Bearer token
  * authentication via the existing admin auth middleware pattern.
  */
 import { Hono } from 'hono';

package/dist/routes/admin-runs.d.ts

@@ -14,9 +14,9 @@
  *   GET /api/v1/admin/runs/:runId/ephemeral-key   — scrub status
  *   GET /api/v1/admin/runs/:runId/secret-outputs  — masked by default; ?reveal=true
  *
- * This is the server-side counterpart to `kici-admin runs` — the dogfooded
- * replacement for hand-rolled curl commands and dashboard clicks when
- * verifying execution state.
+ * This is the server-side counterpart to `kici-admin runs`, which replaces
+ * hand-rolled curl commands and dashboard clicks when verifying execution
+ * state.
  */
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';

package/dist/routes/admin-scheduled-jobs.d.ts

@@ -6,9 +6,8 @@
  *     Requires: scheduled_job.trigger role permission (owner + admin roles)
  *     Returns: { triggered: true, ok: boolean, durationMs: number, error?: string }
  *
- * Phase A's E2E smoke uses this endpoint to force a cold-store-archive
- * tick without waiting for the hourly cron. Future dashboard "Run now"
- * buttons use it too.
+ * Use it, for example, to force a cold-store-archive tick without waiting
+ * for the hourly cadence.
  *
  * The access_log row is written directly (not via the typed
  * AccessLogWriter) because `scheduled_job.trigger` is not in the

package/dist/routes/health.d.ts

@@ -1,5 +1,14 @@
+import { type BuildFingerprint } from '@kici-dev/shared';
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
+/**
+ * The fields the orchestrator adds to its `/health` body. The route below
+ * returns this type, and `kici-admin orchestrator status` renders it.
+ */
+export interface OrchestratorLivenessInfo extends BuildFingerprint {
+    /** ISO-8601 time the orchestrator bundle was built. */
+    buildDate: string;
+}
 export interface HealthRoutesDeps {
     /** Optional DB instance for readiness checks */
     db?: Kysely<Database>;

package/dist/scaler/container-backend.d.ts

@@ -41,7 +41,7 @@ export interface ContainerScalerBackendOptions {
     runtime?: 'docker' | 'podman' | 'auto';
     /** Default resource limits applied when label set has none */
     defaultResources?: ResourceRequest;
-    /** Extra host:IP mappings injected into spawned containers (e.g. ["verdaccio.local:host-gateway"]) */
+    /** Extra host:IP mappings injected into spawned containers (e.g. ["registry.local:host-gateway"]) */
     extraHosts?: string[];
     /** Disable nftables-based network isolation (default: true). Set to false when nft is unavailable (e.g. rootless containers without NET_ADMIN). */
     networkIsolation?: boolean;

package/dist/scaler/firecracker-backend.d.ts

@@ -21,13 +21,6 @@ import type { IpAllocator, IpAllocationResult } from './ip-allocator.js';
 import type { AgentTokenStore } from '../agent/token-store.js';
 import { type FirecrackerBridgeConfig, type BridgeHealth, type ExecOptions } from '../firecracker/host-network.js';
 import type { ScalerBackend, ScalerDestroyContext, ScalerEntry, ManagedAgent, LabelSetConfig, ScalerEventCallback, ValidationResult, EffectiveLimits, SpawnContext } from './types.js';
-/**
- * Infrastructure interfaces that share the `kici-` prefix but must NEVER be
- * deleted by the orphan sweep. Bridges (kici-br0/kici-br1) carry all VM
- * traffic; kici-m01 is the staging metadata interface. Losing any of these
- * kills all running VMs.
- */
-export declare const PROTECTED_INTERFACES: readonly string[];
 /** Extended ManagedAgent that includes the allocated IP for cleanup */
 export interface FirecrackerManagedAgent extends ManagedAgent {
     /** Allocated IP address for TAP/IP release during destroy */
@@ -80,6 +73,11 @@ export interface FirecrackerScalerBackendOptions {
     cidr?: string;
     /** Gateway IP for guest networking */
     gateway: string;
+    /**
+     * Extra `host:address` mappings the rootfs `/init` appends to each guest's
+     * `/etc/hosts`; `host-gateway` resolves to {@link gateway}. None by default.
+     */
+    extraHosts?: string[];
     /** Netmask for guest networking */
     netmask: string;
     /** nft table name for host-network diagnostics. @default 'kici' */
@@ -145,6 +143,8 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
     private readonly bridgeName;
     private readonly cidr;
     private readonly gateway;
+    /** The MMDS `kici-extra-hosts` value, or undefined when the scaler maps no host. */
+    private readonly guestExtraHosts;
     /** Host services the orchestrator directed agents at, as `hostAccess` entries. */
     private readonly hostServices?;
     private readonly netmask;
@@ -180,6 +180,11 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
      * because `cleanupFailedSpawn` removes the tracking entry.
      */
     private abandonSpawn;
+    /**
+     * {@link abandonSpawn} from a path that cannot await it (an abort listener, a
+     * process exit handler). A failure is logged.
+     */
+    private abandonSpawnDetached;
     getScalerContext(agentId: string): Record<string, unknown> | undefined;
     /**
      * Bridge config for host-network diagnostics (read-only snapshot).
@@ -305,9 +310,9 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
     /**
      * Default interval for periodic orphan sweeps (15 minutes).
      *
-     * Long-running orchestrators need in-process orphan sweeps because the
-     * external kici-leak-sweep timer skips TAP cleanup while a staging
-     * orchestrator is active (to avoid racing spawns). Without this, leaked
+     * Long-running orchestrators need in-process orphan sweeps because a
+     * host-level cleanup job skips TAP cleanup while an orchestrator is active
+     * (to avoid racing spawns). Without this, leaked
      * TAPs accumulate until the orchestrator restarts — which can be weeks.
      */
     private static readonly ORPHAN_SWEEP_INTERVAL_MS;

package/dist/scaler/firecracker-extra-hosts.d.ts

@@ -0,0 +1,20 @@
+/** The address keyword for the bridge gateway, as the container runtimes spell it. */
+export declare const HOST_GATEWAY = "host-gateway";
+export interface ExtraHost {
+    host: string;
+    /** An IPv4 or IPv6 address, or {@link HOST_GATEWAY}. */
+    address: string;
+}
+/**
+ * Parse one `host:address` entry. The host ends at the first colon, so an
+ * IPv6 address keeps its own colons. Throws on a malformed entry.
+ */
+export declare function parseExtraHost(entry: string): ExtraHost;
+/**
+ * The MMDS value the rootfs `/init` reads: `host:address` pairs joined by
+ * commas, with `host-gateway` replaced by `gateway`. `undefined` when the
+ * scaler configures no mapping, so the guest gets none. Throws on a malformed
+ * entry, and on `host-gateway` when `gateway` is not an IP address.
+ */
+export declare function renderGuestExtraHosts(entries: readonly string[] | undefined, gateway: string): string | undefined;
+//# sourceMappingURL=firecracker-extra-hosts.d.ts.map

package/dist/scaler/machine-ledger.d.ts

@@ -13,10 +13,9 @@
  * `mkdir` succeeds for exactly one caller when the directory does not exist,
  * so it works as a portable `flock` substitute without any native dependency.
  *
- * The plan considered `proper-lockfile` and `fs-ext` first; neither is a
- * transitive dep today (`pnpm why proper-lockfile` and `pnpm why fs-ext`
- * both empty), so we use the documented `mkdir` fallback. This avoids
- * adding a native binding for the sake of a single locking primitive.
+ * Neither `proper-lockfile` nor `fs-ext` is a dependency, so this uses the
+ * `mkdir` lock instead. This avoids adding a native binding for the sake of
+ * a single locking primitive.
  *
  * ## Crash safety
  *

package/dist/scaler/scaler-state-store.d.ts

@@ -346,7 +346,7 @@ export declare class ScalerStateStore {
      * the prune's verdict does not depend on it. It is written because the row
      * is the only surviving account of what became of a provision once the spawn
      * row is gone — which is what an operator investigating a torn-down
-     * provision, and the E2E that pins this behaviour, read it for.
+     * provision reads it for.
      */
     recordProvisionCondemned(agentId: string, scalerName: string, reason: string): Promise<void>;
     /**

package/dist/scaler/types.d.ts

@@ -476,7 +476,10 @@ export interface ScalerEntry {
     runtime?: 'docker' | 'podman' | 'auto';
     /** Orchestrator URL for spawned agents to connect back to */
     orchestratorUrl?: string;
-    /** Extra host:IP mappings injected into spawned containers (e.g. ["verdaccio.local:host-gateway"]) */
+    /**
+     * Extra host:IP mappings for spawned agents (e.g. ["registry.local:host-gateway"]): the
+     * container runtime's ExtraHosts, or each Firecracker guest's /etc/hosts.
+     */
     extraHosts?: string[];
     /** Disable nftables-based network isolation for container backend (default: true). Set to false when nft is unavailable. */
     networkIsolation?: boolean;

package/dist/secrets/audit-logger.d.ts

@@ -4,7 +4,7 @@
  * Records all secret access/denial events to the secret_audit_log table
  * for compliance and security monitoring.
  *
- * Phase D: query() supports cold-store read-through via the optional
+ * query() supports cold-store read-through via the optional
  * `coldStore` constructor argument and an `includeArchived` query
  * filter. Hot-only behavior is unchanged when neither is supplied.
  */
@@ -32,7 +32,7 @@ export declare class AuditLogger {
      * engine's `shouldRecordSecretResolve` helper) since they're written
      * once per JOB-step secret resolution and dwarf every other action's
      * volume. Denied resolves and every other action (`setSecret`,
-     * `deleteSecret`, `rotateKey`, `secret-outputs.reveal`) bypass the
+     * `deleteSecret`, the scope writes, `rotateKey`, `secret-outputs.reveal`) bypass the
      * sampler — they are transactional with the mutation and must always
      * land.
      *
@@ -54,7 +54,7 @@ export declare class AuditLogger {
         limit?: number;
         offset?: number;
         /**
-         * Phase D opt-in. When true, falls through to cold-store via
+         * Opt-in. When true, falls through to cold-store via
          * `loadSecretAuditLogRange` for any portion of the requested
          * window past the warm cutoff. Default false preserves the
          * original semantics.

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

@@ -56,9 +56,8 @@ export declare const REDUCED_PRIVILEGE_MARKER = "**Reduced privileges (untrusted
  *   event, and an untrusted tier also reaches an internal-event child run that
  *   inherited it.
  *
- * Kept in step with the dashboard's reduced-privilege banner
- * (`packages/dashboard/src/components/run-detail/degraded-run-banner.tsx`),
- * which describes the same run and may be read beside these checks.
+ * Kept in step with the dashboard's reduced-privilege banner, which
+ * describes the same run and may be read beside these checks.
  */
 export declare function buildReducedPrivilegeNote(tier: string | null | undefined, lockFileSource?: string | null): string | null;
 //# sourceMappingURL=reduced-privilege-note.d.ts.map

package/dist/security/trust-policy-store.d.ts

@@ -67,9 +67,9 @@ export declare class TrustPolicyStore {
 }
 /**
  * Build a TrustPolicyStore backed by its own connection pool to the given
- * orchestrator database URL. Mirrors `createHeldRunStoreFromUrl`; consumed by
- * E2E tests that assert the pushed policy is persisted in the real deployed
- * orchestrator DB rather than held in process memory.
+ * orchestrator database URL. Mirrors `createHeldRunStoreFromUrl`; exported for
+ * tests that assert the pushed policy is persisted in a real orchestrator DB
+ * rather than held in process memory.
  */
 export declare function createTrustPolicyStoreFromUrl(databaseUrl: string, opts?: {
     maxConnections?: number;

package/dist/server.d.ts

@@ -7,12 +7,13 @@
  *
  * Both modes connect a PlatformClient to the Platform relay and run an agent WS server.
  *
- * Startup sequence follows packages/platform/src/server.ts pattern:
+ * Startup sequence (the same one the Platform follows):
  * config -> DB -> migrations -> provider registry -> dispatcher -> PlatformClient -> app -> HTTP -> heartbeat
  *
  * Graceful shutdown in reverse order:
  * Platform client -> agent WS -> heartbeat -> HTTP -> DB
  */
+import '@kici-dev/shared/load-service-env-file';
 import type { OrchestratorFaultInjection } from './fault-injection-types.js';
 /**
  * Boot the Platform-connected orchestrator. Factored out of the module entry so