@kici-dev/orchestrator 0.17.0 → 0.19.0

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

@@ -6,15 +6,11 @@
  *   registration disable <id> | enable <id>
  *   registration delete <id> [--yes]
  *
- * A distinct namespace from `workflow list` — `workflow` is workflow-code,
- * `registration` is the registered-workflow-instance row in
- * workflow_registrations. Both coexist.
+ * `workflow` is workflow code; `registration` is a workflow_registrations row.
  *
- * `list` and `show` are dual-mode: HTTP (via AdminApiClient on the
- * /api/v1/admin/registrations admin API) or `--database-url` (direct DB).
- * `disable`, `enable` and `delete` are HTTP only: they are the operator path
- * for the dashboard's registration writes, and the admin route bumps the
- * registry version so every peer reloads.
+ * `list` and `show` use the admin API or `--database-url`. `disable`,
+ * `enable` and `delete` are HTTP only: they back the dashboard's registration
+ * writes, and the admin route bumps the registry version so every peer reloads.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/remote-source.d.ts

@@ -1,16 +1,10 @@
 /**
- * Remote-source inspection command for kici-admin.
- *
- * Subcommand namespace: `kici-admin remote-source show`.
- *
- * The remote-source anchor (`remote_sources` table) maps the deterministic
- * routing key `remote:<orgId>` to the orchestrator's canonical org id so a
- * Platform-relayed `kici run remote` resolves the real tenant. It is
- * auto-provisioned on Platform auth; this command lets an operator inspect or
- * confirm the row when debugging org-anchor issues on a hidden orchestrator.
- *
- * Reads the orchestrator DB directly (on-host operator inspection), so it stays
- * usable even when Platform is unreachable.
+ * `kici-admin remote-source show`. The `remote_sources` row maps the routing
+ * key `remote:<orgId>` to the orchestrator's canonical org id, so a
+ * Platform-relayed `kici run remote` resolves the real tenant. Platform auth
+ * provisions it; this inspects it when debugging org anchoring on a hidden
+ * orchestrator. It reads the DB directly, so it works with the Platform
+ * unreachable.
  */
 import type { Command } from 'commander';
 export declare function registerRemoteSourceCommands(program: Command): void;

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

@@ -1,8 +1,4 @@
-/**
- * Key rotation command for kici-admin.
- *
- * Re-encrypts every master-key-wrapped store with the current master key.
- */
+/** `kici-admin rotate-key`: re-encrypt every master-key-wrapped store with the current key. */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 export declare function registerRotateCommand(program: Command, getClient: () => AdminApiClient): void;

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

@@ -1,30 +1,4 @@
-/**
- * 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. 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
- *   runs jobs <runId>                  List jobs for a run (optional steps)
- *   runs logs <runId> --job <jobId>    Print a page of one step's log lines
- *   runs ephemeral-key <runId>         Show scrub status of the run's key
- *   runs secret-outputs <runId>        List secret outputs (masked / reveal)
- *
- * Filter flags for `runs list`:
- *   --status            -> ?status=<csv>  (comma-separated, e.g. success,failed)
- *   --workflow-name     -> ?workflowName=<name>
- *   --repo              -> ?repo=<owner/repo>
- *   --since             -> ?since=<ISO-8601>
- *   --count             -> ?count=true    (emits only the count)
- *   --limit             -> ?limit=<n>     (default 20, max 100)
- *   --offset            -> ?offset=<n>    (default 0)
- *
- * Output:
- *   default             Aligned ASCII table
- *   --json              Raw JSON.stringify of the full response
- */
+/** `kici-admin runs`: read access to execution runs and their sub-resources over the admin API. */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 import { type AgentStepLogs } from '@kici-dev/engine';
@@ -34,8 +8,5 @@ import { type AgentStepLogs } from '@kici-dev/engine';
  * lines, or when the orchestrator does not report which case applies.
  */
 export declare function emptyStepLogNote(stepIndex: number, logs: Pick<AgentStepLogs, 'totalLines' | 'recorded'>): string | null;
-/**
- * Register the `runs` command group with kici-admin.
- */
 export declare function registerRunsCommands(program: Command, getClient: () => AdminApiClient): void;
 //# sourceMappingURL=runs.d.ts.map

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

@@ -12,17 +12,15 @@
  *                         running orchestrator (recovery for a wedged node whose
  *                         data disk is full).
  *
- * `reap-orphans` loads the orchestrator's LOCAL config (no HTTP admin API, no
- * DB) and runs the liveness-driven reaper, which spares every live VM. It is the sanctioned operator path for
- * the ENOSPC bootstrap deadlock: when the data disk is 100% full the
- * orchestrator crash-loops before its in-process orphan sweep can run, so a
- * tool that frees disk WITHOUT the orchestrator is required.
+ * `reap-orphans` loads the LOCAL config (no admin API, no DB) and runs the
+ * liveness-driven reaper, which spares every live VM. It is the operator path
+ * for the ENOSPC bootstrap deadlock: on a full data disk the orchestrator
+ * crash-loops before its own orphan sweep can run.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 /** Probe the local orchestrator /health endpoint. Healthy => it reaps itself. */
 export declare function isOrchestratorHealthy(port: number, basePath: string): Promise<boolean>;
-/** The `scaler orphans` options as Commander parses them. */
 export interface ScalerOrphansOptions {
     target?: string;
     all: boolean;
@@ -45,12 +43,7 @@ export interface ScalerOrphansIo {
 type OrphansClient = Pick<AdminApiClient, 'listScalerOrphans' | 'stopScalerOrphans'>;
 /** `45s`, `12m3s`, `1h2m`, `3d4h`. */
 export declare function formatAge(seconds: number): string;
-/**
- * `kici-admin scaler orphans`: list the live Firecracker VMs a node's
- * orchestrator does not track, and with `--stop` stop the orphaned ones.
- *
- * @returns the process exit code
- */
+/** @returns the process exit code */
 export declare function runScalerOrphans(client: OrphansClient, opts: ScalerOrphansOptions, io: ScalerOrphansIo): Promise<number>;
 export interface ScalerReloadOptions {
     single: boolean;

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

@@ -1,12 +1,4 @@
-/**
- * Secret management commands for kici-admin.
- *
- * Provides scoped secret operations:
- *   secret scopes, list, set, delete
- *   secret scope create|rename|delete
- *
- * Secret values are write-only -- there is no "get value" command.
- */
+/** `kici-admin secret`: scoped secrets. Values are write-only; there is no "get value" command. */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 export declare function registerSecretCommands(program: Command, getClient: () => AdminApiClient): void;

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

@@ -1,11 +1,9 @@
 /**
- * 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.
+ * Reads a local KiCI service's health endpoints. `kici-admin orchestrator
+ * status` and `kici-admin agent status` both render through here, so they agree
+ * on layout and on missing-field handling.
  */
 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
@@ -18,7 +16,7 @@ export declare function readEnvContent(envFilePath: string, warn?: (line: string
 export interface LocalEndpoint {
     host: string;
     port: number;
-    /** The prefix the service's routes are mounted under; empty when they sit at `/`. */
+    /** Empty when routes sit at `/`. */
     pathPrefix: string;
 }
 /**
@@ -41,10 +39,7 @@ export type LocalJsonResult<T> = {
 } | {
     kind: 'no-answer';
 };
-/**
- * GET a JSON body from a service on this host. `acceptStatuses` names the
- * non-2xx codes whose body is still an answer; `headers` carries credentials.
- */
+/** `acceptStatuses` names the non-2xx codes whose body is still an answer. */
 export declare function requestLocalJson<T>(endpoint: LocalEndpoint, pathname: string, opts?: {
     acceptStatuses?: readonly number[];
     timeoutMs?: number;

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

@@ -1,16 +1,10 @@
 /**
- * Shared access-log recorder for the direct-DB kici-admin subcommands.
+ * Access-log recorder for the direct-DB kici-admin subcommands, which bypass
+ * the HTTP admin API and would otherwise leave no `access_log` trail. It writes
+ * one `admin_cli` row per mutation, attributed to the operator's OS identity.
  *
- * The mutating db / host subcommands act straight against Postgres (bypassing
- * the orchestrator HTTP admin API), so without this they would leave no
- * `access_log` trail — unlike the HTTP/WS admin path. This helper records one
- * `admin_cli`-source row per mutation, attributed to a service_account actor
- * derived from the operator's OS identity, so the audit story is identical
- * regardless of transport.
- *
- * Best-effort by design: the orchestrator access_log is a broad audit stream
- * whose writer swallows insert failures so a broken audit table can never take
- * down an admin command. This recorder inherits that contract.
+ * Best-effort, like the access_log writer: a broken audit table never takes
+ * down an admin command.
  */
 import type { Kysely } from 'kysely';
 import { type AccessLogAction, type AccessLogOutcome, type AccessLogTargetType, type ServiceAccountActor } from '@kici-dev/engine';
@@ -28,19 +22,16 @@ export interface AdminCliAccessEntry {
     routingKey?: string | null;
 }
 /**
- * The actor for a bare-metal CLI operator. There is no Keycloak sub on the
- * box, so we attribute to a service_account keyed on the OS identity — the
- * same actor family the HTTP CLI-driven admin routes use.
+ * No Keycloak sub exists on the box, so the actor is a service_account keyed
+ * on the OS identity, as the HTTP CLI-driven admin routes use.
  */
 export declare function adminCliActor(): ServiceAccountActor;
 /** Record on an already-open orchestrator-DB Kysely handle. Never throws. */
 export declare function recordAdminCliAccessOnDb(db: Kysely<Database>, entry: AdminCliAccessEntry): Promise<void>;
 /**
- * Open a short-lived connection to the orchestrator's own DB (auditDbUrl, or
- * KICI_DATABASE_URL) and record there. Used by the provisioning subcommands
- * whose own connection targets a schemaless / admin DB with no access_log
- * table. A best-effort no-op when no URL resolves (pure bootstrap): the
- * subcommand's stderr banner is the audit floor in that case.
+ * Record through a short-lived connection to the orchestrator DB, for
+ * provisioning subcommands whose own DB has no access_log table. A no-op with
+ * no URL (pure bootstrap), where the stderr banner is the audit floor.
  */
 export declare function recordAdminCliAccess(entry: AdminCliAccessEntry, auditDbUrl?: string): Promise<void>;
 //# sourceMappingURL=admin-cli-access-log.d.ts.map

package/dist/cli/commands/shared/bare-metal-binary-check.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The bare-metal `binaryPath` check `kici-admin orchestrator upgrade` runs
+ * before it installs or restarts anything.
+ *
+ * The restarted orchestrator refuses to start when a `binaryPath` is not an
+ * executable file, or is a Node.js version-manager shim (a mise, Volta, asdf or
+ * nodenv shim runs the version manager, not an agent). A missing file usually
+ * comes from a version-manager alias (mise `node/24`) that moved to a new
+ * runtime with no `kici-agent`, while the upgrade installs under the runtime
+ * the service unit runs. The scaler config is read the way the service reads it.
+ */
+/** The upgrade flag that turns a refusal of this check into a warning. */
+export declare const SKIP_BINARY_PATH_CHECK_FLAG = "--skip-binary-path-check";
+/** What is wrong with one bare-metal `binaryPath`. */
+export declare enum BinaryPathIssue {
+    /** Not an executable file: the restarted orchestrator would not start. */
+    Missing = "missing",
+    /** A version-manager shim, not a `kici-agent`: the restarted orchestrator would not start. */
+    VersionManagerShim = "version-manager-shim",
+    /** Runs a `kici-agent` from another install than the service's runtime. */
+    OtherInstall = "other-install",
+    /** Goes through a version-manager alias or shim that can move. */
+    VersionManagerPath = "version-manager-path"
+}
+export interface BinaryPathFinding {
+    issue: BinaryPathIssue;
+    scaler: string;
+    binaryPath: string;
+    message: string;
+}
+/**
+ * The version-manager alias or shim `binaryPath` goes through, as words for
+ * the operator, or null when the path names a fixed runtime. Reads the
+ * configured path, not its target: an alias resolves to the right file until
+ * another runtime is installed.
+ */
+export declare function versionManagerPathKind(binaryPath: string): string | null;
+/**
+ * The `<name>@<version>` of the package that owns `file` (its realpath), read
+ * from the nearest `package.json` above it. Null when no such file is found.
+ */
+export declare function owningPackageVersion(file: string): string | null;
+export interface CheckBinaryPathArgs {
+    configured: Pick<BinaryPathFinding, 'scaler' | 'binaryPath'>;
+    /** Resolves a relative `binaryPath`, as the service's working directory does. */
+    workingDirectory: string;
+    /**
+     * The `kici-agent` installed with the service's runtime, or null when the
+     * upgrade provides none (an archive install, a standalone package).
+     */
+    expectedAgent: string | null;
+    /** What `expectedAgent` runs after the upgrade, e.g. `kici-admin@0.17.0`. */
+    expectedVersion: string | null;
+    /** True when the upgrade installs `expectedAgent` before it restarts. */
+    willInstall: boolean;
+    /** The scaler config file, for the remedy text. */
+    scalerConfigPath: string;
+}
+/**
+ * Classify one `binaryPath`. An empty result means it resolves to the agent
+ * installed with the service's runtime: the upgrade restarts onto it as is.
+ */
+export declare function checkBinaryPath(args: CheckBinaryPathArgs): BinaryPathFinding[];
+/** The scaler config files an instance's env file names, resolved like the service does. */
+export declare function scalerConfigLocation(envContent: string, workingDirectory: string): {
+    configPath: string;
+    configDir: string | undefined;
+} | null;
+export interface PreflightArgs {
+    serviceName: string;
+    envFilePath: string;
+    workingDirectory: string;
+    expectedAgent: string | null;
+    expectedVersion: string | null;
+    willInstall: boolean;
+    /** `--skip-binary-path-check`: report a refusal as a warning and go on. */
+    skip: boolean;
+    warn: (line: string) => void;
+}
+/**
+ * Prints each warning, and throws when a `binaryPath` is not executable or is a
+ * version-manager shim, unless `skip` is set. An unreadable scaler config is
+ * reported and not checked: the service reads it again at its own startup.
+ */
+export declare function preflightBareMetalBinaryPaths(args: PreflightArgs): Promise<void>;
+//# sourceMappingURL=bare-metal-binary-check.d.ts.map

package/dist/cli/commands/shared/cli-action.d.ts

@@ -7,10 +7,7 @@ export declare function resolveDirectDbUrl(explicit?: string): string | null;
 export declare function resolveDatabaseUrl(explicit?: string): string;
 /** Parse an optional integer flag; throws naming the flag on a non-integer. */
 export declare function parseIntOption(raw: string | undefined, label: string): number | undefined;
-/**
- * Wrap a Commander action so any thrown error prints `Error: <message>` to
- * stderr and exits 1.
- */
+/** A thrown error prints `Error: <message>` to stderr and exits 1. */
 export declare function cliAction<A extends unknown[]>(fn: (...args: A) => Promise<void> | void): (...args: A) => Promise<void>;
 /** Print `value` as one JSON line when `json` is set, otherwise hand it to `render`. */
 export declare function printJsonOr<T>(json: boolean | undefined, value: T, render: (v: T) => void): void;

package/dist/cli/commands/shared/confirm.d.ts

@@ -1,19 +1,14 @@
-/** Message of the error raised when stdin ends before the operator answers. */
+/** Raised when stdin ends before an answer. */
 export declare const NO_CONFIRMATION_ANSWER: string;
-/** The streams the prompt writes to and reads from. */
 export interface ConfirmIo {
     input: NodeJS.ReadableStream;
     output: NodeJS.WritableStream;
 }
 /**
- * Write `prompt` and read one line of answer.
- *
- * Resolves true when the line is `y` or `yes` (any case, surrounding spaces
- * ignored) and false for any other line. Rejects with
- * {@link NO_CONFIRMATION_ANSWER} when stdin ends before a line arrives, as it
- * does for a script, a cron job or a `< /dev/null` redirect. Resolving false
- * there would let a verb run without `--yes` exit 0 having done nothing, and
- * the script that ran it would read that as success.
+ * True for a `y` / `yes` line (any case, trimmed), false for any other line.
+ * Rejects with {@link NO_CONFIRMATION_ANSWER} when stdin ends first (a script,
+ * cron or `< /dev/null`): resolving false would exit 0 having done nothing,
+ * which the calling script reads as success.
  */
 export declare function confirmPrompt(prompt: string, io?: ConfirmIo): Promise<boolean>;
 //# sourceMappingURL=confirm.d.ts.map

package/dist/cli/commands/shared/db.d.ts

@@ -1,16 +1,5 @@
-/**
- * Shared database helper for CLI commands that need direct DB access.
- *
- * Provides a withDb() wrapper that creates a database connection from the
- * URL it is given (or KICI_DATABASE_URL when none is passed), runs a callback,
- * and ensures cleanup.
- */
 import pg from 'pg';
 import { Kysely } from 'kysely';
-/**
- * Execute a callback with a database connection, then clean up.
- *
- * Connects to `databaseUrl`, or to KICI_DATABASE_URL when none is passed.
- */
+/** Runs `fn` on a connection to `databaseUrl` (default KICI_DATABASE_URL), then cleans up. */
 export declare function withDb<T>(fn: (db: Kysely<any>, pool: pg.Pool) => Promise<T>, databaseUrl?: string | undefined): Promise<T>;
 //# sourceMappingURL=db.d.ts.map

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

@@ -1,16 +1,13 @@
 /**
- * Permissions for a service env file written by `kici-admin`.
- *
- * Both installers write a file that carries credentials — the orchestrator's
- * holds KICI_SECRET_KEY, KICI_DATABASE_URL and KICI_PLATFORM_TOKEN, the
- * agent's holds KICI_AGENT_TOKEN — so neither may be group- or
- * world-readable. The same mode guards the temporary Postgres password file in
+ * Mode for a `kici-admin` service env file. Both installers' files carry credentials (the
+ * orchestrator's KICI_SECRET_KEY, KICI_DATABASE_URL and KICI_PLATFORM_TOKEN; the
+ * agent's KICI_AGENT_TOKEN), so neither may be group- or world-readable. The
+ * same mode guards the temporary Postgres password file in
  * `orchestrator-service/install.ts` and the peer credential file in
  * `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 restricts the
- * folder that holds the file instead (`restrictEnvFileAccess`,
+ * POSIX-only: on Windows Node toggles the read-only attribute and changes no
+ * ACL, so a Windows install restricts the folder instead (`restrictEnvFileAccess`,
  * `cli/service/windows-acl.ts`).
  */
 export declare const ENV_FILE_MODE = 384;

package/dist/cli/commands/shared/secret-input.d.ts

@@ -1,26 +1,16 @@
 /**
- * Shared input-mode helper for `kici-admin secret set` and
- * `kici-admin variable set`.
- *
- * Resolves a value from exactly one of:
+ * Input mode for `secret set` and `variable set`: exactly one of
  *   --value <plaintext>   — argv literal (warned; goes into shell history)
  *   --prompt              — interactive no-echo prompt (TTY only)
  *   --from-stdin          — pipe (full stdin until EOF)
  *   --from-file <path>    — file contents (--trim default-on)
  *   --from-env  <VAR>     — env var contents
  *
- * Default-mode resolution when no flag is provided:
- *   TTY     -> --prompt
- *   non-TTY -> --from-stdin
- *
- * Optional checks:
- *   --confirm-fingerprint <hex>  — SHA-256 fingerprint guard against
- *     paste corruption.
+ * With no flag: TTY -> --prompt, non-TTY -> --from-stdin.
+ * `--confirm-fingerprint <hex>` guards against paste corruption (SHA-256).
  *
- * The helper does NOT print to stdout (it returns the value). It DOES
- * write to stderr for the `--value` warning, the prompt label, and any
- * "empty value" warning. Stdout is reserved for the caller's confirmation
- * output so the caller's `--dry-run` summary stays clean.
+ * Writes only to stderr (warnings, prompt label): stdout is reserved for the
+ * caller's output, so its `--dry-run` summary stays clean.
  */
 export interface SecretInputOptions {
     value?: string;
@@ -33,14 +23,10 @@ export interface SecretInputOptions {
 }
 export interface SecretInputResult {
     value: string;
-    /** Which input mode supplied the value (after default resolution). */
+    /** After default resolution. */
     source: 'value' | 'stdin' | 'file' | 'env' | 'prompt';
 }
 export declare function resolveSecretInput(opts: SecretInputOptions, stderr?: NodeJS.WritableStream, stdin?: NodeJS.ReadStream): Promise<SecretInputResult>;
-/**
- * Compute the canonical SHA-256 fingerprint for a value. Helper for
- * callers (tests, --dry-run output) that want to display the same hex
- * the user would pass to `--confirm-fingerprint`.
- */
+/** The SHA-256 hex a user passes to `--confirm-fingerprint`. */
 export declare function fingerprintValue(value: string): string;
 //# sourceMappingURL=secret-input.d.ts.map

package/dist/cli/commands/shared/service-verbs.d.ts

@@ -1,19 +1,13 @@
 /**
- * The service lifecycle verbs shared by `kici-admin agent` and `kici-admin orchestrator`:
- * `uninstall`, `start`, `stop`, `restart` and `logs`.
- *
- * Target resolution goes through resolveInstanceTarget — the priority chain every
- * lifecycle command uses (--instance-dir > --name > CWD manifest > refusal with
- * candidate list). `--name` has no default.
+ * `uninstall`, `start`, `stop`, `restart` and `logs`, shared by `kici-admin agent`
+ * and `kici-admin orchestrator`. Targets resolve through resolveInstanceTarget
+ * (--instance-dir > --name > CWD manifest > refusal with candidates); `--name`
+ * has no default.
  */
 import type { Command } from 'commander';
 export type ServiceComponent = 'agent' | 'orchestrator';
-/**
- * Register `uninstall`, `start`, `stop` and `restart` on a component's command group.
- * Commander lists subcommands in registration order, so the caller places this
- * between `install` and `status`.
- */
+/** Commander lists subcommands in registration order: call this between `install` and `status`. */
 export declare function registerServiceLifecycleVerbs(parent: Command, component: ServiceComponent): void;
-/** Register `logs` on a component's command group (listed after `status`). */
+/** Listed after `status`. */
 export declare function registerServiceLogsVerb(parent: Command, component: ServiceComponent): void;
 //# sourceMappingURL=service-verbs.d.ts.map

package/dist/cli/commands/shared/unbound-context-warning.d.ts

@@ -12,12 +12,10 @@ export interface WarnIfContextUnboundArgs {
     /** Where the warning goes; stderr by default. */
     warn?: (line: string) => void;
 }
-/** The warning line for a context with no binding. */
 export declare function unboundContextWarning(orgId: string, name: string): string;
 /**
- * Print the unbound-context warning when `name` is a context a job can resolve
- * through (a fixed or glob context, `ContextType`) that has no binding. A
- * template row is a seed for other contexts, not a job context, and stays silent.
+ * Warns for a fixed or glob context (`ContextType`) with no binding. A template
+ * row seeds other contexts, is no job context, and stays silent.
  */
 export declare function warnIfContextUnbound(args: WarnIfContextUnboundArgs): Promise<void>;
 //# sourceMappingURL=unbound-context-warning.d.ts.map

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

@@ -1,12 +1,9 @@
 import type { AdminApiClient } from '../../api-client.js';
 import type { UpgradeHooks } from './versioned-upgrade.js';
 /**
- * Resolve the database URL the pre-upgrade dump connects with.
- *
- * The instance's env file is the authority — the same file the service itself
- * is started from — so the dump is taken against exactly the database the
- * running orchestrator uses, not whatever the operator's shell happens to
- * export.
+ * The pre-upgrade dump's database URL. The service's own env file is the
+ * authority, so the dump hits the database the orchestrator uses, not
+ * whatever the operator's shell exports.
  */
 export declare function readDatabaseUrlFromEnvFile(contents: string): string | null;
 export interface BuildUpgradeHooksIo {
@@ -14,19 +11,13 @@ export interface BuildUpgradeHooksIo {
     now?: () => Date;
 }
 /**
- * Build the hook set for an orchestrator upgrade.
- *
- * `instanceDir` is resolved lazily, at the moment a hook runs, because the
- * upgrade resolves its target after the command is registered.
+ * `instanceDir` resolves lazily, when a hook runs: the upgrade resolves its
+ * target after the command is registered.
  */
 export declare function buildUpgradeHooks(tryGetClient: () => AdminApiClient | null, io?: BuildUpgradeHooksIo): UpgradeHooks;
 /**
- * Read `KICI_DATABASE_URL` from the instance env file, falling back to the
- * process environment.
- *
- * Throws rather than returning null: an upgrade that cannot find the database
- * must refuse loudly, since a silent skip is exactly the failure this hook
- * exists to prevent.
+ * From the env file, else the process environment. Throws rather than
+ * returning null: a silent skip is the failure this hook exists to prevent.
  */
 export declare function resolveDatabaseUrl(envFilePath: string, readFile: (p: string) => string): string;
 //# sourceMappingURL=upgrade-hooks.d.ts.map

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

@@ -10,19 +10,15 @@ export interface WaitOpts {
     sleep?: (ms: number) => Promise<void>;
 }
 /**
- * Poll until no jobs are running, or the deadline passes.
- *
- * Extracted so the upgrade and `kici-admin orchestrator drain --wait` share one
- * implementation rather than two that can disagree about what quiesced means.
+ * Poll until no jobs are running, or the deadline passes. The upgrade and
+ * `kici-admin orchestrator drain --wait` share it so they agree on what
+ * quiesced means.
  */
 export declare function waitForQuiesce(poll: () => Promise<DrainSnapshot>, opts: WaitOpts): Promise<{
     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.
- */
+/** Printed when a version switch cannot read the live migration ledger. */
 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 {
@@ -30,10 +26,8 @@ export interface MigrationStatusRow {
     status: string;
 }
 /**
- * The last applied migration reported by a running service.
- *
- * Returns null when nothing has been applied — a fresh database — which the
- * caller must not confuse with "could not read it".
+ * The last applied migration. Null means a fresh database, which the caller
+ * must not confuse with "could not read it".
  */
 export declare function appliedHead(rows: readonly MigrationStatusRow[]): string | null;
 /** Migrations applied after `head`, in ledger order. */
@@ -49,15 +43,12 @@ export type SchemaGuardVerdict = {
     message: string;
 };
 /**
- * Decide whether the version pointer may move.
- *
- * Three outcomes, and the middle one is the compatibility shim: an instance
- * 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.
+ * Decide whether the version pointer may move. `unknown-head` is a compat
+ * shim: an install from before `migrationHeads`, or whose upgrade away from
+ * the target ran without admin access, has no recorded head, and refusing
+ * would break its documented `--rollback`. It warns and falls through to the
+ * confirmation; the next version change with admin access records the head
+ * and arms the guard.
  */
 export declare function schemaGuardVerdict(input: {
     targetVersion: string;
@@ -66,22 +57,20 @@ export declare function schemaGuardVerdict(input: {
 }): SchemaGuardVerdict;
 /** Merge one version's head into the manifest map, never replacing it. */
 export declare function mergeMigrationHead(existing: Record<string, string> | undefined, version: string, head: string | null): Record<string, string> | undefined;
-/** Read the live applied head, returning null when the service cannot answer. */
+/**
+ * The live migration rows, or null when the service or admin API cannot
+ * answer: that is no evidence about the schema, so null means "cannot tell".
+ */
 export declare function readLiveMigrationRows(fetchStatus: () => Promise<{
     migrations: MigrationStatusRow[];
 }>): Promise<MigrationStatusRow[] | null>;
-/** Format the reason a pre-upgrade backup could not be taken. */
 export declare function backupRefusalMessage(reason: string): string;
 /**
- * Format the drain-timeout refusal.
- *
- * The refusal leaves the coordinator draining — deliberately, so the in-flight
- * jobs finish without new ones piling up behind them. But a drained
- * coordinator accepts nothing, so the message has to say so and name the way
- * back; an operator who reads only "wait and re-run" does not know their CI is
- * stalled meanwhile.
+ * The drain-timeout refusal. It leaves the coordinator draining on purpose so
+ * in-flight jobs finish without new ones piling up, and so must say that CI
+ * accepts nothing meanwhile and name the way back.
  */
 export declare function drainTimeoutMessage(jobsRunning: number, timeoutSeconds: number): string;
-/** Describe a failure to reach the admin API during the pre-stop phase. */
+/** A failure to reach the admin API during the pre-stop phase. */
 export declare function adminApiUnavailable(action: string, err: unknown): string;
 //# sourceMappingURL=upgrade-safety.d.ts.map