@kici-dev/orchestrator 0.17.0 → 0.18.0

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

@@ -1,19 +1,8 @@
 /**
- * Shared run-cancellation path.
- *
- * `cancelRunWithReason` is the single canonical implementation of "cancel
- * this whole run, recording a reason". It is invoked by:
- *
- *  - the operator-facing `POST /api/v1/admin/runs/:runId/cancel` route
- *    (user-initiated `kici cancel`), and
- *  - the WorkflowDeadlineDetector, which cancels runs that exceeded their
- *    workflow-level wall-clock timeout (TimeoutReason.workflow_timeout).
- *
- * Keeping one implementation means the deadline enforcer and the user cancel
- * follow identical mechanics: send `job.cancel` to the agents running the
- * run's jobs, cancel queued dispatch rows, mark pending/queued jobs cancelled,
- * stamp the failure reason, and drive the run terminal when no agent work is
- * outstanding.
+ * The single "cancel this whole run, recording a reason" path, shared by the
+ * `POST /api/v1/admin/runs/:runId/cancel` route (`kici cancel`) and the
+ * WorkflowDeadlineDetector (TimeoutReason.workflow_timeout), so both follow
+ * identical mechanics.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -33,18 +22,16 @@ export interface CancelRunDeps {
      */
     instanceId?: string;
     /**
-     * Forward `job.cancel` to the coordinator holding the agent's socket, with
-     * `force` when the cancel is forced. Returns whether the send left this
-     * process. Undefined ⇒ no peer transport, so a job owned by a sibling is
-     * unreachable rather than orphaned.
+     * Forward `job.cancel` to the coordinator holding the agent's socket; returns
+     * whether the send left this process. Undefined ⇒ no peer transport, so a
+     * job owned by a sibling is unreachable rather than orphaned.
      */
     cancelJobOnPeer?: (peerId: string, runId: string, jobId: string, reason: string, force?: boolean) => boolean;
     /** How stale a `cluster_instances` heartbeat may be and still read as live. */
     ownershipGraceMs?: number;
     /**
-     * Reject a held run's workflow-scoped hold: `rejectWorkflow` bound to the live
-     * processing deps. A cancel of a `held` run goes through it so the approval
-     * request is withdrawn with the run. Undefined where no provider wiring
+     * `rejectWorkflow` bound to the live processing deps, so a cancel of a `held`
+     * run withdraws its approval request. Undefined where no provider wiring
      * exists; the held run is then still cancelled and its holds rejected.
      */
     rejectHeldWorkflow?: (hold: HeldRun, reason: string, opts?: RejectHeldWorkflowOptions) => Promise<boolean>;
@@ -61,23 +48,19 @@ export interface CancelRunResult {
     /** Number of `job.cancel` messages dispatched to agents (running jobs). */
     agentsNotified: number;
     /**
-     * Jobs whose owning coordinator is alive but could not be reached — the peer
-     * send failed, or there is no peer transport. They are NOT notified and they
-     * are NOT orphaned: the job may well still be running, so the run stays
-     * `cancelling` and the re-drive sweep tries again.
+     * Jobs whose owning coordinator is alive but unreachable (peer send failed,
+     * or no peer transport). Not notified and NOT orphaned: the job may still be
+     * running, so the run stays `cancelling` and the re-drive sweep retries.
      */
     unreachable: number;
     /** Number of pending/queued execution_jobs rows marked cancelled. */
     pendingCancelled: number;
-    /**
-     * True when the run was already in a terminal status, so the cancel was a
-     * no-op: no agent was notified and no row was written.
-     */
+    /** The run was already terminal: a no-op, nothing notified or written. */
     alreadyTerminal: boolean;
     /**
-     * Set when the run was `held` and a decision reached its holds first — an
-     * approve, a reject or an expiry — so the cancel wrote nothing. Entry points
-     * refuse the cancel with {@link heldRunCancelRefusal}.
+     * The run was `held` and an approve, reject or expiry reached its holds
+     * first, so the cancel wrote nothing. Entry points refuse it with
+     * {@link heldRunCancelRefusal}.
      */
     decidedBeforeCancel?: HeldRunDecidedFirst;
 }
@@ -100,27 +83,20 @@ export declare class HeldRunCancelRefusedError extends Error {
 }
 /**
  * Cancel a whole run, recording `reason` on its cancelled jobs and (if not
- * already set) on the run's failure_reason. Sends `job.cancel` to every agent
- * holding a dispatched job for the run; cancels queued dispatch rows; marks
- * pending/queued jobs cancelled. When no agent had outstanding work, drives
- * the run to its terminal status immediately so the run does not linger in
- * `cancelling`.
+ * already set) on the run's failure_reason: sends `job.cancel` to every agent
+ * holding a dispatched job, cancels queued dispatch rows, marks pending/queued
+ * jobs cancelled. When no agent had outstanding work, drives the run terminal
+ * immediately so it does not linger in `cancelling`.
  *
- * A cancel targeting a run that is already terminal is a no-op: the run's
- * status is read first and, when terminal, the function returns
- * `alreadyTerminal: true` having written nothing. Entry points map that to
- * their own convention (the operator route answers 409; the dashboard/MCP path
- * returns a structured already-terminal result).
+ * An already-terminal run is a no-op returning `alreadyTerminal: true`; the
+ * operator route answers 409, the dashboard/MCP path a structured result.
  */
 export declare function cancelRunWithReason(deps: CancelRunDeps, runId: string, reason: string, options?: CancelRunOptions): Promise<CancelRunResult>;
 /**
- * Send `job.cancel` down this coordinator's own socket for the agent.
- *
- * Only an OPEN socket can receive it. A socket mid-close is still in the
- * registry until its close handler unregisters it, and sending to it throws, so
- * a non-OPEN socket leaves the job un-notified and the orphan sweep takes it.
- * The send is wrapped so one bad socket cannot abort the whole cancellation and
- * strand the run in `cancelling`.
+ * Send `job.cancel` down this coordinator's own socket for the agent. A
+ * mid-close socket stays registered until its close handler runs and throws on
+ * send, so a non-OPEN socket leaves the job to the orphan sweep. The send is
+ * wrapped so one bad socket cannot strand the run in `cancelling`.
  */
 export declare function sendLocalCancel(args: {
     registry: Pick<AgentRegistry, 'get'>;

package/dist/cancel/dashboard-cancel-handler.d.ts

@@ -2,8 +2,8 @@
  * The cancel handler behind the dashboard, the `kici runs cancel` CLI, and the
  * MCP `cancel_run` tool.
  *
- * It delegates to `cancelRunWithReason` so the customer-facing cancel follows
- * the same mechanics as the operator-facing one: an already-terminal run is a
+ * Delegates to `cancelRunWithReason` so it follows the operator-facing cancel's
+ * mechanics: an already-terminal run is a
  * no-op, only OPEN agent sockets are notified, queued dispatch rows are
  * cancelled, pending jobs are marked cancelled, and a run with no outstanding
  * agent work is driven terminal.

package/dist/cancel/peer-job-cancel.d.ts

@@ -1,17 +1,16 @@
 /**
  * The receiving end of `peer.job.cancel`.
  *
- * A sibling forwards a cancel to the coordinator its agent is connected to,
- * which it reads from the host roster. That coordinator's dispatcher tracks the
- * job only when it dispatched or re-adopted it: an agent that reconnected here
- * from a sibling, or one not yet back after this process restarted, is known
- * only to `dispatch_queue.agent_id`. So the agent is resolved from the
- * dispatcher first and from the dispatch record second, and a cancel that
- * cannot be delivered is logged with the reason.
+ * A sibling forwards a cancel to the coordinator its agent is connected to (read
+ * from the host roster). That dispatcher tracks the job only when it dispatched
+ * or re-adopted it: an agent that reconnected here from a sibling, or one not yet
+ * back after this process restarted, is known only to `dispatch_queue.agent_id`.
+ * So the agent is resolved from the dispatcher first and the dispatch record
+ * second, and an undeliverable cancel is logged with the reason.
  *
- * On a worker the receiver also removes the jobs of the cancel that are still
- * queued (waiting for an agent spawn), and stop-marks the dispatched ones so a
- * requeue cannot bring them back. A removed job is reported `dequeued`.
+ * On a worker the receiver also removes the cancel's still-queued jobs (waiting
+ * for an agent spawn), reported `dequeued`, and stop-marks the dispatched ones so
+ * a requeue cannot bring them back.
  */
 import type { Kysely } from 'kysely';
 import { z } from 'zod';
@@ -41,10 +40,8 @@ export interface PeerJobCancelDeps {
     /** The durable dispatch record. Absent on a worker, which has no database. */
     lookupDispatched?: (runId: string, jobId: string | undefined) => Promise<DispatchedAgent[]>;
     /**
-     * Remove this process's queued (not yet dispatched) jobs of the cancel, and
-     * stop-mark its dispatched ones so a requeue cannot bring them back. Wired only
-     * on a worker, whose queue lives in memory; a coordinator's queue rows are
-     * settled by its own run-cancel path.
+     * Wired only on a worker, whose queue lives in memory; a coordinator's queue rows
+     * are settled by its own run-cancel path.
      */
     releaseQueued?: (runId: string, jobId: string | undefined) => Promise<string[]>;
     logger: {

package/dist/cancel/sweep-stuck-cancelling.d.ts

@@ -7,24 +7,20 @@ export interface SweepStuckCancellingDeps {
         force: boolean;
     }) => Promise<unknown>;
     /**
-     * How long a run may sit in `cancelling` before it is re-driven. Twice the
-     * recovery grace period: long enough that a graceful agent teardown finishes
-     * on its own, short enough that a dropped cancel does not sit for an hour.
+     * Time in `cancelling` before a re-drive: twice the recovery grace period, so
+     * a graceful teardown finishes on its own but a dropped cancel does not sit
+     * for an hour.
      */
     stuckAfterMs: number;
 }
 /**
- * Re-drive the cancel for runs left in `cancelling`.
+ * Re-drive the cancel for runs left in `cancelling`. A peer blip drops a cancel
+ * sent over the peer channel, leaving the jobs executing; the workflow-deadline
+ * detector re-scans `cancelling` runs only when they HAVE a workflow timeout,
+ * so this covers every other run.
  *
- * A cancel reaches its target over the peer channel, and a peer blip drops it.
- * The run then sits in `cancelling` with its jobs still executing, and nothing
- * retries: the workflow-deadline detector re-scans `cancelling` runs, but only
- * ones that HAVE a workflow timeout, so a run without one waits forever. This
- * extends the same coverage to every run.
- *
- * Leader-gated by its caller, and idempotent by construction — re-driving a
- * cancel that already landed re-sends `job.cancel` to an agent that is already
- * unwinding, and re-driving one whose jobs are all terminal completes the run.
+ * Leader-gated by its caller, and idempotent: re-driving re-sends `job.cancel`
+ * to an agent already unwinding, or completes a run whose jobs are all terminal.
  *
  * @returns how many runs were re-driven.
  */

package/dist/cli/api-client.d.ts

@@ -1,10 +1,4 @@
-/**
- * HTTP client wrapper for the kici-admin CLI.
- *
- * Communicates with the orchestrator admin API via Bearer token authentication.
- * All methods are thin wrappers around fetch() that handle JSON serialization,
- * error formatting, and URL construction.
- */
+/** kici-admin's HTTP client for the orchestrator admin API (Bearer token auth). */
 import type { PeerForgetOutcome, ScalerLiveVm, ScalerReloadAnswer, ScalerReloadInstanceResult, ScalerVmStopResult } from '@kici-dev/engine';
 /** `POST /api/v1/admin/peers/forget`: one result per coordinator, this one first. */
 export interface PeerForgetResponseBody {
@@ -60,16 +54,14 @@ export interface FleetTopologyResponse {
     nodes: FleetTopologyNodeResponse[];
 }
 /**
- * Universal-git configuration shape carried in `git_config` on
- * generic_webhook_sources. Matches `UniversalGitConfigSchema` in
- * `providers/universal-git/config.ts`. Kept as a loose `Record` here to
- * avoid a cross-package import in the CLI wire type.
+ * A source's `git_config`; matches `UniversalGitConfigSchema` in
+ * `providers/universal-git/config.ts`, kept a loose `Record` to avoid a
+ * cross-package import in the CLI wire type.
  */
 export type GenericSourceGitConfigPayload = Record<string, unknown>;
 /**
- * Wire shape for a local filesystem source's config
- * (`{ repoBasePath, cloneUrlBase?, inPlace? }`).
- * Matches `LocalSourceConfigSchema` in `providers/local/local-source-config.ts`.
+ * A local source's config; matches `LocalSourceConfigSchema` in
+ * `providers/local/local-source-config.ts`.
  */
 export interface GenericSourceLocalConfigPayload {
     repoBasePath: string;
@@ -77,9 +69,6 @@ export interface GenericSourceLocalConfigPayload {
     /** In-place profile: the repoBasePath is the operator's real working tree. */
     inPlace?: boolean;
 }
-/**
- * Response shape for generic webhook sources from the admin API.
- */
 export interface GenericSourceResponse {
     id: string;
     customer_id: string;
@@ -105,42 +94,29 @@ export interface GenericSourceResponse {
     git_config?: string | GenericSourceGitConfigPayload | null;
 }
 /**
- * `fetch` rejects with a bare `TypeError: fetch failed` when it cannot reach the
- * host — it names neither the address dialled nor the knob that sets it. Printed
- * through the CLI's `Error: ${message}` handler that becomes `Error: fetch
- * failed`, which reads like a fault in the subcommand rather than a misaddressed
- * client, and sends the operator debugging the wrong thing.
- *
- * The trap is sharpened by two details of this CLI. The base URL comes from
- * `KICI_ADMIN_URL`, not the `KICI_ORCHESTRATOR_URL` an operator is likelier to
- * have exported; and subcommands accepting `--database-url` fall back to direct
- * DB access, so on a host with `KICI_DATABASE_URL` set they keep working while
- * the HTTP-only ones fail — making it look like specific subcommands are broken.
- *
- * So: name the address, name the variable, and name the near-miss.
+ * A bare `TypeError: fetch failed` names neither the address nor the knob that
+ * sets it, so it reads as a broken subcommand rather than a misaddressed client.
+ * The base URL comes from `KICI_ADMIN_URL`, not `KICI_ORCHESTRATOR_URL`, and
+ * subcommands with `--database-url` fall back to direct DB access, so with
+ * `KICI_DATABASE_URL` set only the HTTP-only ones fail. The error therefore names
+ * the address, the variable and the near-miss.
  */
 /**
- * Best-effort one-line detail from a rejected `fetch`. Returns '' when nothing
- * useful is available, so the caller can omit the parenthetical rather than
- * print an empty one.
+ * Best-effort one-line detail from a rejected `fetch`; '' when none, so the
+ * caller omits the parenthetical.
  */
 export declare function firstCauseMessage(err: unknown): string;
 /**
- * True when a rejected `fetch` failed at the transport layer, as opposed to
- * failing while the request was still being built.
- *
- * `fetch` uses a `TypeError` for both, so they are easy to conflate — but only
- * a transport failure means the orchestrator was actually dialled. Measured
- * against Node 24's undici:
+ * True when a rejected `fetch` failed at the transport layer, not while the
+ * request was being built. Both are a `TypeError`, but only a transport failure
+ * means the orchestrator was dialled. Measured against Node 24's undici:
  *
  *   closed port    → TypeError('fetch failed')                       cause: Error(ECONNREFUSED)
  *   invalid header → TypeError('Headers.append: … invalid header …') cause: undefined
  *   invalid URL    → TypeError('Failed to parse URL from …')         cause: Error(ERR_INVALID_URL)
  *
- * The discriminator is therefore the message, NOT the presence of a `cause`:
- * the invalid-URL case carries one. undici uses exactly `fetch failed` for a
- * transport failure and a descriptive message for everything it rejects before
- * opening a connection.
+ * So the discriminator is the message, NOT a `cause` (the invalid-URL case has
+ * one): undici says exactly `fetch failed` only for a transport failure.
  */
 export declare function isTransportFailure(err: unknown): boolean;
 /** The admin API address kici-admin dials when neither --url nor KICI_ADMIN_URL is set. */
@@ -152,33 +128,12 @@ export declare class AdminApiClient {
     private readonly baseUrl;
     private readonly token;
     constructor(baseUrl: string, token: string);
-    /**
-     * Make an authenticated HTTP request to the admin API.
-     */
     private request;
-    /**
-     * Public GET request returning parsed JSON.
-     */
     get<T>(path: string): Promise<T>;
-    /**
-     * Public POST request returning parsed JSON.
-     */
     post<T>(path: string, body: unknown): Promise<T>;
-    /**
-     * Public PATCH request returning parsed JSON.
-     */
     patch<T>(path: string, body: unknown): Promise<T>;
-    /**
-     * Public PUT request returning parsed JSON.
-     */
     put<T>(path: string, body: unknown): Promise<T>;
-    /**
-     * Public DELETE request returning parsed JSON.
-     */
     delete<T>(path: string): Promise<T>;
-    /**
-     * Public GET request returning raw response text.
-     */
     getText(path: string): Promise<string>;
     /** Enumerate the cluster topology for `debug-bundle --fleet --list` / `--pick`. */
     getFleetTopology(): Promise<FleetTopologyResponse>;
@@ -367,13 +322,9 @@ export declare class AdminApiClient {
         tokens: any[];
     }>;
     /**
-     * Revoke an agent token.
-     *
-     * The orchestrator both flips `agent_tokens.revoked_at` AND
-     * synchronously closes every in-flight agent WS authenticated by
-     * this token. The returned `kicked` count is the number
-     * of WS connections that were closed on the wire — surface it to
-     * the operator so they know the revocation actually propagated.
+     * Revoke an agent token: the orchestrator sets `agent_tokens.revoked_at` AND
+     * synchronously closes every agent WS authenticated by it. `kicked` counts
+     * the closed connections; show it so the operator sees the revocation propagated.
      */
     revokeAgentToken(id: string): Promise<{
         kicked: number;
@@ -430,7 +381,6 @@ export declare class AdminApiClient {
         draining: boolean;
         jobsRunning: number;
     }>;
-    /** Forget a departed peer on this coordinator and every connected sibling. */
     /**
      * Forget a departed peer on this coordinator and every connected sibling. A
      * refusal that only needs the backstop acknowledgement comes back as a body
@@ -532,10 +482,9 @@ export declare class AdminApiClient {
         }>;
     }>;
     /**
-     * List execution runs. `status` accepts either a single status or a
-     * comma-separated list (e.g. `success,failed`). `since` is an ISO-8601
-     * timestamp; only runs with `created_at` strictly later than this value
-     * are returned.
+     * List runs. `status` takes one status or a comma-separated list (e.g.
+     * `success,failed`). `since` is an ISO-8601 timestamp; only runs with
+     * `created_at` strictly later are returned.
      */
     listRuns(opts?: {
         status?: string;

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

@@ -1,28 +1,8 @@
 /**
- * Access log commands for kici-admin.
- *
- * Operator-facing read access to the orchestrator's access_log table
- * (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
- *
- * Filter flags for `list`:
- *   --org             -> ?orgId=
- *   --actor-type      -> ?actorType=
- *   --actor-id        -> ?actorId=
- *   --action          -> ?action=
- *   --source          -> ?source=
- *   --outcome         -> ?outcome=
- *   --target-type     -> ?targetType=
- *   --target-id       -> ?targetId=
- *   --from / --to     -> ?from= / ?to= (ISO timestamps)
- *   --q               -> ?q= (substring of error_message, trigram-indexed)
- *   --limit           -> ?limit= (default 50, max 200)
- *   --cursor          -> ?cursor=
- *   --json            Emit raw JSON
+ * `kici-admin access-log`: the access_log table (read and mutation
+ * attribution by ActorPrincipal) instead of raw psql. `list` filter flags map
+ * 1:1 to query params; `--q` is a trigram-indexed substring of error_message,
+ * and `--limit` defaults to 50, max 200.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

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

@@ -5,9 +5,8 @@ import { type AgentPackageStorage } from '../../agent-packaging/index.js';
 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). */
+/** The cache-bucket storage client (S3 only). */
 export declare function resolveUploadStorage(): AgentPackageStorage;
-/** Options for {@link runAgentPackageRefresh} (the auto-package-on-upgrade hook). */
 export interface AgentPackageRefreshOptions {
     platforms?: AgentPlatformType[];
     nodeMirror?: string;
@@ -15,20 +14,13 @@ export interface AgentPackageRefreshOptions {
     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.
+ * Produce and upload the agent payloads for the current version after a
+ * versioned upgrade. Best-effort: a filesystem-cache orchestrator has no bucket,
+ * so it logs and skips; a produce/upload error is reported but does not fail
+ * the already-completed upgrade. Idempotent. 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).
- */
+/** Must run after registerAgentCommands, which creates the `agent` group. */
 export declare function registerAgentPackage(program: Command): void;
 //# sourceMappingURL=agent-package.d.ts.map

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

@@ -1,9 +1,7 @@
 /**
- * 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.
+ * The env file `kici-admin agent install` writes. The agent's config loader
+ * refuses unknown KICI_* variables, so a misspelt key stops the agent at
+ * startup; `agent-env.test.ts` loads the output through that loader.
  */
 export interface AgentEnvFields {
     /** First line of the file, a `#` comment naming what wrote it. */
@@ -15,6 +13,5 @@ export interface AgentEnvFields {
     /** 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/index.d.ts

@@ -1,14 +1,8 @@
 /**
- * Agent service command group registration.
- *
- * Adds install, uninstall, start, stop, restart, status, logs, and upgrade
- * subcommands to the existing `agent` command group for managing the agent
- * as a system service.
- *
- * These commands manage local services directly and do NOT use AdminApiClient.
- * They coexist with the existing agent token management commands (register, list, revoke).
- *
- * Must be called AFTER registerAgentCommands() so the `agent` command already exists.
+ * Adds install, uninstall, start, stop, restart, status, logs and upgrade
+ * to the `agent` group beside its token commands (register, list,
+ * revoke). They manage local services directly and do NOT use AdminApiClient.
+ * Must run AFTER registerAgentCommands(), which creates the group.
  */
 import type { Command } from 'commander';
 export declare function registerAgentServiceCommands(program: Command): void;

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

@@ -1,15 +1,8 @@
 /**
- * `kici-admin agent install` command.
- *
- * Registers the agent as a native system service on the current platform.
- * Accepts orchestrator URL and token for connecting to the orchestrator.
- *
- * Targeting is folder-anchored: the install writes an instance manifest
- * into the deploy folder (`--instance-dir`, default: CWD) and appends a
- * row to the host-wide instance index so every lifecycle command can
- * reconstruct the ServiceConfig without re-deriving paths. A create-path
- * guard refuses to clobber a same-named foreign instance unless `--force`
- * is passed.
+ * `kici-admin agent install`: registers the agent as a native service.
+ * Folder-anchored: it writes an instance manifest into `--instance-dir`
+ * (default: CWD) and a host-wide index row, from which every lifecycle command
+ * rebuilds the ServiceConfig. A same-named foreign instance is refused without `--force`.
  */
 import type { Command } from 'commander';
 export declare function registerAgentInstall(agent: Command): void;

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

@@ -1,13 +1,8 @@
 /**
- * `kici-admin agent status` command.
- *
- * 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 >
- * refusal with candidate list).
+ * `kici-admin agent status`: OS-level service state (state, PID, uptime) plus
+ * the agent's `/health` (ID, orchestrator connection, active jobs, version,
+ * build fingerprint, uptime). The target resolves via resolveInstanceTarget,
+ * like every lifecycle command.
  */
 import type { Command } from 'commander';
 export declare function registerAgentStatusCommand(parent: Command): void;

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

@@ -1,20 +1,8 @@
 /**
- * `kici-admin agent upgrade` command.
- *
- * Upgrades the agent using the versioned directory layout:
- * - Extracts new version alongside old versions
- * - Updates symlink (Unix) or service registration (Windows) atomically
- * - Preserves old versions for rollback
- * - No database migrations (agents are stateless)
- *
- * Targeting is folder-anchored: the resolution priority is
- *   1. `--instance-dir <path>`
- *   2. `--name <name>`
- *   3. CWD manifest (`./.kici-agent.json`)
- *   4. otherwise refuses with a candidate-list error.
- *
- * `--name` no longer has a default — every invocation must resolve via one
- * of the above paths.
+ * `kici-admin agent upgrade`: the versioned-directory upgrade
+ * (`performVersionedUpgrade`), with no database migrations because agents are
+ * stateless. `--name` has no default: the target resolves from
+ * `--instance-dir`, `--name`, or the CWD `./.kici-agent.json`.
  */
 import type { Command } from 'commander';
 export declare function registerAgentUpgradeCommand(parent: Command): void;

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

@@ -1,34 +1,21 @@
-/**
- * Agent token management commands for kici-admin.
- *
- * Provides CRUD operations for agent authentication tokens:
- *   agent register, list, revoke
- */
+/** `kici-admin agent register|list|revoke`: agent token management. */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 /**
- * The authorized label scope a static agent token is minted with.
- *
- * Beyond the operator's own `--labels` set, the authorized scope carries:
+ * The authorized label scope a static agent token is minted with: the
+ * operator's `--labels`, plus
  *
- * - A mandatory (taint) label must also be advertisable (the selector side),
- *   so union it into the authorized labels — a taint the agent can't even
- *   advertise would be incoherent.
- * - Every real agent derives its `kici:role:*` labels from its own host and
- *   advertises them at registration, so a scope omitting them can never admit
- *   the agent that presents it: the orchestrator's register-time scope gate
- *   closes the connection with `Agent labels exceed token-bound scope`. A role
- *   the agent can't even advertise is incoherent for the same reason a taint
- *   is. The mint site cannot know which roles the target host will derive — the
- *   agent discovers them from its own capabilities — so the whole role
- *   namespace is authorized and the agent advertises the subset it has.
+ * - each mandatory (taint) label, which must also be advertisable;
+ * - the whole `kici:role:*` namespace. An agent derives its roles from its own
+ *   host and advertises them at registration, so a scope without them fails the
+ *   register-time gate (`Agent labels exceed token-bound scope`); the mint site
+ *   cannot know which roles the host will derive.
  *
- * The operator's own labels still bound everything else: a token minted with
- * `--labels linux,x64` still refuses an agent advertising `gpu`. An agent that
- * must carry no roles at all sets `KICI_ROLES=` on its own side.
+ * The operator's labels still bound everything else: `--labels linux,x64`
+ * refuses an agent advertising `gpu`. An agent with no roles sets `KICI_ROLES=`.
  *
- * Returns undefined when the operator supplied no labels and no taint — an
- * unscoped token, which the register-time gate skips entirely.
+ * Undefined with no labels and no taint: an unscoped token, which the
+ * register-time gate skips.
  */
 export declare function authorizedAgentTokenLabels(baseLabels: readonly string[], mandatoryLabels: readonly string[] | undefined): string[] | undefined;
 export declare function registerAgentCommands(program: Command, getClient: () => AdminApiClient): void;