@kici-dev/orchestrator 0.11.0 → 0.12.0

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

@@ -1,12 +1,11 @@
 /**
  * Predicate + projection evaluation for the shared `createMockDb` harness.
  *
- * Kept BYTE-IDENTICAL in two places —
- * `packages/orchestrator/src/__test-helpers__/mock-db-query.ts` and
- * `packages/platform/src/__test-helpers__/mock-db-query.ts`. Each package owns an
+ * Kept BYTE-IDENTICAL in the orchestrator and the Platform, which each carry a
+ * copy. Each package owns an
  * independent `createMockDb` builder and neither package may import the other, so
- * the evaluator is duplicated rather than shared. `mock-db-mirror.test.ts` in both
- * packages fails the moment the copies diverge.
+ * the evaluator is duplicated rather than shared. A drift test fails the moment
+ * the copies diverge.
  *
  * `createMockDb` used to return its configured rows verbatim, whatever the
  * query asked for: a `.where(...)` or a `.select([...])` was recorded on a spy

package/dist/agent/agent-version.d.ts

@@ -4,8 +4,8 @@
  * An agent reports its own package version in `agent.register`
  * (`agentRegisterSchema.version`), and the field is optional — an agent old
  * enough to omit it predates every feature this module gates on. The
- * orchestrator and the agent are deployed and upgraded independently
- * (`.claude/rules/compatibility.md`), so a feature the orchestrator ships is
+ * orchestrator and the agent are deployed and upgraded independently,
+ * so a feature the orchestrator ships is
  * routinely dispatched to a fleet that cannot run it, and the version is the
  * only fact the orchestrator has about what the fleet understands.
  */
@@ -16,9 +16,9 @@ type VersionBase = [number, number, number];
  * the string is not a version at all.
  *
  * The prerelease suffix is dropped rather than ordered because the suffixes in
- * play are build counters from the dev registry (`0.5.0-9159`), not semver
- * release candidates. Strict semver orders those BELOW `0.5.0`, which would
- * read every staging agent as too old for a feature it in fact carries.
+ * play are build counters (`0.5.0-9159`), not semver release candidates. Strict
+ * semver orders those BELOW `0.5.0`, which would read every agent on a
+ * prerelease build as too old for a feature it in fact carries.
  */
 export declare function parseVersionBase(version: string): VersionBase | null;
 /**

package/dist/agent/dispatcher.d.ts

@@ -444,6 +444,32 @@ export declare class Dispatcher {
     private failRefusedDispatch;
     /** Free the slot and tracking a claim took on its agent; a claim for no agent took none. */
     private releaseClaimAccounting;
+    /**
+     * Release the slot and tracking `jobId` holds on `agentId`, if the job is
+     * still tracked there. Returns false when another path (a refusal, a
+     * put-back, a disconnect) already took it.
+     */
+    private releaseTrackedClaim;
+    /**
+     * Hand a job this coordinator just claimed from the queue to `agentId`,
+     * whose slot the claim took. A query that fails before the job is sent
+     * returns the claim ({@link returnUndeliveredClaim}) and rethrows, so the
+     * agent is not left holding a slot for a job it never received.
+     *
+     * @returns whether the job was sent.
+     */
+    private sendClaimedJob;
+    /**
+     * Put back a job a queue claim took but did not send: a query failed between
+     * the claim and the send. The agent's slot (and the job's tracking, once
+     * taken) is released so the agent takes work again, and the row returns to
+     * pending without spending a dispatch attempt, since no agent saw it. The
+     * next drain or the pending re-drive offers it again. A job a refusal or a
+     * disconnect already took is left to that path. If the put-back fails too,
+     * the row stays dispatched with no ack deadline and the stale-dispatch scan
+     * reaps it.
+     */
+    private returnUndeliveredClaim;
     /** Record that a job began executing on its agent. */
     markJobStarted(jobId: string): void;
     /**

package/dist/agent/registry.d.ts

@@ -117,7 +117,7 @@ export interface AgentEntry {
      * The `agent_tokens.id` row used to authenticate this connection, or
      * `null` when auth mode is `none`. Indexed by `tokenIdIndex` so a
      * synchronous revocation kick can enumerate every WS authenticated by
-     * a given token. in the pentest catalog.
+     * a given token.
      */
     tokenId: string | null;
     hostname: string | null;
@@ -240,10 +240,9 @@ export declare class AgentRegistry {
      *
      * Idempotent: re-scheduling the same tokenId is a no-op as long as
      * a timer is still queued — a token's `expires_at` doesn't shift
-     * across reconnects of the same agent. Closes the sister gap
-     * to the revocation finding (`agent-token-revocation-stale-ws`,
-     * fixed in `993bc3d9d`) where natural TTL expiration had no
-     * propagation path to in-flight WS connections.
+     * across reconnects of the same agent. Revocation kicks a token's
+     * in-flight WS connections at once; these timers do the same when
+     * the token reaches its natural TTL.
      */
     private readonly tokenExpiryTimers;
     /**
@@ -317,10 +316,9 @@ export declare class AgentRegistry {
      * Caller is the agent WS handler at register-time, when the token's
      * `agent_tokens.expires_at` column is non-null. Static tokens have
      * `expires_at = null` and are skipped at the call site (they have
-     * no TTL by design). Closes the sister gap to the revocation
-     * finding (`agent-token-revocation-stale-ws`, fixed in `993bc3d9d`)
-     * where natural TTL expiration had no propagation path to
-     * in-flight WS connections.
+     * no TTL by design). Revocation kicks a token's in-flight WS
+     * connections at once; this timer does the same at the token's
+     * natural TTL.
      */
     scheduleExpiryKick(tokenId: string, expiresAt: Date): void;
     /**

package/dist/agent-packaging/node-runtime-members.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The members of an official Node.js Linux or macOS archive that a KiCI payload
+ * vendors, relative to the archive's `node-v<version>-<os>-<arch>/` directory:
+ * the `node` binary, the `npm` and `npx` launchers, and the bundled npm package.
+ * With them in place, the agent's `resolveNpm()` finds
+ * `<nodeDir>/../lib/node_modules/npm/bin/npm-cli.js` beside the vendored `node`,
+ * so the builder role needs no npm on the host.
+ *
+ * This module has no imports so that repository tooling can read the list:
+ * `scripts/lib/node-dist.mjs` (the standalone package builder) keeps its own
+ * copy, and its test pins the two lists equal.
+ */
+export declare const NODE_RUNTIME_MEMBERS: readonly ['bin/node', 'bin/npm', 'bin/npx', 'lib/node_modules/npm'];
+//# sourceMappingURL=node-runtime-members.d.ts.map

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, wss }.
+ * Same pattern as the Platform's app: returns { app, wss }.
  */
 import type { Kysely } from 'kysely';
 import type pg from 'pg';
@@ -197,7 +197,7 @@ export interface AppDependencies {
      */
     faultInjection?: import('./fault-injection-types.js').OrchestratorFaultInjection;
     /**
-     * Orchestrator-owned provenance signing (Phase 1 root of trust). Present when
+     * Orchestrator-owned provenance signing (the 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`
@@ -342,7 +342,7 @@ export interface AppDependencies {
     globalWorkflowPolicy?: GlobalWorkflowPolicy;
     /** Inbound webhook delivery log writer. Optional -- if not set, deliveries are not persisted to event_log. */
     eventLogWriter?: EventLogWriter;
-    /** Cold-store handle (Phase E). Optional -- when present, admin event-log routes can serve archived rows. */
+    /** Cold-store handle. Optional -- when present, admin event-log routes can serve archived rows. */
     coldStore?: ColdStore | null;
     /** Read + mutation attribution log writer. Optional -- if not set, access_log rows are not written. */
     accessLogWriter?: AccessLogWriter;

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

@@ -50,7 +50,7 @@ export interface ApplyDecisionResult {
 export interface ApplyDecisionDeps {
     orgId: string;
     store: HeldRunStore;
-    /** Team name → member user ids (from the Plan-1 trust-policy cache). */
+    /** Team name → member user ids (from the trust-policy cache). */
     teamMembershipLookup: TeamMembershipLookup;
     /** Whether the run triggerer may self-approve (org_settings.allow_self_approval). */
     allowSelfApproval: boolean;

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

@@ -88,11 +88,10 @@ export declare class AccessLogWriter {
     recordInTransaction(executor: Kysely<Database> | Transaction<Database>, entry: AccessLogRecord): Promise<void>;
     private insert;
     /**
-     * Phase D: delegates to `loadAccessLogRange` so cold-store rows are
+     * Delegates to `loadAccessLogRange` so cold-store rows are
      * merged transparently when pagination crosses the warm cutoff. The
      * caller-visible `{items, nextCursor}` shape is preserved. NO
-     * --include-archived flag — access_log is "paginated/transparent"
-     * per design §7 row 11.
+     * --include-archived flag — access_log is "paginated/transparent".
      */
     query(filter: AccessLogQueryFilter): Promise<AccessLogQueryResult>;
     /**

package/dist/cli/commands/access-log.d.ts

@@ -2,9 +2,9 @@
  * Access log commands for kici-admin.
  *
  * Operator-facing read access to the orchestrator's access_log table
- * (read + mutation attribution with ActorPrincipal). Dogfood replacement
- * for raw psql when an operator asks "who read this run's payload last
- * Tuesday" or "show me everything a platform_operator actor did".
+ * (read + mutation attribution with ActorPrincipal). Use it instead of raw
+ * psql when an operator asks "who read this run's payload last Tuesday" or
+ * "show me everything a platform_operator actor did".
  *
  *   access-log list   List access-log rows with filters (cursor-paginated)
  *   access-log show   Show a single entry by id

package/dist/cli/commands/agent-service/agent-env.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The env file `kici-admin agent install` writes for a new agent. Each field
+ * lands in the variable the agent's config loader reads; that loader refuses
+ * any KICI_* variable it does not know, so a misspelt key here stops the agent
+ * at startup. `agent-env.test.ts` loads the rendered file through the agent's
+ * own loader to hold the two together.
+ */
+export interface AgentEnvFields {
+    /** First line of the file, a `#` comment naming what wrote it. */
+    header: string;
+    orchestratorUrl?: string;
+    token?: string;
+    /** Routing labels, written comma-separated. */
+    labels?: string[];
+    /** The agent's HTTP port; omitted, the agent uses its default. */
+    port?: number;
+}
+/** Render the env file, one `KEY=value` line per field that was given. */
+export declare function renderAgentEnvFile(fields: AgentEnvFields): string;
+//# sourceMappingURL=agent-env.d.ts.map

package/dist/cli/commands/agent-service/status.d.ts

@@ -1,9 +1,9 @@
 /**
  * `kici-admin agent status` command.
  *
- * Shows OS-level service status (state, PID, uptime) and queries
- * the running agent's health API for agent-specific info (labels,
- * orchestrator connection, current job).
+ * Shows OS-level service status (state, PID, uptime) and queries the
+ * running agent's `/health` endpoint for its ID, orchestrator connection,
+ * active job count, version, build fingerprint and uptime.
  *
  * Target resolution goes through resolveInstanceTarget — the same priority chain
  * every lifecycle command uses (--instance-dir > --name > CWD manifest >

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

@@ -6,7 +6,7 @@
  *                                   unverifiable rows; `--all` re-evaluates
  *                                   every row. Direct DB + object storage.
  *
- * Classified `kici-admin` (orchestrator DB plane) per .claude/rules/platform-admin.md.
+ * Belongs to `kici-admin`: it works on the orchestrator's database.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

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

@@ -18,8 +18,8 @@
  *
  *   Direct-DB mode: activated when `--database-url` is passed (or
  *   KICI_DATABASE_URL / DATABASE_URL is set). Opens its own pool and runs the
- *   SQL directly via *Direct helpers in @kici-dev/shared. Used by E2E
- *   `globalSetup` helpers that need to seed envs before the orchestrator is up.
+ *   SQL directly via *Direct helpers in @kici-dev/shared, so a setup script can
+ *   seed contexts before the orchestrator is up.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/event-dlq.d.ts

@@ -6,12 +6,11 @@
  *   event-dlq retry <id>     — clear DLQ flag, schedule for retry, pg_notify
  *   event-dlq discard <id>   — permanently delete a DLQ event
  *
- * Operator dogfooding path for at-least-once event delivery. Customers
- * should generally never see anything in
- * the DLQ — when something lands here it usually means a workflow handler is
- * consistently failing and should be fixed at its root cause. This CLI is the
- * triage surface: inspect last_error, retry once a fix is deployed, or discard
- * if the event is no longer relevant.
+ * Operator triage path for at-least-once event delivery. Customers should
+ * generally never see anything in the DLQ — when something lands here it
+ * usually means a workflow handler is consistently failing and should be fixed
+ * at its root cause. This CLI is the triage surface: inspect last_error, retry
+ * once a fix is deployed, or discard if the event is no longer relevant.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/event-log.d.ts

@@ -2,9 +2,8 @@
  * Inbound webhook delivery log commands for kici-admin.
  *
  * Operator-facing read access to the orchestrator's event_log table via the
- * admin HTTP API. Dogfood replacement for raw psql / log-grep when an
- * operator asks "did delivery <id> arrive, and what did its payload look
- * like".
+ * admin HTTP API. Use it instead of raw psql / log-grep when an operator
+ * asks "did delivery <id> arrive, and what did its payload look like".
  *
  *   event-log list   List inbound deliveries with filters
  *   event-log show   Show a single delivery (optionally with payload)

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

@@ -7,9 +7,7 @@
  * READ-ONLY — mutations (purge-stale) live in `maintenance.ts` instead.
  * Dual-mode: HTTP (via AdminApiClient) or `--database-url` (direct DB).
  *
- * supersedes the original `cache list|show` framing: the real tables
- * the E2E call sites touch are execution_runs / execution_jobs, not
- * dedup_cache.
+ * The rows come from execution_runs / execution_jobs, not dedup_cache.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/orchestrator-service/status.d.ts

@@ -1,9 +1,9 @@
 /**
  * `kici-admin orchestrator status` command.
  *
- * Shows OS-level service status (state, PID, uptime) and queries
- * the running orchestrator's health API for KiCI-specific info
- * (mode, DB connectivity, agents, jobs, scaler).
+ * Shows OS-level service status (state, PID, uptime) and queries the
+ * running orchestrator's `/health` and `/ready` endpoints for its version,
+ * build fingerprint, uptime and readiness (database reachable, boot finished).
  *
  * Target resolution goes through resolveInstanceTarget — the same priority chain
  * every lifecycle command uses (--instance-dir > --name > CWD manifest >
@@ -11,6 +11,13 @@
  */
 import type { Command } from 'commander';
 import { type ServicePlatform } from '../../service/index.js';
+/**
+ * How long to wait for `/ready`. Its database check waits up to the pool's
+ * acquire timeout before it reports `database: false`, so the wait covers that
+ * timeout plus a margin. An acquire timeout of 0 lets the pool wait without
+ * limit; the default then bounds the wait.
+ */
+export declare function readinessTimeoutMs(envContent: string): number;
 /**
  * The config files this install owns, for an operator who wants to inspect
  * them. Derived from the instance manifest and the env file on disk, not from

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

@@ -7,8 +7,7 @@
  * READ-ONLY — mutations live in `maintenance.ts` (queue clear) instead.
  * Dual-mode: HTTP (via AdminApiClient) or `--database-url` (direct DB).
  *
- * supersedes the original `cache list|show` framing — the E2E call
- * sites were actually querying dispatch_queue, not a dedup cache.
+ * The rows come from dispatch_queue, not a dedup cache.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

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

@@ -2,9 +2,8 @@
  * Execution run commands for kici-admin.
  *
  * Provides operator-facing read access to execution runs and their
- * sub-resources via the orchestrator's admin HTTP API. This is the
- * dogfooded replacement for hand-rolled curl commands when inspecting
- * run state.
+ * sub-resources via the orchestrator's admin HTTP API. Use it instead of
+ * hand-rolled curl commands when inspecting run state.
  *
  *   runs list                          List execution runs (table or JSON)
  *   runs show <runId>                  Show run detail with jobs and steps

package/dist/cli/commands/service-health.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Reads a locally installed KiCI service's health endpoints and formats what
+ * they report. `kici-admin orchestrator status` and `kici-admin agent status`
+ * both render through here, so the two sections agree on layout and on how a
+ * missing field is handled.
+ */
+import { type BuildFingerprint, type LivenessBase } from '@kici-dev/shared';
+/** A label and its value: one line of a status section. */
+export type StatusRow = readonly [label: string, value: string];
+/**
+ * Read the env file, or empty content when it is missing or unreadable. A file
+ * this account may not read is reported: the port and address the caller then
+ * falls back to may not be the ones the service uses. On Windows only
+ * LocalSystem and Administrators can read a service's env file.
+ */
+export declare function readEnvContent(envFilePath: string, warn?: (line: string) => void): string;
+/** Where a service installed on this host answers HTTP. */
+export interface LocalEndpoint {
+    host: string;
+    port: number;
+    /** The prefix the service's routes are mounted under; empty when they sit at `/`. */
+    pathPrefix: string;
+}
+/**
+ * Where the service answers, read from its env file: `KICI_PORT` (or
+ * `defaultPort`), `KICI_HOST` and `KICI_BASE_PATH`. A service bound to every
+ * interface is reached on `localhost`; one bound to a single address is reached
+ * there. The agent reads none of the last two, so its env file never sets them.
+ */
+export declare function readLocalEndpoint(envContent: string, defaultPort: number): LocalEndpoint;
+/** The URL of `pathname` on `endpoint`, with an IPv6 host bracketed. */
+export declare function localUrl(endpoint: LocalEndpoint, pathname: string): string;
+/**
+ * GET a JSON body from a service on this host. `acceptStatuses` names the
+ * non-2xx codes whose body is still an answer: `/ready` returns its checks
+ * with a 503 when one fails. Returns null when nothing answers in time.
+ */
+export declare function fetchLocalJson<T>(endpoint: LocalEndpoint, pathname: string, opts?: {
+    acceptStatuses?: readonly number[];
+    timeoutMs?: number;
+}): Promise<T | null>;
+/**
+ * A `/health` body with its deprecated `buildCommit` replaced by its version.
+ * A service older than this CLI reports a commit ID from KiCI's private
+ * repository there, which a reader cannot resolve; `--json` keeps the key, a
+ * string as before, and carries the release version in it. A body that reports
+ * no `buildCommit` comes back unchanged.
+ */
+export declare function hideBuildCommit<T extends {
+    version?: string;
+    buildCommit?: string;
+}>(health: T): T;
+/**
+ * Rows for the build fingerprint and process uptime of a `/health` body. A
+ * field the body lacks is skipped, so a service older than this CLI renders
+ * the fields it does report. The version line never shows `buildCommit`
+ * (see {@link hideBuildCommit}).
+ */
+export declare function buildInfoRows(health: Partial<LivenessBase & BuildFingerprint & {
+    buildDate: string;
+}>): StatusRow[];
+/**
+ * A status section: a blank separator line, the heading, then one line per
+ * row with each value starting at `valueColumn`. A body with no field this CLI
+ * recognises still gets a line saying so, so the heading never stands alone.
+ */
+export declare function formatHealthSection(heading: string, rows: readonly StatusRow[], valueColumn: number): string[];
+//# sourceMappingURL=service-health.d.ts.map

package/dist/cli/commands/shared/env-file-mode.d.ts

@@ -9,8 +9,9 @@
  * `cluster/peer-credentials.ts`.
  *
  * The guarantee is POSIX-only. Node maps a mode onto Windows by toggling the
- * read-only attribute and changes no ACL, so a Windows install must restrict
- * the file itself.
+ * read-only attribute and changes no ACL, so a Windows install restricts the
+ * folder that holds the file instead (`restrictEnvFileAccess`,
+ * `cli/service/windows-acl.ts`).
  */
 export declare const ENV_FILE_MODE = 384;
 //# sourceMappingURL=env-file-mode.d.ts.map

package/dist/cli/commands/shared/upgrade-safety.d.ts

@@ -19,6 +19,11 @@ export declare function waitForQuiesce(poll: () => Promise<DrainSnapshot>, opts:
     quiesced: boolean;
     jobsRunning: number;
 }>;
+/**
+ * What a version switch prints when it cannot read the live migration ledger,
+ * so it could not compare the schema to the recorded head.
+ */
+export declare const SCHEMA_NOT_CHECKED = "The running service could not be reached, so the schema was not checked.";
 /** One entry of `GET /api/v1/admin/db/migrate/status`. */
 export interface MigrationStatusRow {
     name: string;
@@ -47,11 +52,12 @@ export type SchemaGuardVerdict = {
  * Decide whether the version pointer may move.
  *
  * Three outcomes, and the middle one is the compatibility shim: an instance
- * installed before `migrationHeads` existed has no recorded head, and refusing
- * there would break the documented `--rollback` on exactly the installs that
- * predate the guard. So an unknown head warns loudly and falls through to the
- * existing confirmation prompt; the map is populated at the next version
- * change, arming the guard one upgrade later.
+ * installed before `migrationHeads` existed, or one whose upgrade away from the
+ * target ran without admin access, has no recorded head, and refusing there
+ * would break the documented `--rollback` on exactly those installs. So an
+ * unknown head warns loudly and falls through to the existing confirmation
+ * prompt; the map is populated at the next version change with admin access,
+ * arming the guard one upgrade later.
  */
 export declare function schemaGuardVerdict(input: {
     targetVersion: string;

package/dist/cli/commands/shared/versioned-upgrade.d.ts

@@ -11,9 +11,9 @@ import { type NpmInstallTarget, type ResolvedInstance, type ServiceManager, type
 import type { LaunchSpec, ServiceConfig } from '../../service/types.js';
 import { type MigrationStatusRow } from './upgrade-safety.js';
 /** Component types that can be upgraded. */
-type UpgradeComponent = 'orchestrator' | 'agent';
+export type UpgradeComponent = 'orchestrator' | 'agent';
 /** Options for the versioned upgrade command. */
-interface VersionedUpgradeOptions {
+export interface VersionedUpgradeOptions {
     platform?: ServicePlatform;
     /**
      * Service name. No default — targeting flows through {@link resolveInstanceTarget}
@@ -130,8 +130,8 @@ export declare function resolveUpgradeTarget(args: {
  * Install base for a KiCI component instance.
  *
  * Name-scoped so that two instances of the same component (e.g. an org's
- * dogfood orchestrator and an E2E test orchestrator) own independent
- * versioned trees and symlinks. Per-platform bases:
+ * production orchestrator and a test orchestrator on the same host) own
+ * independent versioned trees and symlinks. Per-platform bases:
  *   - systemd / compose: /opt/kici/<name>/
  *   - launchd:           /usr/local/kici/<name>/
  *   - windows:           C:\Program Files\KiCI\<name>\
@@ -171,6 +171,55 @@ export declare function checkPickFlagConflicts(opts: {
     rollback?: boolean;
     cleanup?: boolean;
 }): string | null;
+/**
+ * Stop the service, register it again on Windows, then start it: the restart
+ * every npm-source upgrade ends with.
+ *
+ * `npm install -g` replaces the package in place, so the launch command the
+ * service runs (`spec`, read back from its registration) stays valid. On
+ * Windows the registration around that command (the service wrapper's
+ * arguments, the description, the recovery settings) is whatever the CLI that
+ * installed it wrote, so `install` writes the current one, as the archive
+ * upgrade does. A launch command that names a file that does not exist was
+ * read back wrong, so it is not registered: the service restarts as it was,
+ * with a warning. systemd and launchd keep their unit as it is.
+ */
+export declare function restartOntoInstalledPackage(args: {
+    manager: ServiceManager;
+    config: ServiceConfig;
+    platform: ServicePlatform;
+    spec: LaunchSpec | null;
+}): Promise<void>;
+/**
+ * Extract a release archive into `tmpDir` and return the release folder in it.
+ * On Windows a release from before KICI_ENV_FILE is refused here, before
+ * anything is copied into the install base or the service is stopped.
+ */
+export declare function extractRelease(args: {
+    archivePath: string;
+    tmpDir: string;
+    component: UpgradeComponent;
+    platform: ServicePlatform;
+    version: string;
+    config: ServiceConfig;
+}): string;
+/**
+ * Put the release in `archivePath` at `versionedDirPath`. The release is
+ * extracted and checked first ({@link extractRelease}); only then is a folder
+ * already at `versionedDirPath` removed, which the caller allows with
+ * `--force`, and the release copied in. A refused release leaves the install
+ * base as it was.
+ */
+export declare function installRelease(args: {
+    archivePath: string;
+    tmpDir: string;
+    installBase: string;
+    versionedDirPath: string;
+    component: UpgradeComponent;
+    platform: ServicePlatform;
+    version: string;
+    config: ServiceConfig;
+}): void;
 /**
  * Perform a versioned directory upgrade for a KiCI component.
  *
@@ -252,13 +301,36 @@ export declare function planNpmSourceUpgrade(opts: {
     force: boolean;
     windows: boolean;
 }): NpmSourceUpgradeAction;
-/** Injected process runner seam for {@link installGlobalPackage}. */
-type SpawnRunner = (cmd: string, args: string[], opts?: {
+/** Injected process runner seam for the npm calls of an npm-source upgrade. */
+export type SpawnRunner = (cmd: string, args: string[], opts?: {
     env?: NodeJS.ProcessEnv;
 }) => {
     status: number | null;
+    stdout: string;
     stderr: string;
 };
+/**
+ * The cmd.exe command line for npm on Windows. npm is a batch file there, which
+ * Node.js starts only through a shell, and Node.js joins the parts of a shell
+ * command with spaces and quotes none of them. The standard Node.js install is
+ * under `C:\Program Files`, so the npm path is quoted here. An argument with a
+ * character outside those of a package name, a version or a flag is refused
+ * rather than handed to cmd.exe.
+ */
+export declare function windowsShellCommand(cmd: string, args: string[]): string;
+/**
+ * Whether `version` of the KiCI packages reads KICI_ENV_FILE, asked of the
+ * registry the unit's npm installs from. A release that reads it publishes the
+ * env-file loader in `@kici-dev/shared`, which every KiCI package of the same
+ * version depends on.
+ */
+export declare function npmReleaseReadsEnvFile(target: NpmInstallTarget, version: string, run?: SpawnRunner): {
+    ok: true;
+    reads: boolean;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Install `<owningPackage>@<version>` globally under the unit's own pinned node,
  * so it lands in exactly the global prefix the unit's ExecStart resolves from.
@@ -278,6 +350,47 @@ export declare function installGlobalPackage(target: NpmInstallTarget, version:
     stderr: string;
 };
 export declare function performVersionedUpgrade(component: UpgradeComponent, opts: VersionedUpgradeOptions, hooks?: UpgradeHooks): Promise<void>;
+/** The inputs of {@link restartOnlyUpgrade}. */
+export interface RestartOnlyArgs {
+    component: UpgradeComponent;
+    config: ServiceConfig;
+    resolvedInstance: ResolvedInstance;
+    manager: ServiceManager;
+    verdict: NpmSourceLaunchVerdict;
+    opts: VersionedUpgradeOptions;
+    platform: ServicePlatform;
+    /** The launch command read from the registration before the upgrade. */
+    spec: LaunchSpec | null;
+}
+/** The inputs of {@link performSelfDrivingInstall}. */
+export interface SelfDriveArgs extends Omit<RestartOnlyArgs, 'verdict'> {
+    action: {
+        target: NpmInstallTarget;
+        version: string;
+    };
+    /** Runs npm; tests inject it. */
+    run?: SpawnRunner;
+}
+/**
+ * Restart-only path: the operator pre-installed `@kici-dev/<pkg>@<version>` (or
+ * kici-admin) themselves. Verify the unit will launch the invoking CLI's version,
+ * restart onto it, and persist the manifest version.
+ */
+export declare function restartOnlyUpgrade(args: RestartOnlyArgs): Promise<void>;
+/**
+ * Self-driving path: install the resolved global package under the unit's own
+ * pinned node/npm, restart, and verify the unit now launches the requested
+ * version.
+ */
+export declare function performSelfDrivingInstall(args: SelfDriveArgs): Promise<void>;
+/**
+ * Stop the service, switch the active version pointer to an already-installed
+ * versioned directory (atomic symlink on Unix; re-registration + version file
+ * on Windows), restart, and persist the new `kiciVersion` into the manifest.
+ *
+ * Shared by `--rollback` (switch to the previous version) and `--pick` (switch
+ * to any chosen installed version).
+ */
 export declare function switchToInstalledVersion(args: {
     component: UpgradeComponent;
     platform: ServicePlatform;
@@ -293,5 +406,4 @@ export declare function switchToInstalledVersion(args: {
     /** Skip the confirmation the unknown-head warning falls through to. */
     yes?: boolean;
 }): Promise<void>;
-export {};
 //# sourceMappingURL=versioned-upgrade.d.ts.map