@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/routes/admin-event-dlq.d.ts

@@ -1,9 +1,7 @@
 /**
- * Admin API routes for the event DLQ (dead-letter queue).
- *
- * Exposes the orchestrator-side DLQ — events that exhausted their dispatch
- * retry budget — over Bearer-auth HTTP so operators can list, manually retry,
- * or discard rows from the kici-admin CLI / dashboard.
+ * Admin API for the event dead-letter queue (events that exhausted their
+ * dispatch retry budget), over Bearer-auth HTTP for the kici-admin CLI /
+ * dashboard.
  *
  *   GET    /api/v1/admin/event-dlq        — list DLQ events (limit + cursor)
  *   GET    /api/v1/admin/event-dlq/count  — number of DLQ events (for badge)

package/dist/routes/admin-event-inspect.d.ts

@@ -1,14 +1,13 @@
 /**
- * Admin API routes for inspecting internal events (`kici_events`).
- *
+ * Admin routes to inspect internal events (`kici_events`):
  *   GET /api/v1/admin/events      — list events, newest first (name, outcome, time filters)
  *   GET /api/v1/admin/events/:id  — one event: its payload and the runs it dispatched
  *
  * Each row carries its dispatch state (`pending`, `leased`, `retrying`,
  * `processed`, `dlq`) and, once processed, how the router resolved it
  * (`matched`, `no-target-repo`, …) with the number of workflows it reached.
- * Both routes need `event_dlq.read`, the permission that already gates reading
- * `kici_events` rows; the payload on `show` also needs
+ * Both routes need `event_dlq.read` (which gates reading `kici_events` rows);
+ * the payload on `show` also needs
  * `event_log.read_payload`. A routing-key-scoped token sees only events
  * emitted under its own key.
  */

package/dist/routes/admin-event-log.d.ts

@@ -1,11 +1,7 @@
 /**
  * Admin API routes for the inbound webhook delivery log (event_log table).
- *
- * Operator-facing read access to the per-delivery records the orchestrator
- * persists for every inbound webhook. Mirrors the dashboard's WS handler
- * (`DashboardHandler.handleEventLogList/Detail`) but is exposed over HTTP +
- * Bearer auth so operators can read it from the CLI without going through
- * the dashboard.
+ * Mirrors the dashboard's WS handler (`DashboardHandler.handleEventLogList/Detail`)
+ * over HTTP + Bearer auth, so operators can read it from the CLI.
  *
  *   GET /api/v1/admin/event-log
  *     Filters: orgId, routingKey, event, status, from, to, deliveryId, limit, offset
@@ -29,7 +25,7 @@ export interface AdminEventLogRoutesDeps {
     logStorage: LogStorage;
     tokenManager: TokenManager;
     rbac: RbacEnforcer;
-    /** Optional cold-store for archived event_log rows. */
+    /** Holds archived event_log rows. */
     coldStore?: ColdStore;
 }
 export declare function createAdminEventLogRoutes(deps: AdminEventLogRoutesDeps): Hono<AdminEnv>;

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

@@ -1,11 +1,7 @@
 /**
- * Admin API routes for generic webhook sources and trust management.
- *
- * Provides CRUD endpoints for managing generic webhook sources (create, list,
- * get, update, delete, enable, disable) and cross-repo trust relationships.
- *
- * All routes are protected by Bearer token authentication via the existing
- * admin auth middleware pattern from admin.ts.
+ * Admin API CRUD for generic webhook sources (create, list, get, update,
+ * delete, enable, disable) and cross-repo trust relationships. Every route
+ * requires Bearer token auth, the admin auth middleware pattern from admin.ts.
  */
 import { Hono } from 'hono';
 import type pg from 'pg';
@@ -24,11 +20,9 @@ interface AdminEventRouteDeps {
     tokenManager: TokenManager;
     rbac: RbacEnforcer;
     /**
-     * The in-process bundle registry. The POST /generic-sources handler
-     * registers a local / universal-git bundle into this registry
-     * immediately after the source row lands in the DB, so the next
-     * webhook against that source resolves the right normalizer without
-     * waiting for an orchestrator restart.
+     * POST /generic-sources registers a local / universal-git bundle here right
+     * after the row lands, so the next webhook resolves the right normalizer
+     * without an orchestrator restart.
      */
     providerRegistry: ProviderRegistry;
     /** Passed through to `registerProviderBundleForSource` (universal-git bundle
@@ -40,31 +34,23 @@ interface AdminEventRouteDeps {
     /** Fleet-wide settings reader; threads the live lock-file cap into newly-registered universal-git sources. */
     clusterSettings?: ClusterSettingsReader;
     /**
-     * The canonical Platform organization id this orchestrator authenticated
-     * as, or `undefined` when it is not Platform-connected (independent mode)
-     * or has not authenticated yet.
+     * The Platform org id this orchestrator authenticated as; `undefined` in
+     * independent mode or before authentication.
      *
-     * A generic source mints the routing key `generic:<orgId>:<id>`, and the
-     * Platform refuses to register a key naming an organization other than the
-     * authenticated one. So a source created under a mismatched org would
-     * register, be rejected, and silently never deliver — and its published
-     * webhook URL, which the Platform composes from the Platform org id, would
-     * 404. The create handler refuses the mismatch up front instead.
+     * A generic source mints `generic:<orgId>:<id>`, and the Platform refuses a
+     * key naming another org, so a mismatched source would silently never
+     * deliver and its webhook URL (composed from the Platform org id) would 404.
+     * The create handler refuses the mismatch up front.
      */
     getPlatformOrgId?: () => string | undefined;
     /**
-     * Optional — when provided, the `POST /api/v1/admin/events/emit` route is
-     * mounted so operators can INSERT into `kici_events` + `pg_notify` via HTTP.
-     * Mirrors `emitKiciEventDirect` in `@kici-dev/shared` (direct-DB CLI mode).
+     * When set, mounts `POST /api/v1/admin/events/emit` (INSERT into `kici_events`
+     * + `pg_notify` over HTTP). Mirrors `emitKiciEventDirect` in `@kici-dev/shared`
+     * (direct-DB CLI mode).
      */
     pool?: pg.Pool;
 }
-/**
- * Create admin API routes for generic webhook sources and trust management.
- *
- * @param deps - Admin event route dependencies
- * @returns Hono app with admin event routes mounted at /api/v1/admin/*
- */
+/** Routes mounted at /api/v1/admin/*. */
 export declare function createAdminEventRoutes(deps: AdminEventRouteDeps): Hono<AdminEnv>;
 export {};
 //# sourceMappingURL=admin-events.d.ts.map

package/dist/routes/admin-held-runs.d.ts

@@ -1,42 +1,36 @@
 /**
  * Admin API routes for reading and answering held runs.
  *
- * Exposes GET `/api/v1/admin/held-runs` and POST
- * `/api/v1/admin/held-runs/decision` so `kici-admin held-run list|approve|reject`
- * can release a hold locally, without a Platform.
+ * GET `/api/v1/admin/held-runs` and POST `/api/v1/admin/held-runs/decision` let
+ * `kici-admin held-run list|approve|reject` release a hold locally, without a Platform.
  *
- * **Independent orchestrators only.** Wherever a Platform is attached it owns
- * who may answer a hold: the Platform's held-run trust gate resolves the hold's
- * type and requires `ci_trust:write` for a security hold and `contexts:write` /
- * `contexts:admin` for the rest, against the acting member's org RBAC. This
- * route authenticates with an orchestrator admin token, which carries
- * orchestrator RBAC and no Platform membership at all — so answering a hold here
- * on a Platform-attached deployment would land a release the Platform's own gate
- * never authorized. Both write and read therefore refuse with 409 in
- * `platform` / `hybrid` / `observed`, mirroring the trust-policy write verbs.
+ * **Independent orchestrators only.** With a Platform attached, the Platform's
+ * held-run trust gate owns who may answer a hold: `ci_trust:write` for a security
+ * hold, `contexts:write` / `contexts:admin` for the rest, against the acting
+ * member's org RBAC. An orchestrator admin token carries no Platform membership,
+ * so answering here would land a release that gate never authorized. Both verbs
+ * therefore refuse with 409 in `platform` / `hybrid` / `observed`, mirroring the
+ * trust-policy write verbs.
  *
- * On an independent orchestrator there is no upstream authority, and until this
- * route existed an approval-queue hold there had no answer at all: `/kici
- * approve` releases the `security` queue only, and the dashboard, `kici
- * approve` and the MCP tools all reach the applier over the Platform relay.
+ * On an independent orchestrator this route is the only answer to an
+ * approval-queue hold: `/kici approve` releases the `security` queue only, and the
+ * dashboard, `kici approve` and the MCP tools reach the applier over the Platform relay.
  *
- * Answering goes through the shared `applyDecision` applier, not through a
- * direct row flip, so an approve here obeys the hold's own
- * `approval_requirement` clauses, records a `held_run_approvals` row, and — this
- * is the part a row flip silently skips — resumes the held element through
- * `routeRelease`, which re-dispatches the job or replays the workflow dispatch.
+ * Answering goes through the shared `applyDecision` applier, not a direct row
+ * flip, so an approve obeys the hold's `approval_requirement` clauses, records a
+ * `held_run_approvals` row, and resumes the held element through `routeRelease`
+ * (re-dispatch the job or replay the workflow dispatch) — the part a row flip skips.
  *
- * The resume runs AFTER this route answers. The decision is durable at the
- * applier's own transaction, and the resume it triggers is unbounded work whose
- * latency has no business being the operator's — see
- * `ApplyDecisionResult.consequence`. The access-log entry is written when that
- * consequence settles, so a resume that failed is recorded as `error` with its
- * message rather than being lost behind a successful-looking answer.
+ * The resume runs AFTER this route answers: the decision is durable at the
+ * applier's transaction, and the resume is unbounded work whose latency must not
+ * be the operator's (see `ApplyDecisionResult.consequence`). The access-log entry
+ * is written when that consequence settles, so a failed resume is recorded as
+ * `error` with its message, not hidden behind a successful-looking answer.
  *
  * Releasing a hold lets the held work RUN; it does not make its contributor
- * trusted. The resumed dispatch replays the trust resolution the hold was
- * created under, so an untrusted fork PR still runs with the base-branch lock
- * file, no install/registry secrets, and an isolated cache write scope.
+ * trusted. The resumed dispatch replays the hold's trust resolution, so an
+ * untrusted fork PR still runs with the base-branch lock file, no
+ * install/registry secrets, and an isolated cache write scope.
  */
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
@@ -50,43 +44,32 @@ import type { AccessLogWriter } from '../audit/access-log.js';
 import type { Database, HeldRun } from '../db/types.js';
 import { type AdminEnv } from './admin-env.js';
 /**
- * Wording for the Platform-managed refusal, surfaced verbatim by the CLI.
- *
- * It names the surfaces that DO answer a hold on a Platform-attached
- * orchestrator, because "not here" without "there instead" is the refusal an
- * operator reads as a broken build.
+ * Platform-managed refusal, surfaced verbatim by the CLI. It names the surfaces
+ * that DO answer the hold, because "not here" without "there instead" reads as a
+ * broken build.
  */
 export declare const PLATFORM_MANAGED_HELD_RUN_MESSAGE: string;
 /**
- * Wording for the step-scope refusal.
- *
- * A step-scoped hold is answered by notifying the waiting agent through the
- * step-approval bridge, which an independent orchestrator does not wire — so
- * this route has no way to tell the agent. Flipping the row anyway would be
- * strictly worse than refusing: the agent would keep waiting while the row left
- * `pending`, putting it beyond the stale detector's expiry sweep, so the step
- * would block with nothing left to release OR expire it.
+ * Step-scope refusal. A step-scoped hold is answered through the step-approval
+ * bridge, which an independent orchestrator does not wire. Flipping the row
+ * anyway is worse than refusing: the agent keeps waiting while the row leaves
+ * `pending`, beyond the stale detector's expiry sweep, so nothing can release
+ * OR expire the step.
  */
 export declare const STEP_SCOPE_UNSUPPORTED_MESSAGE: string;
 /**
- * Wording for an `--as` id the approval directory does not hold.
- *
- * The directory is the enumerable set of subjects this route will answer as. An
- * id it does not carry is refused rather than passed through, because an
- * unvalidated approver subject is free text: it would let an operator token
- * write any string it liked into `held_run_approvals.approver_user_id` and
- * satisfy any `{user}` clause by naming it.
+ * Refusal for an `--as` id the approval directory does not hold. The directory is
+ * the enumerable set of subjects this route answers as; an unvalidated subject is
+ * free text that would let an operator token write any string into
+ * `held_run_approvals.approver_user_id` and satisfy any `{user}` clause by naming it.
  */
 export declare function unregisteredApproverMessage(userId: string): string;
 /** The release wiring the applier needs to actually resume a released element. */
 export interface HeldRunReleaseWiring {
     /**
-     * Re-dispatch a job-scoped release.
-     *
-     * REQUIRED, and the mount is conditional on it. A release path that flips the
-     * row without dispatching looks like it works and does nothing — the hold
-     * reads `approved`, the job never starts, and no sweep will ever look at the
-     * row again.
+     * Re-dispatch a job-scoped release. REQUIRED, and the mount is conditional on
+     * it: flipping the row without dispatching leaves the hold `approved`, the job
+     * never started, and no sweep ever looking at the row again.
      */
     onJobRelease: (signal: ReleaseSignal) => Promise<void>;
     /** Replay the stored dispatch context of a released workflow-scoped hold. */
@@ -101,41 +84,34 @@ export interface HeldRunReleaseWiring {
     resolveCheckStatusPoster?: ResolveCheckStatusPoster;
 }
 export interface HeldRunRouteDeps {
-    /** The held-run store the decision is applied through. */
     store: HeldRunStore;
     /**
-     * The org approval directory — the only place an independent orchestrator
-     * holds team membership, and therefore the only thing that can satisfy a
-     * `{team}` clause on a hold's requirement.
+     * The org approval directory — the only team membership an independent
+     * orchestrator holds, so the only thing that can satisfy a `{team}` clause.
      */
     directory: TrustDirectoryStore;
     /**
-     * Orchestrator database, for the two per-decision reads the applier needs
-     * that no store owns: `org_settings.allow_self_approval` and the run's
-     * triggerer.
+     * For the per-decision reads no store owns: `org_settings.allow_self_approval`
+     * and the run's triggerer.
      */
     db: Kysely<Database>;
     rbac: RbacEnforcer;
-    /** This orchestrator's mode; decides whether either verb is permitted at all. */
+    /** Decides whether either verb is permitted at all. */
     mode: OrchestratorMode;
     /**
-     * Audit sink, REQUIRED for the same reason the trust-policy route's is: the
-     * guarantee this route makes is that a locally-answered hold is always
-     * attributable, and an optional sink would leave that resting on every
-     * construction site remembering to pass one.
+     * REQUIRED, as on the trust-policy route: a locally-answered hold is always
+     * attributable, and an optional sink would rest that on every construction
+     * site remembering to pass one.
      */
     accessLog: AccessLogWriter;
     release: HeldRunReleaseWiring;
 }
 /**
- * The approval subject for a decision taken through an admin token.
- *
- * Namespaced `service:<token user id>`, matching how the dashboard applier
- * derives a subject for a service-account actor. The namespace is what keeps it
- * from ever colliding with a Keycloak sub named by an `approvers:` clause: an
- * operator token answers as itself, never as a person it typed the name of.
- * `held_run_approvals.approver_user_id` is the record of who approved, and a
- * subject the operator merely asserted would make that record false.
+ * Approval subject for an admin-token decision: `service:<token user id>`, as the
+ * dashboard applier derives for a service-account actor. The namespace keeps it
+ * from colliding with a Keycloak sub named by an `approvers:` clause: an operator
+ * token answers as itself, never as a person it typed, so
+ * `held_run_approvals.approver_user_id` stays a true record of who approved.
  *
  * Re-exported from the shared subject module so this route and the dashboard
  * handler cannot drift into two `service:` namespaces.

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

@@ -1,16 +1,13 @@
 /**
- * Admin API routes for ops-grade maintenance operations that don't fit
- * cleanly under a single resource namespace:
+ * Admin maintenance operations that span resource namespaces:
  *
  *   POST /api/v1/admin/queue/clear             — TRUNCATE dispatch_queue
  *   POST /api/v1/admin/execution/purge-stale   — DELETE execution runs + jobs
  *   POST /api/v1/admin/sources/purge-stale     — DELETE orphan sources + scoped secrets
  *   POST /api/v1/admin/secrets/purge           — DELETE scoped_secrets (bulk)
  *
- * Each endpoint accepts a minimal JSON body for scoping (e.g. routing key,
- * org ID) and supports a "dry run" mode where applicable. All mutations are
- * gated by the admin auth middleware in admin.ts, so unauthenticated access
- * is impossible.
+ * Each takes a minimal JSON scoping body (routing key, org ID), with a dry run
+ * where applicable. All are gated by the admin auth middleware in admin.ts.
  */
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';

package/dist/routes/admin-orchestrator-drain.d.ts

@@ -1,6 +1,4 @@
 /**
- * Orchestrator drain admin routes.
- *
  * Backs the `kici-admin orchestrator drain` / `resume` / `drain --status`
  * verbs used to quiesce a coordinator before an upgrade. Mounted inside
  * `createAdminRoutes` at `/api/v1/admin/orchestrator/drain`, so it inherits the

package/dist/routes/admin-org-settings.d.ts

@@ -1,13 +1,10 @@
 /**
- * Admin API routes for org-level global workflow settings.
+ * GET / PATCH `/api/v1/admin/org-settings/global-workflows`: lets `kici-admin`
+ * read and write the per-org `org_settings` row without the Platform dashboard
+ * proxy, so the CLI stays operable when the Platform is unavailable.
  *
- * Exposes GET / PATCH `/api/v1/admin/org-settings/global-workflows` so
- * `kici-admin` can read and write the per-org row in `org_settings`
- * without going through the Platform dashboard proxy — the CLI stays
- * operable even when Platform is unavailable.
- *
- * Mutations require the `secret.write` RBAC capability (already granted to
- * admin / owner roles), matching the gating posture used by source admin.
+ * Mutations require `secret.write` (granted to admin / owner), matching the
+ * gating used by source admin.
  */
 import { Hono } from 'hono';
 import { type Kysely } from 'kysely';
@@ -26,18 +23,15 @@ interface OrgSettingsRouteDeps {
      */
     globalWorkflowsEnabledDefault: boolean;
     /**
-     * This orchestrator's mode.
-     *
      * The dashboard-write policy needs it: disabling `held_runs.approve` /
      * `held_runs.reject` is coherent only where `kici-admin held-run` can still
      * answer a hold, which is independent mode alone.
      */
     mode: OrchestratorMode;
     /**
-     * Optional — when wired, each `dashboard_write_policy` flip emits one
-     * `access_log` row (`org_settings.dashboard_write_policy.update`)
-     * carrying the operation name + prior/next state in `actor_meta`.
-     * Reset calls additionally stamp `reset: true`.
+     * When wired, each `dashboard_write_policy` flip emits one `access_log` row
+     * (`org_settings.dashboard_write_policy.update`) carrying the operation name
+     * + prior/next state in `actor_meta`; reset calls also stamp `reset: true`.
      */
     accessLog?: AccessLogWriter;
 }

package/dist/routes/admin-peer-forget.d.ts

@@ -18,7 +18,6 @@ import type { AccessLogWriter } from '../audit/access-log.js';
 import { type PeerForgetResult } from '../cluster/peer-forget.js';
 import type { RbacEnforcer } from '../secrets/rbac.js';
 import { type AdminEnv } from './admin-env.js';
-/** What the route needs from the coordinator it runs on. */
 export interface PeerForgetRouteDeps {
     /**
      * Forget `instanceId` here, then on every connected sibling coordinator

package/dist/routes/admin-queue-execution.d.ts

@@ -1,13 +1,13 @@
 /**
- * Admin API routes for queue + execution READ operations (5a #3 /).
+ * Admin API routes for queue + execution READ operations.
  *
  *   GET /api/v1/admin/queue                   — list dispatch_queue
  *   GET /api/v1/admin/queue/:id               — show one dispatch_queue row
  *   GET /api/v1/admin/executions              — list execution_runs
  *   GET /api/v1/admin/executions/:runId       — show one run + its jobs
  *
- * All routes are gated by the admin auth middleware mounted in admin.ts
- * and require `secret.read` RBAC (the closest existing read-grade permission).
+ * Gated by the admin auth middleware in admin.ts; each requires `secret.read`
+ * RBAC (the closest existing read-grade permission).
  */
 import { Hono } from 'hono';
 import { type Kysely } from 'kysely';

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

@@ -1,9 +1,6 @@
 /**
- * Admin API routes for workflow registration management.
- *
- * Provides endpoints for listing, inspecting, refreshing, disabling and
- * deleting workflow registrations. All routes are protected by Bearer token
- * authentication via the existing admin auth middleware pattern.
+ * Admin routes to list, inspect, refresh, disable and delete workflow
+ * registrations, all behind the shared admin Bearer auth middleware.
  */
 import { Hono } from 'hono';
 import type { RegistrationStore } from '../registration/registration-store.js';
@@ -18,18 +15,12 @@ export interface AdminRegistrationRoutesDeps {
     tokenManager: TokenManager;
     rbac: RbacEnforcer;
     /**
-     * Resolves a bound environment by name for registration-time satisfiability.
      * When present, a manual registration is rejected up front if a job binds a
      * provably-unsatisfiable environment list (missing/disabled env, or
      * mutually-exclusive fixed branch/trigger/repo restrictions).
      */
     contextStore?: Pick<ContextStore, 'matchContext'>;
 }
-/**
- * Create admin API routes for workflow registration management.
- *
- * @param deps - Admin registration route dependencies
- * @returns Hono app with registration routes mounted at /api/v1/admin/registrations
- */
+/** Routes mounted at /api/v1/admin/registrations. */
 export declare function createAdminRegistrationRoutes(deps: AdminRegistrationRoutesDeps): Hono<AdminEnv>;
 //# sourceMappingURL=admin-registrations.d.ts.map

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

@@ -1,22 +1,18 @@
 /**
- * Admin API routes for execution run inspection.
- *
- * Provides read-only endpoints for listing runs and inspecting per-run
- * sub-resources (jobs, ephemeral key status, secret outputs). All routes
- * are protected by Bearer token authentication and an RBAC permission
- * check (`run.read` for most, `secret.reveal` for the reveal variant of
- * `secret-outputs`).
+ * Read-only admin API for execution runs and their sub-resources. Every route
+ * requires a Bearer token and an RBAC permission: `run.read`, plus
+ * `secret.reveal` for the reveal variant of `secret-outputs`.
  *
  * Endpoints:
  *   GET /api/v1/admin/runs                        — list runs with filters
  *   GET /api/v1/admin/runs/:runId                 — run header fields only
  *   GET /api/v1/admin/runs/:runId/jobs            — jobs list (optional steps)
+ *   GET /api/v1/admin/runs/:runId/structured      — aggregated run detail
+ *   GET /api/v1/admin/runs/:runId/jobs/:jobId/steps/:stepIndex/logs — step logs
  *   GET /api/v1/admin/runs/:runId/ephemeral-key   — scrub status
  *   GET /api/v1/admin/runs/:runId/secret-outputs  — masked by default; ?reveal=true
  *
- * This is the server-side counterpart to `kici-admin runs`, which replaces
- * hand-rolled curl commands and dashboard clicks when verifying execution
- * state.
+ * Server side of `kici-admin runs`.
  */
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
@@ -28,12 +24,10 @@ import type { ResolvedMasterKeys } from '../secrets/config.js';
 import type { LogStorage } from '../reporting/log-storage.js';
 import { type AdminEnv } from './admin-env.js';
 /**
- * Statuses accepted by the `?status=` filter.
- *
- * The full canonical union rather than just `ExecutionRunStatus.options`: only
- * run statuses can appear in `execution_runs.status`, but the job-only members
- * were accepted before and match no row, so keeping them avoids turning
- * an empty result into a rejected request.
+ * Statuses accepted by the `?status=` filter: the full canonical union, not
+ * just `ExecutionRunStatus.options`. Job-only members match no
+ * `execution_runs` row but stay accepted, so such a filter returns an empty
+ * result rather than a rejected request.
  */
 export declare const RUN_STATUSES: ReadonlySet<string>;
 export interface AdminRunRoutesDeps {
@@ -43,24 +37,17 @@ export interface AdminRunRoutesDeps {
     /** Required to reveal secret-output plaintext via ?reveal=true. */
     auditLogger?: AuditLogger;
     /**
-     * The orchestrator master key, plus the previous generation during a
-     * rotation grace window. Required to reveal secret-output plaintext; a row
-     * still sealed under the old key reveals until `rotate-key` has swept the
-     * table.
+     * The master key, plus the previous generation during a rotation grace
+     * window. Required to reveal secret-output plaintext; a row still sealed
+     * under the old key reveals until `rotate-key` has swept the table.
      */
     masterKeys?: ResolvedMasterKeys | null;
     /**
-     * Log storage backend. Required only by the agent step-logs endpoint
-     * (`/runs/:runId/jobs/:jobId/steps/:stepIndex/logs`); when absent, that
-     * path 503s cleanly.
+     * Required only by the step-logs endpoint
+     * (`/runs/:runId/jobs/:jobId/steps/:stepIndex/logs`), which 503s without it.
      */
     logStorage?: LogStorage;
 }
-/**
- * Create admin API routes for execution run inspection.
- *
- * @param deps - Admin run route dependencies
- * @returns Hono app with run routes mounted at /api/v1/admin/runs
- */
+/** Run routes, mounted at /api/v1/admin/runs. */
 export declare function createAdminRunRoutes(deps: AdminRunRoutesDeps): Hono<AdminEnv>;
 //# sourceMappingURL=admin-runs.d.ts.map

package/dist/routes/admin-scaler-orphans.d.ts

@@ -12,9 +12,10 @@
  *   stop the approved VMs nothing tracks (`scaler.manage`).
  *
  * The node is this coordinator, or the peer `target` names, reached over the
- * authenticated peer channel. The coordinator adds the one tracker only it
- * can answer — a non-terminal job in its dispatch queue bound to the VM's
- * agent — and never forwards a bound VM to the node's stop.
+ * authenticated peer channel. The coordinator adds the trackers only it can
+ * answer — a non-terminal job in its dispatch queue bound to the VM's agent,
+ * and the agent registered with it or a peer — and never forwards a VM either
+ * tracker covers to the node's stop.
  */
 import { Hono } from 'hono';
 import { type PeerScalerOrphansResponse } from '@kici-dev/engine';
@@ -23,7 +24,6 @@ import type { RbacEnforcer } from '../secrets/rbac.js';
 import { type ScalerOrphansAnswer, type ScalerOrphansRequest } from '../scaler/orphan-requests.js';
 import { ScalerOrphansForwardFailure } from '../cluster/scaler-orphans-peer.js';
 import { type AdminEnv } from './admin-env.js';
-/** What the routes need from the coordinator they run on. */
 export interface ScalerOrphansRouteDeps {
     /** This coordinator's instance id. */
     instanceId: string;

package/dist/routes/admin-scaler-reload.d.ts

@@ -1,9 +1,8 @@
 /**
  * Reload the scaler config, behind `kici-admin scaler reload`.
  *
- * Mounted inside `createAdminRoutes` at `/api/v1/admin`, so the Bearer-token
- * auth middleware has already resolved the caller's role. Needs an unscoped
- * token and the `scaler.manage` permission (owner, admin).
+ * Mounted inside `createAdminRoutes` at `/api/v1/admin`, behind its Bearer-token
+ * auth. Needs an unscoped token and `scaler.manage` (owner, admin).
  *
  * - `POST /api/v1/admin/scaler/reload { single?, timeoutMs? }` — re-read the
  *   scaler config on this orchestrator and, unless `single`, on every peer it
@@ -12,16 +11,14 @@
  *   one first: `200` when no instance refused its file or went unanswered,
  *   `422` otherwise.
  *
- * The route runs the scaler reload only: it does not reload the orchestrator
- * config, so it never bumps the config version the peers follow, and a
- * `single` reload stays on this orchestrator.
+ * It never reloads the orchestrator config, so it never bumps the config
+ * version the peers follow, and a `single` reload stays on this orchestrator.
  */
 import { Hono } from 'hono';
 import { type ScalerReloadInstanceResult } from '@kici-dev/engine';
 import type { AccessLogWriter } from '../audit/access-log.js';
 import type { RbacEnforcer } from '../secrets/rbac.js';
 import { type AdminEnv } from './admin-env.js';
-/** What the route needs from the orchestrator it runs on. */
 export interface ScalerReloadRouteDeps {
     /** This orchestrator's instance id, the audit row's target. */
     instanceId: string;
@@ -31,7 +28,7 @@ export interface ScalerReloadRouteDeps {
      */
     reload: (single: boolean, timeoutMs: number) => Promise<ScalerReloadInstanceResult[]>;
 }
-/** How long the route waits for each peer by default. */
+/** Default wait per peer. */
 export declare const DEFAULT_SCALER_RELOAD_TIMEOUT_MS = 60000;
 export declare function createScalerReloadRoutes(deps: {
     scalerReload: ScalerReloadRouteDeps;

package/dist/routes/admin-scheduled-jobs.d.ts

@@ -9,10 +9,9 @@
  * Use it, for example, to force a cold-store-archive tick without waiting
  * for the hourly cadence.
  *
- * The access_log row is written directly (not via the typed
- * AccessLogWriter) because `scheduled_job.trigger` is not in the
- * protocol-level AccessLogAction enum — matching the pattern the
- * scheduler wrapper itself uses for `scheduled_job.tick` failure rows.
+ * The access_log row is written directly, not via the typed AccessLogWriter,
+ * because `scheduled_job.trigger` is not in the protocol-level AccessLogAction
+ * enum; the scheduler wrapper does the same for `scheduled_job.tick` failures.
  */
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';