@kici-dev/orchestrator 0.1.13 → 0.1.15

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';
@@ -89,6 +91,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;
     /**

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';

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

@@ -0,0 +1,116 @@
+import type { CacheRefScope } from '@kici-dev/engine';
+import type { CacheStorage } from '../storage/types.js';
+/**
+ * Cluster-wide default quota: 5 GiB. Serves as the fallback when an org has no
+ * per-org override in `org_settings.user_cache_quota_bytes`. The cluster-wide
+ * value is itself operator-configurable via KICI_USER_CACHE_QUOTA_BYTES.
+ */
+export declare const DEFAULT_USER_CACHE_QUOTA_BYTES: number;
+/**
+ * Cluster-wide default entry TTL: 7 days. Fallback when an org has no per-org
+ * override in `org_settings.user_cache_ttl_ms`. The cluster-wide value is
+ * operator-configurable via KICI_USER_CACHE_TTL_MS.
+ */
+export declare const DEFAULT_USER_CACHE_TTL_MS: number;
+/**
+ * Per-org override of the cache quota + TTL, read from `org_settings` at
+ * operation time. A field left `undefined` means "no per-org override" — the
+ * cluster-wide default applies. Injected into `UserCache` so the cache stays
+ * decoupled from the DB layer (and unit-testable with a stub reader).
+ */
+export interface UserCacheOrgLimits {
+    quotaBytes?: number;
+    ttlMs?: number;
+}
+/** Resolves the per-org cache limits for an org id (e.g. an `org_settings` read). */
+export type UserCacheOrgLimitsReader = (orgId: string) => Promise<UserCacheOrgLimits>;
+/** Identifies the org + repo + write scope a cache operation targets. */
+export interface UserCacheRef {
+    org: string;
+    repo: string;
+    scope: CacheRefScope;
+    /** Required when scope === 'isolated' — the per-run isolation namespace. */
+    runId?: string;
+}
+/** Outcome of a restore: whether an entry matched and how to fetch it. */
+export interface UserCacheRestoreResult {
+    hit: boolean;
+    matchedKey?: string;
+    downloadUrl?: string;
+    tarHash?: string;
+}
+/** Outcome of begin-save: a presigned PUT to a temp key, or skip when the key already exists. */
+export interface UserCacheBeginSaveResult {
+    skip: boolean;
+    uploadUrl?: string;
+    tempKey?: string;
+}
+export declare class UserCache {
+    private readonly storage;
+    /** Cluster-wide default quota (the `KICI_USER_CACHE_QUOTA_BYTES` value). */
+    private readonly defaultQuotaBytes;
+    /** Cluster-wide default TTL (the `KICI_USER_CACHE_TTL_MS` value). */
+    private readonly defaultTtlMs;
+    /** Optional per-org override reader; absent = always use the cluster defaults. */
+    private readonly orgLimitsReader?;
+    constructor(opts: {
+        storage: CacheStorage;
+        /** Cluster-wide default quota (env-var default). */
+        quotaBytes?: number;
+        /** Cluster-wide default TTL (env-var default). */
+        ttlMs?: number;
+        /** Per-org override reader (org_settings). When unset, defaults apply. */
+        orgLimitsReader?: UserCacheOrgLimitsReader;
+    });
+    /**
+     * Resolve the effective quota + TTL for an org: the per-org override from
+     * `org_settings` when present, otherwise the cluster-wide default. A reader
+     * failure falls back to the defaults (logged) — the cache must never fail a
+     * restore/save because the settings lookup hiccupped.
+     */
+    private resolveLimits;
+    /**
+     * Sanitize a path segment so a key can never escape its org/repo/scope
+     * namespace. Beyond stripping disallowed characters, a segment consisting
+     * only of dots (`.`, `..`, …) is replaced wholesale: such a segment is a
+     * dot-segment that HTTP/S3 path canonicalization collapses (`a/./b` → `a/b`,
+     * `a/../b` → `b`), which both corrupts the namespace and breaks the SigV4
+     * signature on a pre-signed PUT/GET. Repo identifiers like `.` (the internal
+     * provider's repo id) hit exactly this case, so the all-dots guard keeps the
+     * object key canonical and the namespace boundary intact.
+     */
+    private seg;
+    /** Org-level prefix: the per-tenant isolation boundary and quota scope. */
+    private orgPrefix;
+    /** Org + repo prefix shared by every scope of a repo. */
+    private repoPrefix;
+    /** Namespace prefix for the WRITE scope of a ref (shared OR per-run isolated). */
+    private writePrefix;
+    /** Namespace prefixes the ref may READ, in priority order. Isolated reads its own run scope, then shared. */
+    private readPrefixes;
+    private finalKey;
+    /** Restore: try the exact key across read prefixes, then restoreKeys prefix scan (newest wins). */
+    restore(ref: UserCacheRef & {
+        key: string;
+        restoreKeys?: string[];
+    }): Promise<UserCacheRestoreResult>;
+    /** Try the exact key in read-prefix priority order. */
+    private restoreExact;
+    /** restoreKeys prefix fallback (ordered); within a prefix, list() returns newest-first. */
+    private restoreByPrefix;
+    /** Begin a save: presigned PUT to a temp key, or skip=true when the immutable key exists. */
+    beginSave(ref: UserCacheRef & {
+        key: string;
+    }): Promise<UserCacheBeginSaveResult>;
+    /** Commit a save: copy temp -> final, init metadata, store companion hash/size, delete temp, enforce quota. */
+    commitSave(ref: UserCacheRef & {
+        key: string;
+        tarHash: string;
+        sizeBytes: number;
+        tempKey?: string;
+    }): Promise<void>;
+    private readHash;
+    /** Evict oldest entries for the org until total tarball size <= the per-org quota. */
+    private enforceQuota;
+}
+//# sourceMappingURL=user-cache.d.ts.map

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

@@ -0,0 +1,56 @@
+/**
+ * Shared run-cancellation path.
+ *
+ * `cancelRunWithReason` is the single canonical implementation of "cancel
+ * this whole run, recording a reason". It is invoked by:
+ *
+ *  - the operator-facing `POST /api/v1/admin/runs/:runId/cancel` route
+ *    (user-initiated `kici cancel`), and
+ *  - the WorkflowDeadlineDetector, which cancels runs that exceeded their
+ *    workflow-level wall-clock timeout (TimeoutReason.workflow_timeout).
+ *
+ * Keeping one implementation means the deadline enforcer and the user cancel
+ * follow identical mechanics: send `job.cancel` to the agents running the
+ * run's jobs, cancel queued dispatch rows, mark pending/queued jobs cancelled,
+ * stamp the failure reason, and drive the run terminal when no agent work is
+ * outstanding.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { JobQueue } from '../queue/job-queue.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+export interface CancelRunDeps {
+    db: Kysely<Database>;
+    jobQueue: JobQueue;
+    dispatcher: Dispatcher;
+    registry: AgentRegistry;
+    executionTracker: ExecutionTracker;
+}
+export interface CancelRunOptions {
+    /** Force immediate SIGKILL on the agent (skip graceful hooks). */
+    force?: boolean;
+    /** Attribution stamped into execution_runs.cancelled_by. */
+    cancelledBy?: string;
+}
+export interface CancelRunResult {
+    /** Number of `job.cancel` messages dispatched to agents (running jobs). */
+    agentsNotified: number;
+    /** Number of pending/queued execution_jobs rows marked cancelled. */
+    pendingCancelled: number;
+}
+/**
+ * Cancel a whole run, recording `reason` on its cancelled jobs and (if not
+ * already set) on the run's failure_reason. Sends `job.cancel` to every agent
+ * holding a dispatched job for the run; cancels queued dispatch rows; marks
+ * pending/queued jobs cancelled. When no agent had outstanding work, drives
+ * 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.
+ */
+export declare function cancelRunWithReason(deps: CancelRunDeps, runId: string, reason: string, options?: CancelRunOptions): Promise<CancelRunResult>;
+//# sourceMappingURL=cancel-run.d.ts.map

package/dist/cli/commands/environment.d.ts

@@ -6,6 +6,7 @@
  *   environment set-policy     — update policy fields (branch, reviewers, timers, trust)
  *   environment list           — list environments for an org
  *   environment show           — show a single environment with variables + bindings
+ *   environment delete         — delete an environment (cascades bindings, variables, overrides; held-run history survives; pending held runs block with a clear error, resolved holds do not)
  *   environment create-template — create/update an environment template + its seed variables
  *
  * Each command supports two modes (stage-4 pattern from `maintenance.ts`):

package/dist/cli/service/index.d.ts

@@ -12,7 +12,7 @@ export { detectPlatform, isRoot, kiciConfigRoot, getConfigDir, getLogDir, getCac
 export { resolveUserLevel, type PrivilegeOpts } from './privilege.js';
 export type { Component, InstanceManifest, IndexEntry, ResolveOptions, ResolvedInstance, } from './instance/types.js';
 export { COMPONENTS, isComponent } from './instance/types.js';
-export { manifestFilename, manifestPath, readManifest, writeManifest, } from './instance/manifest.js';
+export { manifestFilename, manifestPath, readManifest, writeManifest, readKiciVersion, } from './instance/manifest.js';
 export { indexPath, readIndex, writeIndex, appendIndexEntry, removeIndexEntry, } from './instance/index-file.js';
 export { listInstances, resolveInstance, formatRefusal } from './instance/resolve.js';
 export type { ListedInstance, ResolveArgs, ListInstancesArgs } from './instance/resolve.js';

package/dist/cli/service/instance/manifest.d.ts

@@ -18,4 +18,13 @@ export declare function readManifest(instanceDir: string, component: Component):
  * Returns the full path written.
  */
 export declare function writeManifest(instanceDir: string, manifest: InstanceManifest): string;
+/**
+ * Read the running kici-admin's version from the orchestrator package.json.
+ *
+ * `process.env.npm_package_version` is only populated under `npm run` and is
+ * undefined when kici-admin runs as a globally-installed binary, which is the
+ * actual install path. Reading from the package.json on disk is the only
+ * reliable source.
+ */
+export declare function readKiciVersion(): string;
 //# sourceMappingURL=manifest.d.ts.map