@kici-dev/orchestrator 0.1.21 → 0.1.23

package/dist/config.d.ts

@@ -68,6 +68,7 @@ declare const configSchema: z.ZodObject<{
     staleDetectorScanIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     staleDetectorThresholdMultiplier: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     jobHeartbeatIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    githubAppNameRefreshIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     secretKey: z.ZodOptional<z.ZodString>;
     secretKeyFile: z.ZodOptional<z.ZodString>;
     secretKeyOld: z.ZodOptional<z.ZodString>;
@@ -84,6 +85,8 @@ declare const configSchema: z.ZodObject<{
     agentTokenTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rosterGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rosterTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    hostRebootDeadlineMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    orchestratorHostAgentId: z.ZodOptional<z.ZodString>;
     maxFanoutHosts: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     eventRouterMaxChainDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     eventRouterRateLimitPerWorkflowPerMinute: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -197,11 +200,13 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     staleDetectorScanIntervalMs: number;
     staleDetectorThresholdMultiplier: number;
     jobHeartbeatIntervalMs: number;
+    githubAppNameRefreshIntervalMs: number;
     pgCustomerSecrets: boolean;
     agentAuth: "token" | "none";
     agentTokenTtlMs: number;
     rosterGraceMs: number;
     rosterTtlMs: number;
+    hostRebootDeadlineMs: number;
     maxFanoutHosts: number;
     eventRouterMaxChainDepth: number;
     eventRouterRateLimitPerWorkflowPerMinute: number;
@@ -265,6 +270,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     secretKeyOld?: string | undefined;
     secretKeyFileOld?: string | undefined;
     bootstrapAdminToken?: string | undefined;
+    orchestratorHostAgentId?: string | undefined;
     testEventFailFirstN?: string | undefined;
     otelExporterOtlpEndpoint?: string | undefined;
     clusterName?: string | undefined;

package/dist/dashboard/needs-edges.d.ts

@@ -1,13 +1,14 @@
-import { IfFailedPolicy } from '@kici-dev/engine';
+import type { ExecutionJobStatus } from '@kici-dev/engine';
 /** A single resolved upstream dependency edge for a job. */
 export interface JobNeedEdge {
     upstreamName: string;
-    ifFailed: IfFailedPolicy;
+    /** Upstream terminal statuses that satisfy this edge (the run-on set). */
+    runOn: ExecutionJobStatus[];
 }
 /** Group raw execution_job_needs rows by downstream job_name. */
 export declare function groupNeedsByJobName(rows: ReadonlyArray<{
     job_name: string;
     upstream_name: string;
-    if_failed: string;
+    run_on: string;
 }>): Map<string, JobNeedEdge[]>;
 //# sourceMappingURL=needs-edges.d.ts.map

package/dist/db/migrations/047_needs_run_on.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=047_needs_run_on.d.ts.map

package/dist/db/migrations/048_host_reboot_pending.d.ts

@@ -0,0 +1,19 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `host_roster.reboot_pending_until timestamptz NULL` — the persisted
+ * reboot-pending flag for workflow-level host restart.
+ *
+ * Set when an agent's `restartHost()` step calls `host.requestReboot` (so it
+ * survives an orchestrator restart during the host's reboot window). While the
+ * value is in the future it (1) makes the agent's imminent disconnect an
+ * expected reboot rather than a recovery-fail, (2) gates the pinned-drain off
+ * so the post-restart job is not dispatched into the about-to-reboot box, and
+ * (3) clears on the next reconnect (down-then-up), releasing the held job. NULL
+ * = no reboot pending.
+ *
+ * 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=048_host_reboot_pending.d.ts.map

package/dist/db/migrations/049_held_runs_payload.d.ts

@@ -0,0 +1,14 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `held_runs.payload jsonb NULL` — the drift payload captured when a
+ * `when: 'drift'` step-approval gate fires. Holds `{ summaryMarkdown, drift }`:
+ * the author's `summarize(drift)` rendering plus the structured drift blob, so
+ * the dashboard approval queue and the CLI render the computed diff the
+ * operator approves. NULL for every non-drift hold.
+ *
+ * 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=049_held_runs_payload.d.ts.map

package/dist/db/migrations/050_sources_slug.d.ts

@@ -0,0 +1,17 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `sources.slug TEXT NULL` — the GitHub App slug (the URL-safe identifier
+ * GitHub assigns, e.g. `my-kici-app`).
+ *
+ * For GitHub-App sources GitHub is the source of truth for both the display
+ * `name` and the `slug`: both are captured at creation and kept fresh by the
+ * daily refresher + `kici-admin source refresh`. NULL when the identity fetch
+ * hasn't populated it yet (manual `--app-id` flow whose initial fetch failed,
+ * or a row created before the rollout).
+ *
+ * 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=050_sources_slug.d.ts.map

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

@@ -1,5 +1,5 @@
 import type { ColumnType, Generated, Insertable, Selectable, Updateable } from 'kysely';
-import type { ApprovalRequirement, ApproverClause, InitFailure } from '@kici-dev/engine';
+import type { ApprovalRequirement, ApproverClause, InitFailure, StepApprovalPayload } from '@kici-dev/engine';
 /**
  * PostgreSQL-only database types.
  * Column names use snake_case matching the actual database column names.
@@ -486,8 +486,13 @@ export interface ExecutionJobNeedsTable {
     job_name: string;
     /** Upstream job name (the job that must complete first) */
     upstream_name: string;
-    /** Per-edge failure policy: 'skip' (default) or 'run' */
-    if_failed: Generated<string>;
+    /**
+     * Per-edge run-on status-set: a JSON-encoded array of upstream terminal
+     * statuses (ExecutionJobStatus[]) that satisfy the edge. Default
+     * `'["success"]'`. The downstream dispatches when the upstream's terminal
+     * status is a member of this set.
+     */
+    run_on: Generated<string>;
 }
 export type ExecutionJobNeeds = Selectable<ExecutionJobNeedsTable>;
 export type NewExecutionJobNeeds = Insertable<ExecutionJobNeedsTable>;
@@ -600,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>;
 }
@@ -695,7 +706,7 @@ export interface HeldRunsTable {
     step_index: number | null;
     /**
      * What created the hold: 'environment' (mandatory env policy) | 'explicit'
-     * (SDK `requireApproval`). Engine `TriggerSource`.
+     * (SDK `approval`). Engine `TriggerSource`.
      */
     trigger_source: Generated<string>;
     /**
@@ -703,6 +714,11 @@ export interface HeldRunsTable {
      * must satisfy. Null for legacy rows that predate the approval model.
      */
     approval_requirement: ColumnType<ApprovalRequirement | null, ApprovalRequirement | string | null | undefined, ApprovalRequirement | string | null>;
+    /**
+     * Drift payload `{ summaryMarkdown, drift }` captured when a `when: 'drift'`
+     * step-approval gate fires. Null for every non-drift hold.
+     */
+    payload: ColumnType<StepApprovalPayload | null, StepApprovalPayload | string | null | undefined, StepApprovalPayload | string | null>;
 }
 export type HeldRun = Selectable<HeldRunsTable>;
 export type NewHeldRun = Insertable<HeldRunsTable>;
@@ -853,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>;
@@ -1215,6 +1238,12 @@ export interface SourcesTable {
     routing_key: string;
     /** JSONB config (non-sensitive, e.g. { appId: '12345' }) */
     config: string;
+    /**
+     * GitHub App slug (the URL-safe identifier GitHub assigns, e.g.
+     * `my-kici-app`). NULL until the GitHub identity fetch populates it. GitHub
+     * is the source of truth for both `name` and `slug` on GitHub-App sources.
+     */
+    slug: string | null;
     /** Customer/org identifier for secret and environment scoping */
     customer_id: Generated<string>;
     /** When this source was created */
@@ -1616,6 +1645,23 @@ export interface HostRosterTable {
      */
     host_properties: ColumnType<Record<string, string | number | boolean>, Record<string, string | number | boolean> | string | undefined, Record<string, string | number | boolean> | string>;
     last_seen: ColumnType<Date, Date | string | undefined, Date | string>;
+    /**
+     * Reboot-pending flag for workflow-level host restart. When set to a future
+     * timestamp, the host's imminent disconnect is an expected reboot (not a
+     * recovery-fail) and its pinned post-restart job is held until the host
+     * 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/deployment/deployment-identity.d.ts

@@ -0,0 +1,9 @@
+import { type DeploymentIdentity } from '@kici-dev/engine';
+/**
+ * Read the orchestrator's deployment shape from the env the installer injects
+ * (`KICI_DEPLOY_MODE` / `KICI_DEPLOY_CONTAINER` / `KICI_DEPLOY_CONTAINER_RUNTIME`).
+ * Hand-run / dev orchestrators carry no `KICI_DEPLOY_*` env and report `unknown`.
+ * Container fields are kept only for the `compose` mode.
+ */
+export declare function readDeploymentIdentity(env?: NodeJS.ProcessEnv): DeploymentIdentity;
+//# sourceMappingURL=deployment-identity.d.ts.map

package/dist/entry-helpers.d.ts

@@ -19,6 +19,13 @@ export interface ProviderSource {
     routingKey: string;
     name: string;
     subtype: SourceSubtype;
+    /**
+     * GitHub App slug (URL-safe identifier GitHub assigns). Only set for
+     * GitHub-App sources, where it propagates orchestrator → Platform → dashboard
+     * alongside the display `name`. Undefined for generic / universal-git / local
+     * sources, and for a GitHub source whose identity fetch hasn't run yet.
+     */
+    slug?: string;
 }
 /**
  * Map a generic_webhook_sources `provider_type` (plus optional `git_config`

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

@@ -4,7 +4,7 @@
  * Manages the lifecycle: pending -> approved/rejected/expired.
  */
 import { type Kysely } from 'kysely';
-import { type ApprovalRequirement, type ApproverClause, ApprovalDecision, HoldScope, TriggerSource } from '@kici-dev/engine';
+import { type ApprovalRequirement, type ApproverClause, type StepApprovalPayload, ApprovalDecision, HoldScope, TriggerSource } from '@kici-dev/engine';
 import type { Database, HeldRun, HeldRunApproval } from '../db/types.js';
 /** Status values for held runs (held_runs table). */
 export declare enum HeldRunStatus {
@@ -51,6 +51,12 @@ export interface CreateHoldData {
      * the automated release sweeps can find their rows.
      */
     holdType?: string;
+    /**
+     * Drift payload `{ summaryMarkdown, drift }` captured for a `when: 'drift'`
+     * step gate; persisted to `held_runs.payload` and surfaced in the dashboard
+     * approval queue + the CLI. Omit for non-drift holds.
+     */
+    payload?: StepApprovalPayload;
 }
 /** A single decision to record against a hold. */
 export interface RecordDecisionData {
@@ -98,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/github-app-name-refresher/github-app-name-refresher.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Daily refresh of every GitHub source's display name + slug from GitHub.
+ *
+ * GitHub is the source of truth for a GitHub-App source's display name and
+ * slug. They are captured at creation, but an operator can rename the App in
+ * the GitHub UI afterwards — this periodic task re-fetches `GET /app` for each
+ * GitHub source and, when the name or slug drifted, writes the new values to
+ * the `sources` row. The `sources_change` DB trigger then fans the change out
+ * (SourceManager reload → `platformClient.updateSources()` → re-register), so
+ * the Platform `webhook_sources` row and the dashboard Sources tab pick up the
+ * new name/slug without any extra plumbing here.
+ *
+ * Lifecycle mirrors `StaleRunDetector`: `start()` runs an immediate refresh
+ * (so a rename made while the orchestrator was down propagates on next boot)
+ * then a `setInterval`; `stop()` clears it. Per-source errors are logged and
+ * never abort the loop.
+ */
+/** The slice of {@link SourceStore} this module needs. */
+export interface RefreshableSourceStore {
+    listSources(): Promise<Array<{
+        routing_key: string;
+        provider: string;
+        name: string;
+        slug: string | null;
+    }>>;
+    getSourceWithSecrets(routingKey: string): Promise<{
+        provider: string;
+        config: string;
+        privateKey: string;
+    } | null>;
+    updateSource(routingKey: string, updates: {
+        name?: string;
+        slug?: string | null;
+    }): Promise<unknown>;
+}
+/** Fetch a GitHub App's authoritative identity. Matches `fetchGithubAppIdentity`. */
+export type FetchGithubAppIdentity = (creds: {
+    appId: string;
+    privateKey: string;
+}) => Promise<{
+    name: string;
+    slug: string;
+}>;
+/** Outcome of a single source refresh. */
+export interface RefreshResult {
+    routingKey: string;
+    changed: boolean;
+    oldName: string;
+    newName: string;
+    oldSlug: string | null;
+    newSlug: string;
+}
+/**
+ * Re-fetch one GitHub source's identity from GitHub and persist it when the
+ * name or slug drifted. Shared by the daily task and `kici-admin source
+ * refresh`. Throws for a missing or non-GitHub routing key.
+ */
+export declare function refreshGithubSourceIdentity(sourceStore: RefreshableSourceStore, routingKey: string, fetchIdentity: FetchGithubAppIdentity): Promise<RefreshResult>;
+export interface GithubAppNameRefresherDeps {
+    sourceStore: RefreshableSourceStore;
+    fetchIdentity: FetchGithubAppIdentity;
+    /** Refresh cadence in ms. Default cluster value: 24h (`config.githubAppNameRefreshIntervalMs`). */
+    scanIntervalMs: number;
+}
+export declare class GithubAppNameRefresher {
+    private readonly sourceStore;
+    private readonly fetchIdentity;
+    private readonly scanIntervalMs;
+    private interval;
+    constructor(deps: GithubAppNameRefresherDeps);
+    /** Immediate refresh then periodic scans. */
+    start(): Promise<void>;
+    stop(): void;
+    /** Refresh every GitHub source once. Per-source failures are isolated. */
+    refresh(): Promise<void>;
+}
+//# sourceMappingURL=github-app-name-refresher.d.ts.map

package/dist/index.js

@@ -1892,6 +1892,23 @@ function createInstallationOctokit(config, installationId) {
 * registration and returns it on the conversion response, so both GitHub and
 * the Platform end up sharing the same secret with zero operator effort.
 */
+/**
+* Validate a self-hosted webhook URL supplied via `source add github
+* --webhook-url`. Must be a well-formed absolute `https://` URL. Returns the URL
+* verbatim on success; throws a clear error otherwise. The validated URL is
+* baked into `manifest.hook_attributes.url` as-is — KiCI adds no ingress and
+* does not receive events at it; the operator owns delivery.
+*/
+function validateWebhookUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error(`--webhook-url must be a valid absolute URL: ${value}`);
+	}
+	if (url.protocol !== "https:") throw new Error(`--webhook-url must be an https:// URL (got ${url.protocol}//…)`);
+	return value;
+}
 function buildGithubAppManifest(input) {
 	return {
 		name: input.name,
@@ -1930,6 +1947,7 @@ async function convertManifestCode(code, deps = {}) {
 	return {
 		appId: String(d.id),
 		slug: d.slug,
+		name: d.name,
 		privateKey: d.pem,
 		webhookSecret: d.webhook_secret,
 		clientId: d.client_id,
@@ -2178,7 +2196,8 @@ async function storeAndRegister(opts, client, deps, creds) {
 	try {
 		return await client.post("/api/v1/admin/sources", {
 			provider: "github",
-			name: opts.name,
+			name: creds.name,
+			slug: creds.slug,
 			appId: creds.appId,
 			privateKey: creds.privateKey,
 			webhookSecret: creds.webhookSecret
@@ -2195,7 +2214,7 @@ async function storeAndRegister(opts, client, deps, creds) {
 	}
 }
 async function runGithubManifestSetup(opts, client, deps = realManifestSetupDeps) {
-	const webhookUrl = await resolveWebhookUrl(client);
+	const webhookUrl = opts.webhookUrl ? validateWebhookUrl(opts.webhookUrl) : await resolveWebhookUrl(client);
 	const state = randomBytes(16).toString("hex");
 	const createUrl = manifestCreateUrl(opts.githubOrg);
 	const loopback = await deps.startLoopback({

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/orchestrator-core.d.ts

@@ -23,7 +23,7 @@ import { DedupCache } from './webhook/dedup.js';
 import { ObserverRegistry } from './ws/observer-registry.js';
 import { AgentMetricsAggregator } from './metrics/agent-metrics-aggregator.js';
 import { SourceLocationStore } from './app.js';
-import { type LabelMatcher, type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage } from '@kici-dev/engine';
+import { ExecutionJobStatus, type LabelMatcher, type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage } from '@kici-dev/engine';
 import { ScalerManager } from './scaler/index.js';
 import type { ScalerConfig } from './scaler/index.js';
 import type { CacheStorage } from './storage/index.js';
@@ -253,6 +253,17 @@ export declare function buildUpstreamOutputsByBase(baseNames: string[], rows: Ar
     variant_label?: string | null;
     status?: string | null;
 }>): Record<string, Record<string, unknown>> | undefined;
+/**
+ * Build the downstream `upstreamJobStatuses` map keyed by each upstream job
+ * row's name. A single non-fanned upstream is keyed by its base name; a
+ * fanned-out upstream contributes one entry per expanded child name (`base
+ * (child)`). The agent uses this to stamp `ctx.needs.<job>.status` (single) and
+ * the per-child status of group / matrix / host-fanout entries.
+ */
+export declare function buildUpstreamStatusesByBase(rows: Array<{
+    job_name: string;
+    status?: string | null;
+}>): Record<string, ExecutionJobStatus> | undefined;
 /**
  * Fold a `runsOnAll` upstream's host children into the `byHost` envelope
  * `{ byHost: { '<host>': outputs }, summary: { succeededHosts, failedHosts, outputs } }`.
@@ -302,6 +313,7 @@ export declare function buildMatrixOutputsEnvelope(baseName: string, children: A
 export declare function mergeUpstreamOutputs(db: Kysely<Database>, runId: string, jobName: string, needs: unknown, dispatchSecrets: Record<string, string> | undefined, secretKey: string): Promise<{
     mergedSecrets: Record<string, string> | undefined;
     upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined;
+    upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined;
 }>;
 export declare function bootstrapOrchestrator(config: AppConfig, hooks: OrchestratorHooks, options?: {
     otelSdk?: {

package/dist/pipeline/decorating-secret-resolver.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI-secret overlay for `kici run` test dispatch.
+ *
+ * Wraps the orchestrator's environment `SecretResolver` and overlays the
+ * developer's CLI-uploaded local secrets on top of the env-resolved secrets,
+ * with CLI winning on collision. Passed to the shared dispatch core via
+ * `ProcessingDeps.secretResolver`, so the core's secret-resolution path is
+ * unchanged and oblivious to "test secrets".
+ *
+ * Precedence: env-resolved secrets → CLI context for the requested environment
+ * → CLI flat. The CLI flat overlay is applied last so a CLI flat key always
+ * wins.
+ */
+import type { SecretResolverApi, ResolvedSecretMeta } from '../secrets/secret-resolver.js';
+/** Decrypted CLI-uploaded local secrets: flat keys + per-context namespaces. */
+export interface CliSecrets {
+    flat: Record<string, string>;
+    contexts: Record<string, Record<string, string>>;
+}
+export declare class DecoratingSecretResolver implements SecretResolverApi {
+    private readonly base;
+    private readonly cli;
+    constructor(base: SecretResolverApi, cli: CliSecrets);
+    resolveForJob(orgId: string, environmentName: string): 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>>;
+}
+//# sourceMappingURL=decorating-secret-resolver.d.ts.map