@kici-dev/orchestrator 0.1.27 → 0.3.0

package/dist/__test-helpers__/mock-db.d.ts

@@ -28,6 +28,8 @@ export interface MockDbOptions {
     insertReturning?: unknown;
     /** Row returned by update chains ending in .returningAll().executeTakeFirstOrThrow() or executeTakeFirst(). Default: undefined */
     updatedRow?: unknown;
+    /** Rows returned by update chains ending in .returningAll().execute(). Default: [] */
+    updatedRows?: unknown[];
     /** Row returned by update chains ending in .returning(...).executeTakeFirst(). Default: undefined */
     updateReturning?: unknown;
     /** Result for update .execute() calls. Default: { numUpdatedRows: 0n } */

package/dist/agent/dispatcher.d.ts

@@ -1,7 +1,14 @@
 import type { AgentRegistry } from './registry.js';
 import { type JobQueue, type QueuedJob, type QueuedJobInput } from '../queue/job-queue.js';
-import type { ScaleResult } from '../scaler/types.js';
+import type { ScaleResult, ScalerRedispatchTrigger } from '../scaler/types.js';
 import type { ResourceRequest } from '@kici-dev/engine';
+/**
+ * Default per-pass cap on how many pending jobs a capacity-freed re-drive
+ * re-offers to the scaler. Bounds the burst so a single free event cannot storm
+ * the scaler; the per-backend spawn semaphore bounds actual provisioning, and a
+ * job that gets `at-capacity` again simply stays pending for the next tick.
+ */
+export declare const DEFAULT_REDRIVE_BATCH = 10;
 /**
  * Metrics interface for dispatch operations.
  * Allows the dispatcher to update Prometheus counters without
@@ -12,6 +19,8 @@ export interface DispatchMetrics {
     incJobsDispatched(status: 'dispatched' | 'queued' | 'rejected'): void;
     /** Set the queue depth gauge. */
     setQueueDepth(depth: number): void;
+    /** Record `count` pending jobs re-driven through the scaler by `trigger`. */
+    incScalerRedispatch(trigger: ScalerRedispatchTrigger, count: number): void;
 }
 /**
  * Narrow slice of `HostRosterStore` the dispatcher needs for the host-restart
@@ -27,6 +36,12 @@ export interface HostRosterRebootStore {
 }
 /**
  * Result of a dispatch attempt.
+ *
+ * `duplicate` = the dispatch_queue row for a preassigned (rerouted) jobId
+ * already existed, so nothing was dispatched here (the claimed agent slot is
+ * released and onDispatch is NOT called). The reroute caller should treat the
+ * job as already handled. Only reachable on a reroute re-dispatch — first-
+ * dispatch paths use a fresh UUID that can never collide.
  */
 type DispatchResult = {
     status: 'dispatched';
@@ -38,6 +53,9 @@ type DispatchResult = {
 } | {
     status: 'queued-no-backend';
     jobId: string;
+} | {
+    status: 'duplicate';
+    jobId: string;
 } | {
     status: 'rejected';
     reason: string;
@@ -60,6 +78,13 @@ export declare class Dispatcher {
     private readonly metrics;
     private readonly onDispatch;
     private readonly onNoMatchingAgent?;
+    /**
+     * Single-flight guard for `retryPendingScaleRequests`. The capacity-freed
+     * hook and the leader-gated sweep can both fire concurrently; this prevents
+     * two re-drives from double-offering the same pending jobs to the scaler in
+     * the same tick.
+     */
+    private redriveInFlight;
     /**
      * Tracks which jobs are dispatched to which agents.
      * Used for marking jobs as failed on agent disconnect.
@@ -134,6 +159,9 @@ export declare class Dispatcher {
     private get gracePeriodMs();
     /** Host roster store for the reboot-pending gate; undefined ⇒ flow inert. */
     private readonly rosterStore?;
+    /** Coordinator drain predicate; when true, new jobs queue Pending instead of
+     *  dispatching. Defaults to never-draining. */
+    private readonly isDraining;
     constructor(deps: {
         registry: AgentRegistry;
         queue: JobQueue;
@@ -142,7 +170,7 @@ export declare class Dispatcher {
         /** Optional hook called when no agent matches the job's labels.
          *  When set, receives the per-job `resources` so the scaler can apply
          *  per-scaler / per-orchestrator / per-machine caps before spawning. */
-        onNoMatchingAgent?: (labels: string[], jobId: string, runId: string, excludeLabels: string[], resources?: ResourceRequest) => Promise<ScaleResult>;
+        onNoMatchingAgent?: (labels: string[], jobId: string, runId: string, excludeLabels: string[], resources?: ResourceRequest, orgId?: string) => Promise<ScaleResult>;
         /** Max reconnection delay from agent config (default 60s). Used to derive grace period. */
         maxReconnectDelayMs?: number;
         /** Callback fired when a job is permanently failed before/outside agent execution. */
@@ -161,6 +189,10 @@ export declare class Dispatcher {
          * reboot-pending behavior is inert (every host reads not-pending).
          */
         rosterStore?: HostRosterRebootStore;
+        /** Coordinator drain predicate. When true, dispatch() enqueues new jobs as
+         *  Pending and onAgentAvailable() claims nothing — jobs already on agents
+         *  finish. Defaults to never-draining. */
+        isDraining?: () => boolean;
     });
     /**
      * Dispatch a job to a matching agent, or queue it if none available.
@@ -172,6 +204,24 @@ export declare class Dispatcher {
      * 4. If queue full: return 'rejected'.
      */
     dispatch(job: QueuedJobInput): Promise<DispatchResult>;
+    /**
+     * Re-drive the scaler for jobs still pending after an `at-capacity` verdict.
+     *
+     * Called by the capacity-freed hook (`ScalerManager.onCapacityFreed`) and the
+     * leader-gated `PendingScaleSweeper`. Lists the oldest pending jobs (FIFO
+     * fairness — the longest-waiting burst victim gets the freed slot first) and
+     * re-runs the SAME `onNoMatchingAgent` → `requestScale` path used at dispatch
+     * time, so the re-drive inherits the per-backend spawn semaphore and cap
+     * accounting. A job that returns `at-capacity` again just stays pending for
+     * the next free/sweep tick — no retry state, no backoff bookkeeping.
+     *
+     * Single-flight: a second call while one is in flight returns 0, so an
+     * overlapping hook+sweep cannot double-offer the same jobs. Bounded by
+     * `maxJobs` so one free event cannot storm the scaler.
+     *
+     * @returns the number of jobs that entered `spawning`.
+     */
+    retryPendingScaleRequests(maxJobs?: number, trigger?: ScalerRedispatchTrigger): Promise<number>;
     /**
      * Dispatch a host-fanout pinned child. The job targets exactly
      * `job.pinnedAgentId`: if that agent is locally connected, satisfies the

package/dist/agent/host-roster-reaper.d.ts

@@ -31,8 +31,7 @@ export declare class HostRosterReaper {
     private readonly scanIntervalMs;
     private readonly setUnreachableGauge;
     private readonly rebootSweep;
-    private timer;
-    private isLeader;
+    private readonly scheduler;
     constructor(opts: HostRosterReaperOptions);
     onBecomeLeader(): void;
     onLoseLeadership(): void;

package/dist/agent/host-roster.d.ts

@@ -3,6 +3,22 @@ import { type HostInventoryEntry, type InventorySelector, type LabelMatcher } fr
 import type { Database, HostRosterRow } from '../db/types.js';
 /** Typed host-vars bag carried by roster rows (`string | number | boolean`). */
 export type HostProperties = Record<string, string | number | boolean>;
+/**
+ * Reserved `host_properties` key holding the self-contained agent-payload version
+ * the orchestrator last staged onto a host. Read by the fleet-convergence gate;
+ * the `kici:` namespace is orchestrator-reserved so an agent never reports it.
+ */
+export declare const STAGED_AGENT_VERSION_KEY = "kici:staged-agent-version";
+/**
+ * Drop every orchestrator-reserved `kici:`-namespaced key from an
+ * agent-reported host-property bag. Agent-reported properties win the roster
+ * shallow-merge, so without this an agent could FORGE reserved keys the
+ * orchestrator trusts — the staged-version convergence gate and the
+ * root-executed restart commands both read `kici:` keys. Only orchestrator
+ * writes (`recordStagedVersion`) and operator declares (`declareStatic`) set
+ * this namespace; a registering agent never may.
+ */
+export declare function stripReservedProperties(props: HostProperties): HostProperties;
 /**
  * Pre-agent reach metadata for a declared host — how to SSH to it for bootstrap
  * bring-up before it has a KiCI agent. All fields nullable: a host with no reach
@@ -15,6 +31,12 @@ export interface HostReach {
     sshUser: string | null;
     sshPort: number | null;
     sshKeySecret: string | null;
+    /**
+     * When true, the box can reach the orchestrator's object storage — bring-up
+     * picks the `s3-direct` delivery mode (box pulls the payload via a presigned
+     * URL). NULL / false ⇒ the conservative `ssh-push` fallback.
+     */
+    s3Reachable: boolean | null;
 }
 /**
  * Derived (read-time) status of a roster host. Never a stored mutable column:
@@ -131,6 +153,7 @@ export declare class HostRosterStore {
         sshUser?: string;
         sshPort?: number;
         sshKeySecret?: string;
+        s3Reachable?: boolean;
     }): Promise<{
         created: boolean;
     }>;
@@ -140,6 +163,17 @@ export declare class HostRosterStore {
      */
     getReach(agentId: string): Promise<HostReach | null>;
     get(agentId: string): Promise<HostRosterRow | null>;
+    /**
+     * Record the self-contained agent-payload version the orchestrator staged onto
+     * a host (bring-up or fleet re-stage). Stored in `host_properties` under a
+     * reserved key so the convergence gate can compare it against the target
+     * INDEPENDENTLY of the agent's own self-reported bundle version (two payloads
+     * can carry the same self-report but different staged keys). Shallow-merged, so
+     * it survives agent re-register (the agent never reports this reserved key).
+     */
+    recordStagedVersion(agentId: string, version: string): Promise<void>;
+    /** Read a host's recorded staged agent-payload version, or null when never staged. */
+    getStagedVersion(agentId: string): Promise<string | null>;
     listAll(): Promise<HostRosterRow[]>;
     /**
      * Resolve every roster host matching a `runsOnAll` predicate (OR-of-AND

package/dist/agent/ownership-refusal.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The single refusal wording sent to an agent whose job-scoped frame was not
+ * accepted on ownership grounds.
+ *
+ * Deliberately identical whether the database decided "not owned" or could not
+ * decide at all. A caller that could tell the two apart would hold an oracle for
+ * job existence, upload-commit state, and orchestrator database health — so the
+ * two cases are indistinguishable on the wire, and the distinction lives only in
+ * the orchestrator's own logs.
+ */
+export declare const OWNERSHIP_REFUSED = "this job is not owned by this agent";
+//# sourceMappingURL=ownership-refusal.d.ts.map

package/dist/agent/ownership-tracker.d.ts

@@ -10,21 +10,40 @@
  * - Violation counting with sliding window (default: 5 violations in 60s)
  * - Escalation: disconnect agent after threshold violations
  */
+/**
+ * Verdict of the DB-backed ownership lookup.
+ *
+ * `unknown` is the load-bearing member: it separates "the database says this
+ * agent does not own the job" (evidence of a misrouted or spoofed frame) from
+ * "the lookup could not be answered" (a query failure or a timeout). Only the
+ * former is a violation — counting an unanswerable check as evidence would let
+ * one transient database outage disconnect every connected agent at once.
+ */
+export type OwnershipDbResult = 'owned' | 'not-owned' | 'unknown';
+/** Deadline for a single DB-backed ownership lookup before it resolves `unknown`. */
+export declare const DEFAULT_OWNERSHIP_DB_CHECK_TIMEOUT_MS = 5000;
 interface OwnershipTrackerOpts {
     /** Check if a job is owned by the given agent (active or in grace window). */
     isJobOwnedByAgent: (agentId: string, jobId: string) => boolean;
     /**
-     * Optional DB-backed fallback. Returns true when the orchestrator
-     * DB shows the (agent, job) pair as previously owned by this coord
-     * OR a sibling coord — i.e. either currently `dispatched`/`recovering`
-     * with the same `agent_id` / `recovery_agent_id`, or recently
-     * `completed`/`failed`. When a Raft leader switch wipes the
-     * in-memory `agentJobs` Map on the replacement coord, this fallback
-     * accepts late `log.chunk` / `step.status` chunks from agents that
-     * are still draining instead of rejecting them as ownership
-     * violations.
+     * Optional DB-backed fallback. Returns `owned` when the orchestrator DB shows
+     * the (agent, job) pair as held by this coord OR a sibling coord — i.e.
+     * currently `dispatched`/`recovering` with the same `agent_id` /
+     * `recovery_agent_id`, or already terminal. `not-owned` is a decided refusal;
+     * `unknown` means the lookup itself could not be answered.
+     *
+     * When a Raft leader switch wipes the in-memory `agentJobs` Map on the
+     * replacement coord, this fallback accepts late frames from agents that are
+     * still draining instead of rejecting them as ownership violations.
      */
-    isJobOwnedByAgentInDb?: (agentId: string, jobId: string) => Promise<boolean>;
+    isJobOwnedByAgentInDb?: (agentId: string, jobId: string) => Promise<OwnershipDbResult>;
+    /**
+     * Per-lookup deadline in ms, read fresh on every call so an operator can
+     * retune it fleet-wide without a restart. The read is itself bounded by
+     * {@link DEFAULT_OWNERSHIP_DB_CHECK_TIMEOUT_MS}, which is also the fallback
+     * when it stalls, throws, or returns a delay `setTimeout` cannot honour.
+     */
+    getTimeoutMs?: () => Promise<number>;
     /** Callback to disconnect an agent after escalation. */
     onDisconnect: (agentId: string, reason: string) => void;
     /** Number of violations before escalation (default: 5). */
@@ -35,6 +54,7 @@ interface OwnershipTrackerOpts {
 export declare class OwnershipTracker {
     private readonly isJobOwnedByAgent;
     private readonly isJobOwnedByAgentInDb?;
+    private readonly getTimeoutMs?;
     private readonly onDisconnect;
     private readonly violationThreshold;
     private readonly violationWindowMs;
@@ -63,15 +83,43 @@ export declare class OwnershipTracker {
     checkOwnership(agentId: string, jobId: string, messageType: string): boolean;
     /**
      * Async fallback used by message handlers that want HA-safe
-     * acceptance of post-failover chunks. Returns true if the DB shows
+     * acceptance of post-failover frames. Returns true if the DB shows
      * the (agent, job) pair as currently or recently owned by any coord
-     * in the cluster. On true, caches the result so subsequent same-pair
-     * chunks return true synchronously via `checkOwnership`. On false,
-     * records a violation exactly once (no recursive recordViolation
-     * from the synchronous call site — `checkOwnership` skipped it
-     * when the DB fallback was configured).
+     * in the cluster. On `owned`, caches the result so subsequent
+     * same-pair frames return true synchronously via `checkOwnership`.
+     * On `not-owned`, records a violation exactly once (no recursive
+     * recordViolation from the synchronous call site — `checkOwnership`
+     * skipped it when the DB fallback was configured). On `unknown` the
+     * frame is refused without a violation: an unanswerable check is not
+     * evidence of misbehaviour, and treating it as such would let one
+     * database outage disconnect the whole fleet.
      */
     validateAsync(agentId: string, jobId: string, messageType: string): Promise<boolean>;
+    /**
+     * Run the DB-backed lookup under a deadline. A query that throws or outruns
+     * the deadline resolves `unknown` — never `not-owned` — so a sick database
+     * refuses frames without accusing the agent of anything.
+     */
+    private resolveFromDb;
+    /**
+     * Resolve the deadline for one lookup, itself bounded by
+     * {@link DEFAULT_OWNERSHIP_DB_CHECK_TIMEOUT_MS}.
+     *
+     * The knob is stored in the same database the deadline exists to survive, so
+     * reading it unbounded would stall the very frame the deadline is there to
+     * refuse — the agent would wait out its own acknowledgment deadline instead
+     * of getting an answer. A read that stalls, throws, or yields a value
+     * `setTimeout` cannot honour (non-finite, sub-millisecond, or past
+     * {@link MAX_TIMER_DELAY_MS}) falls back to the compile-time default.
+     */
+    private resolveTimeoutMs;
+    /**
+     * Cache a DB-proven (agent, job) pair so the next frame on the same pair
+     * short-circuits in `checkOwnership`. The per-agent set is capped (generously
+     * — a typical agent runs a handful of jobs) so a misbehaving agent cannot
+     * grow it without bound.
+     */
+    private rememberDbAccepted;
     /**
      * Record a violation for an agent. If threshold is exceeded within the
      * violation window, triggers disconnect escalation.

package/dist/agent/token-store.d.ts

@@ -1,5 +1,18 @@
 import { type Kysely } from 'kysely';
 import type { Database, AgentTokenRow } from '../db/types.js';
+/**
+ * `created_by` marker prefix for single-use bootstrap (init-runner) tokens.
+ * A bootstrap token stores `created_by: '<this prefix><targetAgentId>'` so the
+ * register-time identity binding (agent-handler Gate 2) and the single-use
+ * consume check can both recognize it and resolve the bound agent id.
+ */
+export declare const BOOTSTRAP_CREATED_BY_PREFIX = "bootstrap:";
+/**
+ * Resolve the agent id an ephemeral token binds its holder to. Scaler tokens
+ * store the id verbatim in `created_by`; bootstrap tokens store it behind
+ * `BOOTSTRAP_CREATED_BY_PREFIX`. Returns the bare target agent id in both cases.
+ */
+export declare function boundAgentIdFromCreatedBy(createdBy: string): string;
 /**
  * Safe token row shape returned from list/validate (excludes token_hash).
  */

package/dist/agent-packaging/availability.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Availability gate for version-keyed agent packages.
+ *
+ * The fleet auto-upgrade convergence NEVER rolls a host to a version whose
+ * self-contained payload objects don't exist in the cache bucket — that would
+ * stage stale/absent bytes (or leave the fleet at a version skew). This helper
+ * `head`s each platform's payload object and reports which are missing, so the
+ * caller can HOLD (the convergence gate) or skip re-producing (the upgrade
+ * hook). It never throws — the caller decides hold-vs-alarm.
+ */
+import type { AgentPlatform } from '@kici-dev/shared';
+import { type AgentPackageDownloadStorage } from './download.js';
+/** Verdict of an availability check across a platform set for one version. */
+export interface PayloadAvailability {
+    /** True only when EVERY requested platform's payload object exists. */
+    available: boolean;
+    /** The platforms whose version-keyed payload object is absent. */
+    missing: AgentPlatform[];
+}
+/**
+ * Check that a version's agent payloads exist for every requested platform.
+ * Fail-closed by construction: an absent object lands in `missing`, so a caller
+ * that gates on `available` can never converge onto a version whose bytes are
+ * not present.
+ */
+export declare function assertPayloadsAvailable(storage: AgentPackageDownloadStorage, version: string, platforms: AgentPlatform[]): Promise<PayloadAvailability>;
+//# sourceMappingURL=availability.d.ts.map

package/dist/agent-packaging/build-package.d.ts

@@ -0,0 +1,16 @@
+import type { AgentPlatform } from '@kici-dev/shared';
+export interface BuildAgentPackageOptions {
+    platform: AgentPlatform;
+    version: string;
+    nodeVersion: string;
+    outDir: string;
+    nodeMirror?: string;
+    npmRegistry?: string;
+}
+export interface AgentPackageResult {
+    tarballPath: string;
+    sha256: string;
+}
+/** Package the installed @kici-dev/agent + a vendored Node + npm into a self-contained tarball. */
+export declare function buildSelfContainedAgentPackage(opts: BuildAgentPackageOptions): Promise<AgentPackageResult>;
+//# sourceMappingURL=build-package.d.ts.map

package/dist/agent-packaging/download.d.ts

@@ -0,0 +1,30 @@
+import type { AgentPlatform } from '@kici-dev/shared';
+/**
+ * Read side of the cache-bucket agent-package store: mint a box-routable
+ * presigned GET URL and read the payload's sha256 sidecar. Satisfied by the
+ * orchestrator S3 cache storage client (`getUrl` presigns against the external,
+ * container-routable endpoint; `get` reads the `.sha256` object).
+ */
+export interface AgentPackageDownloadStorage {
+    getUrl(key: string): Promise<string | null>;
+    get(key: string): Promise<Buffer | null>;
+    has(key: string): Promise<boolean>;
+}
+/** Cache-bucket key for a payload's sha256 sidecar (mirrors the upload layout). */
+export declare function agentPackageHashKey(version: string, platform: AgentPlatform): string;
+/** Parse a `sha256sum`-style `<hex>  <name>` sidecar into the leading hex token. */
+export declare function parseSha256Sidecar(contents: string): string | null;
+/**
+ * Mint a presigned GET URL for a version-keyed agent payload and read its
+ * sha256 sidecar. Returns null when the payload object is absent (an
+ * unresolvable version) so the caller fails fast with a clear error rather than
+ * staging stale bytes. The URL is box-routable (external endpoint); no standing
+ * S3 credential ever leaves the orchestrator.
+ */
+export declare function presignAgentPackageDownload(storage: AgentPackageDownloadStorage, version: string, platform: AgentPlatform): Promise<{
+    url: string;
+    sha256: string | null;
+} | null>;
+/** True when a version-keyed payload object exists (backs the availability gate). */
+export declare function agentPackageExists(storage: AgentPackageDownloadStorage, version: string, platform: AgentPlatform): Promise<boolean>;
+//# sourceMappingURL=download.d.ts.map

package/dist/agent-packaging/index.d.ts

@@ -0,0 +1,9 @@
+export * from './node-binary.js';
+export * from './install-closure.js';
+export * from './build-package.js';
+export * from './upload.js';
+export * from './download.js';
+export * from './store.js';
+export * from './availability.js';
+export * from './refresh.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent-packaging/install-closure.d.ts

@@ -0,0 +1,30 @@
+import { type AgentPlatform } from '@kici-dev/shared';
+export interface InstallClosureOptions {
+    version: string;
+    platform: AgentPlatform;
+    /** npm --prefix target; a package.json is seeded so npm installs into <prefix>/node_modules. */
+    prefixDir: string;
+    npmRegistry?: string;
+}
+/**
+ * The `@kici-dev/agent@<spec>` argument for the install.
+ *
+ * In production the agent is published to npm at the exact single-version, so we
+ * pin it verbatim (`@kici-dev/agent@0.2.0`) — the payload is provably the version
+ * the orchestrator runs. In development (`KICI_DEV=true`) the local Verdaccio
+ * registry only carries prerelease builds (`<version>-<buildCounter>`), so we
+ * match the current base version's prereleases instead — the same
+ * prerelease-compatible resolution the rest of the dev tooling uses.
+ */
+export declare function agentInstallSpec(version: string): string;
+/**
+ * `npm install @kici-dev/agent@<version>` for the TARGET platform into prefixDir.
+ *
+ * `--cpu`/`--os` make npm resolve every transitive optional native binding (incl.
+ * `@oxc-transform/binding-<platform>`) for the target platform, not the host —
+ * the same mechanism `scripts/package.mjs` relies on for oxc. `--omit=dev` keeps
+ * the closure to the runtime tree. When the published `@kici-dev/agent` ships an
+ * `npm-shrinkwrap.json`, npm resolves the exact released + tested tree.
+ */
+export declare function installAgentClosure(opts: InstallClosureOptions): Promise<void>;
+//# sourceMappingURL=install-closure.d.ts.map

package/dist/agent-packaging/node-binary.d.ts

@@ -0,0 +1,26 @@
+import { type AgentPlatform } from '@kici-dev/shared';
+export interface DownloadNodeOptions {
+    version: string;
+    platform: AgentPlatform;
+    /** Absolute path the verified `node` executable is written to. */
+    destBinPath: string;
+    /** Overrides https://nodejs.org/dist (air-gap mirror). */
+    nodeMirror?: string;
+}
+/**
+ * Download + SHASUMS256-verify the Node runtime for a glibc-Linux platform and
+ * vendor `node` + `npm` into the payload.
+ *
+ * Fetches the release's SHASUMS256.txt, finds the entry for the target
+ * platform's `.tar.gz`, downloads the archive, verifies its sha256 against that
+ * entry, and extracts the runtime into `<prefix>/` (where `<prefix>` is the
+ * grandparent of `destBinPath`): the `node` binary at `<prefix>/bin/node`, the
+ * `bin/npm` + `bin/npx` launcher symlinks, and the bundled npm package under
+ * `<prefix>/lib/node_modules/npm`. npm is required so the booted agent can
+ * install a workflow's `.kici/` dependencies on a box with no system Node —
+ * `resolveNpm()` finds it at `<nodeDir>/../lib/node_modules/npm/bin/npm-cli.js`.
+ * The vendored Node is what the produced payload boots on — no system Node is
+ * ever used.
+ */
+export declare function downloadNodeBinary(opts: DownloadNodeOptions): Promise<void>;
+//# sourceMappingURL=node-binary.d.ts.map

package/dist/agent-packaging/refresh.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Auto-refresh of version-keyed agent payloads on `orchestrator upgrade`.
+ *
+ * The automation-completeness principle: auto-deploy ⟹ auto-upgrade ⟹
+ * auto-package. After the orchestrator is upgraded to version V, this hook
+ * produces + uploads `agent-packages/V/kici-agent-<platform>.tar.gz(.sha256)`
+ * for the platforms the fleet already runs, so the convergence gate finds the
+ * bytes it needs with no separate operator step. Idempotent: a platform whose
+ * payload already exists for V is skipped, so a re-run is a no-op.
+ */
+import { AgentPlatform } from '@kici-dev/shared';
+import { type AgentPackageDownloadStorage } from './download.js';
+/** Storage surface the refresh needs: existence check, listing, put. */
+export interface RefreshStorage extends AgentPackageDownloadStorage {
+    put(key: string, data: Buffer | string): Promise<void>;
+    list(subPrefix: string): Promise<string[]>;
+}
+/** Result of one produced payload, as `kici-admin agent package` yields it. */
+export interface BuiltPayload {
+    tarballPath: string;
+    sha256: string;
+}
+export interface RefreshDeps {
+    /** Build one platform's self-contained payload for `version` (the packaging lib). */
+    build: (platform: AgentPlatform, version: string) => Promise<BuiltPayload>;
+    /** Optional log sink (defaults to no-op); the CLI wires console.log. */
+    log?: (msg: string) => void;
+}
+export interface RefreshResult {
+    produced: AgentPlatform[];
+    skipped: AgentPlatform[];
+}
+/**
+ * The platforms the fleet already has payloads for — the union across every
+ * version present in the store EXCEPT `excludeVersion` (the just-upgraded
+ * target, whose payloads we are about to (re)produce). Preserves the fleet's
+ * arch coverage across an upgrade. Empty ⇒ the caller falls back to the
+ * bootstrap default set.
+ */
+export declare function discoverFleetPlatforms(storage: RefreshStorage, excludeVersion: string): Promise<AgentPlatform[]>;
+/**
+ * Produce + upload the target version's payloads for the fleet's platform set,
+ * skipping any already present (idempotent). Explicit `platforms` override the
+ * discovery; otherwise the fleet's existing arch coverage is preserved, falling
+ * back to the bootstrap default (`AgentPlatform.options`) on a fresh store.
+ */
+export declare function refreshAgentPackages(storage: RefreshStorage, version: string, opts: {
+    platforms?: AgentPlatform[];
+}, deps: RefreshDeps): Promise<RefreshResult>;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/agent-packaging/store.d.ts

@@ -0,0 +1,15 @@
+import type { CacheStorage } from '../storage/types.js';
+import type { AppConfig } from '../config.js';
+import type { AgentPackageDownloadStorage } from './download.js';
+/**
+ * Resolve the agent-package store the bring-up presign handler reads from.
+ *
+ * Defaults to the orchestrator's OWN cache bucket (`cacheStorage`) — never a
+ * vendor CDN. An `s3://bucket[/prefix]` override (`KICI_AGENT_BINARY_SOURCE`)
+ * points the presign at another bucket on the SAME S3 endpoint (the customer
+ * supply-chain mirror); the config schema already rejects an http(s) source so
+ * no external HTTP default can slip in. Returns undefined when no cache storage
+ * is configured and no override is set (the presign RPC then refuses loudly).
+ */
+export declare function resolveAgentPackageStore(config: AppConfig, cacheStorage: CacheStorage | undefined): AgentPackageDownloadStorage | undefined;
+//# sourceMappingURL=store.d.ts.map

package/dist/agent-packaging/upload.d.ts

@@ -0,0 +1,24 @@
+import { AgentPlatform } from '@kici-dev/shared';
+/** Minimal storage surface — satisfied by the orchestrator S3 cache storage client. */
+export interface AgentPackageStorage {
+    put(key: string, data: Buffer | string): Promise<void>;
+}
+/** The cache-bucket sub-prefix under which all version-keyed payloads live. */
+export declare const AGENT_PACKAGES_PREFIX = "agent-packages/";
+/** Cache-bucket key for a version-keyed agent payload. */
+export declare function agentPackageKey(version: string, platform: AgentPlatform): string;
+/**
+ * Parse an `agent-packages/<version>/kici-agent-<platform>.tar.gz` key back into
+ * its version + platform, or null when the key is not a payload tarball (e.g. a
+ * `.sha256` sidecar or an unrelated key). Used to discover the fleet's platform
+ * set from the store on upgrade.
+ */
+export declare function parseAgentPackageKey(key: string): {
+    version: string;
+    platform: AgentPlatform;
+} | null;
+/** Upload a produced payload + its sha256 sidecar to the cache bucket. */
+export declare function uploadAgentPackage(storage: AgentPackageStorage, version: string, platform: AgentPlatform, tarballPath: string, sha256: string): Promise<{
+    key: string;
+}>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/app-on-error.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The orchestrator's last-resort HTTP error handler.
+ *
+ * Without one, Hono answers an unhandled throw with a bare, unstructured 500:
+ * no JSON body, no route context, and nothing written to our own logs. Every
+ * admin router already catches inside its handlers (routes/admin-errors.ts),
+ * and the auth path catches inside its middleware (routes/admin-auth.ts) -- this
+ * covers whatever neither does.
+ *
+ * It is a backstop, not a substitute for a specific boundary: a targeted catch
+ * can return the right status for its failure (503 when authentication cannot
+ * be completed), while a generic net can only say "something broke".
+ */
+import type { ErrorHandler } from 'hono';
+export interface OnErrorOptions {
+    /** Which app this handler guards. The orchestrator has exactly two Hono roots. */
+    role: 'coordinator' | 'worker';
+    logger?: {
+        error(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+/**
+ * Build the `app.onError` handler for one Hono composition root.
+ *
+ * @param opts - The app role recorded on every log line, and an optional logger.
+ * @returns A Hono error handler returning a structured 500.
+ */
+export declare function createOnErrorHandler(opts: OnErrorOptions): ErrorHandler;
+//# sourceMappingURL=app-on-error.d.ts.map