@kici-dev/orchestrator 0.1.22 → 0.1.23

package/dist/db/migrations/051_binding_host_pattern.d.ts

@@ -0,0 +1,18 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add a per-host dimension to environment secret bindings:
+ *
+ * - `environment_bindings.host_pattern text NOT NULL DEFAULT '**'` — the host
+ *   selector a binding applies to (exact / glob / regex, matched against a
+ *   fan-out child's agentId / hostname / labels). `'**'` matches every host, so
+ *   existing rows are backfilled to `'**'` and keep their fleet-wide behaviour.
+ * - The binding unique key widens from `(environment_id, scope_pattern)` to
+ *   `(environment_id, scope_pattern, host_pattern)` so the same scope can carry
+ *   distinct per-host selectors.
+ *
+ * Idempotent: re-running on a DB that already has the column / index is a no-op.
+ * Additive — staging data is preserved.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=051_binding_host_pattern.d.ts.map

package/dist/db/migrations/052_host_reach_metadata.d.ts

@@ -0,0 +1,19 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add pre-agent reach metadata to the host roster so a declared host (no agent
+ * yet) can be reached over SSH for bootstrap bring-up:
+ *
+ * - `host_roster.address text NULL` — IP / hostname to SSH to.
+ * - `host_roster.ssh_user text NULL` — SSH login user (defaults to `root` at use site).
+ * - `host_roster.ssh_port int NULL` — SSH port (defaults to 22 at use site).
+ * - `host_roster.ssh_key_secret text NULL` — scoped-secret ref (`scope/key`)
+ *   holding the bring-up private key. The orchestrator resolves it server-side;
+ *   the key never lives in the roster.
+ *
+ * All nullable: a host with no reach metadata simply cannot be bootstrapped and
+ * behaves exactly as before. Idempotent (`ADD COLUMN IF NOT EXISTS`); additive,
+ * so staging data is preserved.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=052_host_reach_metadata.d.ts.map

package/dist/db/migrations/053_agent_token_single_use.d.ts

@@ -0,0 +1,17 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add a single-use marker to agent tokens for the bootstrap (init-runner)
+ * bring-up flow:
+ *
+ * - `agent_tokens.consumed_at timestamptz NULL` — set the first time a
+ *   single-use bootstrap token is consumed (at `agent.register`). A second
+ *   register with the same token is rejected. NULL = never consumed (the
+ *   default for every existing static / ephemeral token, which stay reusable
+ *   until expiry).
+ *
+ * Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+ * preserved.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=053_agent_token_single_use.d.ts.map

package/dist/db/types.d.ts

@@ -605,6 +605,12 @@ export interface EnvironmentBindingsTable {
     environment_id: string;
     /** Scope pattern for matching (e.g. workflow name glob, repo pattern) */
     scope_pattern: string;
+    /**
+     * Host selector this binding applies to (exact / glob / regex over a fan-out
+     * child's agentId / hostname / labels). `'**'` (the default) matches every
+     * host.
+     */
+    host_pattern: Generated<string>;
     /** When this binding was created */
     created_at: Generated<Date>;
 }
@@ -863,6 +869,13 @@ export interface AgentTokenTable {
     revoked_at: Date | null;
     /** When this token expires (null = never, static tokens) */
     expires_at: Date | null;
+    /**
+     * Single-use marker for bootstrap (init-runner) tokens. Set the first time
+     * the token is consumed at `agent.register`; a second register is rejected.
+     * NULL = never consumed (every static / ephemeral token stays reusable until
+     * expiry).
+     */
+    consumed_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
 }
 export type AgentTokenRow = Selectable<AgentTokenTable>;
 export type NewAgentTokenRow = Insertable<AgentTokenTable>;
@@ -1639,6 +1652,16 @@ export interface HostRosterTable {
      * reconnects (down-then-up). NULL = no reboot pending.
      */
     reboot_pending_until: ColumnType<Date | null, Date | string | null, Date | string | null>;
+    /**
+     * Pre-agent reach metadata: how to SSH to a declared host before it has a
+     * KiCI agent, for bootstrap bring-up. All nullable — a host with no reach
+     * metadata cannot be bootstrapped and behaves exactly as before.
+     */
+    address: ColumnType<string | null, string | null | undefined, string | null>;
+    ssh_user: ColumnType<string | null, string | null | undefined, string | null>;
+    ssh_port: ColumnType<number | null, number | null | undefined, number | null>;
+    /** Scoped-secret ref (`scope/key`) holding the bring-up private key. */
+    ssh_key_secret: ColumnType<string | null, string | null | undefined, string | null>;
     created_at: Generated<Date>;
     updated_at: ColumnType<Date, Date | string | undefined, Date | string>;
 }

package/dist/environments/binding-store.d.ts

@@ -6,6 +6,14 @@
  */
 import type { Kysely } from 'kysely';
 import type { Database, EnvironmentBinding } from '../db/types.js';
+/**
+ * A scope→environment binding with its host selector. `hostPattern` defaults to
+ * `'**'` (all hosts) when omitted.
+ */
+export interface BindingInput {
+    scopePattern: string;
+    hostPattern?: string;
+}
 /**
  * Data access layer for environment bindings.
  */
@@ -17,10 +25,11 @@ export declare class BindingStore {
     /**
      * Replace all bindings for an environment in a transaction.
      *
-     * Deletes existing bindings and inserts the new set atomically.
-     * Pass an empty array to clear all bindings.
+     * Deletes existing bindings and inserts the new set atomically. Each binding
+     * carries a `scopePattern` and an optional `hostPattern` (defaulting to
+     * `'**'`). Pass an empty array to clear all bindings.
      */
-    set(orgId: string, environmentId: string, scopePatterns: string[]): Promise<void>;
+    set(orgId: string, environmentId: string, bindings: BindingInput[]): Promise<void>;
     /** Find bindings for an environment (alias for list, used by secret resolver). */
     findBindingsForEnvironment(orgId: string, environmentId: string): Promise<EnvironmentBinding[]>;
 }

package/dist/environments/held-runs.d.ts

@@ -104,8 +104,32 @@ export declare class HeldRunStore {
      * the created row.
      */
     createHold(orgId: string, data: CreateHoldData): Promise<HeldRun>;
+    /** INSERT one decision row using the given executor (root or transaction). */
+    private insertDecisionRow;
+    /** Flip a pending hold to 'approved' using the given executor. Undefined if not pending. */
+    private flipToApproved;
+    /** Flip a pending hold to 'rejected' using the given executor. Undefined if not pending. */
+    private flipToRejected;
+    /** Map a released held_runs row to the resume ReleaseSignal. */
+    private toReleaseSignal;
     /** Record one approve/reject decision against a hold. */
     recordDecision(heldRunId: string, data: RecordDecisionData): Promise<HeldRunApproval>;
+    /**
+     * Atomically record an approve decision and release the (now-satisfied) hold.
+     * The INSERT into `held_run_approvals` and the `held_runs` → approved UPDATE
+     * run in a single transaction, so a crash between them cannot strand the hold
+     * `pending` with a recorded approve. Throws if the hold is not found or no
+     * longer pending (the whole transaction rolls back).
+     */
+    recordAndRelease(orgId: string, heldRunId: string, data: RecordDecisionData): Promise<ReleaseSignal>;
+    /**
+     * Atomically record a reject decision and reject the hold. The INSERT and the
+     * `held_runs` → rejected UPDATE run in a single transaction, so a crash
+     * between them cannot strand the hold `pending` with a recorded reject (which
+     * would poison `evaluate()` forever). Throws if the hold is not found or no
+     * longer pending (the whole transaction rolls back).
+     */
+    recordAndReject(orgId: string, heldRunId: string, data: RecordDecisionData, reason?: string): Promise<HeldRun>;
     /** List the recorded decisions for a hold, oldest first. */
     listDecisions(heldRunId: string): Promise<HeldRunApproval[]>;
     /** Get a single held run by id (org-scoped). Returns null if absent. */

package/dist/metrics/prometheus.d.ts

@@ -8,6 +8,8 @@ export declare function setDeclaredHostsUnreachable(value: number): void;
 export declare function setStaleRunsCurrent(value: number): void;
 interface ScalerUsageRow {
     scaler: string;
+    /** Backend type for this scaler (rollup dimension). `__global__` for the orchestrator-wide row. */
+    scalerType?: string;
     machinePool?: string;
     cpus: number;
     memBytes: number;

package/dist/pipeline/dispatch-matched-workflow.d.ts

@@ -14,10 +14,12 @@
  * results through the pipeline.
  */
 import { ExecutionJobStatus, InitFailureCategory, CacheRefScope } from '@kici-dev/engine';
-import type { LabelMatcher, LockWorkflow, LockJob, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent } from '@kici-dev/engine';
+import type { LabelMatcher, LockWorkflow, LockJob, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, HostFacts } from '@kici-dev/engine';
 import { type HostRosterStore } from '../agent/host-roster.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { QueuedJobInput } from '../queue/job-queue.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import { type ProcessingDeps } from './processor.js';
 /**
@@ -120,6 +122,12 @@ export interface WorkflowDispatchContext {
      * runsOnAll ∩ target. Narrow-only. Undefined for webhook runs (no narrowing).
      */
     target?: HostTargetSelector;
+    /**
+     * Resolved (coerced + defaulted + validated) workflow-dispatch inputs from
+     * `kici run --input`. Carried onto every dispatched job's request so the agent
+     * exposes them as `ctx.dispatchInputs`. Undefined for webhook runs.
+     */
+    dispatchInputs?: Record<string, unknown>;
 }
 export interface DispatchMatchedWorkflowResult {
     /** Number of jobs successfully dispatched (non-rejected). */
@@ -144,6 +152,30 @@ export interface DispatchMatchedWorkflowOptions {
      */
     reuseRunId?: string;
 }
+type DispatchFn = (input: QueuedJobInput) => ReturnType<Dispatcher['dispatch']>;
+interface DispatchSetup {
+    /** Wrapped dispatcher that injects ctx.extraJobConfig into every dispatch. */
+    dispatcher: {
+        dispatch: DispatchFn;
+    };
+    /** WebhookInfo overlaid with effective routing key + provider. */
+    info: WebhookInfo;
+    /** Composite delivery id on cross-source, otherwise info.deliveryId. */
+    effectiveDeliveryId: string;
+    workflowConcurrency: {
+        cancelInProgress?: boolean;
+        max?: number;
+    } | undefined;
+    workflowTimeoutMs: number | undefined;
+    /**
+     * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`),
+     * carried on `ctx.extraJobConfig` by the test-trigger / `kici run --check`
+     * path. Persisted onto the `execution_runs` row so `computeRunStatus` can
+     * fail a `check-fail-on-drift` run that detected drift. Undefined for the
+     * default apply-mode webhook path.
+     */
+    checkMode: string | undefined;
+}
 interface RejectedJob {
     jobId: string;
     jobName: string;
@@ -157,6 +189,20 @@ interface RejectedJob {
      */
     terminalStatus?: ExecutionJobStatus;
 }
+/**
+ * Build the QueuedJobInput for a synthetic `__bringup__` job: the orchestrator
+ * dispatches one per declared-but-un-agented `includeUninitialized` child to an
+ * agent holding `kici:capability:ssh-transport`, which runs the agent-side
+ * `ensureInitRunner(targetAgentId)` over SSH. The init-runner then connects
+ * under `targetAgentId`, and the child's pinned-hold (already queued with that
+ * pin) drains its bootstrap steps onto it. The bring-up job clones nothing and
+ * runs no sandbox (`bringupOnly`).
+ */
+export declare function buildBringupJobInput(args: {
+    ctx: WorkflowDispatchContext;
+    setup: DispatchSetup;
+    targetAgentId: string;
+}): QueuedJobInput;
 /**
  * Phase B orchestrator: probe caches, dispatch the build job (if needed),
  * and surface enough state for downstream phases to skip / continue
@@ -227,8 +273,9 @@ export interface WavePlan {
  * Compute the rolling-wave plan for a materialized job set.
  *
  * For each base job declaring `maxParallel` whose fan-out produced more than one
- * child, children are ordered deterministically by `variant_label` (the matrix
- * suffix / hostname, via `expandedName`) and every child at index `>=
+ * child, children are ordered deterministically by `fanoutIndex` (the
+ * agentId / variant-label rank assigned at materialization; falling back to
+ * `expandedName` for children with no index) and every child at index `>=
  * maxParallel` is held (`wave_gated=true`). The first `maxParallel` dispatch
  * immediately; held children release one-per-terminal via the wave-scheduler.
  * Every child of a bounded-wave base — held or not — gets a `policy` entry so
@@ -241,6 +288,14 @@ export declare function materializeStaticJobsSafe(staticJobs: readonly LockJob[]
     expansionMap: Map<string, readonly string[]>;
     matrixFailures: RejectedJob[];
 }>;
+/**
+ * Build the per-host secret-resolution context for a materialized child. A
+ * `runsOnAll` host child carries its identity on `mat.agent` (preferred) or
+ * `mat.pinnedAgentId`/`mat.host`; a non-host child (matrix/static) has none, so
+ * resolution stays fleet-wide (`'**'`-only). Returns `undefined` when there are
+ * no host facts to scope by.
+ */
+export declare function hostCtxFromMat(mat: MaterializedJob): HostFacts | undefined;
 export interface GeneratedJobConfig {
     /**
      * The generated lock job with its `name` and `needs` rewritten to expanded

package/dist/pipeline/test-pipeline.d.ts

@@ -73,6 +73,12 @@ export interface TestTriggerInput {
      * context, where it post-filters each runsOnAll job's matched roster.
      */
     target?: HostTargetSelector;
+    /**
+     * Raw operator-supplied `kici run --input KEY=VALUE` pairs (not coerced /
+     * defaulted). Validated + coerced + defaulted here against the matched
+     * workflow's lock dispatch descriptor before dispatch.
+     */
+    dispatchInputs?: Record<string, string>;
 }
 /**
  * Result of processing a test trigger.

package/dist/reporting/log-writer.d.ts

@@ -21,7 +21,26 @@ export declare class LogWriter {
     private readonly logStorage;
     private readonly observerRegistry?;
     private readonly isTestRun?;
+    /**
+     * In-flight `logStorage.append` promises, keyed by runId. `appendChunk` is
+     * called fire-and-forget from the agent WS handler (it does not await the
+     * storage write), so a run can flip to a terminal status while the final
+     * log chunk's append is still pending. `drain(runId)` lets a reader (the
+     * test-run logs cursor endpoint) wait for those pending writes before it
+     * reports the stream as fully drained — without this, the `done` flag can
+     * be returned `true` while the last user-visible log line is not yet on
+     * disk, dropping it from a blocking `kici run remote` follow.
+     */
+    private readonly pendingAppends;
     constructor(deps: LogWriterDeps);
+    /**
+     * Await every in-flight log append for `runId` that was registered before
+     * this call. Settles even if an append rejected (errors are already logged
+     * by `appendChunk`); the point is ordering, not error propagation. New
+     * appends started after this call are not waited on — a terminal run emits
+     * no further chunks, so the snapshot taken at call time is complete.
+     */
+    drain(runId: string): Promise<void>;
     /**
      * Append log lines from an agent to storage in JSONL format.
      *

package/dist/scaler/manager.d.ts

@@ -39,6 +39,23 @@ export interface ResolvedResources {
         memBytes: number;
     };
 }
+/**
+ * Build the scaler-usage metric rows: one per active scaler (stamped with its
+ * backend type) plus a `__global__` rollup row. Pure so it is unit-testable
+ * without constructing a full ScalerManager.
+ */
+export declare function buildScalerUsageRows(perScalerUsage: ReadonlyMap<string, {
+    cpus: number;
+    memBytes: number;
+}>, globalUsage: {
+    cpus: number;
+    memBytes: number;
+}, scalerTypeOf: (name: string) => string | undefined): Array<{
+    scaler: string;
+    scalerType?: string;
+    cpus: number;
+    memBytes: number;
+}>;
 /**
  * Status summary for metrics and health endpoints.
  */

package/dist/secrets/secret-resolver.d.ts

@@ -15,7 +15,7 @@
  * longest-path-wins uses scope path after stripping backend prefix.
  * audit log includes backend name.
  */
-import { type EnvironmentBinding, type ScopedSecret } from '@kici-dev/engine';
+import { type EnvironmentBinding, type HostFacts, type ScopedSecret } from '@kici-dev/engine';
 import type { Logger } from '@kici-dev/shared';
 import type { AuditLogger } from './audit-logger.js';
 /**
@@ -69,13 +69,13 @@ export interface ResolvedSecretMeta {
  * can flow through `ProcessingDeps.secretResolver`.
  */
 export interface SecretResolverApi {
-    resolveForJob(orgId: string, environmentName: string): Promise<Record<string, string>>;
+    resolveForJob(orgId: string, environmentName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
     resolveNamed(orgId: string, scope: string, key: string, opts?: {
         store?: string;
         runId?: string;
         jobId?: string;
     }): Promise<string | null>;
-    resolveForJobWithMeta(orgId: string, environmentName: string): Promise<Record<string, ResolvedSecretMeta>>;
+    resolveForJobWithMeta(orgId: string, environmentName: string, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
 }
 /**
  * Resolves secrets for a job by matching environment bindings against scoped secrets
@@ -98,9 +98,13 @@ export declare class SecretResolver implements SecretResolverApi {
      *
      * @param orgId - Organization ID
      * @param environmentName - Environment name to resolve secrets for
+     * @param hostCtx - Optional fan-out child identity for per-host resolution.
+     *   When supplied, each binding is gated by its `host_pattern` and its
+     *   `scope_pattern` is templated per-child; when omitted, only fleet-wide
+     *   (`'**'`) non-templated bindings contribute.
      * @returns Flat map of decrypted secret key-value pairs
      */
-    resolveForJob(orgId: string, environmentName: string): Promise<Record<string, string>>;
+    resolveForJob(orgId: string, environmentName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
     /**
      * Resolve a single named secret by (orgId, scope, key), optionally scoped to
      * a specific backend. Bypasses environment bindings — this is a direct
@@ -126,7 +130,7 @@ export declare class SecretResolver implements SecretResolverApi {
      *
      * Returns the secret value along with which backend and scope provided it.
      */
-    resolveForJobWithMeta(orgId: string, environmentName: string): Promise<Record<string, ResolvedSecretMeta>>;
+    resolveForJobWithMeta(orgId: string, environmentName: string, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
     /**
      * Collect all secrets from all backend stores, prefixing scopes.
      * Per /: unreachable backends are tracked but not fatal here.
@@ -145,8 +149,17 @@ export declare class SecretResolver implements SecretResolverApi {
      */
     private checkScopedFailure;
     /**
-     * Find the winning secret for a given key (highest scope depth after prefix strip).
+     * Find the winning secret for a given key, mirroring the engine scope
+     * resolver's host-aware matching and `(host specificity, scope depth)`
+     * precedence so the enriched metadata reports the same secret the flat
+     * resolution selected.
      */
     private findWinningSecret;
+    /**
+     * Resolve the effective scope pattern a binding contributes for a host,
+     * applying the host gate and per-child scope templating. Mirrors the engine
+     * scope resolver's `bindingScopeForHost`. Returns `null` to skip the binding.
+     */
+    private bindingScopeForHost;
 }
 //# sourceMappingURL=secret-resolver.d.ts.map