@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/routes/admin-sources.d.ts

@@ -1,12 +1,11 @@
 /**
- * Admin API routes for webhook source management.
+ * Admin CRUD API for webhook sources (GitHub Apps, etc.). Source secrets
+ * (private keys, webhook secrets) are stored via PgSecretStore and never
+ * exposed in list/get responses; only GET /sources/:routingKey/webhook-secret
+ * returns the webhook secret.
  *
- * Provides CRUD endpoints for managing webhook sources (GitHub Apps, etc.)
- * through the admin API. Source secrets (private keys, webhook secrets) are
- * stored via PgSecretStore and never exposed in list/get responses.
- *
- * All routes are mounted under /api/v1/admin/sources and protected by
- * the admin auth middleware in admin.ts.
+ * Mounted under /api/v1/admin/sources, behind the admin auth middleware in
+ * admin.ts.
  */
 import { Hono } from 'hono';
 import type { SourceStore } from '../sources/source-store.js';
@@ -17,12 +16,11 @@ import { type AdminEnv } from './admin-env.js';
 interface SourceRouteDeps {
     sourceStore: SourceStore;
     /**
-     * Resolve the public webhook URL for a freshly added source so the CLI can
-     * print it, by mode: platform and hybrid read the Platform's URL from the
-     * `source.register.ack` (hybrid falls back to its own URL); observed and
-     * independent return this orchestrator's own per-source URL. A null URL
-     * carries a `webhookNote` that says why. Omitted in deployments with no
-     * resolver wired (the route then returns `webhookUrl: null`).
+     * Resolve a freshly added source's public webhook URL for the CLI, by mode:
+     * platform and hybrid read the Platform's URL from the `source.register.ack`
+     * (hybrid falls back to its own URL); observed and independent return this
+     * orchestrator's own per-source URL. A null URL carries a `webhookNote`
+     * saying why. Without a resolver the route returns `webhookUrl: null`.
      */
     resolveSourceWebhookUrl?: (params: {
         routingKey: string;
@@ -30,11 +28,10 @@ interface SourceRouteDeps {
         sourceId: string;
     }) => Promise<WebhookUrlResolution>;
     /**
-     * Resolve the org-scoped GitHub webhook URL for the manifest setup flow
-     * BEFORE any App exists. The GitHub webhook URL is org-scoped
-     * (`<base>/webhook/<orgId>/github`), not app-scoped, so it can be computed
-     * up front and baked into the App manifest. Returns null + a note when the
-     * orchestrator cannot resolve it for its mode.
+     * Resolve the GitHub webhook URL for the manifest setup flow BEFORE any App
+     * exists: it is org-scoped (`<base>/webhook/<orgId>/github`), not
+     * app-scoped, so it can be baked into the App manifest. Returns null + a
+     * note when the orchestrator cannot resolve it for its mode.
      */
     resolveGithubWebhookUrl?: () => Promise<WebhookUrlResolution>;
     /**
@@ -47,20 +44,14 @@ interface SourceRouteDeps {
         customerId: string | null;
     }) => string | null;
     /**
-     * Fetch a GitHub App's authoritative `{ name, slug }`, events and permissions
-     * from GitHub. Injectable for tests; defaults to the real
-     * `fetchGithubAppIdentity`. Used by the `source refresh` route.
+     * Fetch a GitHub App's authoritative `{ name, slug }`, events and
+     * permissions, for the `source refresh` route. Test seam; defaults to
+     * `fetchGithubAppIdentity`.
      */
     fetchAppIdentity?: FetchGithubAppIdentity;
-    /**
-     * List a GitHub App's installations. Injectable for tests; defaults to
-     * `listGithubAppInstallations`. Used by the `source refresh` route.
-     */
+    /** For the `source refresh` route. Test seam; defaults to `listGithubAppInstallations`. */
     fetchAppInstallations?: FetchGithubAppInstallations;
-    /**
-     * Replay a window of GitHub webhook deliveries for one App. Injectable for
-     * tests; defaults to the real `redeliverWindow`.
-     */
+    /** Test seam; defaults to `redeliverWindow`. */
     redeliverDeliveries?: RedeliverDeliveries;
 }
 /** Replay a delivery window for a GitHub App. Matches `redeliverWindow`. */

package/dist/routes/admin-trust-policy.d.ts

@@ -1,23 +1,20 @@
 /**
- * Admin API routes for the org trust policy and the approval directory it
- * arrives with.
+ * Admin API for the org trust policy and its approval directory.
  *
- * Exposes GET / PATCH `/api/v1/admin/trust-policy` so `kici-admin` can read the
- * enforced policy and, on an independent orchestrator, set it, plus
- * GET / PATCH / DELETE `/api/v1/admin/trust-policy/directory` for the approval
- * directory that arrives with it.
+ * GET / PATCH `/api/v1/admin/trust-policy` let `kici-admin` read the enforced
+ * policy and, on an independent orchestrator, set it; GET / PATCH / DELETE
+ * `/api/v1/admin/trust-policy/directory` cover the approval directory.
  *
- * Both are Platform-owned wherever a Platform is attached: the Platform pushes
- * them together on `trust_policy.update` and the next push would clobber a
- * local write. Every write verb therefore refuses on any Platform-attached
- * orchestrator, and the refusal is server-side so it cannot be bypassed by
- * calling the API directly. On an independent orchestrator there is no upstream
- * authority at all, so the operator is the only possible one — which is what
- * the directory's PATCH and DELETE are for. Without them nobody can ever be
- * registered as an approver there, and `/kici approve` can release no hold.
+ * Both are Platform-owned wherever a Platform is attached: it pushes them
+ * together on `trust_policy.update`, and the next push would clobber a local
+ * write. So every write verb refuses on a Platform-attached orchestrator,
+ * server-side so a direct API call cannot bypass it. On an independent
+ * orchestrator the operator is the only authority, hence the directory's PATCH
+ * and DELETE: without them nobody can be registered as an approver there, and
+ * `/kici approve` can release no hold.
  *
- * GET stays available in every mode: reading the cache is what lets an operator
- * tell a stale directory from an absent one.
+ * GET works in every mode: reading the cache lets an operator tell a stale
+ * directory from an absent one.
  */
 import { Hono } from 'hono';
 import type { OrchestratorMode } from '@kici-dev/engine';
@@ -26,54 +23,40 @@ import type { TrustDirectoryStore } from '../security/trust-directory-store.js';
 import type { RbacEnforcer } from '../secrets/rbac.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 import { type AdminEnv } from './admin-env.js';
-/**
- * Wording for the Platform-managed refusal. Shared with the CLI through the
- * response body — the CLI surfaces this verbatim rather than inventing its own.
- */
+/** Platform-managed refusal; the CLI shows it verbatim from the response body. */
 export declare const PLATFORM_MANAGED_MESSAGE: string;
 /**
- * Wording for the directory's own Platform-managed refusal. Separate from
- * {@link PLATFORM_MANAGED_MESSAGE} because it names a different thing to change
- * and a different place to change it: identity links and member CI trust levels
- * are org membership, not a policy switch.
+ * The directory's Platform-managed refusal. Separate from
+ * {@link PLATFORM_MANAGED_MESSAGE}: identity links and member CI trust levels are
+ * org membership, changed elsewhere, not a policy switch.
  */
 export declare const PLATFORM_MANAGED_DIRECTORY_MESSAGE: string;
 interface TrustPolicyRouteDeps {
     store: TrustPolicyStore;
     /**
-     * The org approval directory — the Platform's cache where one is attached,
-     * the operator's own registrations where none is.
-     *
-     * REQUIRED for the same reason `accessLog` is: an optional store would let an
-     * orchestrator mount a `directory` endpoint that reports "nothing cached" on
-     * every call, which reads identically to a genuinely empty cache and is
-     * exactly the wrong answer to give an operator debugging a refused approval.
+     * The Platform's cache where one is attached, the operator's own
+     * registrations where none is. REQUIRED: an optional store would let a
+     * `directory` endpoint report "nothing cached" on every call, identical to a
+     * genuinely empty cache — the wrong answer for an operator debugging a
+     * refused approval.
      */
     directory: TrustDirectoryStore;
     rbac: RbacEnforcer;
     /** This orchestrator's mode; decides whether PATCH is permitted at all. */
     mode: OrchestratorMode;
     /**
-     * Whether the Platform connection is up right now.
-     *
-     * `mode` alone cannot answer this: it says a Platform is configured, not that
-     * one is reachable, and the two differ during exactly the outage that leaves
-     * the directory below frozen. Read per request rather than captured once, so
-     * a reconnect is reflected without re-mounting the route.
-     *
-     * Absent on an independent orchestrator, which has no connection to report.
+     * Whether the Platform connection is up right now. `mode` says a Platform is
+     * configured, not reachable, and the two differ during exactly the outage
+     * that freezes the directory. Read per request so a reconnect shows without
+     * re-mounting. Absent on an independent orchestrator.
      */
     platformConnected?: () => boolean;
     /**
-     * Audit sink for the PATCH, written inside the policy transaction.
-     *
-     * REQUIRED, not optional. The guarantee this route makes is that a loosened
-     * `forkPolicy` can never land unattributed; an optional sink would leave that
-     * resting on every construction site remembering to pass one, and a route
-     * built without one would accept the write and silently skip the audit. A
-     * required dependency moves the guarantee from convention to the compiler —
-     * and `admin.ts` skips mounting the route entirely rather than mounting an
-     * unauditable one.
+     * Audit sink for the PATCH, written inside the policy transaction. REQUIRED
+     * so a loosened `forkPolicy` can never land unattributed: an optional sink
+     * would rely on every construction site passing one, and a route built
+     * without it would skip the audit silently. `admin.ts` skips mounting the
+     * route rather than mounting an unauditable one.
      */
     accessLog: AccessLogWriter;
 }

package/dist/routes/admin.d.ts

@@ -1,11 +1,8 @@
 /**
- * Admin API routes for secrets management.
+ * Admin API routes: contexts, secrets, tokens, audit log queries and key
+ * rotation, all behind Bearer token authentication and RBAC permission checks.
  *
- * Provides CRUD endpoints for contexts, secrets, tokens, audit log queries,
- * and key rotation. All routes are protected by Bearer token authentication
- * and RBAC permission checks.
- *
- * Secret values are write-only -- there is deliberately no "get secret value"
+ * Secret values are write-only: there is deliberately no "get secret value"
  * endpoint. Values are only read during dispatch resolution.
  */
 import { Hono } from 'hono';
@@ -36,22 +33,18 @@ import { type AdminEnv } from './admin-env.js';
 export interface AdminRouteDeps {
     tokenManager: TokenManager;
     /**
-     * Connection string handed to the DB migration routes, which run schema work
-     * on their own timeout-free pool. Optional so WS-only / test admins can omit
-     * it; omitting it makes those routes fall back to the shared pool.
+     * Connection string for the DB migration routes, which run schema work on
+     * their own timeout-free pool. When omitted (WS-only / test admins) those
+     * routes fall back to the shared pool.
      */
     databaseUrl?: string;
-    /**
-     * Orchestrator operating mode. Gates mode-specific admin behavior. Optional so
-     * WS-only / test admins can omit it.
-     */
+    /** Gates mode-specific admin behavior. Omitted by WS-only / test admins. */
     mode?: OrchestratorMode;
     /**
-     * Whether the Platform connection is up right now, read per request.
-     *
-     * Reported by the trust-policy directory route so an operator can tell a
-     * directory that is merely old from one that cannot refresh at all. Absent on
-     * an independent orchestrator and on a test admin, which have no connection.
+     * Whether the Platform connection is up right now, read per request. The
+     * trust-policy directory route reports it so an operator can tell a directory
+     * that is merely old from one that cannot refresh at all. Absent on an
+     * independent orchestrator and on a test admin, which have no connection.
      */
     platformConnected?: () => boolean;
     /**
@@ -65,49 +58,40 @@ export interface AdminRouteDeps {
     auditLogger: AuditLogger;
     /**
      * Fleet-wide default for the global-workflows master switch, applied when the
-     * cluster column is NULL. Optional so WS-only / test admins can omit it;
-     * omitting it means the secure default (disabled).
+     * cluster column is NULL. Omitted means the secure default (disabled).
      */
     globalWorkflowsEnabledDefault?: boolean;
     /**
-     * Optional -- the coordinator drain controller. When provided, the
-     * `POST`/`GET /api/v1/admin/orchestrator/drain` routes are mounted (backing
-     * the `kici-admin orchestrator drain` verbs). Omitted on WS-only admins.
+     * When provided, mounts `POST`/`GET /api/v1/admin/orchestrator/drain` (the
+     * `kici-admin orchestrator drain` verbs). Omitted on WS-only admins.
      */
     drainController?: DrainController;
-    /** Optional -- for agent token CRUD endpoints. */
+    /** Backs the agent token CRUD endpoints. */
     tokenStore?: AgentTokenStore;
     /**
-     * Optional -- for kicking in-flight agent WS on token revoke.
-     *
-     * The DELETE /api/v1/agent-tokens/:id route calls
-     * `agentRegistry.disconnectByTokenId(id)` synchronously after
-     * `tokenStore.revoke(id)` so a revoked token loses data-plane
-     * authority immediately instead of staying live until the agent
-     * itself disconnects. Mirrors the fix on the orch->Platform
-     * leg (`disconnectByKeyId`).
+     * DELETE /api/v1/agent-tokens/:id calls `agentRegistry.disconnectByTokenId(id)`
+     * synchronously after `tokenStore.revoke(id)` so a revoked token loses
+     * data-plane authority immediately instead of staying live until the agent
+     * disconnects. Mirrors the orch->Platform leg (`disconnectByKeyId`).
      *
-     * When unset, the DELETE route returns 503 — agent-token revoke is
-     * meaningless without the kick path because a revoked token would
-     * still grant in-flight authority for hours-to-days.
+     * When unset, the DELETE route returns 503: without the kick path a revoked
+     * token would still grant in-flight authority for hours-to-days.
      */
     agentRegistry?: AgentRegistry;
     /**
-     * Optional -- fan out the revoke to every peer in a clustered orchestrator.
-     *
-     * The DELETE /api/v1/agent-tokens/:id route calls this after the synchronous
-     * local kick, so every peer's `AgentRegistry.disconnectByTokenId(tokenId)`
-     * runs locally and closes its own in-flight WS for the same token. Mirrors
-     *'s Valkey fan-out pattern on the orch->Platform leg.
+     * Fans the revoke out to every peer in a clustered orchestrator. The DELETE
+     * route calls it after the synchronous local kick, so each peer's
+     * `AgentRegistry.disconnectByTokenId(tokenId)` closes its own in-flight WS for
+     * the same token. Mirrors the Valkey fan-out pattern on the orch->Platform leg.
      *
-     * Unset on standalone deployments (no peer fabric) -- the local kick alone
-     * is sufficient there.
+     * Unset on standalone deployments (no peer fabric), where the local kick
+     * alone is sufficient.
      */
     broadcastAgentTokenRevoke?: (tokenId: string) => void;
-    /** Optional -- for source management endpoints. */
+    /** Backs the source management endpoints. */
     sourceStore?: SourceStore;
     /**
-     * Optional -- resolves the public webhook URL for a newly added source so
+     * Resolves the public webhook URL for a newly added source so
      * `kici-admin source add` can print it. The rules per mode live in
      * `sources/webhook-url-resolvers.ts`.
      */
@@ -117,84 +101,78 @@ export interface AdminRouteDeps {
         sourceId: string;
     }) => Promise<WebhookUrlResolution>;
     /**
-     * Optional -- resolves the org-scoped GitHub webhook URL for the manifest
-     * setup pre-flight (before any App exists), by mode.
+     * Resolves the org-scoped GitHub webhook URL for the manifest setup
+     * pre-flight (before any App exists), by mode.
      */
     resolveGithubWebhookUrl?: () => Promise<WebhookUrlResolution>;
-    /** Optional — builds the direct-ingress URL `source list` prints per GitHub source. */
+    /** Builds the direct-ingress URL `source list` prints per GitHub source. */
     resolveSourceIngressUrl?: (row: {
         id: string;
         customerId: string | null;
     }) => string | null;
-    /** Optional -- for DB migration endpoints. */
+    /** Backs the DB migration endpoints. */
     db?: Kysely<any>;
-    /** Optional -- for DB migration endpoints. */
+    /** Backs the DB migration endpoints. */
     pool?: pg.Pool;
-    /** Optional -- for cluster join token creation. */
+    /** Backs cluster join token creation. */
     joinTokenManager?: JoinTokenManager;
-    /** Optional -- for secret backend management endpoints. */
+    /** Backs the secret backend management endpoints. */
     backendRegistry?: BackendRegistry;
-    /** Optional -- for secret backend health checking. */
     backendHealthChecker?: BackendHealthChecker;
-    /** Optional -- for secret backend scope sync. */
     backendSyncManager?: BackendSyncManager;
     /**
-     * Optional -- for `POST /api/v1/admin/rotate-key`.
-     *
-     * When set, `rotate-key` re-encrypts `config_versions` alongside
-     * `scoped_secrets` in two sequential transactions. When unset (e.g. a
-     * secret-store-only admin deployment), config rotation is skipped and the
+     * When set, `POST /api/v1/admin/rotate-key` re-encrypts `config_versions`
+     * alongside `scoped_secrets` in two sequential transactions. When unset (e.g.
+     * a secret-store-only admin deployment), config rotation is skipped and the
      * response reports `reEncryptedConfigs: 0`.
      */
     sharedStore?: SharedConfigStore;
     /**
-     * Optional -- the resolved master key, for `POST /api/v1/admin/rotate-key`.
-     *
-     * When set, `rotate-key` additionally sweeps the four remaining
+     * When set, `POST /api/v1/admin/rotate-key` also sweeps the remaining
      * master-key-wrapped stores: `orchestrator_signing_keys`,
-     * `dashboard_encryption_keys`, `run_ephemeral_keys` and `run_secret_outputs`.
+     * `dashboard_encryption_keys`, `run_ephemeral_keys`, `run_secret_outputs` and the
+     * sealed job secrets in `pending_job_contexts`.
      * When unset the secrets subsystem is off and there is nothing wrapped to
      * sweep, so those counts report 0.
      */
     masterKeys?: ResolvedMasterKeys | null;
     /**
-     * Optional -- attribution writer for routes that emit an `access_log`
-     * row directly (today: org-settings dashboard-write policy flips). When
-     * unset, those routes execute the mutation without recording — the
-     * write is best-effort, never gating.
+     * Attribution writer for routes that emit an `access_log` row directly
+     * (today: org-settings dashboard-write policy flips). When unset, those
+     * routes run the mutation without recording: the write is best-effort, never
+     * gating.
      */
     accessLog?: AccessLogWriter;
     /**
-     * Optional -- the coordinator's live-VM listing and stop, for this node or a
-     * `--target` peer. Backs `GET /api/v1/admin/scaler/orphans` and
+     * The coordinator's live-VM listing and stop, for this node or a `--target`
+     * peer. Backs `GET /api/v1/admin/scaler/orphans` and
      * `POST /api/v1/admin/scaler/orphans/stop` (`kici-admin scaler orphans`).
      * Bound by orchestrator-core once the cluster is up.
      */
     scalerOrphans?: ScalerOrphansRouteDeps;
     /**
-     * Optional -- reload the scaler config here and on every connected peer.
-     * Backs `POST /api/v1/admin/scaler/reload` (`kici-admin scaler reload`).
-     * Bound by orchestrator-core once the cluster is up.
+     * Reloads the scaler config here and on every connected peer. Backs
+     * `POST /api/v1/admin/scaler/reload` (`kici-admin scaler reload`). Bound by
+     * orchestrator-core once the cluster is up.
      */
     scalerReload?: ScalerReloadRouteDeps;
     /**
-     * Optional -- forget a departed peer here and on every connected sibling
-     * coordinator. Backs `POST /api/v1/admin/peers/forget` (`kici-admin peer
-     * forget`). Bound by orchestrator-core once the cluster is up.
+     * Forgets a departed peer here and on every connected sibling coordinator.
+     * Backs `POST /api/v1/admin/peers/forget` (`kici-admin peer forget`). Bound by
+     * orchestrator-core once the cluster is up.
      */
     peerForget?: PeerForgetRouteDeps;
     /**
-     * Optional -- the peer view behind
-     * `GET /api/v1/admin/cluster-settings/propagation` (the propagation section of
-     * `kici-admin cluster-settings show`). Bound by orchestrator-core once the
-     * cluster is up; the route is not mounted without it.
+     * The peer view behind `GET /api/v1/admin/cluster-settings/propagation` (the
+     * propagation section of `kici-admin cluster-settings show`). Bound by
+     * orchestrator-core once the cluster is up; the route is not mounted without it.
      */
     clusterSettingsPropagation?: ClusterSettingsPropagationSource;
     /**
-     * Optional -- fulfil deferred attestations on demand (mints in the running
-     * orchestrator process, which owns the Platform WS). Backs
-     * `POST /api/v1/admin/attestations/retry` (the `kici-admin attestations retry`
-     * command). Unset on a WS-only / non-coordinator admin.
+     * Fulfils deferred attestations on demand (mints in the running orchestrator
+     * process, which owns the Platform WS). Backs
+     * `POST /api/v1/admin/attestations/retry` (`kici-admin attestations retry`).
+     * Unset on a WS-only / non-coordinator admin.
      */
     retryAttestations?: (opts: {
         runId?: string;
@@ -205,19 +183,14 @@ export interface AdminRouteDeps {
         rejected: number;
     }>;
     /**
-     * Optional -- the resume wiring behind `kici-admin held-run approve|reject`.
-     * When set (alongside `db` + `accessLog`), the local held-run read and
-     * decision routes are mounted; they refuse with 409 on a Platform-attached
-     * orchestrator. Unset leaves them unmounted, which is the honest state for an
-     * app that cannot dispatch a released hold.
+     * The resume wiring behind `kici-admin held-run approve|reject`. When set
+     * (alongside `db` + `accessLog`), the local held-run read and decision routes
+     * are mounted; they refuse with 409 on a Platform-attached orchestrator. Unset
+     * leaves them unmounted, the honest state for an app that cannot dispatch a
+     * released hold.
      */
     heldRunRelease?: HeldRunReleaseWiring;
 }
-/**
- * Create admin API routes with Bearer token authentication and RBAC.
- *
- * @param deps - Admin route dependencies (token manager, RBAC, secret store, audit logger, etc.)
- * @returns Hono app with admin routes mounted at /api/v1/admin/*
- */
+/** Admin routes under /api/v1/admin/* (and /api/v1/agent-tokens), Bearer-authed with RBAC. */
 export declare function createAdminRoutes(deps: AdminRouteDeps): Hono<AdminEnv>;
 //# sourceMappingURL=admin.d.ts.map

package/dist/routes/caller-identity.d.ts

@@ -1,12 +1,9 @@
 /**
- * Caller identity for orchestrator HTTP routes that act on behalf of the
- * person or tool presenting a credential.
- *
- * Today the one credential is an admin token, resolved through the shared
- * bearer-auth boundary (`resolveBearerAuth`), so the 401 / 503 semantics are
- * identical to every admin route. The caller is a tagged union so a later
- * credential kind (a signed command, for one) joins as another variant without
- * touching the routes that consume it.
+ * Caller identity for HTTP routes acting for whoever presents a credential.
+ * The one credential is an admin token, resolved through `resolveBearerAuth`,
+ * so the 401 / 503 semantics match every admin route. The caller is a tagged
+ * union so another credential kind (e.g. a signed command) can join as a
+ * variant without touching the consuming routes.
  */
 import type { Context } from 'hono';
 import { type ActorPrincipal } from '@kici-dev/engine';
@@ -32,10 +29,6 @@ export type CallerOutcome = {
     error: string;
 };
 /**
- * Resolve the request's caller.
- *
- * @param c - The request context (the `Authorization` header is read).
- * @param deps - The token validator and log scope, as for `resolveBearerAuth`.
  * @param opts.requireUnscoped - Refuse a routing-key-scoped token with 403.
  *   Routes whose routing key the server chooses set it: a scoped token has no
  *   key of its own to compare there, so accepting it would widen its reach.

package/dist/routes/capabilities.d.ts

@@ -1,23 +1,18 @@
 /**
- * Orchestrator capability manifest exposed to REST clients (the CLI).
+ * `/capabilities`: a versioned manifest the CLI reads to format actionable
+ * errors on a feature gap (e.g. `kici status --logs` against an orchestrator
+ * without the logs endpoint). See `docs/architecture/coordinator-worker.md`
+ * for the minimum-version semantics this mirrors for the WS connections.
  *
- * The `/capabilities` endpoint returns a small versioned manifest the CLI can
- * read on demand to format actionable errors when it detects a feature gap
- * (e.g. `kici status --logs` against an orchestrator that lacks the logs
- * endpoint). See `docs/architecture/coordinator-worker.md` for the minimum-
- * version semantics this mirrors for the WS connections.
- *
- * Public (no auth) — same security posture as `/health`, which already exposes
- * the orchestrator's version. Version info must be reachable without a token
- * so the CLI can fetch it even when authenticated calls fail with 404/401.
+ * Public (no auth), like `/health`, which already exposes the version: the CLI
+ * must reach it even when authenticated calls fail with 404/401.
  */
 import { Hono } from 'hono';
 export interface CapabilitiesManifest {
-    /** Orchestrator package version (injected at build time). */
+    /** Injected at build time. */
     orchestratorVersion: string;
-    /** Protocol version the orchestrator speaks. */
     protocolVersion: number;
-    /** Minimum protocol version the orchestrator accepts from peers/clients. */
+    /** Minimum protocol version accepted from peers/clients. */
     minProtocolVersion: number;
 }
 export declare function createCapabilitiesRoutes(): Hono;

package/dist/routes/diagnostics.d.ts

@@ -1,16 +1,8 @@
 /**
- * Diagnostic health check HTTP endpoint.
- *
- * Provides GET /admin/diagnose for monitoring system integration.
- * Returns structured JSON with per-check results and overall status.
+ * GET /admin/diagnose for monitoring systems: structured JSON with per-check
+ * results and an overall status.
  */
 import { Hono } from 'hono';
 import type { DiagnosticDeps } from '../diagnostics/types.js';
-/**
- * Create diagnostic routes.
- *
- * @param deps - Dependencies for diagnostic checks
- * @returns Hono app with /admin/diagnose endpoint
- */
 export declare function createDiagnosticsRoutes(deps: DiagnosticDeps): Hono;
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/routes/fleet.d.ts

@@ -6,8 +6,7 @@
  * POST /admin/fleet-bundle     — drive the recursive fan-out and stream the
  *                               assembled nested ZIP back as an octet-stream.
  *
- * Both are protected by the same Bearer admin-token auth as the other admin
- * routes (token-manager validation).
+ * Both use the same Bearer admin-token auth as the other admin routes.
  */
 import { Hono } from 'hono';
 import type { TokenManager } from '../secrets/token-manager.js';

package/dist/routes/github-webhook.d.ts

@@ -5,11 +5,9 @@ import type { SourceStore } from '../sources/source-store.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import { type VerifyInboundDeps } from '../webhook/verify-inbound.js';
 import { WebhookIngestOutcome } from '../pipeline/process-webhook.js';
-/** Dependencies for the direct GitHub webhook ingress route. */
 export interface GithubWebhookRoutesDeps {
     /** Local source lookup (by UUID). */
     sourceStore: SourceStore;
-    /** Inbound verification deps (db + secret store + generic source manager). */
     verifyDeps: VerifyInboundDeps;
     /** Pipeline entry — owns the atomic dedup claim + dispatch. */
     onWebhook: (info: WebhookInfo) => Promise<WebhookIngestOutcome>;
@@ -19,9 +17,8 @@ export interface GithubWebhookRoutesDeps {
     maxGithubPayloadBytes?: number;
 }
 /**
- * Whether the orchestrator serves the direct GitHub ingress route for a given
- * operating mode. Hybrid, independent, and observed modes serve their own
- * ingress; platform mode is relay-only (no local GitHub source to serve).
+ * Hybrid, independent and observed modes serve their own GitHub ingress;
+ * platform mode is relay-only (no local GitHub source to serve).
  */
 export declare function shouldServeGithubIngress(mode: OrchestratorMode): boolean;
 /**

package/dist/routes/health.d.ts

@@ -1,38 +1,25 @@
 import { type BuildFingerprint } from '@kici-dev/shared';
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
-/**
- * The fields the orchestrator adds to its `/health` body. The route below
- * returns this type, and `kici-admin orchestrator status` renders it.
- */
+/** Fields the orchestrator adds to `/health`, rendered by `kici-admin orchestrator status`. */
 export interface OrchestratorLivenessInfo extends BuildFingerprint {
     /** ISO-8601 time the orchestrator bundle was built. */
     buildDate: string;
 }
 export interface HealthRoutesDeps {
-    /** Optional DB instance for readiness checks */
+    /** Enables the DB readiness check. */
     db?: Kysely<Database>;
     /**
-     * Optional warmth latch. Returns `true` only once the orchestrator boot
-     * sequence has finished (all subsystems started, HTTP server serving). When
-     * provided, `/ready` returns `503` until it flips `true`, so a caller can
-     * gate on the orchestrator being ready to serve rather than merely live.
-     * Absent → warm defaults to `true` (callers that don't wire the latch are
-     * unaffected).
+     * Warmth latch: `true` only once boot has finished (all subsystems started,
+     * HTTP server serving). When provided, `/ready` returns `503` until it flips,
+     * so a caller can gate on ready-to-serve rather than merely live. Absent →
+     * warm defaults to `true`.
      */
     isWarm?: () => boolean;
 }
 /**
- * Create orchestrator health routes with database readiness check.
- *
- * Delegates to the shared health route helper, providing
- * a database connectivity check as the readiness probe.
- *
  * - GET /health - Liveness probe (always 200)
  * - GET /ready  - Readiness probe (checks DB if provided)
- *
- * @param deps - Dependencies (optional database for readiness)
- * @returns Hono app with health routes
  */
 export declare function createHealthRoutes(deps?: HealthRoutesDeps): import("hono").Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
 //# sourceMappingURL=health.d.ts.map

package/dist/routes/provenance-oidc.d.ts

@@ -19,9 +19,9 @@ export interface ProvenanceOidcRoutesDeps {
     /** Whether orchestrator-owned signing is configured. */
     enabled: boolean;
     /**
-     * Dashboard-encryption key repo. When present, the JWKS additionally serves
-     * the non-revoked X25519 `use:'enc'` key(s) for browser-sealed dashboard
-     * writes (the Verified tier's trust root). Independent of provenance signing.
+     * When present, the JWKS also serves the non-revoked X25519 `use:'enc'` key(s)
+     * for browser-sealed dashboard writes (the Verified tier's trust root).
+     * Independent of provenance signing.
      */
     dashboardEncryptionRepo?: Pick<DashboardEncryptionKeyRepo, 'listNonRevoked'>;
 }