@kici-dev/orchestrator 0.1.21 → 0.1.23

package/dist/agent/dispatcher.d.ts

@@ -13,6 +13,18 @@ export interface DispatchMetrics {
     /** Set the queue depth gauge. */
     setQueueDepth(depth: number): void;
 }
+/**
+ * Narrow slice of `HostRosterStore` the dispatcher needs for the host-restart
+ * flow. Kept as an interface so the dispatcher doesn't import the full store
+ * (which pulls in engine label matchers) and to make the reboot logic testable
+ * with a tiny in-memory stub.
+ */
+export interface HostRosterRebootStore {
+    /** True when the host's reboot-pending deadline is still in the future. */
+    isRebootPending(agentId: string, nowMs: number): Promise<boolean>;
+    /** Clear the reboot-pending flag (down-then-up release on reconnect). */
+    clearRebootPending(agentId: string): Promise<void>;
+}
 /**
  * Result of a dispatch attempt.
  */
@@ -120,6 +132,8 @@ export declare class Dispatcher {
     private readonly recoveringJobs;
     /** Grace period = 2x max reconnection delay. */
     private get gracePeriodMs();
+    /** Host roster store for the reboot-pending gate; undefined ⇒ flow inert. */
+    private readonly rosterStore?;
     constructor(deps: {
         registry: AgentRegistry;
         queue: JobQueue;
@@ -139,6 +153,14 @@ export declare class Dispatcher {
         getAckTimeoutMs?: (job: QueuedJob) => Promise<number>;
         /** Cancel + disconnect an agent whose dispatch ack deadline expired. */
         onAckTimeout?: (agentId: string, jobId: string, runId: string) => void;
+        /**
+         * Host roster store, used for the workflow-level host-restart flow: gate the
+         * pinned-drain off for a reboot-pending agent, and treat a reboot-pending
+         * agent's disconnect as the expected reboot (complete its in-flight job
+         * success rather than starting the recovery-fail timer). Omitted ⇒ the
+         * reboot-pending behavior is inert (every host reads not-pending).
+         */
+        rosterStore?: HostRosterRebootStore;
     });
     /**
      * Dispatch a job to a matching agent, or queue it if none available.
@@ -181,6 +203,20 @@ export declare class Dispatcher {
      * Dequeues matching jobs from the queue while the agent has capacity,
      * calling onDispatch for each.
      */
+    /**
+     * Drop agents whose reboot-pending flag is set from a candidate list. Used by
+     * the label-routed dispatch path so a post-restart job is never sent to a host
+     * that is about to reboot. No-op when no roster store is wired.
+     */
+    private filterRebootPending;
+    /**
+     * Release a reboot-pending host on its real reconnect (down-then-up). Clears
+     * the persisted flag so the very next `onAgentAvailable` drain dispatches the
+     * held post-restart job. Call this ONLY from the (re-)register path — a fresh
+     * connection after the box rebooted — never from a still-connected drain
+     * trigger (job completion / agent.status), which must keep the gate closed.
+     */
+    releaseRebootPending(agentId: string): Promise<void>;
     onAgentAvailable(agentId: string): Promise<void>;
     /** Record that a job began executing on its agent. */
     markJobStarted(jobId: string): void;
@@ -239,6 +275,14 @@ export declare class Dispatcher {
      * asynchronously when recovery timers expire).
      */
     onAgentDisconnect(agentId: string): Promise<string[]>;
+    /**
+     * Reboot-pending agent disconnected: complete its in-flight started job(s) as
+     * success (the restart job, which already reported success, may already be
+     * terminal — `markCompleted` is a no-op / guarded in that case). Never starts
+     * a recovery timer. Untracks the jobs so the reconnect does not reconcile a
+     * phantom in-flight set.
+     */
+    private completeInFlightForReboot;
     /** Drop grace-window entries owned by an agent. */
     private cleanupGraceEntriesForAgent;
     /**

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

@@ -1,6 +1,6 @@
 import type { HostRosterStore } from './host-roster.js';
 export interface HostRosterReaperOptions {
-    store: Pick<HostRosterStore, 'reapEphemeralPastTtl' | 'countStaticUnreachable'>;
+    store: Pick<HostRosterStore, 'reapEphemeralPastTtl' | 'countStaticUnreachable' | 'listExpiredRebootPending' | 'clearRebootPending'>;
     ttlMs: number;
     /** Grace window for the connected-but-stale case in `countStaticUnreachable`. */
     graceMs: number;
@@ -30,6 +30,7 @@ export declare class HostRosterReaper {
     private readonly graceMs;
     private readonly scanIntervalMs;
     private readonly setUnreachableGauge;
+    private readonly rebootSweep;
     private timer;
     private isLeader;
     constructor(opts: HostRosterReaperOptions);

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

@@ -3,6 +3,19 @@ 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>;
+/**
+ * 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
+ * metadata cannot be bootstrapped. `sshKeySecret` is a scoped-secret ref
+ * (`scope/key`) the orchestrator resolves server-side; the key never lives here.
+ */
+export interface HostReach {
+    agentId: string;
+    address: string | null;
+    sshUser: string | null;
+    sshPort: number | null;
+    sshKeySecret: string | null;
+}
 /**
  * Derived (read-time) status of a roster host. Never a stored mutable column:
  * status is computed from the shared `last_seen` + `connected_instance_id` so
@@ -96,13 +109,36 @@ export declare class HostRosterStore {
     markDisconnected(agentId: string, instanceId: string): Promise<void>;
     /** Coarse heartbeat stamp — same owner-guard as markDisconnected. */
     stampLastSeen(agentId: string, instanceId: string): Promise<void>;
-    /** Operator pre-declare of a static host before its agent dials in. */
+    /**
+     * Operator pre-declare of a static host. A re-declare of an existing agent_id
+     * converges the operator-owned columns (labels, hostname, reach,
+     * host_properties) to the newly-declared values while preserving the
+     * agent-reported liveness/identity columns (connected_instance_id, last_seen,
+     * platform, arch, lifecycle_class, token_id, reboot_pending_until). The
+     * optional reach fields (`address`/`sshUser`/`sshPort`/`sshKeySecret`) carry
+     * how to SSH to the host for bootstrap bring-up. Each operator field is
+     * preserve-on-omit: an omitted field keeps the existing column value.
+     *
+     * Returns `{ created: true }` when the declare inserted a new row,
+     * `{ created: false }` when it converged an existing one.
+     */
     declareStatic(input: {
         agentId: string;
-        labels: string[];
+        labels?: string[];
         hostname?: string;
         properties?: HostProperties;
-    }): Promise<void>;
+        address?: string;
+        sshUser?: string;
+        sshPort?: number;
+        sshKeySecret?: string;
+    }): Promise<{
+        created: boolean;
+    }>;
+    /**
+     * Read a host's pre-agent reach metadata. Returns null when the host is not
+     * in the roster; a host declared without reach fields reads back with nulls.
+     */
+    getReach(agentId: string): Promise<HostReach | null>;
     get(agentId: string): Promise<HostRosterRow | null>;
     listAll(): Promise<HostRosterRow[]>;
     /**
@@ -139,7 +175,25 @@ export declare class HostRosterStore {
      * depends on `graceMs`).
      */
     countStaticUnreachable(graceMs: number): Promise<number>;
+    /** Remove a host from the roster by agent id. Returns rows deleted. */
+    removeStatic(agentId: string): Promise<number>;
     /** Delete ephemeral rows whose last_seen is older than ttl. Returns count. */
     reapEphemeralPastTtl(ttlMs: number): Promise<number>;
+    /**
+     * Mark a host as about-to-reboot until `until`. Set by the `host.requestReboot`
+     * API handler when an agent's `restartHost()` step runs. While the value is in
+     * the future, the host's disconnect is the expected reboot and its pinned
+     * post-restart job is held.
+     */
+    setRebootPending(agentId: string, until: Date): Promise<void>;
+    /** Clear the reboot-pending flag (on reconnect, deadline expiry, or cancel). */
+    clearRebootPending(agentId: string): Promise<void>;
+    /** True when the host has a reboot-pending deadline still in the future at `nowMs`. */
+    isRebootPending(agentId: string, nowMs: number): Promise<boolean>;
+    /**
+     * Agent ids whose reboot-pending deadline has passed at `nowMs`. The deadline
+     * sweep clears these; the held post-restart job then hits the queue timeout.
+     */
+    listExpiredRebootPending(nowMs: number): Promise<string[]>;
 }
 //# sourceMappingURL=host-roster.d.ts.map

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

@@ -41,6 +41,35 @@ export declare class AgentTokenStore {
      * @returns The plaintext token (shown once).
      */
     createEphemeral(agentId: string, labels: string[], ttlMs: number): Promise<string>;
+    /**
+     * Mint a single-use, short-TTL bootstrap token for an init-runner bring-up.
+     *
+     * The token is stored as `agent_type: 'ephemeral'` (so the existing expiry
+     * cleanup reaps it) and is bound to exactly the init-runner label set. It is
+     * single-use: `consumeBootstrapToken` sets `consumed_at` on first
+     * `agent.register`, and a second register is rejected. A leaked token is
+     * therefore inert after enrollment AND after its short TTL elapses.
+     *
+     * @param targetAgentId - The agent id the init-runner will register as.
+     * @param ttlMs - Time-to-live in milliseconds (short, ~10 min).
+     * @param labels - The init-runner labels the token authorizes.
+     * @returns The plaintext token (shown once) and the DB row ID.
+     */
+    mintBootstrapToken(opts: {
+        targetAgentId: string;
+        ttlMs: number;
+        labels: string[];
+    }): Promise<{
+        token: string;
+        id: string;
+    }>;
+    /**
+     * Consume a single-use bootstrap token by id. Sets `consumed_at` only when it
+     * is currently null, so the first register wins and any subsequent attempt
+     * with the same token returns false (already consumed). Returns true when
+     * this call performed the consumption.
+     */
+    consumeBootstrapToken(id: string): Promise<boolean>;
     /**
      * Validate a plaintext token against stored hashes.
      *

package/dist/approvals/step-approval-bridge.d.ts

@@ -17,6 +17,11 @@ export interface StepApprovalRequest {
     reason: string;
     /** Per-gate timeout (seconds); falls back to the org default. */
     timeoutSeconds?: number;
+    /** Computed drift payload for a `when: 'drift'` gate; persisted on the hold. */
+    payload?: {
+        summaryMarkdown: string;
+        drift: unknown;
+    };
 }
 /** Dependencies injected into the bridge. */
 export interface StepApprovalBridgeDeps {

package/dist/cli/commands/source-manifest.d.ts

@@ -17,6 +17,14 @@ export interface ManifestSetupOptions {
     name: string;
     noBrowser?: boolean;
     githubOrg?: string;
+    /**
+     * Self-hosted webhook URL override. When set, it is baked verbatim into the
+     * App manifest's `hook_attributes.url` and the platform-mode webhook-URL
+     * resolution is skipped — so the flow works even where the auto-resolved KiCI
+     * platform URL is unavailable. KiCI adds no ingress at this URL; the operator
+     * owns delivery. Advanced/self-hosted only.
+     */
+    webhookUrl?: string;
 }
 /** Injectable boundary so unit tests can stub GitHub + the browser + stdin. */
 export interface ManifestSetupDeps {

package/dist/cli/service/compose.d.ts

@@ -7,6 +7,18 @@
  * platform with Docker or Podman installed.
  */
 import type { ServiceManager, ServiceConfig, ServiceStatus, LogOptions, DiscoveredInstance, LaunchSpec } from './types.js';
+/** Container runtime binary (`podman` or `docker`); compose form is `${runtime} compose`. */
+type Runtime = 'podman' | 'docker';
+/**
+ * Detect which container runtime is available.
+ * Tries podman compose first, then docker compose.
+ *
+ * Exported so the orchestrator installer can resolve the runtime once when
+ * injecting the `KICI_DEPLOY_CONTAINER_RUNTIME` env var for a compose deploy.
+ *
+ * @throws When neither runtime is found.
+ */
+export declare function detectRuntime(): Runtime;
 export declare class ComposeServiceManager implements ServiceManager {
     private runtime;
     /** Get the runtime binary (`podman` or `docker`), detecting it if not already done. */
@@ -24,4 +36,5 @@ export declare class ComposeServiceManager implements ServiceManager {
     list(isUserLevel: boolean): Promise<DiscoveredInstance[]>;
     readLaunchSpec(_config: ServiceConfig): Promise<LaunchSpec | null>;
 }
+export {};
 //# sourceMappingURL=compose.d.ts.map

package/dist/cli/service/deploy-env.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Deployment-identity env injection for the orchestrator installer.
+ *
+ * The orchestrator reports its own deployment shape (systemd / launchd /
+ * windows / compose) in `source.register` so the dashboard can build the
+ * correct `kici-admin` invocation. The shape is only knowable at install time
+ * (a running container can't learn its own container name), so the installer
+ * injects it into the orchestrator's env file via these `KICI_DEPLOY_*` vars.
+ */
+import type { ServicePlatform } from './types.js';
+/** Inputs the installer already has when it writes the env file. */
+export interface DeployEnvInput {
+    platform: ServicePlatform;
+    /** The service / container name the installer assigns (= ServiceConfig.name). */
+    serviceName: string;
+    /** Container runtime, only meaningful for the `compose` platform. */
+    containerRuntime?: 'podman' | 'docker';
+}
+/**
+ * Build the `KICI_DEPLOY_*` env lines for a given deployment shape. The mode
+ * line is always emitted; container name + runtime are emitted only for the
+ * `compose` platform (the only shape with a container to `exec` into).
+ */
+export declare function buildDeployEnvLines(input: DeployEnvInput): string[];
+/**
+ * Append the freshly-computed deploy lines to existing env-file content,
+ * idempotently: any pre-existing `KICI_DEPLOY_*` line is stripped first so a
+ * re-install / upgrade heals the shape rather than duplicating it.
+ */
+export declare function upsertDeployEnvLines(existingContent: string, lines: string[]): string;
+//# sourceMappingURL=deploy-env.d.ts.map