@kici-dev/orchestrator 0.10.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/api-client.d.ts

@@ -158,6 +158,25 @@ export declare class AdminApiClient {
     }>;
     setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
     deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
+    /**
+     * Create an empty secret scope. A `<backend>:` qualifier selects the
+     * backend; an unqualified scope targets the PG backend. Creating a scope
+     * that already exists succeeds and changes nothing.
+     */
+    createScope(orgId: string, scope: string): Promise<{
+        created: boolean;
+    }>;
+    /**
+     * Rename a secret scope inside its backend. The route refuses a move between
+     * backends and a rename onto a scope that already exists.
+     */
+    renameScope(orgId: string, oldScope: string, newScope: string): Promise<{
+        renamed: boolean;
+    }>;
+    /** Delete a secret scope and every secret in it. */
+    deleteScope(orgId: string, scope: string): Promise<{
+        deleted: boolean;
+    }>;
     /**
      * Create (or upsert) a deployment context. `allowLocalExecution` lets
      * CLI-initiated / local runs resolve secrets through this context.
@@ -273,7 +292,7 @@ export declare class AdminApiClient {
         to?: string;
         limit?: number;
         offset?: number;
-        /** Phase D opt-in for cold-store read-through. */
+        /** Opt-in cold-store read-through. */
         includeArchived?: boolean;
     }): Promise<any[]>;
     createToken(data: {

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

@@ -1,3 +1,13 @@
+/**
+ * `kici-admin attestations` — orchestrator-DB-direct provenance maintenance.
+ *
+ *   attestations reverify [--all]   Recompute stored verdicts (verify-at-ingest
+ *                                   backfill). Default scope: pending /
+ *                                   unverifiable rows; `--all` re-evaluates
+ *                                   every row. Direct DB + object storage.
+ *
+ * Belongs to `kici-admin`: it works on the orchestrator's database.
+ */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 export declare function registerAttestationsCommands(program: Command, getClient: () => AdminApiClient): void;

package/dist/cli/commands/cold-store-impl.d.ts

@@ -45,7 +45,7 @@ export declare function replayChunk(opts: {
     instanceId?: string;
 }): Promise<void>;
 /**
- * Phase F — promote a chunk's rows BACK into the orchestrator PG.
+ * Promote a chunk's rows back into the orchestrator PG.
  * Mirrors the Platform-side `replayIntoPg`. Adapter must implement
  * `replayInsert` — currently only `execution_runs`.
  */
@@ -65,7 +65,7 @@ export declare function reconcile(opts: {
     instanceId?: string;
 }): Promise<void>;
 /**
- * Phase 2 — list chunks past their cold-retention horizon. Read-only;
+ * List chunks past their cold-retention horizon. Read-only;
  * no S3 or PG mutation. Emits one JSON line per row so the output is
  * easy to pipe through `jq` / `column -t` / etc.
  */
@@ -77,7 +77,7 @@ export declare function listPurgeable(opts: {
     instanceId?: string;
 }): Promise<void>;
 /**
- * Phase 2 — delete S3 objects + clean up PG bookkeeping for chunks
+ * Delete S3 objects + clean up PG bookkeeping for chunks
  * past their cold-retention horizon. Defaults to dry-run; pass
  * `--apply` to actually delete.
  */

package/dist/cli/commands/cold-store.d.ts

@@ -1,9 +1,9 @@
 /**
  * Cold-store commands for kici-admin (orchestrator side).
  *
- * Phase C: every subcommand has a real implementation that builds an
- * `OrchestratorColdStore` against the orchestrator Postgres + S3 and
- * delegates to the helpers in `cold-store-impl.ts`. Mirrors
+ * Every subcommand builds an `OrchestratorColdStore` against the
+ * orchestrator Postgres + S3 and delegates to the helpers in
+ * `cold-store-impl.ts`. Mirrors
  * `kici-platform-admin cold-store …` on the Platform side.
  *
  *   cold-store archive-now <table>       Run one cycle for a single adapter
@@ -11,7 +11,10 @@
  *   cold-store list-chunks <table>       List chunks for a table
  *   cold-store verify-chunk <chunkId>    Recompute contentHash for a chunk
  *   cold-store replay-chunk <chunkId>    Re-run UPDATE+DELETE for a stuck chunk
+ *   cold-store replay-into-pg <chunkId>  Promote a chunk's rows back into PG
  *   cold-store reconcile <table>         Rebuild orphaned manifests from data
+ *   cold-store list-purgeable            List chunks past cold retention
+ *   cold-store purge-now                 Purge expired chunks (dry-run default)
  *   cold-store peek-chunk <chunkId>      Stream the first N rows of a chunk
  *
  * The CLI talks **directly** to the orchestrator Postgres (and the same

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

@@ -8,16 +8,18 @@
  *   context show           — show a single context with variables + bindings
  *   context delete         — delete a context (cascades bindings, variables, overrides; held-run history survives; pending held runs block with a clear error, resolved holds do not)
  *   context create-template — create/update a context template + its seed variables
+ *   context source-override list|set|delete — per-source variable overrides (HTTP only)
  *
- * Each command supports two modes (stage-4 pattern from `maintenance.ts`):
+ * Each command except `source-override` supports two modes, the same split
+ * `maintenance.ts` uses:
  *
  *   HTTP mode (default): requires `--url` + `--token`, routes through the
  *   orchestrator admin HTTP API at /api/v1/admin/contexts.
  *
  *   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/dashboard-encryption-key.d.ts

@@ -1,3 +1,21 @@
+/**
+ * `kici-admin dashboard-encryption-key` — the orchestrator's X25519
+ * dashboard-encryption key: the trust root a browser seals a secret / variable
+ * value to under the `encrypted` dashboard-write posture, so the hosted control
+ * plane relays only opaque ciphertext.
+ *
+ *   dashboard-encryption-key show     Print the active kid, its public JWK, where
+ *                                     the JWKS is published, and the Verified-tier
+ *                                     URL (when that tier is opted into).
+ *   dashboard-encryption-key list     List every key on record (kid / status / created_at).
+ *   dashboard-encryption-key rotate   Mint a new active key; the prior active key
+ *                                     is retired from the published JWKS, but its
+ *                                     private half stays on record so envelopes
+ *                                     already sealed to it still decrypt.
+ *
+ * The PRIVATE half is master-key wrapped (`KICI_SECRET_KEY`) in the orchestrator
+ * DB and is never exportable — recovery from a lost key is a routine rotation.
+ */
 import type { Command } from 'commander';
 export declare function registerDashboardEncryptionKeyCommands(program: Command): void;
 //# sourceMappingURL=dashboard-encryption-key.d.ts.map

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 (Phase 5 of the
- * event durability work). 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/registration.d.ts

@@ -1,16 +1,20 @@
 /**
- * Workflow registration read CLI commands for kici-admin (5a #4).
+ * Workflow registration CLI commands for kici-admin.
  *
  *   registration list [--org <id>] [--routing-key <k>] [--repo <ident>] [--limit <n>]
  *   registration show <id>
+ *   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; the existing `workflow list` is
- * untouched by this plan.
+ * workflow_registrations. Both coexist.
  *
- * Dual-mode: HTTP (via AdminApiClient on the existing
+ * `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.
  */
 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/secret.d.ts

@@ -3,6 +3,7 @@
  *
  * Provides scoped secret operations:
  *   secret scopes, list, set, delete, fix-prefixed-scopes
+ *   secret scope create|rename|delete
  *
  * Secret values are write-only -- there is no "get value" command.
  */

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/confirm.d.ts

@@ -0,0 +1,19 @@
+/** Message of the error raised when stdin ends before the operator answers. */
+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.
+ */
+export declare function confirmPrompt(prompt: string, io?: ConfirmIo): Promise<boolean>;
+//# sourceMappingURL=confirm.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