@kici-dev/orchestrator 0.1.27 → 0.3.0

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

@@ -0,0 +1,34 @@
+import type { Command } from 'commander';
+import { type AgentPlatform as AgentPlatformType } from '@kici-dev/shared';
+import { type AgentPackageStorage } from '../../agent-packaging/index.js';
+/** The orchestrator's own version (single-version invariant) = the packaged agent version. */
+export declare function resolveKiciVersion(): string;
+/** Parse the --platform value: default set | single | CSV | `all`. */
+export declare function parsePlatforms(raw: string | undefined): AgentPlatformType[];
+/** Build the cache-bucket storage client from the orchestrator config (S3 only). */
+export declare function resolveUploadStorage(): AgentPackageStorage;
+/** Options for {@link runAgentPackageRefresh} (the auto-package-on-upgrade hook). */
+export interface AgentPackageRefreshOptions {
+    platforms?: AgentPlatformType[];
+    nodeMirror?: string;
+    npmRegistry?: string;
+    nodeVersion?: string;
+}
+/**
+ * Auto-produce + upload the agent payloads for the orchestrator's current
+ * version after a versioned upgrade (the C9 automation-completeness hook).
+ *
+ * Best-effort by design: a filesystem-cache orchestrator has no bucket to serve
+ * payloads from, so it logs and skips rather than failing the upgrade; a
+ * produce/upload error is reported but non-fatal to the (already-completed)
+ * orchestrator upgrade. Idempotent — a version whose payloads already exist is
+ * a no-op. Returns true when a refresh ran (S3 configured), false when skipped.
+ */
+export declare function runAgentPackageRefresh(opts?: AgentPackageRefreshOptions): Promise<boolean>;
+/**
+ * Register the `kici-admin agent package` producer on the existing `agent`
+ * command group. Must be called after registerAgentCommands (which creates the
+ * group).
+ */
+export declare function registerAgentPackage(program: Command): void;
+//# sourceMappingURL=agent-package.d.ts.map

package/dist/cli/commands/check-run.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Check-run read CLI command for kici-admin.
+ *
+ *   check-run list --sha <sha> [--check-name <name>] [--limit <n>] [--json]
+ *
+ * READ-ONLY. Answers "did we post that check run?" — the question that
+ * previously needed raw SQL against `check_run_tracking`.
+ *
+ * Each column answers a different half of it:
+ *   - CHECK_RUN_ID   the check run was created at the provider.
+ *   - CREATE_STATE   stamped `pending` BEFORE the create and never reset on
+ *                    failure, so `pending` distinguishes an in-flight create
+ *                    from a missing one — it does not prove success.
+ *   - TERMINAL_SENT  the terminal `completed` update was accepted by the
+ *                    provider.
+ *
+ * Every write on this table is best-effort, so an em dash is "no record", never
+ * proof that the call failed.
+ *
+ * Direct-DB only: there is no admin HTTP route for check-run tracking, so this
+ * requires `--database-url` (or `KICI_DATABASE_URL`) the same way `attestations`,
+ * `cluster` and `cold-store` do.
+ */
+import type { Command } from 'commander';
+export declare function registerCheckRunCommands(program: Command): void;
+//# sourceMappingURL=check-run.d.ts.map

package/dist/cli/commands/cluster-settings.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cluster-settings management commands for kici-admin.
+ *
+ * Subcommand namespace: `kici-admin cluster-settings <show|set|reset>`.
+ *
+ * Talks to the orchestrator admin API directly (not the Platform dashboard
+ * proxy), so the CLI stays operable even when Platform is unavailable. Backed
+ * by `packages/orchestrator/src/routes/admin-cluster-settings.ts`.
+ *
+ * These knobs are fleet-wide (a single `cluster_settings` row), not per-tenant.
+ * For per-tenant knobs use `kici-admin org-settings`.
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../api-client.js';
+/**
+ * One text knob. Kept separate from {@link KnobSpec} because the value parser,
+ * the PATCH body type, and the `show` formatter all differ — a string knob has
+ * no `min` floor and is validated by shape, not by magnitude.
+ */
+interface StringKnobSpec {
+    field: string;
+    flag: string;
+    label: string;
+    /** Human-facing description of the accepted shape, used in the error message. */
+    expects: string;
+    validate: (value: string) => boolean;
+}
+/** camelCase → value (null clears the override). */
+type PatchBody = Record<string, number | string | null>;
+/** Parse an integer CLI flag with a minimum, exiting with an error on failure. */
+export declare function parseKnobValue(flag: string, value: string, min: number): number;
+/** Validate a text CLI flag against its knob's shape, exiting on failure. */
+export declare function parseStringKnobValue(knob: StringKnobSpec, value: string): string;
+/** Assemble the PATCH body from provided `set` flags (exits if none given). */
+export declare function buildClusterPatch(opts: Record<string, string | undefined>): PatchBody;
+/** Build the reset PATCH body: all knobs → null, or just the flagged ones. */
+export declare function buildClusterReset(opts: Record<string, boolean | undefined>): PatchBody;
+/**
+ * Check that `issuer` actually publishes a dashboard-encryption key.
+ *
+ * Runs after the setting has already been written, so it never throws: a
+ * network fault, a non-2xx status and a malformed body all come back as a
+ * `reason` the caller prints as a warning. The check is advisory — the CLI may
+ * sit in a different network position than the browser that will do the real
+ * fetch, so a failure is definitive but a pass is not a guarantee.
+ */
+export declare function checkVerifiedIssuerPublishes(issuer: string, fetchImpl?: typeof fetch): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export declare function registerClusterSettingsCommands(program: Command, getClient: () => AdminApiClient): void;
+export {};
+//# sourceMappingURL=cluster-settings.d.ts.map

package/dist/cli/commands/dashboard-encryption-key.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerDashboardEncryptionKeyCommands(program: Command): void;
+//# sourceMappingURL=dashboard-encryption-key.d.ts.map

package/dist/cli/commands/db-backup.d.ts

@@ -0,0 +1,71 @@
+import os from 'node:os';
+import type { Kysely } from 'kysely';
+import type { Database, NewBackupRun } from '../../db/types.js';
+export type RunFn = (bin: string, args: string[], opts?: {
+    env?: NodeJS.ProcessEnv;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export type FsLike = {
+    writeFile: (path: string, data: string) => Promise<void>;
+    readFile: (path: string) => Promise<string>;
+};
+export interface BackupManifest {
+    createdAt: string;
+    byteSize: number;
+    secretKeyVersion: number | null;
+    pgServerVersion: string;
+    migrationsHash: string;
+    clusterId: string | null;
+    hostname: string;
+}
+export declare function manifestPath(dumpPath: string): string;
+export declare function defaultDumpPath(now: Date): string;
+export declare function parsePgToolMajor(versionOutput: string): number;
+export declare function serverVersionMajor(numStr: string): number;
+export declare function assertToolVersionCompatible(toolMajor: number, serverMajor: number, tool: 'pg_dump' | 'pg_restore'): void;
+export declare function pgToolVersion(bin: 'pg_dump' | 'pg_restore', run?: RunFn): Promise<number>;
+export declare function writeManifest(dumpPath: string, m: BackupManifest, fs?: FsLike): Promise<void>;
+export declare function readManifest(dumpPath: string, fs?: FsLike): Promise<BackupManifest | null>;
+export declare function readServerAndKeyMeta(pool: import('pg').Pool): Promise<{
+    serverVersionNum: string;
+    secretKeyVersion: number | null;
+    clusterId: string | null;
+}>;
+/**
+ * Translate a libpq connection URL into a PG* environment overlay. The
+ * connection URL (which embeds the DB password) MUST NOT be passed as a
+ * pg_dump/pg_restore argv element: `/proc/<pid>/cmdline` is world-readable, so
+ * a URL-in-argv leaks the DB password to every local user for the tool's
+ * lifetime. libpq reads PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE/PGSSLMODE
+ * from the environment (`/proc/<pid>/environ`, owner-only 0400) instead — the
+ * same credential-off-the-command-line discipline used elsewhere in the repo.
+ * Only the components that are actually present are set, so socket / trust
+ * connections (no password, no port) are left untouched.
+ */
+export declare function pgEnvFromUrl(url: string): NodeJS.ProcessEnv;
+export declare function runPgDump(url: string, outputPath: string, run?: RunFn): Promise<void>;
+export declare function runPgRestore(url: string, inputPath: string, run?: RunFn): Promise<void>;
+export declare function recordBackupRun(db: Kysely<Database>, row: NewBackupRun): Promise<void>;
+export declare function buildBackupManifest(input: {
+    now: Date;
+    byteSize: number;
+    serverVersionNum: string;
+    secretKeyVersion: number | null;
+    clusterId: string | null;
+    migrationsHash: string;
+    hostname: string;
+}): BackupManifest;
+/**
+ * Message to print after a restore about the secret-key requirement. Returns
+ * null when the dump carried no encrypted secrets (nothing to warn about),
+ * a loud warning when secrets exist but no `KICI_SECRET_KEY` is set on the box,
+ * or an informational reminder when a key IS set (it must be the matching one).
+ */
+export declare function restoreKeyWarning(input: {
+    secretKeyVersion: number | null;
+    keyEnvPresent: boolean;
+}): string | null;
+export { os };
+//# sourceMappingURL=db-backup.d.ts.map

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

@@ -0,0 +1,31 @@
+/**
+ * `kici-admin orchestrator drain` / `resume` CLI verbs.
+ *
+ * Quiesce a coordinator before an upgrade: stop dispatching new jobs, let
+ * in-flight jobs finish, report when quiesced. `--wait` polls status
+ * client-side until `jobsRunning` reaches 0 or the timeout elapses; exit codes
+ * are scriptable (0 quiesced/initiated, 2 wait timed out, 1 error).
+ */
+import type { Command } from 'commander';
+import type { AdminApiClient } from '../../api-client.js';
+type Snapshot = {
+    draining: boolean;
+    jobsRunning: number;
+};
+export interface WaitOpts {
+    timeoutMs: number;
+    intervalMs: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Poll `poll` until jobsRunning hits 0 or the timeout elapses. Pure with an
+ * injectable clock + sleep so it is testable without real time.
+ */
+export declare function waitForQuiesce(poll: () => Promise<Snapshot>, opts: WaitOpts): Promise<{
+    quiesced: boolean;
+    jobsRunning: number;
+}>;
+export declare function registerOrchestratorDrain(orchestrator: Command, getClient: () => AdminApiClient): void;
+export {};
+//# sourceMappingURL=drain.d.ts.map

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

@@ -2,11 +2,14 @@
  * Orchestrator service command group registration.
  *
  * Registers `kici-admin orchestrator` with install, uninstall, start, stop,
- * restart, status, logs, and upgrade subcommands for managing the orchestrator
- * as a system service.
+ * restart, status, logs, upgrade, drain, and resume subcommands for managing the
+ * orchestrator as a system service.
  *
- * These commands manage local services directly and do NOT use AdminApiClient.
+ * The lifecycle verbs (install/start/stop/…) manage local services directly and
+ * do NOT use AdminApiClient. The drain/resume verbs DO — they talk to the running
+ * coordinator's admin HTTP API to quiesce it before an upgrade.
  */
 import type { Command } from 'commander';
-export declare function registerOrchestratorServiceCommands(program: Command): void;
+import type { AdminApiClient } from '../../api-client.js';
+export declare function registerOrchestratorServiceCommands(program: Command, getClient: () => AdminApiClient): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/orchestrator-service/install-env.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Env-file resolution + content for `kici-admin orchestrator install`.
+ *
+ * Three write paths — the interactive wizard, copying a supplied --env-file,
+ * or writing an enumerated stub the operator fills in by hand — plus the
+ * flag/TTY precedence that picks between them. Kept out of install.ts so the
+ * command action stays small and the decision + stub content are unit-testable
+ * without driving the whole install through Commander.
+ */
+import type { OrchestratorSourceHint } from '../../wizard/orchestrator-wizard.js';
+/** Which config source the install writes the env file from. */
+export type InstallEnvMode = 'wizard' | 'env-file' | 'stub';
+/** Result of writing the install env file. */
+export interface WriteInstallEnvResult {
+    /** Present only in wizard mode when the operator opted into a GitHub App source. */
+    sourceHint?: OrchestratorSourceHint;
+}
+/** Public compose quickstart, pointed at from the stub env file. */
+export declare const COMPOSE_QUICKSTART_URL = "https://docs.kici.dev/user/quickstart/compose/";
+export interface WizardModeInput {
+    /** --wizard=true / --no-wizard=false / undefined when neither is passed. */
+    wizard?: boolean;
+    /** --env-file value, if any. */
+    envFile?: string;
+    /** --dev (spins up a local Postgres and fills the DB URL). */
+    dev?: boolean;
+    /** Whether stdout is attached to an interactive terminal. */
+    isTTY: boolean;
+    /** Whether the process runs under CI (non-interactive). */
+    isCI: boolean;
+}
+/**
+ * Pick the install env mode. Precedence: an explicit --env-file wins; then an
+ * explicit --wizard / --no-wizard; --dev keeps the stub (it provisions the DB,
+ * so the wizard's DB prompt would be redundant); otherwise the wizard is the
+ * default only on a bare interactive terminal (mirrors `kici init`), and every
+ * non-interactive/scripted install writes the stub.
+ */
+export declare function resolveWizardMode(input: WizardModeInput): InstallEnvMode;
+/**
+ * Build the stub env file: every required key with an inline explanation, a
+ * generation command for the two secrets, and a pointer to the compose
+ * quickstart. Fills KICI_DATABASE_URL from a --dev container URL when present.
+ */
+export declare function buildStubEnv(opts: {
+    devDbUrl?: string;
+}): string;
+export interface WriteInstallEnvArgs {
+    mode: InstallEnvMode;
+    envFilePath: string;
+    /** Source path for env-file mode. */
+    envFileSource?: string;
+    /** Dev-provisioned DB URL, threaded into the stub / appended to an env file. */
+    devDbUrl?: string;
+}
+/** Materialise the env file for the resolved mode. */
+export declare function writeInstallEnvFile(args: WriteInstallEnvArgs): Promise<WriteInstallEnvResult>;
+//# sourceMappingURL=install-env.d.ts.map

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

@@ -2,11 +2,55 @@
  * Secret management commands for kici-admin.
  *
  * Provides scoped secret operations:
- *   secret scopes, list, set, delete
+ *   secret scopes, list, set, delete, fix-prefixed-scopes
  *
  * Secret values are write-only -- there is no "get value" command.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
+/** One planned rename from a stored qualified scope to its bare path. */
+export interface PrefixedScopeRename {
+    from: string;
+    to: string;
+    backendName: string;
+}
+/** One stored scope that cannot be repaired automatically. */
+export interface PrefixedScopeSkip {
+    scope: string;
+    reason: string;
+}
+/** Outcome of planning the repair of legacy qualifier-bearing scopes. */
+export interface PrefixedScopeFixPlan {
+    renames: PrefixedScopeRename[];
+    skips: PrefixedScopeSkip[];
+}
+/**
+ * Plan the repair of scopes stored with a `<backend>:` qualifier still attached.
+ *
+ * Before backend-qualified routing landed on the HTTP admin plane, a scope
+ * written as `pg:production` was stored verbatim, so the stored name carries a
+ * qualifier the resolver now strips before it reaches the store. Such a row is
+ * unreachable: every read addresses the bare `production`.
+ *
+ * Only a `pg:` qualifier is repaired. The scopes handed in come out of the PG
+ * store, so a row named `vault:foo` is a PG row wearing another backend's
+ * name: renaming it to `foo` would turn it into a genuine PG secret, moving it
+ * across a backend boundary and past a `pgCustomerSecrets: false` setting that
+ * exists to keep customer secrets out of PG. That is the same cross-backend
+ * move the rename route refuses, so it is reported as a skip instead.
+ *
+ * An unregistered head is left alone entirely -- it is an ordinary (if
+ * unusual) scope path, not a stale qualifier.
+ *
+ * A repair whose bare target already exists is SKIPPED, never merged: merging
+ * two scopes would silently overwrite whichever key the two share, and there
+ * is no way to tell which value the operator meant to keep.
+ *
+ * Pure -- no I/O, so the decision table is unit-testable without a database.
+ *
+ * @param scopes - Scope names as currently stored in the PG backend.
+ * @param backendNames - Names of the registered secret backends.
+ */
+export declare function planPrefixedScopeFixes(scopes: string[], backendNames: string[]): PrefixedScopeFixPlan;
 export declare function registerSecretCommands(program: Command, getClient: () => AdminApiClient): void;
 //# sourceMappingURL=secret.d.ts.map

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

@@ -0,0 +1,46 @@
+/**
+ * Shared access-log recorder for the direct-DB kici-admin subcommands.
+ *
+ * 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.
+ */
+import type { Kysely } from 'kysely';
+import { type AccessLogAction, type AccessLogOutcome, type AccessLogTargetType, type ServiceAccountActor } from '@kici-dev/engine';
+import type { Database } from '../../../db/types.js';
+export interface AdminCliAccessEntry {
+    action: AccessLogAction;
+    target: {
+        type: AccessLogTargetType;
+        id: string;
+    } | null;
+    outcome: AccessLogOutcome;
+    errorMessage?: string | null;
+    meta?: Record<string, unknown>;
+    orgId?: string | null;
+    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.
+ */
+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.
+ */
+export declare function recordAdminCliAccess(entry: AdminCliAccessEntry, auditDbUrl?: string): Promise<void>;
+//# sourceMappingURL=admin-cli-access-log.d.ts.map

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

@@ -7,8 +7,8 @@
  * - Preserve old versions for rollback
  * - Optional cleanup of old versions
  */
-import { type ResolvedInstance, type ServiceManager, type ServicePlatform } from '../../service/index.js';
-import type { ServiceConfig } from '../../service/types.js';
+import { type NpmInstallTarget, type ResolvedInstance, type ServiceManager, type ServicePlatform } from '../../service/index.js';
+import type { LaunchSpec, ServiceConfig } from '../../service/types.js';
 /** Component types that can be upgraded. */
 type UpgradeComponent = 'orchestrator' | 'agent';
 /** Options for the versioned upgrade command. */
@@ -29,6 +29,11 @@ interface VersionedUpgradeOptions {
     rollback?: boolean;
     pick?: boolean;
     force?: boolean;
+    /**
+     * Opt-in escape hatch: restart the already-installed package without
+     * self-driving the npm install (the pre-staged / air-gapped path).
+     */
+    restartOnly?: boolean;
 }
 /**
  * Resolved upgrade target: the manifest-backed ServiceConfig the upgrade
@@ -157,6 +162,64 @@ export declare function verifyNpmSourceLaunch(opts: {
     launchedPath: string | null;
     force: boolean;
 }): NpmSourceLaunchVerdict;
+/**
+ * An npm-source upgrade proceeds one of three ways: restart the already-installed
+ * package (`restart-only`, carrying a {@link NpmSourceLaunchVerdict}), self-drive
+ * the install of a resolved target under the unit's own runtime (`self-drive`),
+ * or refuse with an operator-facing message (`error`).
+ */
+export type NpmSourceUpgradeAction = {
+    kind: 'restart-only';
+    verdict: NpmSourceLaunchVerdict;
+} | {
+    kind: 'self-drive';
+    target: NpmInstallTarget;
+    version: string;
+} | {
+    kind: 'error';
+    reason: string;
+};
+/**
+ * Decide how an npm-source upgrade proceeds. `restart-only` re-verifies and
+ * restarts the already-installed package (the pre-staged / air-gapped path).
+ * The default self-drives: it resolves the global package + pinned node from
+ * the unit's launch spec so the CLI can install the target itself. Returns an
+ * `error` action (not a throw) for the two operator-facing refusals.
+ */
+export declare function planNpmSourceUpgrade(opts: {
+    component: UpgradeComponent;
+    spec: LaunchSpec | null;
+    invoked: string;
+    requestedVersion: string | undefined;
+    restartOnly: boolean;
+    force: boolean;
+    windows: boolean;
+}): NpmSourceUpgradeAction;
+/** Injected process runner seam for {@link installGlobalPackage}. */
+type SpawnRunner = (cmd: string, args: string[], opts?: {
+    env?: NodeJS.ProcessEnv;
+}) => {
+    status: number | null;
+    stderr: 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.
+ *
+ * npm derives its global prefix from the node that *runs* npm-cli.js, not from
+ * the location of the npm script — and the unit's `<pinned>/bin/npm` is a
+ * `#!/usr/bin/env node` shebang (or a version-manager bash wrapper invoking a
+ * bare `node`), both of which resolve `node` off PATH. So invoking that npm
+ * bare would inherit whatever node the shell has active — exactly the
+ * version-manager (mise/nvm/asdf) drift this upgrade exists to fix. We prepend
+ * the pinned node's bin dir to PATH so npm always runs under the unit's node
+ * and computes the unit's prefix, regardless of the caller's active node. The
+ * `run` seam is injected in tests.
+ */
+export declare function installGlobalPackage(target: NpmInstallTarget, version: string, run?: SpawnRunner): {
+    ok: boolean;
+    stderr: string;
+};
 export declare function performVersionedUpgrade(component: UpgradeComponent, opts: VersionedUpgradeOptions): Promise<void>;
 /**
  * Stop the service, switch the active version pointer to an already-installed

package/dist/cli/commands/signing-key.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerSigningKeyCommands(program: Command): void;
+//# sourceMappingURL=signing-key.d.ts.map

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

@@ -20,5 +20,17 @@
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
+/** Error shown when both the private key and the webhook secret ask for stdin. */
+export declare const BOTH_STDIN_ERROR = "cannot read both the private key and the webhook secret from stdin \u2014 use @file or --from-env for one of them";
+/**
+ * Resolve the `--webhook-secret` value. A literal value passes through; `-`
+ * reads the secret from stdin; absent stays undefined. The private key can also
+ * be piped via `--stdin`, and stdin can only be consumed once — so `-` here
+ * while the private key also reads stdin is a hard error.
+ */
+export declare function resolveWebhookSecret(opts: {
+    value?: string;
+    privateKeyFromStdin: boolean;
+}, readStdin?: () => Promise<string>): Promise<string | undefined>;
 export declare function registerSourceCommands(program: Command, getClient: () => AdminApiClient): void;
 //# sourceMappingURL=source.d.ts.map

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

@@ -6,5 +6,14 @@
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
+/**
+ * Parse a `--expires` value into an absolute expiry Date.
+ *
+ * Accepts either a duration shorthand relative to now (`<N>d` days,
+ * `<N>h` hours, `<N>m` minutes — e.g. `30d`, `12h`, `45m`) or an
+ * absolute ISO-8601 datetime (e.g. `2026-12-31T00:00:00Z`). Throws on any
+ * other input so a typo never silently creates a non-expiring token.
+ */
+export declare function parseExpiresAt(input: string, now?: Date): Date;
 export declare function registerTokenCommands(program: Command, getClient: () => AdminApiClient): void;
 //# sourceMappingURL=token.d.ts.map

package/dist/cli/commands/trust-policy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Org trust-policy commands for kici-admin.
+ *
+ * Subcommand namespace: `kici-admin trust-policy <show|set>`.
+ *
+ * Talks to the orchestrator admin API directly (not the Platform dashboard
+ * proxy), so the CLI stays operable even when Platform is unavailable. Backed
+ * by `packages/orchestrator/src/routes/admin-trust-policy.ts`.
+ *
+ * `set` only works on an independent orchestrator. Wherever a Platform is
+ * attached the Platform owns the policy and the route refuses with 409; the
+ * message is surfaced verbatim rather than reworded here, so the CLI cannot
+ * drift from what the server actually said.
+ */
+import type { Command } from 'commander';
+import { TrustPolicyEnforcement } from '../../security/trust-policy-gate.js';
+import type { AdminApiClient } from '../api-client.js';
+/**
+ * The policy shape the admin route returns.
+ *
+ * The four policy fields are OPTIONAL because the route omits them under
+ * `enforcement: 'legacy'` — there they would be values nothing enforces, and
+ * printing them is the false assurance this feature exists to remove.
+ */
+export interface TrustPolicyView {
+    customerId: string;
+    forkPolicy?: string;
+    unknownContributorPolicy?: string;
+    workflowChangePolicy?: string;
+    approvalExpiryHours?: number;
+    /** `policy` = the values below are enforced; `legacy` = only the legacy rule. */
+    enforcement?: TrustPolicyEnforcement;
+    source: string | null;
+    updatedAt: string | null;
+    effectiveDefault?: boolean;
+    platformManaged?: boolean;
+}
+/** Render the policy as an aligned table, or as JSON when asked. */
+export declare function formatPolicy(policy: TrustPolicyView, format: string): string;
+/**
+ * Turn CLI flags into a PATCH body, exiting on an unknown value.
+ *
+ * Validating here as well as on the route is deliberate: it turns a typo into a
+ * clear local message naming the accepted values instead of a 400 from the API.
+ */
+export declare function buildPolicyPatch(opts: Record<string, string | undefined>): Record<string, string | number>;
+export declare function registerTrustPolicyCommands(program: Command, getClient: () => AdminApiClient): void;
+//# sourceMappingURL=trust-policy.d.ts.map

package/dist/cli/join.d.ts

@@ -6,7 +6,7 @@
  * writing the local YAML config.
  *
  * Usage:
- *   kici-admin join --token kici_join_v1.xxx.yyy --platform wss://platform.kici.dev/ws --api-key KEY
+ *   kici-admin join --token kici_join_v1.xxx.yyy --platform wss://api.kici.dev/ws --api-key KEY
  *   kici-admin join --token kici_join_v1.xxx.yyy --peer https://orch-1:8080
  */
 import type { Command } from 'commander';

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

@@ -12,9 +12,9 @@ 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, readKiciVersion, resolveVersionFromLaunchSpec, } from './instance/manifest.js';
+export { manifestFilename, manifestPath, readManifest, writeManifest, readKiciVersion, resolveVersionFromLaunchSpec, resolveNpmInstallTarget, type NpmInstallTarget, } from './instance/manifest.js';
 export { indexPath, readIndex, writeIndex, appendIndexEntry, removeIndexEntry, } from './instance/index-file.js';
-export { listInstances, resolveInstance, formatRefusal } from './instance/resolve.js';
+export { listInstances, resolveInstance, formatRefusal, InstanceNotFoundError, } from './instance/resolve.js';
 export type { ListedInstance, ResolveArgs, ListInstancesArgs } from './instance/resolve.js';
 import type { ServiceManager, ServicePlatform } from './types.js';
 /**

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

@@ -39,4 +39,21 @@ export declare function readKiciVersion(): string;
  * stand behind.
  */
 export declare function resolveVersionFromLaunchSpec(spec: LaunchSpec, component: Component): string | null;
+/**
+ * The global npm package + node runtime an npm-source upgrade must install
+ * into, derived from a unit's launch spec. `owningPackage` is the top-level
+ * global package whose ExecStart the unit runs — `kici-admin` when the
+ * component is loaded through its nested node_modules, or `@kici-dev/<component>`
+ * for a standalone install. `npmPath` is the npm co-located with the unit's
+ * pinned node, so `npm install -g` with it lands in exactly the prefix
+ * ExecStart resolves from, regardless of the shell's active node.
+ */
+export interface NpmInstallTarget {
+    nodeExecPath: string;
+    npmPath: string;
+    owningPackage: string;
+}
+export declare function resolveNpmInstallTarget(spec: LaunchSpec, component: Component, opts: {
+    windows: boolean;
+}): NpmInstallTarget | null;
 //# sourceMappingURL=manifest.d.ts.map

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

@@ -41,6 +41,17 @@ export interface ListInstancesArgs {
  * the requested component + isUserLevel.
  */
 export declare function listInstances(args: ListInstancesArgs): Promise<ListedInstance[]>;
+/**
+ * Thrown by resolveInstance when `--name <n>` is given but no installed
+ * instance matches. Lifecycle commands catch this to treat stop/uninstall of
+ * a never-installed instance as an idempotent no-op. Distinct from the
+ * ambiguous-refusal and missing-manifest errors, which stay hard failures.
+ */
+export declare class InstanceNotFoundError extends Error {
+    readonly component: Component;
+    readonly instanceName: string;
+    constructor(component: Component, instanceName: string, message: string);
+}
 export interface ResolveArgs {
     component: Component;
     opts: ResolveOptions;