@kici-dev/orchestrator 0.1.16 → 0.1.18

package/dist/cli.js

@@ -3,9 +3,9 @@ import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import * as path$1 from "node:path";
 import path, { join, resolve } from "node:path";
-import { Command } from "commander";
 import * as fs$1 from "node:fs";
-import fs, { closeSync, createReadStream, createWriteStream, existsSync, openSync, promises, readFileSync, statSync, unwatchFile, watchFile, writeFileSync } from "node:fs";
+import fs, { chmodSync, closeSync, createReadStream, createWriteStream, existsSync, openSync, promises, readFileSync, realpathSync, statSync, unwatchFile, watchFile, writeFileSync } from "node:fs";
+import { Command } from "commander";
 import { BaseColdStore, ChunkLru, addLogsToArchive, chunkObjectKey, clearDispatchQueueDirect, computeChunkId, computeMigrationsHash, createDb, createDbRole, createEnvironmentTemplateDirect, createLogger, createPool, createReadOnlyDbUser, decodeChunk, deleteEnvironmentDirect, dropAndCreateDatabase, emitKiciEventDirect, encodeKeySegment, ensureDatabase, formatBytes, formatUptime, isSchemaCurrent, listEnvironmentsDirect, listExecutionRunsDirect, listQueueDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, parseManifest, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, registerWorkflowManualDirect, resetRaftStateDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, sha256, showEnvironmentDirect, showExecutionRunDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, tablePrefix, toErrorMessage } from "@kici-dev/shared";
 import crypto, { createDecipheriv, createHash, hkdfSync, randomBytes, randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
@@ -19,14 +19,14 @@ import { Migrator } from "kysely/migration";
 import "jsonpath-plus";
 import { execFile, execFileSync, execSync, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import archiver from "archiver";
+import { ZipArchive } from "archiver";
 import { confirm, input, password, select } from "@inquirer/prompts";
 import JSZip from "jszip";
 import { pipeline } from "node:stream/promises";
 import "pg";
+import { KICI_AGENT_ENV_PREFIX, KNOWN_ROLES, ScalerBackendType, ScalerEventType, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES, WS_MAX_PAYLOAD_BYTES, accessLogWarmSqlCase, getAccessLogColdDays, getSecretAuditLogColdDays, matcherSatisfiedBy, minAccessLogWarmDays, minSecretAuditLogWarmDays, scalerAgentLabels, secretAuditLogWarmSqlCase } from "@kici-dev/engine";
 import { DASHBOARD_WRITE_OPERATIONS, DASHBOARD_WRITE_OPERATIONS_BY_NAME, DashboardWriteCategory, DashboardWriteSensitivity } from "@kici-dev/engine/protocol/dashboard-write-operations";
 import { CLUSTER_NAME_FORMAT_MESSAGE } from "@kici-dev/engine/protocol/cluster-name";
-import { KICI_AGENT_ENV_PREFIX, KNOWN_ROLES, ScalerBackendType, ScalerEventType, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES, WS_MAX_PAYLOAD_BYTES, accessLogWarmSqlCase, getAccessLogColdDays, getSecretAuditLogColdDays, minAccessLogWarmDays, minSecretAuditLogWarmDays, scalerAgentLabels, secretAuditLogWarmSqlCase } from "@kici-dev/engine";
 import http from "node:http";
 import { PassThrough } from "node:stream";
 import Docker from "dockerode";
@@ -52,6 +52,8 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 * error formatting, and URL construction.
 */
 var AdminApiClient = class {
+	baseUrl;
+	token;
 	constructor(baseUrl, token) {
 		this.baseUrl = baseUrl;
 		this.token = token;
@@ -977,6 +979,8 @@ var init_schema = __esmMin((() => {
 		}).optional(),
 		agentAuth: z.enum(["token", "none"]).optional(),
 		agentTokenTtlMs: z.coerce.number().optional(),
+		rosterGraceMs: z.coerce.number().optional(),
+		rosterTtlMs: z.coerce.number().optional(),
 		queue: z.object({
 			maxDepth: z.coerce.number().optional(),
 			timeoutMs: z.coerce.number().optional(),
@@ -1053,6 +1057,8 @@ var init_schema = __esmMin((() => {
 		}).optional(),
 		agentAuth: z.enum(["token", "none"]).default("token"),
 		agentTokenTtlMs: z.coerce.number().default(36e5),
+		rosterGraceMs: z.coerce.number().default(3e5),
+		rosterTtlMs: z.coerce.number().default(18e5),
 		queueMaxDepth: z.coerce.number().default(1e3),
 		queueTimeoutMs: z.coerce.number().default(36e5),
 		/**
@@ -1548,8 +1554,8 @@ var init_client = __esmMin((() => {
 //#region src/db/migrations/001_initial.ts
 init_client();
 var _001_initial_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$33,
-	up: () => up$33
+	down: () => down$41,
+	up: () => up$41
 });
 /**
 * Squashed initial migration -- creates the complete Orchestrator database schema.
@@ -2241,7 +2247,7 @@ const DDL_STATEMENTS = [
 	`ALTER TABLE ONLY public.held_runs
     ADD CONSTRAINT held_runs_environment_id_fkey FOREIGN KEY (environment_id) REFERENCES public.environments(id);`
 ];
-async function up$33(db) {
+async function up$41(db) {
 	for (const stmt of DDL_STATEMENTS) await sql.raw(stmt).execute(db);
 	await sql`
     INSERT INTO cluster_meta (key, value)
@@ -2263,7 +2269,7 @@ async function up$33(db) {
 * Rollback drops everything created above. Uses CASCADE on table drops to cut
 * through the FK graph without relying on exact topological order.
 */
-async function down$33(db) {
+async function down$41(db) {
 	for (const [trig, tbl] of [["source_secrets_change_trigger", "scoped_secrets"], ["sources_change_trigger", "sources"]]) await sql.raw(`DROP TRIGGER IF EXISTS ${trig} ON public.${tbl}`).execute(db);
 	for (const table of [
 		"workflow_registrations",
@@ -2310,8 +2316,8 @@ async function down$33(db) {
 //#endregion
 //#region src/db/migrations/002_config_versions_key_version.ts
 var _002_config_versions_key_version_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$32,
-	up: () => up$32
+	down: () => down$40,
+	up: () => up$40
 });
 /**
 * Add key_version column to config_versions so that sensitive-field encryption
@@ -2325,13 +2331,13 @@ var _002_config_versions_key_version_exports = /* @__PURE__ */ __exportAll({
 * No index is needed: rotation does a full-table scan; reads are by
 * `version` primary key and never filter on `key_version`.
 */
-async function up$32(db) {
+async function up$40(db) {
 	await sql`
     ALTER TABLE public.config_versions
       ADD COLUMN key_version integer NOT NULL DEFAULT 1
   `.execute(db);
 }
-async function down$32(db) {
+async function down$40(db) {
 	await sql`
     ALTER TABLE public.config_versions
       DROP COLUMN key_version
@@ -2340,8 +2346,8 @@ async function down$32(db) {
 //#endregion
 //#region src/db/migrations/003_access_log.ts
 var _003_access_log_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$31,
-	up: () => up$31
+	down: () => down$39,
+	up: () => up$39
 });
 /**
 * Access log: one row per read or orchestrator-admin mutation attributable
@@ -2365,7 +2371,7 @@ var _003_access_log_exports = /* @__PURE__ */ __exportAll({
 * Retention is TTL-based via expires_at; packages/orchestrator/src/queue/
 * cleanup.ts picks up the prune pass.
 */
-async function up$31(db) {
+async function up$39(db) {
 	await sql`
     CREATE TABLE public.access_log (
       id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -2403,28 +2409,28 @@ async function up$31(db) {
       ON public.access_log (actor_type, actor_id, created_at DESC)
   `.execute(db);
 }
-async function down$31(db) {
+async function down$39(db) {
 	await sql`DROP TABLE IF EXISTS public.access_log`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/004_rename_bundle_to_source.ts
 var _004_rename_bundle_to_source_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$30,
-	up: () => up$30
+	down: () => down$38,
+	up: () => up$38
 });
-async function up$30(db) {
+async function up$38(db) {
 	await db.schema.alterTable("dispatch_queue").renameColumn("bundle_url", "source_tar_url").execute();
 	await db.schema.alterTable("dispatch_queue").renameColumn("bundle_hash", "source_tar_hash").execute();
 }
-async function down$30(db) {
+async function down$38(db) {
 	await db.schema.alterTable("dispatch_queue").renameColumn("source_tar_url", "bundle_url").execute();
 	await db.schema.alterTable("dispatch_queue").renameColumn("source_tar_hash", "bundle_hash").execute();
 }
 //#endregion
 //#region src/db/migrations/005_cold_store_chunk_counter.ts
 var _005_cold_store_chunk_counter_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$29,
-	up: () => up$29
+	down: () => down$37,
+	up: () => up$37
 });
 /**
 * Cold-store chunk counter table.
@@ -2441,7 +2447,7 @@ var _005_cold_store_chunk_counter_exports = /* @__PURE__ */ __exportAll({
 *
 * sections 5 and 8.
 */
-async function up$29(db) {
+async function up$37(db) {
 	await sql`
     CREATE TABLE public.cold_store_chunk_counts (
       db                TEXT        NOT NULL,
@@ -2459,14 +2465,14 @@ async function up$29(db) {
       ON public.cold_store_chunk_counts (db, table_name)
   `.execute(db);
 }
-async function down$29(db) {
+async function down$37(db) {
 	await sql`DROP TABLE IF EXISTS public.cold_store_chunk_counts`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/006_runs_jobs_steps_archived_at.ts
 var _006_runs_jobs_steps_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$28,
-	up: () => up$28
+	down: () => down$36,
+	up: () => up$36
 });
 /**
 * `execution_runs` / `execution_jobs` / `execution_steps` cold-store
@@ -2502,7 +2508,7 @@ var _006_runs_jobs_steps_archived_at_exports = /* @__PURE__ */ __exportAll({
 *   - `idx_execution_jobs_routing_key_created  (routing_key, created_at)`
 *   - `idx_execution_steps_routing_key_created (routing_key, created_at)`
 */
-async function up$28(db) {
+async function up$36(db) {
 	await sql`
     ALTER TABLE public.execution_runs
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2547,7 +2553,7 @@ async function up$28(db) {
       ON public.execution_steps (routing_key, created_at)
   `.execute(db);
 }
-async function down$28(db) {
+async function down$36(db) {
 	await sql`DROP INDEX IF EXISTS public.idx_execution_steps_routing_key_created`.execute(db);
 	await sql`
     ALTER TABLE public.execution_steps
@@ -2572,8 +2578,8 @@ async function down$28(db) {
 //#endregion
 //#region src/db/migrations/007_audit_logs_archived_at.ts
 var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$27,
-	up: () => up$27
+	down: () => down$35,
+	up: () => up$35
 });
 /**
 * `secret_audit_log` and `access_log` cold-store schema additions, plus
@@ -2613,7 +2619,7 @@ var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
 * `down()` would not have meaningful retention bounds. Acceptable for
 * staging.
 */
-async function up$27(db) {
+async function up$35(db) {
 	await sql`
     ALTER TABLE public.secret_audit_log
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2634,7 +2640,7 @@ async function up$27(db) {
       DROP COLUMN IF EXISTS expires_at
   `.execute(db);
 }
-async function down$27(db) {
+async function down$35(db) {
 	await sql`
     ALTER TABLE public.access_log
       ADD COLUMN expires_at TIMESTAMPTZ NOT NULL DEFAULT (now() + INTERVAL '90 days')
@@ -2662,8 +2668,8 @@ async function down$27(db) {
 //#endregion
 //#region src/db/migrations/008_event_log_archived_at.ts
 var _008_event_log_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$26,
-	up: () => up$26
+	down: () => down$34,
+	up: () => up$34
 });
 /**
 * `event_log` cold-store schema additions plus removal of the
@@ -2701,7 +2707,7 @@ var _008_event_log_archived_at_exports = /* @__PURE__ */ __exportAll({
 * — best effort; rows inserted between `up()` and a hypothetical
 * `down()` would not have meaningful retention bounds.
 */
-async function up$26(db) {
+async function up$34(db) {
 	await sql`
     ALTER TABLE public.event_log
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2717,7 +2723,7 @@ async function up$26(db) {
       DROP COLUMN IF EXISTS expires_at
   `.execute(db);
 }
-async function down$26(db) {
+async function down$34(db) {
 	await sql`
     ALTER TABLE public.event_log
       ADD COLUMN expires_at TIMESTAMPTZ NOT NULL DEFAULT (now() + INTERVAL '30 days')
@@ -2736,8 +2742,8 @@ async function down$26(db) {
 //#endregion
 //#region src/db/migrations/009_access_log_trigram.ts
 var _009_access_log_trigram_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$25,
-	up: () => up$25
+	down: () => down$33,
+	up: () => up$33
 });
 /**
 * Trigram (pg_trgm) index on access_log.error_message for the federated
@@ -2750,7 +2756,7 @@ var _009_access_log_trigram_exports = /* @__PURE__ */ __exportAll({
 * EXISTS` are both safe to re-run. No CONCURRENTLY because Kysely runs
 * migrations inside a transaction; the lock is brief on a sampled table.
 */
-async function up$25(db) {
+async function up$33(db) {
 	await sql`CREATE EXTENSION IF NOT EXISTS pg_trgm`.execute(db);
 	await sql`
     CREATE INDEX IF NOT EXISTS access_log_error_message_trgm_idx
@@ -2759,14 +2765,14 @@ async function up$25(db) {
       WHERE error_message IS NOT NULL
   `.execute(db);
 }
-async function down$25(db) {
+async function down$33(db) {
 	await sql`DROP INDEX IF EXISTS public.access_log_error_message_trgm_idx`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/010_cold_store_chunks.ts
 var _010_cold_store_chunks_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$24,
-	up: () => up$24
+	down: () => down$32,
+	up: () => up$32
 });
 /**
 * Cold-store chunk index — Phase 2 (cold-store purge).
@@ -2798,7 +2804,7 @@ var _010_cold_store_chunks_exports = /* @__PURE__ */ __exportAll({
 * forever. Adapters that don't opt into per-bucket archival via
 * `coldTtlDays` don't insert here either.
 */
-async function up$24(db) {
+async function up$32(db) {
 	await sql`
     CREATE TABLE public.cold_store_chunks (
       db              TEXT        NOT NULL,
@@ -2825,14 +2831,14 @@ async function up$24(db) {
       ON public.cold_store_chunks (db, table_name, tenant_id, archived_at DESC)
   `.execute(db);
 }
-async function down$24(db) {
+async function down$32(db) {
 	await sql`DROP TABLE IF EXISTS public.cold_store_chunks`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/011_drop_source_secrets_notify.ts
 var _011_drop_source_secrets_notify_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$23,
-	up: () => up$23
+	down: () => down$31,
+	up: () => up$31
 });
 /**
 * Drop the `source_secrets_change_trigger` and the
@@ -2851,11 +2857,11 @@ var _011_drop_source_secrets_notify_exports = /* @__PURE__ */ __exportAll({
 * in `001_initial.ts`. They wake up no consumer until the `WebhookSecretManager`
 * is restored, so this migration is safe to roll back.
 */
-async function up$23(db) {
+async function up$31(db) {
 	await sql`DROP TRIGGER IF EXISTS source_secrets_change_trigger ON public.scoped_secrets`.execute(db);
 	await sql`DROP FUNCTION IF EXISTS public.notify_source_secrets_change() CASCADE`.execute(db);
 }
-async function down$23(db) {
+async function down$31(db) {
 	await sql`
     CREATE OR REPLACE FUNCTION public.notify_source_secrets_change() RETURNS trigger
       LANGUAGE plpgsql
@@ -2894,8 +2900,8 @@ async function down$23(db) {
 //#endregion
 //#region src/db/migrations/012_peer_credentials_active_uniq.ts
 var _012_peer_credentials_active_uniq_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$22,
-	up: () => up$22
+	down: () => down$30,
+	up: () => up$30
 });
 /**
 * Add a partial unique index on `peer_credentials (instance_id) WHERE
@@ -2921,7 +2927,7 @@ var _012_peer_credentials_active_uniq_exports = /* @__PURE__ */ __exportAll({
 * `down()` only drops the index; it does NOT undo the dedupe (there's no
 * safe way to recreate revoked rows, and the dedupe is monotonic).
 */
-async function up$22(db) {
+async function up$30(db) {
 	await sql`
     UPDATE public.peer_credentials
     SET revoked_at = NOW()
@@ -2939,14 +2945,14 @@ async function up$22(db) {
       WHERE revoked_at IS NULL
   `.execute(db);
 }
-async function down$22(db) {
+async function down$30(db) {
 	await sql`DROP INDEX IF EXISTS public.peer_credentials_active_uniq`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/013_execution_log_bytes.ts
 var _013_execution_log_bytes_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$21,
-	up: () => up$21
+	down: () => down$29,
+	up: () => up$29
 });
 /**
 * Add `log_bytes BIGINT NOT NULL DEFAULT 0` columns to `execution_runs` and
@@ -2965,7 +2971,7 @@ var _013_execution_log_bytes_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent (`ADD COLUMN IF NOT EXISTS`).
 */
-async function up$21(db) {
+async function up$29(db) {
 	await sql`
     ALTER TABLE public.execution_runs
       ADD COLUMN IF NOT EXISTS log_bytes BIGINT NOT NULL DEFAULT 0
@@ -2975,15 +2981,15 @@ async function up$21(db) {
       ADD COLUMN IF NOT EXISTS log_bytes BIGINT NOT NULL DEFAULT 0
   `.execute(db);
 }
-async function down$21(db) {
+async function down$29(db) {
 	await sql`ALTER TABLE public.execution_runs DROP COLUMN IF EXISTS log_bytes`.execute(db);
 	await sql`ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS log_bytes`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/014_kici_events_lease_retry.ts
 var _014_kici_events_lease_retry_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$20,
-	up: () => up$20
+	down: () => down$28,
+	up: () => up$28
 });
 /**
 * Add lease + retry + DLQ columns to `kici_events` so the EventRouter can
@@ -3017,7 +3023,7 @@ var _014_kici_events_lease_retry_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent (`ADD COLUMN IF NOT EXISTS` + `CREATE INDEX IF NOT EXISTS`).
 */
-async function up$20(db) {
+async function up$28(db) {
 	await sql`
     ALTER TABLE public.kici_events
       ADD COLUMN IF NOT EXISTS claimed_at TIMESTAMPTZ,
@@ -3048,7 +3054,7 @@ async function up$20(db) {
       WHERE dlq_at IS NOT NULL
   `.execute(db);
 }
-async function down$20(db) {
+async function down$28(db) {
 	await sql`DROP INDEX IF EXISTS public.idx_kici_events_dlq`.execute(db);
 	await sql`DROP INDEX IF EXISTS public.idx_kici_events_lease_expired`.execute(db);
 	await sql`DROP INDEX IF EXISTS public.idx_kici_events_retry_due`.execute(db);
@@ -3066,8 +3072,8 @@ async function down$20(db) {
 //#endregion
 //#region src/db/migrations/015_org_settings_customer_scoped.ts
 var _015_org_settings_customer_scoped_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$19,
-	up: () => up$19
+	down: () => down$27,
+	up: () => up$27
 });
 /**
 * Org-scope `org_settings` and qualify each glob entry by source.
@@ -3095,7 +3101,7 @@ var _015_org_settings_customer_scoped_exports = /* @__PURE__ */ __exportAll({
 * Idempotent: a re-run on an already-migrated DB sees `customer_id` exists
 * and the list columns are already jsonb, so it is a no-op.
 */
-async function up$19(db) {
+async function up$27(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3220,7 +3226,7 @@ async function up$19(db) {
 	await sql`DROP TABLE _org_settings_merged`.execute(db);
 	await sql`DROP TABLE _org_settings_stage`.execute(db);
 }
-async function down$19(db) {
+async function down$27(db) {
 	if (!(await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3245,8 +3251,8 @@ async function down$19(db) {
 //#endregion
 //#region src/db/migrations/016_org_settings_allow_http_npm.ts
 var _016_org_settings_allow_http_npm_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$18,
-	up: () => up$18
+	down: () => down$26,
+	up: () => up$26
 });
 /**
 * Add `org_settings.allow_http_npm_registries boolean NOT NULL DEFAULT false`.
@@ -3259,7 +3265,7 @@ var _016_org_settings_allow_http_npm_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: a re-run on a DB that already has the column is a no-op.
 */
-async function up$18(db) {
+async function up$26(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3273,7 +3279,7 @@ async function up$18(db) {
       ADD COLUMN allow_http_npm_registries boolean NOT NULL DEFAULT false
   `.execute(db);
 }
-async function down$18(db) {
+async function down$26(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS allow_http_npm_registries
   `.execute(db);
@@ -3281,8 +3287,8 @@ async function down$18(db) {
 //#endregion
 //#region src/db/migrations/017_org_id_widen.ts
 var _017_org_id_widen_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$17,
-	up: () => up$17
+	down: () => down$25,
+	up: () => up$25
 });
 /**
 * Widen every orchestrator-side `org_id varchar(12)` column to
@@ -3322,17 +3328,17 @@ const ORG_ID_TABLES$1 = [
 	"held_runs",
 	"scoped_secrets"
 ];
-async function up$17(db) {
+async function up$25(db) {
 	for (const table of ORG_ID_TABLES$1) await sql.raw(`ALTER TABLE public.${table} ALTER COLUMN org_id TYPE varchar(16)`).execute(db);
 }
-async function down$17(db) {
+async function down$25(db) {
 	for (const table of ORG_ID_TABLES$1) await sql.raw(`ALTER TABLE public.${table} ALTER COLUMN org_id TYPE varchar(12)`).execute(db);
 }
 //#endregion
 //#region src/db/migrations/018_org_id_prefix_backfill.ts
 var _018_org_id_prefix_backfill_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$16,
-	up: () => up$16
+	down: () => down$24,
+	up: () => up$24
 });
 /**
 * Prefix every orchestrator-side tenant string with `org_` to align
@@ -3377,19 +3383,19 @@ const CUSTOMER_ID_TABLES = [
 	"workflow_registrations",
 	"org_settings"
 ];
-async function up$16(db) {
+async function up$24(db) {
 	for (const table of ORG_ID_TABLES) await sql.raw(`UPDATE public.${table} SET org_id = 'org_' || org_id WHERE org_id <> 'kici-admin' AND org_id NOT LIKE 'org\\_%' ESCAPE '\\'`).execute(db);
 	for (const table of CUSTOMER_ID_TABLES) await sql.raw(`UPDATE public.${table} SET customer_id = 'org_' || customer_id WHERE customer_id <> 'kici-admin' AND customer_id NOT LIKE 'org\\_%' ESCAPE '\\'`).execute(db);
 }
-async function down$16(db) {
+async function down$24(db) {
 	for (const table of CUSTOMER_ID_TABLES) await sql.raw(`UPDATE public.${table} SET customer_id = substring(customer_id from 5) WHERE customer_id LIKE 'org\\_%' ESCAPE '\\'`).execute(db);
 	for (const table of ORG_ID_TABLES) await sql.raw(`UPDATE public.${table} SET org_id = substring(org_id from 5) WHERE org_id LIKE 'org\\_%' ESCAPE '\\'`).execute(db);
 }
 //#endregion
 //#region src/db/migrations/019_generic_sources_change_notify.ts
 var _019_generic_sources_change_notify_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$15,
-	up: () => up$15
+	down: () => down$23,
+	up: () => up$23
 });
 /**
 * Add a Postgres trigger on `generic_webhook_sources` that emits
@@ -3412,7 +3418,7 @@ var _019_generic_sources_change_notify_exports = /* @__PURE__ */ __exportAll({
 * (`notify_sources_change()` + `sources_change_trigger`, defined in
 * `001_initial.ts`).
 */
-async function up$15(db) {
+async function up$23(db) {
 	await sql`
     CREATE FUNCTION public.notify_generic_sources_change() RETURNS trigger
       LANGUAGE plpgsql
@@ -3433,15 +3439,15 @@ async function up$15(db) {
       FOR EACH ROW EXECUTE FUNCTION public.notify_generic_sources_change()
   `.execute(db);
 }
-async function down$15(db) {
+async function down$23(db) {
 	await sql`DROP TRIGGER IF EXISTS generic_sources_change_trigger ON public.generic_webhook_sources`.execute(db);
 	await sql`DROP FUNCTION IF EXISTS public.notify_generic_sources_change()`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/020_org_settings_dashboard_write_policy.ts
 var _020_org_settings_dashboard_write_policy_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$14,
-	up: () => up$14
+	down: () => down$22,
+	up: () => up$22
 });
 /**
 * Add `org_settings.dashboard_write_policy jsonb NOT NULL DEFAULT '{}'`.
@@ -3456,7 +3462,7 @@ var _020_org_settings_dashboard_write_policy_exports = /* @__PURE__ */ __exportA
 *
 * Idempotent: a re-run on a DB that already has the column is a no-op.
 */
-async function up$14(db) {
+async function up$22(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3470,7 +3476,7 @@ async function up$14(db) {
       ADD COLUMN dashboard_write_policy jsonb NOT NULL DEFAULT '{}'::jsonb
   `.execute(db);
 }
-async function down$14(db) {
+async function down$22(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS dashboard_write_policy
   `.execute(db);
@@ -3478,8 +3484,8 @@ async function down$14(db) {
 //#endregion
 //#region src/db/migrations/021_check_run_tracking.ts
 var _021_check_run_tracking_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$13,
-	up: () => up$13
+	down: () => down$21,
+	up: () => up$21
 });
 /**
 * Add `check_run_tracking` table for HA-safe check-run state persistence.
@@ -3503,7 +3509,7 @@ var _021_check_run_tracking_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: a re-run on a DB that already has the table is a no-op.
 */
-async function up$13(db) {
+async function up$21(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.tables
@@ -3534,14 +3540,14 @@ async function up$13(db) {
       WHERE run_id IS NOT NULL
   `.execute(db);
 }
-async function down$13(db) {
+async function down$21(db) {
 	await sql`DROP TABLE IF EXISTS public.check_run_tracking`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/022_scaler_manager_state.ts
 var _022_scaler_manager_state_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$12,
-	up: () => up$12
+	down: () => down$20,
+	up: () => up$20
 });
 /**
 * Add three tables persisting `ScalerManager` per-coord state:
@@ -3568,7 +3574,7 @@ var _022_scaler_manager_state_exports = /* @__PURE__ */ __exportAll({
 * Idempotent: a re-run on a DB that already has any of these tables
 * leaves the existing one alone.
 */
-async function up$12(db) {
+async function up$20(db) {
 	const tableExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3618,7 +3624,7 @@ async function up$12(db) {
     `.execute(db);
 	}
 }
-async function down$12(db) {
+async function down$20(db) {
 	await sql`DROP TABLE IF EXISTS public.scaler_reservations`.execute(db);
 	await sql`DROP TABLE IF EXISTS public.scaler_agent_jobs`.execute(db);
 	await sql`DROP TABLE IF EXISTS public.scaler_spawning_agents`.execute(db);
@@ -3626,8 +3632,8 @@ async function down$12(db) {
 //#endregion
 //#region src/db/migrations/023_dispatch_queue_recovery_deadline.ts
 var _023_dispatch_queue_recovery_deadline_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$11,
-	up: () => up$11
+	down: () => down$19,
+	up: () => up$19
 });
 /**
 * Add `dispatch_queue.recovery_deadline TIMESTAMPTZ` and
@@ -3651,7 +3657,7 @@ var _023_dispatch_queue_recovery_deadline_exports = /* @__PURE__ */ __exportAll(
 * Idempotent: re-running on a DB that already has either column is a
 * no-op.
 */
-async function up$11(db) {
+async function up$19(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3676,7 +3682,7 @@ async function up$11(db) {
       WHERE recovery_deadline IS NOT NULL
   `.execute(db);
 }
-async function down$11(db) {
+async function down$19(db) {
 	await sql`DROP INDEX IF EXISTS public.idx_dispatch_queue_recovery_deadline`.execute(db);
 	await sql`
     ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS recovery_agent_id
@@ -3688,8 +3694,8 @@ async function down$11(db) {
 //#endregion
 //#region src/db/migrations/024_dispatch_queue_provisioning_error.ts
 var _024_dispatch_queue_provisioning_error_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$10,
-	up: () => up$10
+	down: () => down$18,
+	up: () => up$18
 });
 /**
 * Add `dispatch_queue.last_provisioning_error TEXT` recording the most
@@ -3705,7 +3711,7 @@ var _024_dispatch_queue_provisioning_error_exports = /* @__PURE__ */ __exportAll
 *
 * Idempotent: re-running on a DB that already has the column is a no-op.
 */
-async function up$10(db) {
+async function up$18(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3721,7 +3727,7 @@ async function up$10(db) {
         ADD COLUMN last_provisioning_error TEXT
     `.execute(db);
 }
-async function down$10(db) {
+async function down$18(db) {
 	await sql`
     ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS last_provisioning_error
   `.execute(db);
@@ -3729,8 +3735,8 @@ async function down$10(db) {
 //#endregion
 //#region src/db/migrations/025_init_failure.ts
 var _025_init_failure_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$9,
-	up: () => up$9
+	down: () => down$17,
+	up: () => up$17
 });
 /**
 * Add `init_failure jsonb` columns to `execution_runs` and `execution_jobs`.
@@ -3744,7 +3750,7 @@ var _025_init_failure_exports = /* @__PURE__ */ __exportAll({
 * Idempotent: re-running on a DB that already has either column is a no-op
 * for that column.
 */
-async function up$9(db) {
+async function up$17(db) {
 	const colExists = async (table, name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3764,7 +3770,7 @@ async function up$9(db) {
         ADD COLUMN init_failure JSONB DEFAULT NULL
     `.execute(db);
 }
-async function down$9(db) {
+async function down$17(db) {
 	await sql`
     ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS init_failure
   `.execute(db);
@@ -3775,8 +3781,8 @@ async function down$9(db) {
 //#endregion
 //#region src/db/migrations/026_event_log_lockfile_corrupt.ts
 var _026_event_log_lockfile_corrupt_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$8,
-	up: () => up$8
+	down: () => down$16,
+	up: () => up$16
 });
 /**
 * Extend the event_log.status CHECK constraint with 'lockfile_corrupt' so the
@@ -3785,7 +3791,7 @@ var _026_event_log_lockfile_corrupt_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: the DROP ... IF EXISTS / re-ADD pair re-runs cleanly.
 */
-async function up$8(db) {
+async function up$16(db) {
 	await sql`ALTER TABLE event_log DROP CONSTRAINT IF EXISTS event_log_status_check`.execute(db);
 	await sql`
     ALTER TABLE event_log ADD CONSTRAINT event_log_status_check
@@ -3795,7 +3801,7 @@ async function up$8(db) {
     ])))
   `.execute(db);
 }
-async function down$8(db) {
+async function down$16(db) {
 	await sql`ALTER TABLE event_log DROP CONSTRAINT IF EXISTS event_log_status_check`.execute(db);
 	await sql`
     ALTER TABLE event_log ADD CONSTRAINT event_log_status_check
@@ -3808,8 +3814,8 @@ async function down$8(db) {
 //#endregion
 //#region src/db/migrations/027_workflow_timeout.ts
 var _027_workflow_timeout_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$7,
-	up: () => up$7
+	down: () => down$15,
+	up: () => up$15
 });
 /**
 * Add `workflow_timeout_ms integer` to `execution_runs`.
@@ -3827,13 +3833,13 @@ var _027_workflow_timeout_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: re-running on a DB that already has the column is a no-op.
 */
-async function up$7(db) {
+async function up$15(db) {
 	await sql`
     ALTER TABLE public.execution_runs
       ADD COLUMN IF NOT EXISTS workflow_timeout_ms INTEGER DEFAULT NULL
   `.execute(db);
 }
-async function down$7(db) {
+async function down$15(db) {
 	await sql`
     ALTER TABLE public.execution_runs DROP COLUMN IF EXISTS workflow_timeout_ms
   `.execute(db);
@@ -3841,8 +3847,8 @@ async function down$7(db) {
 //#endregion
 //#region src/db/migrations/028_org_settings_user_cache.ts
 var _028_org_settings_user_cache_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$6,
-	up: () => up$6
+	down: () => down$14,
+	up: () => up$14
 });
 /**
 * Add `org_settings.user_cache_quota_bytes bigint` and
@@ -3871,7 +3877,7 @@ async function columnExists(db, column) {
     ) AS exists
   `.execute(db)).rows[0]?.exists ?? false;
 }
-async function up$6(db) {
+async function up$14(db) {
 	if (!await columnExists(db, "user_cache_quota_bytes")) await sql`
       ALTER TABLE public.org_settings
         ADD COLUMN user_cache_quota_bytes bigint
@@ -3881,7 +3887,7 @@ async function up$6(db) {
         ADD COLUMN user_cache_ttl_ms bigint
     `.execute(db);
 }
-async function down$6(db) {
+async function down$14(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS user_cache_quota_bytes
   `.execute(db);
@@ -3892,8 +3898,8 @@ async function down$6(db) {
 //#endregion
 //#region src/db/migrations/029_dispatch_queue_attempts.ts
 var _029_dispatch_queue_attempts_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$5,
-	up: () => up$5
+	down: () => down$13,
+	up: () => up$13
 });
 /**
 * Add `dispatch_queue.dispatch_attempts INT NOT NULL DEFAULT 0`.
@@ -3907,7 +3913,7 @@ var _029_dispatch_queue_attempts_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: re-running on a DB that already has the column is a no-op.
 */
-async function up$5(db) {
+async function up$13(db) {
 	if (!((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3920,7 +3926,7 @@ async function up$5(db) {
         ADD COLUMN dispatch_attempts INT NOT NULL DEFAULT 0
     `.execute(db);
 }
-async function down$5(db) {
+async function down$13(db) {
 	await sql`
     ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS dispatch_attempts
   `.execute(db);
@@ -3928,8 +3934,8 @@ async function down$5(db) {
 //#endregion
 //#region src/db/migrations/030_held_runs_env_set_null.ts
 var _030_held_runs_env_set_null_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$4,
-	up: () => up$4
+	down: () => down$12,
+	up: () => up$12
 });
 /**
 * held_runs.environment_id becomes nullable with ON DELETE SET NULL so
@@ -3940,14 +3946,14 @@ var _030_held_runs_env_set_null_exports = /* @__PURE__ */ __exportAll({
 * Idempotent: dropping the NOT NULL and the constraint are both no-ops on a
 * re-run, and the constraint is re-created with the SET NULL action.
 */
-async function up$4(db) {
+async function up$12(db) {
 	await sql`ALTER TABLE public.held_runs ALTER COLUMN environment_id DROP NOT NULL`.execute(db);
 	await sql`ALTER TABLE public.held_runs DROP CONSTRAINT IF EXISTS held_runs_environment_id_fkey`.execute(db);
 	await sql`ALTER TABLE public.held_runs
     ADD CONSTRAINT held_runs_environment_id_fkey
     FOREIGN KEY (environment_id) REFERENCES public.environments(id) ON DELETE SET NULL`.execute(db);
 }
-async function down$4(db) {
+async function down$12(db) {
 	await sql`ALTER TABLE public.held_runs DROP CONSTRAINT IF EXISTS held_runs_environment_id_fkey`.execute(db);
 	await sql`ALTER TABLE public.held_runs
     ADD CONSTRAINT held_runs_environment_id_fkey
@@ -3957,8 +3963,8 @@ async function down$4(db) {
 //#endregion
 //#region src/db/migrations/031_dispatch_queue_ack_deadline.ts
 var _031_dispatch_queue_ack_deadline_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$3,
-	up: () => up$3
+	down: () => down$11,
+	up: () => up$11
 });
 /**
 * Add `dispatch_queue.ack_deadline TIMESTAMPTZ` and
@@ -3975,7 +3981,7 @@ var _031_dispatch_queue_ack_deadline_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: re-running on a DB that already has either column is a no-op.
 */
-async function up$3(db) {
+async function up$11(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -4000,7 +4006,7 @@ async function up$3(db) {
       WHERE ack_deadline IS NOT NULL
   `.execute(db);
 }
-async function down$3(db) {
+async function down$11(db) {
 	await sql`DROP INDEX IF EXISTS public.idx_dispatch_queue_ack_deadline`.execute(db);
 	await sql`ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS ack_agent_id`.execute(db);
 	await sql`ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS ack_deadline`.execute(db);
@@ -4008,8 +4014,8 @@ async function down$3(db) {
 //#endregion
 //#region src/db/migrations/032_org_settings_dispatch_ack_timeout.ts
 var _032_org_settings_dispatch_ack_timeout_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$2,
-	up: () => up$2
+	down: () => down$10,
+	up: () => up$10
 });
 /**
 * Add `org_settings.dispatch_ack_timeout_ms BIGINT` (nullable).
@@ -4021,7 +4027,7 @@ var _032_org_settings_dispatch_ack_timeout_exports = /* @__PURE__ */ __exportAll
 *
 * Idempotent: a re-run on a DB that already has the column is a no-op.
 */
-async function up$2(db) {
+async function up$10(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -4035,7 +4041,7 @@ async function up$2(db) {
       ADD COLUMN dispatch_ack_timeout_ms BIGINT
   `.execute(db);
 }
-async function down$2(db) {
+async function down$10(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS dispatch_ack_timeout_ms
   `.execute(db);
@@ -4043,8 +4049,8 @@ async function down$2(db) {
 //#endregion
 //#region src/db/migrations/033_org_settings_approval.ts
 var _033_org_settings_approval_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$1,
-	up: () => up$1
+	down: () => down$9,
+	up: () => up$9
 });
 /**
 * Add the two approval-policy columns to `org_settings`:
@@ -4061,7 +4067,7 @@ var _033_org_settings_approval_exports = /* @__PURE__ */ __exportAll({
 * and the orchestrator admin route. Idempotent: a re-run on a DB that already
 * has the columns is a no-op (each column is guarded independently).
 */
-async function up$1(db) {
+async function up$9(db) {
 	const colExists = async (column) => {
 		return (await sql`
       SELECT EXISTS (
@@ -4081,7 +4087,7 @@ async function up$1(db) {
         ADD COLUMN allow_self_approval BOOLEAN NOT NULL DEFAULT true
     `.execute(db);
 }
-async function down$1(db) {
+async function down$9(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS approval_expiry_seconds
   `.execute(db);
@@ -4092,8 +4098,8 @@ async function down$1(db) {
 //#endregion
 //#region src/db/migrations/034_held_runs_generalize.ts
 var _034_held_runs_generalize_exports = /* @__PURE__ */ __exportAll({
-	down: () => down,
-	up: () => up
+	down: () => down$8,
+	up: () => up$8
 });
 /**
 * Generalize `held_runs` from an environment-only hold into the unified
@@ -4115,7 +4121,7 @@ var _034_held_runs_generalize_exports = /* @__PURE__ */ __exportAll({
 * New `held_run_approvals` table: one row per approver decision, FK to
 * `held_runs.id` (uuid) with ON DELETE CASCADE.
 */
-async function up(db) {
+async function up$8(db) {
 	const colExists = async (column) => {
 		return (await sql`
       SELECT EXISTS (
@@ -4148,7 +4154,7 @@ async function up(db) {
       ON public.held_run_approvals USING btree (held_run_id)
   `.execute(db);
 }
-async function down(db) {
+async function down$8(db) {
 	await sql`DROP TABLE IF EXISTS public.held_run_approvals`.execute(db);
 	await sql`ALTER TABLE public.held_runs DROP COLUMN IF EXISTS approval_requirement`.execute(db);
 	await sql`ALTER TABLE public.held_runs DROP COLUMN IF EXISTS trigger_source`.execute(db);
@@ -4156,6 +4162,359 @@ async function down(db) {
 	await sql`ALTER TABLE public.held_runs DROP COLUMN IF EXISTS hold_scope`.execute(db);
 }
 //#endregion
+//#region src/db/migrations/035_pending_workflow_contexts.ts
+var _035_pending_workflow_contexts_exports = /* @__PURE__ */ __exportAll({
+	down: () => down$7,
+	up: () => up$7
+});
+/**
+* Pending workflow dispatch context — backs resume of a workflow whose install
+* gate held. One row per held run: the serializable dispatch inputs needed to
+* rebuild the WorkflowDispatchContext when the hold releases (reviewer approve,
+* wait-timer expiry, concurrency slot free). The row is deleted once the resume
+* dispatch has been kicked off.
+*/
+async function up$7(db) {
+	await sql`
+    CREATE TABLE IF NOT EXISTS public.pending_workflow_contexts (
+      run_id     text PRIMARY KEY,
+      org_id     text NOT NULL,
+      context    jsonb NOT NULL,
+      created_at timestamp with time zone DEFAULT now() NOT NULL
+    )
+  `.execute(db);
+}
+async function down$7(db) {
+	await sql`DROP TABLE IF EXISTS public.pending_workflow_contexts`.execute(db);
+}
+//#endregion
+//#region src/db/migrations/036_attestations.ts
+var _036_attestations_exports = /* @__PURE__ */ __exportAll({
+	down: () => down$6,
+	up: () => up$6
+});
+/**
+* Add the `attestations` table for build-provenance bundles.
+*
+* When a workflow step calls `ctx.attestProvenance`, the agent uploads the
+* signed KiCI bundle to object storage under
+* `provenance/{run_id}/{job_id}/{subject_digest}.kici.json` and the
+* orchestrator records one row here so the dashboard can list and fetch
+* attestations per run/job.
+*
+* Idempotent: a re-run on a DB that already has the table is a no-op.
+*/
+async function up$6(db) {
+	if ((await sql`
+    SELECT EXISTS (
+      SELECT 1 FROM information_schema.tables
+       WHERE table_schema = 'public'
+         AND table_name = 'attestations'
+    ) AS exists
+  `.execute(db)).rows[0]?.exists) return;
+	await sql`
+    CREATE TABLE public.attestations (
+      id              TEXT PRIMARY KEY,
+      run_id          TEXT NOT NULL,
+      job_id          TEXT NOT NULL,
+      subject_name    TEXT NOT NULL,
+      subject_digest  TEXT NOT NULL,
+      storage_key     TEXT NOT NULL,
+      mode            TEXT NOT NULL,
+      media_type      TEXT NOT NULL,
+      created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    )
+  `.execute(db);
+	await sql`
+    CREATE INDEX idx_attestations_run_job
+      ON public.attestations (run_id, job_id)
+  `.execute(db);
+}
+async function down$6(db) {
+	await sql`DROP TABLE IF EXISTS public.attestations`.execute(db);
+}
+//#endregion
+//#region src/db/migrations/037_generic_sources_provider_type_local.ts
+var _037_generic_sources_provider_type_local_exports = /* @__PURE__ */ __exportAll({
+	down: () => down$5,
+	up: () => up$5
+});
+/**
+* Replace the `generic_webhook_sources.provider_type` CHECK constraint so it
+* permits `'local'` instead of `'internal'`, and migrate any carried-over
+* `'internal'` rows to `'local'`.
+*
+* The local filesystem (`file://`) provider is `provider_type='local'`; the
+* value used to be `'internal'`. The original CHECK constraint
+* (`generic_webhook_sources_provider_type_check`) allowed only
+* `{'generic','internal'}`, so writing a `'local'` row fails. Universal-git
+* sources keep `provider_type='generic'` (discriminated by `git_config`), so
+* the new allowed set is `{'generic','local'}`.
+*
+* Idempotent: the constraint is dropped IF EXISTS and recreated; the data
+* backfill is a plain UPDATE that is a no-op once no `'internal'` rows remain.
+*/
+async function up$5(db) {
+	await sql`
+    ALTER TABLE public.generic_webhook_sources
+      DROP CONSTRAINT IF EXISTS generic_webhook_sources_provider_type_check
+  `.execute(db);
+	await sql`
+    UPDATE public.generic_webhook_sources
+       SET provider_type = 'local'
+     WHERE provider_type = 'internal'
+  `.execute(db);
+	await sql`
+    ALTER TABLE public.generic_webhook_sources
+      ADD CONSTRAINT generic_webhook_sources_provider_type_check
+      CHECK (provider_type = ANY (ARRAY['generic'::text, 'local'::text]))
+  `.execute(db);
+}
+async function down$5(db) {
+	await sql`
+    ALTER TABLE public.generic_webhook_sources
+      DROP CONSTRAINT IF EXISTS generic_webhook_sources_provider_type_check
+  `.execute(db);
+	await sql`
+    UPDATE public.generic_webhook_sources
+       SET provider_type = 'internal'
+     WHERE provider_type = 'local'
+  `.execute(db);
+	await sql`
+    ALTER TABLE public.generic_webhook_sources
+      ADD CONSTRAINT generic_webhook_sources_provider_type_check
+      CHECK (provider_type = ANY (ARRAY['generic'::text, 'internal'::text]))
+  `.execute(db);
+}
+//#endregion
+//#region src/db/migrations/038_remote_sources.ts
+var _038_remote_sources_exports = /* @__PURE__ */ __exportAll({
+	down: () => down$4,
+	up: () => up$4
+});
+/**
+* `remote_sources` anchors a Platform-relayed `kici run remote` to its real
+* org. One row per org served by this orchestrator: routing key
+* `remote:<orgId>` maps to the canonical org id, so `resolveOrgId` resolves
+* the real tenant through the same local-source path a webhook takes — no
+* GitHub App, no webhook secret, no manual setup. The row is auto-provisioned
+* on Platform auth from the canonical org id carried on `auth.success`.
+*
+* Idempotent: a re-run on a DB that already has the table is a no-op.
+*/
+async function up$4(db) {
+	if ((await sql`
+    SELECT EXISTS (
+      SELECT 1 FROM information_schema.tables
+       WHERE table_schema = 'public' AND table_name = 'remote_sources'
+    ) AS exists
+  `.execute(db)).rows[0]?.exists) return;
+	await sql`
+    CREATE TABLE public.remote_sources (
+      customer_id  VARCHAR(255) NOT NULL,
+      routing_key  VARCHAR(255) NOT NULL,
+      cluster_id   TEXT,
+      created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      CONSTRAINT remote_sources_customer_id_key UNIQUE (customer_id),
+      CONSTRAINT remote_sources_routing_key_key UNIQUE (routing_key)
+    )
+  `.execute(db);
+}
+async function down$4(db) {
+	await sql`DROP TABLE IF EXISTS public.remote_sources`.execute(db);
+}
+//#endregion
+//#region src/db/migrations/039_host_roster.ts
+var _039_host_roster_exports = /* @__PURE__ */ __exportAll({
+	down: () => down$3,
+	up: () => up$3
+});
+/**
+* `host_roster` is KiCI's declared inventory: one durable row per agent the
+* cluster has ever enrolled, reconciled from the in-memory AgentRegistry on
+* every register/unregister. `lifecycle_class` (snapshot of the auth token's
+* agent_type) drives reaping — `ephemeral` rows are GC'd past their TTL,
+* `static` rows persist and read as `unreachable` when their heartbeat goes
+* stale. `connected_instance_id` records which orchestrator holds the live WS
+* (cluster liveness + the host-fanout reroute target); NULL = disconnected.
+*
+* The roster lives in the shared cluster DB (one table, all instances). Status
+* is derived at read from the shared `last_seen` + `connected_instance_id`, so
+* every instance agrees regardless of which one holds the agent's live WS.
+*
+* Idempotent: a re-run on a DB that already has the table is a no-op.
+*/
+async function up$3(db) {
+	if ((await sql`
+    SELECT EXISTS (
+      SELECT 1 FROM information_schema.tables
+       WHERE table_schema = 'public' AND table_name = 'host_roster'
+    ) AS exists
+  `.execute(db)).rows[0]?.exists) return;
+	await sql`
+    CREATE TABLE public.host_roster (
+      id                    uuid DEFAULT gen_random_uuid() NOT NULL,
+      agent_id              text NOT NULL,
+      token_id              uuid,
+      lifecycle_class       text NOT NULL,
+      labels                text NOT NULL DEFAULT '[]',
+      hostname              text,
+      platform              text,
+      arch                  text,
+      connected_instance_id text,
+      last_seen             timestamptz NOT NULL DEFAULT now(),
+      created_at            timestamptz NOT NULL DEFAULT now(),
+      updated_at            timestamptz NOT NULL DEFAULT now(),
+      CONSTRAINT host_roster_pkey PRIMARY KEY (id),
+      CONSTRAINT host_roster_agent_id_key UNIQUE (agent_id),
+      CONSTRAINT host_roster_lifecycle_class_check
+        CHECK (lifecycle_class = ANY (ARRAY['static'::text, 'ephemeral'::text]))
+    )
+  `.execute(db);
+	await sql`CREATE INDEX idx_host_roster_reap
+              ON public.host_roster (lifecycle_class, last_seen)`.execute(db);
+}
+async function down$3(db) {
+	await sql`DROP TABLE IF EXISTS public.host_roster`.execute(db);
+}
+//#endregion
+//#region src/db/migrations/040_runsonall_pin.ts
+var _040_runsonall_pin_exports = /* @__PURE__ */ __exportAll({
+	down: () => down$2,
+	up: () => up$2
+});
+/**
+* Add the `runsOnAll` host fan-out columns:
+*
+* - `dispatch_queue.pinned_agent_id TEXT` — when set, the queued/dispatched job
+*   targets exactly that agent (a host-fanout child). The dispatcher routes it
+*   only to that agent; the queue drain never hands it to a different one.
+* - `execution_jobs.base_job_name` / `variant_kind` / `variant_label` — generic
+*   fan-out columns (matrix + host uniform). `variant_kind` is `'matrix'` or
+*   `'host'`; `variant_label` is the matrix suffix or the hostname. They make the
+*   logical fan-out job first-class server-side so the dashboard groups on real
+*   fields instead of string-parsing the job name. (`matrix_values` / `group_name`
+*   already exist; the matrix path now also backfills `variant_kind='matrix'`.)
+*
+* Idempotent: re-running on a DB that already has any column is a no-op.
+*/
+async function colExists$2(db, table, name) {
+	return (await sql`
+    SELECT EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema = 'public'
+         AND table_name = ${table}
+         AND column_name = ${name}
+    ) AS exists
+  `.execute(db)).rows[0]?.exists ?? false;
+}
+async function up$2(db) {
+	if (!await colExists$2(db, "dispatch_queue", "pinned_agent_id")) await sql`ALTER TABLE public.dispatch_queue ADD COLUMN pinned_agent_id TEXT`.execute(db);
+	if (!await colExists$2(db, "execution_jobs", "base_job_name")) await sql`ALTER TABLE public.execution_jobs ADD COLUMN base_job_name TEXT`.execute(db);
+	if (!await colExists$2(db, "execution_jobs", "variant_kind")) await sql`ALTER TABLE public.execution_jobs ADD COLUMN variant_kind TEXT`.execute(db);
+	if (!await colExists$2(db, "execution_jobs", "variant_label")) await sql`ALTER TABLE public.execution_jobs ADD COLUMN variant_label TEXT`.execute(db);
+	await sql`
+    CREATE INDEX IF NOT EXISTS idx_dispatch_queue_pinned_agent
+      ON public.dispatch_queue (pinned_agent_id)
+      WHERE pinned_agent_id IS NOT NULL
+  `.execute(db);
+}
+async function down$2(db) {
+	await sql`DROP INDEX IF EXISTS public.idx_dispatch_queue_pinned_agent`.execute(db);
+	await sql`ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS pinned_agent_id`.execute(db);
+	await sql`ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS variant_label`.execute(db);
+	await sql`ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS variant_kind`.execute(db);
+	await sql`ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS base_job_name`.execute(db);
+}
+//#endregion
+//#region src/db/migrations/041_wave_gated.ts
+var _041_wave_gated_exports = /* @__PURE__ */ __exportAll({
+	down: () => down$1,
+	up: () => up$1
+});
+/**
+* Add the rolling fan-out wave-gate columns:
+*
+* - `execution_jobs.wave_gated boolean NOT NULL DEFAULT false` — when a fan-out
+*   job declares `maxParallel`, children beyond the sliding window are persisted
+*   `wave_gated=true` (held, not enqueued). The dispatch loop skips them; the
+*   wave-scheduler clears the flag one-per-terminal as siblings complete (or, on
+*   `failFast`, skips the held remainder).
+* - `execution_jobs.wave_max_parallel int` / `wave_fail_fast boolean` — the
+*   base's wave policy, stamped on every fan-out child so the wave-scheduler can
+*   read it at terminal time without re-fetching the lock file (the tracker has
+*   no lock access). NULL for any job not part of a bounded wave.
+*
+* A composite index on (run_id, base_job_name, wave_gated) supports the
+* wave-scheduler's "next held sibling of this base" lookups.
+*
+* Idempotent: re-running on a DB that already has the columns is a no-op.
+*/
+async function colExists$1(db, table, name) {
+	return (await sql`
+    SELECT EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema = 'public'
+         AND table_name = ${table}
+         AND column_name = ${name}
+    ) AS exists
+  `.execute(db)).rows[0]?.exists ?? false;
+}
+async function up$1(db) {
+	if (!await colExists$1(db, "execution_jobs", "wave_gated")) await sql`ALTER TABLE public.execution_jobs ADD COLUMN wave_gated boolean NOT NULL DEFAULT false`.execute(db);
+	if (!await colExists$1(db, "execution_jobs", "wave_max_parallel")) await sql`ALTER TABLE public.execution_jobs ADD COLUMN wave_max_parallel integer`.execute(db);
+	if (!await colExists$1(db, "execution_jobs", "wave_fail_fast")) await sql`ALTER TABLE public.execution_jobs ADD COLUMN wave_fail_fast boolean`.execute(db);
+	await sql`
+    CREATE INDEX IF NOT EXISTS idx_execution_jobs_wave
+      ON public.execution_jobs (run_id, base_job_name, wave_gated)
+  `.execute(db);
+}
+async function down$1(db) {
+	await sql`DROP INDEX IF EXISTS public.idx_execution_jobs_wave`.execute(db);
+	await sql`ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS wave_fail_fast`.execute(db);
+	await sql`ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS wave_max_parallel`.execute(db);
+	await sql`ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS wave_gated`.execute(db);
+}
+//#endregion
+//#region src/db/migrations/042_dispatch_queue_patterns.ts
+var _042_dispatch_queue_patterns_exports = /* @__PURE__ */ __exportAll({
+	down: () => down,
+	up: () => up
+});
+/**
+* Add pattern columns to dispatch_queue. Exact labels stay in runs_on_labels /
+* exclude_labels (the SQL @> prefilter); regex matchers go here and are applied
+* as a JS post-filter at drain time, since Postgres `~` regex semantics differ
+* from JavaScript `RegExp` and the engine's `matcherSatisfiedBy` is the single
+* matching authority.
+*
+* - `runs_on_patterns jsonb NOT NULL DEFAULT '[]'` — regex matchers the agent's
+*   labels must satisfy.
+* - `exclude_patterns jsonb NOT NULL DEFAULT '[]'` — regex matchers that
+*   disqualify an agent.
+*
+* Idempotent: re-running on a DB that already has the columns is a no-op.
+*/
+async function colExists(db, table, name) {
+	return (await sql`
+    SELECT EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema = 'public'
+         AND table_name = ${table}
+         AND column_name = ${name}
+    ) AS exists
+  `.execute(db)).rows[0]?.exists ?? false;
+}
+async function up(db) {
+	if (!await colExists(db, "dispatch_queue", "runs_on_patterns")) await sql`ALTER TABLE public.dispatch_queue ADD COLUMN runs_on_patterns jsonb NOT NULL DEFAULT '[]'::jsonb`.execute(db);
+	if (!await colExists(db, "dispatch_queue", "exclude_patterns")) await sql`ALTER TABLE public.dispatch_queue ADD COLUMN exclude_patterns jsonb NOT NULL DEFAULT '[]'::jsonb`.execute(db);
+}
+async function down(db) {
+	await sql`ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS exclude_patterns`.execute(db);
+	await sql`ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS runs_on_patterns`.execute(db);
+}
+//#endregion
 //#region src/db/migration-provider.ts
 function createMigrationProvider() {
 	return { async getMigrations() {
@@ -4193,7 +4552,15 @@ function createMigrationProvider() {
 			"031_dispatch_queue_ack_deadline": _031_dispatch_queue_ack_deadline_exports,
 			"032_org_settings_dispatch_ack_timeout": _032_org_settings_dispatch_ack_timeout_exports,
 			"033_org_settings_approval": _033_org_settings_approval_exports,
-			"034_held_runs_generalize": _034_held_runs_generalize_exports
+			"034_held_runs_generalize": _034_held_runs_generalize_exports,
+			"035_pending_workflow_contexts": _035_pending_workflow_contexts_exports,
+			"036_attestations": _036_attestations_exports,
+			"037_generic_sources_provider_type_local": _037_generic_sources_provider_type_local_exports,
+			"038_remote_sources": _038_remote_sources_exports,
+			"039_host_roster": _039_host_roster_exports,
+			"040_runsonall_pin": _040_runsonall_pin_exports,
+			"041_wave_gated": _041_wave_gated_exports,
+			"042_dispatch_queue_patterns": _042_dispatch_queue_patterns_exports
 		};
 	} };
 }
@@ -4260,7 +4627,7 @@ async function runMigrations(opts) {
 * as `kici-admin peer create-token` — open a pool from KICI_DATABASE_URL /
 * DATABASE_URL / --database-url.
 */
-function resolveDatabaseUrl$1(explicit) {
+function resolveDatabaseUrl$2(explicit) {
 	const url = explicit ?? process.env.KICI_DATABASE_URL;
 	if (!url) throw new Error("Database URL required. Pass --database-url or set KICI_DATABASE_URL.");
 	return url;
@@ -4307,7 +4674,7 @@ function registerDbCommands(program, getClient) {
 	});
 	db.command("fresh").description("DROP + CREATE the orchestrator DB, run migrations, record content hash").option("--database-url <url>", "Target database URL (else KICI_DATABASE_URL / DATABASE_URL)").requiredOption("--confirm", "Explicit confirmation (destructive)").option("--yes", "Skip interactive confirmation (for scripted use)").action(async (opts) => {
 		try {
-			const url = resolveDatabaseUrl$1(opts.databaseUrl);
+			const url = resolveDatabaseUrl$2(opts.databaseUrl);
 			const { dbName } = parseDatabaseUrl(url);
 			if (!opts.yes) {
 				if (!await confirmInteractive$1(`About to DROP + RECREATE database "${dbName}". Type "${dbName}" to confirm: `, dbName)) {
@@ -4338,7 +4705,7 @@ function registerDbCommands(program, getClient) {
 	});
 	db.command("ensure <name>").description("CREATE DATABASE IF NOT EXISTS (idempotent)").option("--database-url <url>", "Admin DB URL (else KICI_DATABASE_URL / DATABASE_URL)").option("--owner <role>", "DB owner role (default: URL user). Pass when the admin connection is privileged but the new DB should be owned by a separate non-privileged role.").option("--revoke-connect-public", "After ensure, REVOKE CONNECT ON DATABASE \"<name>\" FROM PUBLIC (recommended on shared clusters).").option("--grant-connect-role <role>", "After ensure (and any --revoke-connect-public), GRANT CONNECT ON DATABASE \"<name>\" TO \"<role>\". Repeatable.", (val, acc) => acc.concat([val]), []).action(async (name, opts) => {
 		try {
-			const baseUrl = resolveDatabaseUrl$1(opts.databaseUrl);
+			const baseUrl = resolveDatabaseUrl$2(opts.databaseUrl);
 			const url = new URL(baseUrl);
 			url.pathname = `/${name}`;
 			const targetUrl = url.toString();
@@ -4357,7 +4724,7 @@ function registerDbCommands(program, getClient) {
 	});
 	db.command("create-role").description("CREATE / ALTER ROLE with LOGIN [+ CREATEDB] (idempotent)").option("--database-url <url>", "Admin DB URL (else KICI_DATABASE_URL / DATABASE_URL)").requiredOption("--user <name>", "Role name to create or update").requiredOption("--password <password>", "Role password (raw — quote as needed)").option("--createdb", "Grant CREATEDB to the new role", false).action(async (opts) => {
 		try {
-			const { adminUrl } = parseDatabaseUrl(resolveDatabaseUrl$1(opts.databaseUrl));
+			const { adminUrl } = parseDatabaseUrl(resolveDatabaseUrl$2(opts.databaseUrl));
 			logInvocation(`create-role ${opts.user}`, adminUrl);
 			const outcome = await createDbRole(adminUrl, {
 				username: opts.user,
@@ -4372,7 +4739,7 @@ function registerDbCommands(program, getClient) {
 	});
 	db.command("create-readonly-user").description("Create a read-only role with SELECT on all tables + default privileges").option("--database-url <url>", "Target DB URL (must connect as owner)").requiredOption("--user <name>", "Read-only role name").requiredOption("--password <password>", "Role password").action(async (opts) => {
 		try {
-			const url = resolveDatabaseUrl$1(opts.databaseUrl);
+			const url = resolveDatabaseUrl$2(opts.databaseUrl);
 			const { dbName } = parseDatabaseUrl(url);
 			logInvocation(`create-readonly-user ${opts.user}`, url);
 			const outcome = await createReadOnlyDbUser(url, {
@@ -4387,7 +4754,7 @@ function registerDbCommands(program, getClient) {
 	});
 	db.command("check-schema").description("Compare bundled migrations vs live schema. Exit 2 on drift.").option("--database-url <url>", "Target DB URL (else KICI_DATABASE_URL / DATABASE_URL)").option("--json", "Emit JSON instead of a human-readable line", false).action(async (opts) => {
 		try {
-			const pool = createPool(resolveDatabaseUrl$1(opts.databaseUrl));
+			const pool = createPool(resolveDatabaseUrl$2(opts.databaseUrl));
 			try {
 				const status = await isSchemaCurrent(pool, createMigrationProvider());
 				if (opts.json) process.stdout.write(JSON.stringify(status) + "\n");
@@ -4404,7 +4771,7 @@ function registerDbCommands(program, getClient) {
 	});
 	db.command("collation-check").description("Compare pg_database.datcollversion against the running libc collation version. Exit 2 on drift.").option("--database-url <url>", "Target DB URL (else KICI_DATABASE_URL / DATABASE_URL)").option("--json", "Emit JSON instead of a human-readable line", false).action(async (opts) => {
 		try {
-			const url = resolveDatabaseUrl$1(opts.databaseUrl);
+			const url = resolveDatabaseUrl$2(opts.databaseUrl);
 			const { dbName } = parseDatabaseUrl(url);
 			const pool = createPool(url);
 			try {
@@ -4434,7 +4801,7 @@ function registerDbCommands(program, getClient) {
 	});
 	db.command("reindex").description("REINDEX DATABASE CONCURRENTLY <db>. Rebuilds every index under the running libc collation rules. Non-blocking but takes minutes + ~2× temp disk.").option("--database-url <url>", "Target DB URL (else KICI_DATABASE_URL / DATABASE_URL)").requiredOption("--confirm", "Explicit confirmation (destructive — long-running)").requiredOption("--reason <text>", "Reason (recorded in stderr banner)").action(async (opts) => {
 		try {
-			const url = resolveDatabaseUrl$1(opts.databaseUrl);
+			const url = resolveDatabaseUrl$2(opts.databaseUrl);
 			const { dbName } = parseDatabaseUrl(url);
 			logInvocation(`reindex ${dbName} (${opts.reason})`, url);
 			const pool = createPool(url);
@@ -4451,7 +4818,7 @@ function registerDbCommands(program, getClient) {
 	});
 	db.command("refresh-collation-version").description("ALTER DATABASE <db> REFRESH COLLATION VERSION. Metadata-only bump; pair with db reindex after a libc-base image rebuild.").option("--database-url <url>", "Target DB URL (else KICI_DATABASE_URL / DATABASE_URL)").requiredOption("--reason <text>", "Reason (recorded in stderr banner)").action(async (opts) => {
 		try {
-			const url = resolveDatabaseUrl$1(opts.databaseUrl);
+			const url = resolveDatabaseUrl$2(opts.databaseUrl);
 			const { dbName } = parseDatabaseUrl(url);
 			logInvocation(`refresh-collation-version ${dbName} (${opts.reason})`, url);
 			const pool = createPool(url);
@@ -4707,6 +5074,119 @@ promisify(execFile);
 createLogger({ prefix: "universal-git:lock-file" });
 createLogger({ prefix: "universal-git:clone-token" });
 //#endregion
+//#region src/providers/local/local-source-config.ts
+/**
+* Configuration for a local filesystem (`file://`) source, stored as JSONB in
+* `generic_webhook_sources.git_config` and discriminated from universal-git
+* config by the row's `provider_type='local'`.
+*
+* A local source clones a git repository that already exists on the agent's
+* filesystem (host path for bare-metal scalers, image-bundled / rootfs /
+* bind-mounted path for container + Firecracker scalers). The orchestrator does
+* not verify in-agent reachability — that is the operator's responsibility.
+*/
+const LocalSourceConfigSchema = z.object({
+	/** Absolute path to the repo (or base dir of repos) on the agent filesystem. */
+	repoBasePath: z.string().min(1).refine((p) => path.isAbsolute(p), { message: "repoBasePath must be an absolute path" }),
+	/** Optional network clone base (git:// / http://) for remote agents that do
+	*  not share the orchestrator's filesystem. When unset, file:// is used. */
+	cloneUrlBase: z.string().min(1).optional()
+}).strict();
+//#endregion
+//#region src/cli/commands/local-trigger.ts
+/**
+* Build and send the synthetic webhook that triggers a run against a local
+* filesystem (`file://`) source. The orchestrator's provider-agnostic generic
+* webhook route (`POST /webhook/:orgId/generic/:sourceId`) dispatches it through
+* the local provider's normalizer. Shared by the `source trigger-local` CLI
+* command and the generated `post-receive` hook.
+*
+* A local repo has no remote forge to send webhooks, so this is the operator's
+* way to drive a run: either by hand (`trigger-local`) or on every push via an
+* installed `post-receive` hook (`install-hook`).
+*/
+/** Build the GitHub-shaped webhook request the local provider normalizer expects. */
+function buildLocalTriggerRequest(input) {
+	const body = JSON.stringify({
+		ref: input.ref,
+		after: input.sha,
+		repository: {
+			full_name: input.repoFullName,
+			default_branch: input.defaultBranch
+		}
+	});
+	return {
+		path: `/webhook/${input.orgId}/generic/${input.sourceId}`,
+		headers: {
+			"content-type": "application/json",
+			"x-event-type": input.event,
+			"x-delivery-id": randomUUID()
+		},
+		body
+	};
+}
+/** Read HEAD ref + sha from a local git repo (used when the operator omits --ref/--sha). */
+function readRepoHead(repoPath) {
+	const sha = execFileSync("git", [
+		"-C",
+		repoPath,
+		"rev-parse",
+		"HEAD"
+	], { encoding: "utf8" }).trim();
+	return {
+		ref: `refs/heads/${execFileSync("git", [
+			"-C",
+			repoPath,
+			"rev-parse",
+			"--abbrev-ref",
+			"HEAD"
+		], { encoding: "utf8" }).trim()}`,
+		sha
+	};
+}
+/** POST the trigger request to the orchestrator base URL. Returns the HTTP status. */
+async function sendLocalTrigger(baseUrl, req) {
+	return (await fetch(`${baseUrl.replace(/\/$/, "")}${req.path}`, {
+		method: "POST",
+		headers: req.headers,
+		body: req.body
+	})).status;
+}
+//#endregion
+//#region src/cli/commands/local-hook.ts
+/**
+* Render + install a git `post-receive` hook that triggers a KiCI run on every
+* push to a local filesystem (`file://`) source. The hook is a thin wrapper
+* around `kici-admin source trigger-local`; it carries no logic of its own.
+*/
+/**
+* Render the post-receive hook script. For each pushed ref the hook calls
+* `kici-admin source trigger-local <id> --ref <ref> --sha <new> --base-url <url>`,
+* so a push to any branch dispatches a run for that ref.
+*/
+function renderPostReceiveHook(opts) {
+	return `#!/usr/bin/env bash
+# KiCI local-source post-receive hook (generated by 'kici-admin source install-hook').
+# Triggers a run for each pushed branch ref.
+set -euo pipefail
+while read -r _old _new ref; do
+  kici-admin source trigger-local ${opts.sourceId} --ref "$ref" --sha "$_new" --base-url ${opts.baseUrl}
+done
+`;
+}
+/**
+* Write the rendered hook into the repo's `.git/hooks/post-receive` and make it
+* executable. Throws when the path is not a git repo (no `.git/hooks` dir).
+*/
+function installPostReceiveHook(repoPath, script) {
+	const hooksDir = path.join(repoPath, ".git", "hooks");
+	if (!existsSync(hooksDir)) throw new Error(`Not a git repo (no .git/hooks): ${repoPath}`);
+	const hookPath = path.join(hooksDir, "post-receive");
+	writeFileSync(hookPath, script, { mode: 493 });
+	chmodSync(hookPath, 493);
+	return hookPath;
+}
+//#endregion
 //#region src/cli/commands/source.ts
 /**
 * Source management commands for kici-admin.
@@ -4728,6 +5208,24 @@ createLogger({ prefix: "universal-git:clone-token" });
 *   --from-env <VAR_NAME>      Read from environment variable
 *   --stdin                    Read from stdin
 */
+/** Default orchestrator base URL for the webhook trigger route, matching the
+*  kici-admin global `--url` default. */
+const DEFAULT_ORCH_URL = process.env.KICI_ADMIN_URL ?? "http://localhost:8080";
+/** Parse a generic source's git_config (string or object) into a LocalSourceConfig.
+*  Returns null when the row is not a valid local source. */
+function parseLocalConfig(s) {
+	if (s.provider_type !== "local" || !s.git_config) return null;
+	const raw = typeof s.git_config === "string" ? safeParse(s.git_config) : s.git_config;
+	const parsed = LocalSourceConfigSchema.safeParse(raw);
+	return parsed.success ? parsed.data : null;
+}
+function safeParse(value) {
+	try {
+		return JSON.parse(value);
+	} catch {
+		return null;
+	}
+}
 /**
 * Short reason shown in `(unavailable — <reason>)` when no webhook URL could be
 * resolved for an added source.
@@ -4809,7 +5307,11 @@ function formatGenericSource(s) {
 		} catch {
 			gc = null;
 		}
-		if (gc) {
+		if (gc && s.provider_type === "local") {
+			console.log(`  Local (file://):      yes`);
+			if (typeof gc.repoBasePath === "string") console.log(`    Repo base path:     ${gc.repoBasePath}`);
+			if (typeof gc.cloneUrlBase === "string") console.log(`    Clone URL base:     ${gc.cloneUrlBase}`);
+		} else if (gc) {
 			console.log(`  Universal-git:        yes`);
 			if (typeof gc.preset === "string") console.log(`    Preset:             ${gc.preset}`);
 			if (typeof gc.gitUrlTemplate === "string") console.log(`    Git URL template:   ${gc.gitUrlTemplate}`);
@@ -4907,7 +5409,7 @@ function registerSourceCommands(program, getClient) {
 			process.exit(1);
 		}
 	});
-	add.command("generic").description("Add a new generic webhook source").requiredOption("--org <orgId>", "Organization/customer ID").requiredOption("--name <name>", "Human-readable source name").option("--verification <method>", "Verification method: hmac_sha256, bearer_token, ip_allowlist, none").option("--secret <value>", "Verification secret (HMAC secret or bearer token, prefix with @ for file)").option("--from-env <varName>", "Read verification secret from environment variable").option("--stdin", "Read verification secret from stdin").option("--event-type-header <header>", "Header name for event type extraction").option("--event-type-path <jsonpath>", "JSONPath for event type extraction from body").option("--idempotency-key-header <header>", "Header name for idempotency key").option("--idempotency-key-path <jsonpath>", "JSONPath for idempotency key from body").option("--dedup-window <seconds>", "Dedup window in seconds (default: 300)", parseInt).option("--max-payload <bytes>", "Maximum payload size in bytes (default: 1048576)", parseInt).option("--allowed-events <events>", "Comma-separated list of allowed event types").option("--strip-headers <headers>", "Comma-separated list of headers to strip").option("--rate-limit <rpm>", "Rate limit in requests per minute (default: 600)", parseInt).option("--preset <name>", "Universal-git preset: forgejo, gitea, gogs, gitlab-repo, github-repo, custom").option("--git-url-template <url>", "Clone URL template with {owner}/{name}/{repo}").option("--credential-ref <key>", "Secret key name (under __source__/<id> scope)").option("--credential-store <backend>", "Secret backend name (default: pg)").option("--credential-type <type>", "Credential type: pat, basic, ssh").option("--credential-user <user>", "Username for PAT/basic auth (default: x-access-token)").option("--ssh-host-key-policy <policy>", "SSH host-key policy: accept-new, pinned").option("--ssh-known-hosts-pem <pathOrValue>", "Pinned SSH known_hosts (prefix with @ for file). Required when --ssh-host-key-policy=pinned").option("--provider-type <type>", "Provider implementation: generic (default) or internal (for E2E/staging internal-webhook routing)").option("--json", "Emit raw JSON (the full source row) instead of formatted text").action(async (opts) => {
+	add.command("generic").description("Add a new generic webhook source").requiredOption("--org <orgId>", "Organization/customer ID").requiredOption("--name <name>", "Human-readable source name").option("--verification <method>", "Verification method: hmac_sha256, bearer_token, ip_allowlist, none").option("--secret <value>", "Verification secret (HMAC secret or bearer token, prefix with @ for file)").option("--from-env <varName>", "Read verification secret from environment variable").option("--stdin", "Read verification secret from stdin").option("--event-type-header <header>", "Header name for event type extraction").option("--event-type-path <jsonpath>", "JSONPath for event type extraction from body").option("--idempotency-key-header <header>", "Header name for idempotency key").option("--idempotency-key-path <jsonpath>", "JSONPath for idempotency key from body").option("--dedup-window <seconds>", "Dedup window in seconds (default: 300)", parseInt).option("--max-payload <bytes>", "Maximum payload size in bytes (default: 1048576)", parseInt).option("--allowed-events <events>", "Comma-separated list of allowed event types").option("--strip-headers <headers>", "Comma-separated list of headers to strip").option("--rate-limit <rpm>", "Rate limit in requests per minute (default: 600)", parseInt).option("--preset <name>", "Universal-git preset: forgejo, gitea, gogs, gitlab-repo, github-repo, custom").option("--git-url-template <url>", "Clone URL template with {owner}/{name}/{repo}").option("--credential-ref <key>", "Secret key name (under __source__/<id> scope)").option("--credential-store <backend>", "Secret backend name (default: pg)").option("--credential-type <type>", "Credential type: pat, basic, ssh").option("--credential-user <user>", "Username for PAT/basic auth (default: x-access-token)").option("--ssh-host-key-policy <policy>", "SSH host-key policy: accept-new, pinned").option("--ssh-known-hosts-pem <pathOrValue>", "Pinned SSH known_hosts (prefix with @ for file). Required when --ssh-host-key-policy=pinned").option("--provider-type <type>", "Provider implementation: generic (default) or local (a git repo on the agent filesystem cloned via file://)").option("--json", "Emit raw JSON (the full source row) instead of formatted text").action(async (opts) => {
 		try {
 			const secret = await resolveSecret({
 				value: opts.secret,
@@ -4959,6 +5461,39 @@ function registerSourceCommands(program, getClient) {
 			process.exit(1);
 		}
 	});
+	add.command("local").description("Register a git repo present on the agent filesystem as a file:// source").requiredOption("--org <orgId>", "Organization/customer ID").requiredOption("--path <dir>", "Absolute path to the repo (or base dir of repos) on the agent filesystem").option("--name <name>", "Human-readable source name", "local").option("--clone-url-base <url>", "Optional git://|http:// base for remote agents that do not share the orchestrator filesystem (default: file://)").option("--json", "Emit raw JSON (the full source row) instead of formatted text").action(async (opts) => {
+		try {
+			if (!path.isAbsolute(opts.path)) {
+				console.error(`Error: --path must be an absolute path: ${opts.path}`);
+				process.exit(1);
+			}
+			const localConfig = { repoBasePath: opts.path };
+			if (opts.cloneUrlBase) localConfig.cloneUrlBase = opts.cloneUrlBase;
+			const s = (await getClient().createGenericSource({
+				orgId: opts.org,
+				name: opts.name,
+				providerType: "local",
+				verificationMethod: "none",
+				localConfig
+			})).source;
+			if (opts.json) {
+				console.log(JSON.stringify(s, null, 2));
+				return;
+			}
+			console.log(`Local source created:`);
+			console.log(`  ID:           ${s.id}`);
+			console.log(`  Name:         ${s.name}`);
+			console.log(`  Routing key:  ${s.routing_key}`);
+			console.log(`  Org:          ${s.customer_id}`);
+			console.log(`  Repo path:    ${opts.path}`);
+			console.log("");
+			console.log(`Trigger runs with: kici-admin source trigger-local ${s.id}`);
+			console.log(`Or install a push hook: kici-admin source install-hook ${s.id}`);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
 	src.command("list-presets").description("List built-in universal-git presets (forge shapes supported out of the box)").option("--format <format>", "Output format: table|json", "table").action((opts) => {
 		const rows = Object.entries(UNIVERSAL_GIT_PRESETS).map(([name, def]) => ({
 			preset: name,
@@ -5070,7 +5605,7 @@ function registerSourceCommands(program, getClient) {
 			process.exit(1);
 		}
 	});
-	src.command("update-generic <id>").description("Update a generic webhook source").option("--name <name>", "New name").option("--verification <method>", "Verification method: hmac_sha256, bearer_token, ip_allowlist, none").option("--secret <value>", "New verification secret (prefix with @ for file)").option("--from-env <varName>", "Read verification secret from environment variable").option("--stdin", "Read verification secret from stdin").option("--event-type-header <header>", "Header name for event type extraction").option("--event-type-path <jsonpath>", "JSONPath for event type extraction from body").option("--idempotency-key-header <header>", "Header name for idempotency key").option("--idempotency-key-path <jsonpath>", "JSONPath for idempotency key from body").option("--dedup-window <seconds>", "Dedup window in seconds", parseInt).option("--max-payload <bytes>", "Maximum payload size in bytes", parseInt).option("--allowed-events <events>", "Comma-separated list of allowed event types").option("--strip-headers <headers>", "Comma-separated list of headers to strip").option("--rate-limit <rpm>", "Rate limit in requests per minute", parseInt).option("--preset <name>", "Universal-git preset").option("--git-url-template <url>", "Clone URL template").option("--credential-ref <key>", "Secret key name").option("--credential-store <backend>", "Secret backend name").option("--credential-type <type>", "Credential type: pat, basic, ssh").option("--credential-user <user>", "Username for PAT/basic auth").option("--ssh-host-key-policy <policy>", "SSH host-key policy: accept-new, pinned").option("--ssh-known-hosts-pem <pathOrValue>", "Pinned SSH known_hosts (prefix with @ for file)").option("--clear-git-config", "Revert this source back to a payload-only generic webhook").option("--provider-type <type>", "Provider implementation: generic (default) or internal (for E2E/staging internal-webhook routing)").option("--json", "Emit raw JSON (the full source row) instead of formatted text").action(async (id, opts) => {
+	src.command("update-generic <id>").description("Update a generic webhook source").option("--name <name>", "New name").option("--verification <method>", "Verification method: hmac_sha256, bearer_token, ip_allowlist, none").option("--secret <value>", "New verification secret (prefix with @ for file)").option("--from-env <varName>", "Read verification secret from environment variable").option("--stdin", "Read verification secret from stdin").option("--event-type-header <header>", "Header name for event type extraction").option("--event-type-path <jsonpath>", "JSONPath for event type extraction from body").option("--idempotency-key-header <header>", "Header name for idempotency key").option("--idempotency-key-path <jsonpath>", "JSONPath for idempotency key from body").option("--dedup-window <seconds>", "Dedup window in seconds", parseInt).option("--max-payload <bytes>", "Maximum payload size in bytes", parseInt).option("--allowed-events <events>", "Comma-separated list of allowed event types").option("--strip-headers <headers>", "Comma-separated list of headers to strip").option("--rate-limit <rpm>", "Rate limit in requests per minute", parseInt).option("--preset <name>", "Universal-git preset").option("--git-url-template <url>", "Clone URL template").option("--credential-ref <key>", "Secret key name").option("--credential-store <backend>", "Secret backend name").option("--credential-type <type>", "Credential type: pat, basic, ssh").option("--credential-user <user>", "Username for PAT/basic auth").option("--ssh-host-key-policy <policy>", "SSH host-key policy: accept-new, pinned").option("--ssh-known-hosts-pem <pathOrValue>", "Pinned SSH known_hosts (prefix with @ for file)").option("--clear-git-config", "Revert this source back to a payload-only generic webhook").option("--provider-type <type>", "Provider implementation: generic (default) or local (a git repo on the agent filesystem cloned via file://)").option("--json", "Emit raw JSON (the full source row) instead of formatted text").action(async (id, opts) => {
 		try {
 			const secret = await resolveSecret({
 				value: opts.secret,
@@ -5117,7 +5652,32 @@ function registerSourceCommands(program, getClient) {
 			process.exit(1);
 		}
 	});
-	src.command("remove <routingKey>").description("Remove a source (GitHub or generic with --generic flag)").option("--yes", "Skip confirmation").option("--generic", "Remove a generic source (routingKey is treated as source ID)").option("--hard", "Permanently delete a generic source (requires --generic)").action(async (routingKey, opts) => {
+	src.command("update-local <id>").description("Update a local filesystem (file://) source").option("--name <name>", "New name").option("--path <dir>", "New absolute repo base path on the agent filesystem").option("--clone-url-base <url>", "New git://|http:// clone base (default: file://)").option("--json", "Emit raw JSON (the full source row) instead of formatted text").action(async (id, opts) => {
+		try {
+			const data = {};
+			if (opts.name) data.name = opts.name;
+			if (opts.path !== void 0) {
+				if (!path.isAbsolute(opts.path)) {
+					console.error(`Error: --path must be an absolute path: ${opts.path}`);
+					process.exit(1);
+				}
+				const localConfig = { repoBasePath: opts.path };
+				if (opts.cloneUrlBase) localConfig.cloneUrlBase = opts.cloneUrlBase;
+				data.localConfig = localConfig;
+			}
+			if (Object.keys(data).length === 0) {
+				console.error("Error: no fields to update. Provide --path and/or --name.");
+				process.exit(1);
+			}
+			const result = await getClient().updateGenericSource(id, data);
+			if (opts.json) console.log(JSON.stringify(result.source, null, 2));
+			else console.log(`Local source updated: ${result.source.id} (${result.source.name})`);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+	src.command("remove <routingKey>").description("Remove a source (GitHub, or generic/local with --generic / --local)").option("--yes", "Skip confirmation").option("--generic", "Remove a generic source (routingKey is treated as source ID)").option("--local", "Remove a local (file://) source (routingKey is treated as source ID)").option("--hard", "Permanently delete a generic/local source (requires --generic or --local)").action(async (routingKey, opts) => {
 		try {
 			if (!opts.yes) {
 				const rl = createInterface({
@@ -5133,12 +5693,13 @@ function registerSourceCommands(program, getClient) {
 					return;
 				}
 			}
-			if (opts.generic) {
+			if (opts.generic || opts.local) {
 				const mode = (await getClient().deleteGenericSource(routingKey, opts.hard)).hard ? "permanently deleted" : "soft-deleted";
-				console.log(`Generic source ${mode}: ${routingKey}`);
+				const kind = opts.local ? "Local" : "Generic";
+				console.log(`${kind} source ${mode}: ${routingKey}`);
 			} else {
 				if (opts.hard) {
-					console.error("Error: --hard flag is only supported with --generic");
+					console.error("Error: --hard flag is only supported with --generic / --local");
 					process.exit(1);
 				}
 				await getClient().delete(`/api/v1/admin/sources/${encodeURIComponent(routingKey)}`);
@@ -5167,6 +5728,106 @@ function registerSourceCommands(program, getClient) {
 			process.exit(1);
 		}
 	});
+	src.command("trigger-local <id>").description("Trigger a run against a local source (reads HEAD when --ref/--sha omitted)").option("--event <event>", "push | pull_request", "push").option("--ref <ref>", "Git ref (default: repo HEAD branch)").option("--sha <sha>", "Commit SHA (default: repo HEAD)").option("--repo-full-name <name>", "owner/name identifier used in the payload", "local/repo").option("--base-url <url>", "Orchestrator base URL", DEFAULT_ORCH_URL).action(async (id, opts) => {
+		try {
+			const { source } = await getClient().getGenericSource(id);
+			const cfg = parseLocalConfig(source);
+			if (!cfg) {
+				console.error(`Error: no local source with id ${id}`);
+				process.exit(1);
+			}
+			const head = opts.ref && opts.sha ? {
+				ref: opts.ref,
+				sha: opts.sha
+			} : readRepoHead(cfg.repoBasePath);
+			const orgId = source.customer_id;
+			const sourceId = source.name;
+			const req = buildLocalTriggerRequest({
+				orgId,
+				sourceId,
+				repoFullName: opts.repoFullName,
+				event: opts.event === "pull_request" ? "pull_request" : "push",
+				ref: head.ref,
+				sha: head.sha,
+				defaultBranch: head.ref.replace("refs/heads/", "")
+			});
+			const status = await sendLocalTrigger(opts.baseUrl, req);
+			console.log(`Triggered local source ${id}: HTTP ${status}`);
+			if (status >= 400) process.exit(1);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+	src.command("install-hook <id>").description("Install a post-receive hook in the local source repo that triggers runs on push").option("--repo <path>", "Repo path (default: the source repoBasePath)").option("--base-url <url>", "Orchestrator base URL", DEFAULT_ORCH_URL).action(async (id, opts) => {
+		try {
+			const { source } = await getClient().getGenericSource(id);
+			const cfg = parseLocalConfig(source);
+			if (!cfg) {
+				console.error(`Error: no local source with id ${id}`);
+				process.exit(1);
+			}
+			const repoPath = opts.repo ?? cfg.repoBasePath;
+			const hookPath = installPostReceiveHook(repoPath, renderPostReceiveHook({
+				sourceId: id,
+				baseUrl: opts.baseUrl
+			}));
+			console.log(`Installed post-receive hook: ${hookPath}`);
+			console.log(`Every push to ${repoPath} will now trigger a run for source ${id}.`);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+}
+/** Read the auto-provisioned remote-source row for an org, if it exists. */
+async function getRemoteSource(db, orgId) {
+	return db.selectFrom("remote_sources").selectAll().where("customer_id", "=", orgId).executeTakeFirst();
+}
+//#endregion
+//#region src/cli/commands/remote-source.ts
+init_client();
+function resolveDatabaseUrl$1(explicit) {
+	const url = explicit ?? process.env.KICI_DATABASE_URL;
+	if (!url) throw new Error("Database URL required. Pass --database-url or set KICI_DATABASE_URL.");
+	return url;
+}
+function registerRemoteSourceCommands(program) {
+	program.command("remote-source").description("Inspect the auto-provisioned remote-source org anchor").command("show <orgId>").description("Print the remote_sources anchor row for an org (routing key remote:<orgId>).").option("--database-url <url>", "Orchestrator DB URL (else KICI_DATABASE_URL)").option("--format <format>", "Output format: json|table", "table").action(async (orgId, opts) => {
+		let url;
+		try {
+			url = resolveDatabaseUrl$1(opts.databaseUrl);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+			return;
+		}
+		const pool = createPool$1(url);
+		const db = createDb$1(pool);
+		try {
+			const row = await getRemoteSource(db, orgId);
+			if (!row) {
+				console.error(`No remote_sources anchor found for org ${orgId}.`);
+				process.exit(1);
+				return;
+			}
+			if (opts.format === "json") {
+				console.log(JSON.stringify(row, null, 2));
+				return;
+			}
+			console.log(`customer_id:  ${row.customer_id}`);
+			console.log(`routing_key:  ${row.routing_key}`);
+			console.log(`cluster_id:   ${row.cluster_id ?? "(none)"}`);
+			console.log(`created_at:   ${new Date(row.created_at).toISOString()}`);
+			console.log(`updated_at:   ${new Date(row.updated_at).toISOString()}`);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		} finally {
+			await db.destroy();
+			await pool.end().catch(() => void 0);
+		}
+	});
 }
 //#endregion
 //#region src/cli/commands/workflow.ts
@@ -6168,7 +6829,7 @@ function registerDebugBundleCommand(program, getClient) {
 				safeRequest(() => client.getText("/metrics"))
 			]);
 			const output = fs$1.createWriteStream(outputPath);
-			const archive = archiver("zip", { zlib: { level: 6 } });
+			const archive = new ZipArchive({ zlib: { level: 6 } });
 			const finalized = new Promise((resolve, reject) => {
 				output.on("close", resolve);
 				archive.on("error", reject);
@@ -6495,8 +7156,18 @@ function isRoot() {
 *
 * Used by the instance index (`<kiciRoot>/instances.json`) which lives
 * outside any per-instance subdir, and as the base for {@link getConfigDir}.
+*
+* `KICI_CONFIG_ROOT` overrides the platform default for both privilege scopes.
+* It exists so a test harness (or a sandboxed run) can point the instance index
+* at an isolated directory instead of sharing the host's `~/.config/kici/` —
+* which otherwise lets concurrent installs clobber each other's index.
 */
 function kiciConfigRoot(isUserLevel) {
+	const override = process.env.KICI_CONFIG_ROOT;
+	if (override) {
+		const sep = os.platform() === "win32" ? "\\" : "/";
+		return override.endsWith(sep) ? override : override + sep;
+	}
 	const plat = os.platform();
 	if (plat === "win32") {
 		if (isUserLevel) return (process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local")) + "\\kici\\";
@@ -6644,6 +7315,37 @@ function readKiciVersion() {
 		return "unknown";
 	}
 }
+/**
+* Resolve the `@kici-dev/<component>` package version that a {@link LaunchSpec}
+* will actually execute, by locating the component's entry script among the
+* spec's tokens and reading the version from the package.json that owns it.
+*
+* Returns null when no resolvable entry script is present (e.g. an opaque
+* `--binary` install) or the owning package.json is missing / name-mismatched.
+* This is what lets the npm-source upgrade refuse to report a version it can't
+* stand behind.
+*/
+function resolveVersionFromLaunchSpec(spec, component) {
+	const pkgName = `@kici-dev/${component}`;
+	const entryRe = new RegExp(`[/\\\\]@kici-dev[/\\\\]${component}[/\\\\]dist[/\\\\](?:server|standalone)\\.js$`);
+	const entry = [spec.execPath, ...spec.args].find((a) => entryRe.test(a));
+	if (!entry) return null;
+	let dir = path.dirname(entry);
+	for (let i = 0; i < 6; i++) {
+		const candidate = path.join(dir, "package.json");
+		if (fs.existsSync(candidate)) try {
+			const pkg = JSON.parse(fs.readFileSync(candidate, "utf-8"));
+			if (pkg.name === pkgName && typeof pkg.version === "string") return pkg.version;
+			return null;
+		} catch {
+			return null;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
 //#endregion
 //#region src/cli/service/instance/index-file.ts
 /**
@@ -6721,27 +7423,54 @@ function removeIndexEntry(kiciRoot, key) {
 */
 /**
 * Reconcile <kiciRoot>/instances.json with the driver's native scan, then
-* rewrite the index dropping entries whose units no longer exist. Returns
-* the merged list filtered to the requested component + isUserLevel.
+* rewrite the index so it mirrors the scanned instances that have a known
+* instanceDir. Two self-heal directions happen here:
+*
+*   - backward: drop index entries whose unit no longer exists.
+*   - forward: adopt an instanceDir the driver recovered from the unit marker
+*     when the index entry is missing or carries no dir — so a lost or emptied
+*     index rebuilds itself from the init system on the next read.
+*
+* The init system is therefore the source of truth for the name→folder mapping
+* (via the X-KiCI-InstanceDir / KiCIInstanceDir / dev.kici.instance-dir / [KiCI-DIR]
+* markers), and the index is a pure cache. Returns the merged list filtered to
+* the requested component + isUserLevel.
 */
 async function listInstances(args) {
 	const { component, isUserLevel, kiciRoot, manager } = args;
 	const scanForComponent = (await manager.list(isUserLevel)).filter((s) => s.component === component);
-	const scanNames = new Set(scanForComponent.map((s) => s.name));
 	const index = readIndex(kiciRoot);
 	const relevantIndex = index.filter((e) => e.component === component && e.isUserLevel === isUserLevel);
-	const survivors = relevantIndex.filter((e) => scanNames.has(e.name));
-	if (survivors.length !== relevantIndex.length) writeIndex(kiciRoot, [...index.filter((e) => !(e.component === component && e.isUserLevel === isUserLevel)), ...survivors]);
-	const indexByName = new Map(survivors.map((e) => [e.name, e]));
-	return scanForComponent.map((s) => {
+	const indexByName = new Map(relevantIndex.map((e) => [e.name, e]));
+	const listed = scanForComponent.map((s) => {
 		const idx = indexByName.get(s.name);
 		return {
 			...s,
 			component,
-			instanceDir: idx?.instanceDir,
+			instanceDir: idx?.instanceDir ?? s.instanceDir,
 			source: idx ? "index+scan" : "scan"
 		};
 	});
+	const reconciled = [];
+	for (const l of listed) {
+		if (!l.instanceDir) continue;
+		reconciled.push({
+			component,
+			name: l.name,
+			platform: l.platform,
+			isUserLevel,
+			instanceDir: l.instanceDir
+		});
+	}
+	if (!sameIndexSet(relevantIndex, reconciled)) writeIndex(kiciRoot, [...index.filter((e) => !(e.component === component && e.isUserLevel === isUserLevel)), ...reconciled]);
+	return listed;
+}
+/** Order-insensitive equality of two index-entry sets (by their full identity). */
+function sameIndexSet(a, b) {
+	if (a.length !== b.length) return false;
+	const key = (e) => `${e.component}\0${e.name}\0${e.platform}\0${e.isUserLevel}\0${e.instanceDir}`;
+	const setA = new Set(a.map(key));
+	return b.every((e) => setA.has(key(e)));
 }
 /**
 * Resolve the target instance for the current lifecycle invocation.
@@ -6863,6 +7592,7 @@ var init_systemd = __esmMin((() => {
 			lines.push("[Unit]");
 			lines.push(`Description=${config.description}`);
 			if (config.component) lines.push(`X-KiCI-Component=${config.component}`);
+			if (config.instanceDir) lines.push(`X-KiCI-InstanceDir=${config.instanceDir}`);
 			lines.push("After=network.target postgresql.service");
 			lines.push("");
 			lines.push("[Service]");
@@ -6999,6 +7729,22 @@ var init_systemd = __esmMin((() => {
 		async isInstalled(config) {
 			return fs.existsSync(this.unitFilePath(config));
 		}
+		async readLaunchSpec(config) {
+			let content;
+			try {
+				content = fs.readFileSync(this.unitFilePath(config), "utf-8");
+			} catch {
+				return null;
+			}
+			const m = content.match(/^ExecStart=(.+?)\s*$/m);
+			if (!m) return null;
+			const tokens = m[1].trim().split(/\s+/).filter(Boolean);
+			if (tokens.length === 0) return null;
+			return {
+				execPath: tokens[0],
+				args: tokens.slice(1)
+			};
+		}
 		async list(isUserLevel) {
 			const unitDir = isUserLevel ? path.join(os.homedir(), ".config", "systemd", "user") : "/etc/systemd/system";
 			if (!fs.existsSync(unitDir)) return [];
@@ -7006,13 +7752,16 @@ var init_systemd = __esmMin((() => {
 			for (const entry of fs.readdirSync(unitDir)) {
 				if (typeof entry !== "string") continue;
 				if (!entry.startsWith("kici-") || !entry.endsWith(".service")) continue;
-				const m = fs.readFileSync(path.join(unitDir, entry), "utf-8").match(/^X-KiCI-Component=(orchestrator|agent)\s*$/m);
+				const content = fs.readFileSync(path.join(unitDir, entry), "utf-8");
+				const m = content.match(/^X-KiCI-Component=(orchestrator|agent)\s*$/m);
 				if (!m) continue;
+				const dirMatch = content.match(/^X-KiCI-InstanceDir=(.+?)\s*$/m);
 				out.push({
 					name: entry.replace(/\.service$/, ""),
 					platform: "systemd",
 					isUserLevel,
-					component: m[1]
+					component: m[1],
+					instanceDir: dirMatch?.[1]
 				});
 			}
 			return out;
@@ -7071,6 +7820,10 @@ var init_launchd = __esmMin((() => {
 		escapeXml(s) {
 			return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 		}
+		/** Inverse of {@link escapeXml} — decode the entities back to literals. */
+		unescapeXml(s) {
+			return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&amp;/g, "&");
+		}
 		/**
 		* Generate a launchd plist XML string from a service config.
 		* Visible for testing.
@@ -7090,6 +7843,10 @@ var init_launchd = __esmMin((() => {
 				lines.push("  <key>KiCIComponent</key>");
 				lines.push(`  <string>${config.component}</string>`);
 			}
+			if (config.instanceDir) {
+				lines.push("  <key>KiCIInstanceDir</key>");
+				lines.push(`  <string>${this.escapeXml(config.instanceDir)}</string>`);
+			}
 			lines.push("  <key>ProgramArguments</key>");
 			lines.push("  <array>");
 			lines.push(`    <string>${this.escapeXml(config.executablePath)}</string>`);
@@ -7309,15 +8066,33 @@ var init_launchd = __esmMin((() => {
 				}
 				const match = content.match(/<key>KiCIComponent<\/key>\s*<string>(orchestrator|agent)<\/string>/);
 				if (!match) continue;
+				const dirMatch = content.match(/<key>KiCIInstanceDir<\/key>\s*<string>([^<]+)<\/string>/);
 				out.push({
 					name: entry.replace(/\.plist$/, ""),
 					platform: "launchd",
 					isUserLevel,
-					component: match[1]
+					component: match[1],
+					instanceDir: dirMatch ? this.unescapeXml(dirMatch[1]) : void 0
 				});
 			}
 			return out;
 		}
+		async readLaunchSpec(config) {
+			let content;
+			try {
+				content = fs.readFileSync(this.plistPath(config), "utf-8");
+			} catch {
+				return null;
+			}
+			const arr = content.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+			if (!arr) return null;
+			const strings = [...arr[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((s) => this.unescapeXml(s[1]));
+			if (strings.length === 0) return null;
+			return {
+				execPath: strings[0],
+				args: strings.slice(1)
+			};
+		}
 	};
 }));
 //#endregion
@@ -7452,61 +8227,61 @@ var init_registry = __esmMin((() => {
 		rolldown: {
 			"linux-x64": {
 				name: "rolldown",
-				version: "1.0.0-rc.9",
+				version: "1.1.1",
 				platform: "linux",
 				arch: "x64",
-				url: "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.9.tgz",
-				sha256: "e97ccb470b8310892a5b5cfae640c728396c16317d1e7c8d305c738f63cfc13b",
+				url: "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.1.1.tgz",
+				sha256: "55bf455e4d6c5df19636c40b434718891a574214bbf09a50e2e7b21b9f640d56",
 				extractPath: "package/",
 				archiveType: "tar.gz"
 			},
 			"linux-arm64": {
 				name: "rolldown",
-				version: "1.0.0-rc.9",
+				version: "1.1.1",
 				platform: "linux",
 				arch: "arm64",
-				url: "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.9.tgz",
-				sha256: "65b675cd2d065f9cac4acba9cab743269f5f21cfe2d34f18dc4ae5e5a80b01e8",
+				url: "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.1.1.tgz",
+				sha256: "af458cfd2ce237a5161bdfdcef960e710c394b966537e1d1374840fb7fc78308",
 				extractPath: "package/",
 				archiveType: "tar.gz"
 			},
 			"darwin-x64": {
 				name: "rolldown",
-				version: "1.0.0-rc.9",
+				version: "1.1.1",
 				platform: "darwin",
 				arch: "x64",
-				url: "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.9.tgz",
-				sha256: "a7b282b2c2f809aed6ef8d90fe1412730e8d73de4a67997f3a91d9fca0568dd5",
+				url: "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.1.1.tgz",
+				sha256: "31bd12457aa41646dcee674d7fa73ec2c4625ef5d34d0ef6c6823cad811de3e2",
 				extractPath: "package/",
 				archiveType: "tar.gz"
 			},
 			"darwin-arm64": {
 				name: "rolldown",
-				version: "1.0.0-rc.9",
+				version: "1.1.1",
 				platform: "darwin",
 				arch: "arm64",
-				url: "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.9.tgz",
-				sha256: "19464bb79c19817892722bfd172874d6853fa07c800deac965cc3c3e7e6e0739",
+				url: "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.1.1.tgz",
+				sha256: "8399e7a87640ffe485ba16289f6c3a7ab69b25d09b43e5896441372bcf6a02f9",
 				extractPath: "package/",
 				archiveType: "tar.gz"
 			},
 			"win32-x64": {
 				name: "rolldown",
-				version: "1.0.0-rc.9",
+				version: "1.1.1",
 				platform: "win32",
 				arch: "x64",
-				url: "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.9.tgz",
-				sha256: "e359891b2508f9dde392367f70e0e8ad3511a595cf2a6d5ee33115eed8de8e86",
+				url: "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.1.1.tgz",
+				sha256: "2b2c34d530db0e2cf15cdbe328822d5d385b19ee3b5aba55771587027b9afa17",
 				extractPath: "package/",
 				archiveType: "tar.gz"
 			},
 			"win32-arm64": {
 				name: "rolldown",
-				version: "1.0.0-rc.9",
+				version: "1.1.1",
 				platform: "win32",
 				arch: "arm64",
-				url: "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.9.tgz",
-				sha256: "e5473c970cdc559a392c8d4ffe10ef758712e7fd19e60f67bc1cb189b5f3260a",
+				url: "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.1.1.tgz",
+				sha256: "d7431cb75d0bed42dd8794b89c3d73ac7129a36465ac020519726f2a9dca1d7c",
 				extractPath: "package/",
 				archiveType: "tar.gz"
 			}
@@ -7615,7 +8390,8 @@ var init_windows = __esmMin((() => {
 			cmdParts.push("--", `"${config.executablePath}"`);
 			for (const arg of config.args ?? []) cmdParts.push(`"${arg}"`);
 			execSync(cmdParts.join(" "), { stdio: "pipe" });
-			const descText = config.component ? `[KiCI:${config.component}] ${config.description}` : config.description;
+			const dirSuffix = config.component && config.instanceDir ? ` [KiCI-DIR:${config.instanceDir}]` : "";
+			const descText = config.component ? `[KiCI:${config.component}] ${config.description}${dirSuffix}` : config.description;
 			execSync(`sc.exe description ${config.name} "${descText.replace(/"/g, "\\\"")}"`, { stdio: "pipe" });
 			execSync(`sc.exe config ${config.name} start= auto`, { stdio: "pipe" });
 			const actions = config.restartPolicy.delays.map((d) => `restart/${d * 1e3}`).join("/");
@@ -7726,18 +8502,39 @@ var init_windows = __esmMin((() => {
 			for (const row of rows) {
 				if (!row || typeof row !== "object") continue;
 				const r = row;
-				const match = (typeof r.Description === "string" ? r.Description : "").match(/^\[KiCI:(orchestrator|agent)\]/);
+				const desc = typeof r.Description === "string" ? r.Description : "";
+				const match = desc.match(/^\[KiCI:(orchestrator|agent)\]/);
 				if (!match) continue;
 				if (typeof r.Name !== "string") continue;
+				const dirMatch = desc.match(/\[KiCI-DIR:([^\]]+)\]/);
 				out.push({
 					name: r.Name,
 					platform: "windows",
 					isUserLevel,
-					component: match[1]
+					component: match[1],
+					instanceDir: dirMatch?.[1]
 				});
 			}
 			return out;
 		}
+		async readLaunchSpec(config) {
+			let raw;
+			try {
+				raw = execSync(`sc.exe qc ${config.name}`, { stdio: "pipe" }).toString();
+			} catch {
+				return null;
+			}
+			const m = raw.match(/BINARY_PATH_NAME\s*:\s*(.+)/);
+			if (!m) return null;
+			const sep = m[1].indexOf(" -- ");
+			if (sep === -1) return null;
+			const tokens = [...m[1].slice(sep + 4).matchAll(/"([^"]*)"|(\S+)/g)].map((t) => t[1] ?? t[2]);
+			if (tokens.length === 0 || !tokens[0]) return null;
+			return {
+				execPath: tokens[0],
+				args: tokens.slice(1)
+			};
+		}
 	};
 }));
 //#endregion
@@ -7878,6 +8675,7 @@ function generateComposeYaml(config) {
 	if (config.component) {
 		lines.push("    labels:");
 		lines.push(`      dev.kici.component: ${config.component}`);
+		if (config.instanceDir) lines.push(`      dev.kici.instance-dir: "${config.instanceDir}"`);
 	}
 	return lines.join("\n") + "\n";
 }
@@ -7970,19 +8768,25 @@ var init_compose = __esmMin((() => {
 				}
 				if (!row || typeof row !== "object") continue;
 				const r = row;
-				const m = (typeof r.Labels === "string" ? r.Labels : "").match(/dev\.kici\.component=(orchestrator|agent)/);
+				const labels = typeof r.Labels === "string" ? r.Labels : "";
+				const m = labels.match(/dev\.kici\.component=(orchestrator|agent)/);
 				if (!m) continue;
 				const name = typeof r.Names === "string" ? r.Names : String(r.Names ?? "");
 				if (!name) continue;
+				const dirMatch = labels.match(/dev\.kici\.instance-dir=([^,]+)/);
 				out.push({
 					name,
 					platform: "compose",
 					isUserLevel,
-					component: m[1]
+					component: m[1],
+					instanceDir: dirMatch?.[1]
 				});
 			}
 			return out;
 		}
+		async readLaunchSpec(_config) {
+			return null;
+		}
 	};
 }));
 //#endregion
@@ -8104,7 +8908,8 @@ async function resolveUpgradeTarget(args) {
 				maxRetries: 5,
 				windowSeconds: 300
 			},
-			component
+			component,
+			instanceDir: resolved.instanceDir
 		},
 		installBase: resolved.manifest.installBase,
 		resolvedInstance: resolved
@@ -8243,6 +9048,51 @@ function updateSymlinkAtomic(installBase, component, version) {
 * 5. Update symlink (Unix) or service registration (Windows)
 * 6. Start service
 */
+/**
+* Resolve the target version for an npm-source upgrade (no --from/--url).
+*
+* The npm-source flow assumes the operator already ran
+* `npm install -g @kici-dev/<pkg>@<version>`, which overwrites the global
+* package in place. The running `kici-admin` binary is therefore the new
+* version, and `running` is its self-reported version. We default the target
+* to it, or validate an explicitly-passed --version matches — a mismatch means
+* the npm install did not actually update the global binary.
+*/
+function resolveNpmSourceVersion(opts) {
+	if (opts.running === "unknown" || opts.running.trim() === "") throw new Error("npm-source upgrade: could not determine the running package version. Pass --from <archive> / --url <url> + --version for an archive-based upgrade instead.");
+	if (opts.requested && opts.requested !== opts.running) throw new Error(`npm-source upgrade: requested --version ${opts.requested} does not match the installed package version ${opts.running}. Run \`npm install -g @kici-dev/<pkg>@${opts.requested}\` first, then re-run the upgrade.`);
+	return opts.running;
+}
+/**
+* Decide whether an npm-source upgrade may proceed, given the version the
+* invoking CLI is (`invoked`) and the version the installed unit will actually
+* launch (`launched`, or null when unresolvable — e.g. an opaque --binary
+* install). On success `manifestVersion` is the value to persist (null = leave
+* the manifest's kiciVersion unchanged because we couldn't verify it).
+*/
+function verifyNpmSourceLaunch(opts) {
+	const { component, invoked, launched, launchedPath, force } = opts;
+	if (launched === null) {
+		if (force) return {
+			ok: true,
+			version: invoked,
+			manifestVersion: null
+		};
+		return {
+			ok: false,
+			reason: "npm-source upgrade aborted: could not determine the version the installed unit will launch (custom --binary install or unparseable launch target). Pass --force to restart without version verification (the manifest version is left unchanged)."
+		};
+	}
+	if (launched !== invoked) return {
+		ok: false,
+		reason: `npm-source upgrade aborted: this kici-admin is version ${invoked}, but the installed unit will launch version ${launched}${launchedPath ? ` (via ${launchedPath})` : ""}. Your \`npm install -g\` updated a different install than the service is pinned to. Install ${invoked} under the unit's runtime (the node its ExecStart points at), or re-run \`kici-admin ${component} install\` to repoint the unit, then retry.`
+	};
+	return {
+		ok: true,
+		version: launched,
+		manifestVersion: launched
+	};
+}
 async function performVersionedUpgrade(component, opts) {
 	try {
 		const platform = detectPlatform(opts.platform);
@@ -8272,8 +9122,8 @@ async function performVersionedUpgrade(component, opts) {
 			return;
 		}
 		if (!opts.from && !opts.url) {
-			console.error("Error: provide --from <archive-path> or --url <url> for the upgrade package");
-			process.exit(1);
+			await performNpmSourceUpgrade(component, config, resolvedInstance, manager, opts);
+			return;
 		}
 		if (!opts.version) {
 			console.error("Error: --version is required to specify the target version");
@@ -8375,6 +9225,54 @@ async function performVersionedUpgrade(component, opts) {
 	}
 }
 /**
+* npm-source upgrade (no --from/--url): the operator has already run
+* `npm install -g @kici-dev/<pkg>@<version>`, replacing the global package
+* in place. The systemd/launchd/Windows unit's ExecStart points at that global
+* package (see install.ts → import.meta.resolve), so a stop+start re-executes
+* the freshly-installed code. No archive, no versioned dir, no symlink.
+*/
+async function performNpmSourceUpgrade(component, config, resolvedInstance, manager, opts) {
+	const invoked = readKiciVersion();
+	resolveNpmSourceVersion({
+		requested: opts.version,
+		running: invoked
+	});
+	if (!await manager.isInstalled(config)) {
+		console.error(`Error: service "${config.name}" is not installed`);
+		process.exit(1);
+	}
+	const spec = await manager.readLaunchSpec(config);
+	const verdict = verifyNpmSourceLaunch({
+		component,
+		invoked,
+		launched: spec ? resolveVersionFromLaunchSpec(spec, component) : null,
+		launchedPath: spec?.execPath ?? null,
+		force: opts.force ?? false
+	});
+	if (!verdict.ok) {
+		console.error(`Error: ${verdict.reason}`);
+		process.exit(1);
+	}
+	if (!opts.yes) {
+		console.log(`This will restart "${config.name}" onto the npm-installed version ${verdict.version}.`);
+		console.log("  The service will be stopped briefly during the restart.");
+		console.log("");
+		if (!await confirm$2("Proceed with upgrade?")) {
+			console.log("Upgrade cancelled.");
+			return;
+		}
+	}
+	console.log("Restarting service onto the npm-installed package...");
+	if ((await manager.status(config)).state === "running") await manager.stop(config);
+	await manager.start(config);
+	if (verdict.manifestVersion !== null) writeManifest(resolvedInstance.instanceDir, {
+		...resolvedInstance.manifest,
+		kiciVersion: verdict.manifestVersion
+	});
+	else console.log("Note: manifest version left unchanged (verification was skipped via --force).");
+	console.log(`Upgrade complete: service "${config.name}" is now running version ${verdict.version}.`);
+}
+/**
 * Handle --rollback: switch symlink to the previous version and restart.
 */
 async function handleRollback(component, platform, installBase, config, manager, opts) {
@@ -8722,7 +9620,7 @@ function registerOrchestratorInstall(orchestrator) {
 			})).find((c) => c.name === serviceName);
 			if (existing && existing.instanceDir !== instanceDir && !opts.force) {
 				const at = existing.instanceDir ?? "(no manifest)";
-				console.error(`Error: an orchestrator instance "${serviceName}" is already installed at ${at}. Pass a different --name, a different --instance-dir, or --force to overwrite.`);
+				console.error(`Error: an orchestrator instance "${serviceName}" is already installed at ${at}.\n\nUpgrading this service? Don't re-run install — installing again is for first-time\nsetup, not upgrades. For an npm-global install run \`npm install -g kici-admin@latest\`\nthen \`kici-admin orchestrator restart\`; for a versioned-directory install run\n\`kici-admin orchestrator upgrade\`.\n\nInstalling a second, separate instance? Pass a different --name or --instance-dir,\nor --force to take over this one.`);
 				process.exit(1);
 			}
 			const configDir = getConfigDir(serviceName, userLevel);
@@ -8791,6 +9689,7 @@ function registerOrchestratorInstall(orchestrator) {
 				isUserLevel: userLevel,
 				user: opts.user,
 				component: "orchestrator",
+				instanceDir,
 				restartPolicy: DEFAULT_RESTART_POLICY
 			};
 			await manager.install(config);
@@ -9297,6 +10196,7 @@ function registerAgentInstall(agent) {
 				workingDirectory: configDir,
 				isUserLevel: userLevel,
 				component: "agent",
+				instanceDir,
 				restartPolicy: DEFAULT_RESTART_POLICY
 			};
 			await manager.install(config);
@@ -9730,6 +10630,7 @@ const TOKEN_PREFIX = "kici_join_v1";
 const DEFAULT_EXPIRY_MS = 36e5;
 const TOKEN_ALREADY_USED_MESSAGE = "Join token has already been used. Generate a new token with: kici admin create-join-token";
 var JoinTokenManager = class {
+	deps;
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -9859,6 +10760,7 @@ const DEFAULT_EXPIRY_DAYS = 90;
 * Used by the coordinator to manage credentials for all cluster members.
 */
 var PeerCredentialStore = class {
+	db;
 	constructor(db) {
 		this.db = db;
 	}
@@ -10087,6 +10989,211 @@ function registerPeerCommands(program, _getClient) {
 		}
 	});
 }
+/**
+* The ONE status-derivation function — used by the store and the kici-admin
+* host CLI. `ready` requires the host to be genuinely live (connected to some
+* instance AND heartbeat fresh — the freshness check catches a crashed
+* instance that never cleared `connected_instance_id`). It never returns
+* `ready` for a not-currently-live host: a not-live `static` reads
+* `unreachable` (the declared-but-absent alarm), a not-live `ephemeral` reads
+* `stale` (scaled down, awaiting reap).
+*/
+function deriveHostStatus(row, nowMs, graceMs) {
+	const ageMs = nowMs - new Date(row.last_seen).getTime();
+	if (row.connected_instance_id !== null && ageMs <= graceMs) return "ready";
+	if (row.lifecycle_class === "ephemeral") return "stale";
+	return "unreachable";
+}
+/**
+* Durable, cluster-shared roster of every agent the cluster has ever enrolled.
+*
+* The in-memory `AgentRegistry` reconciles into this table on register
+* (`upsert`) / unregister (`markDisconnected`), with a coarse heartbeat
+* (`stampLastSeen`). All liveness writes are owner-guarded by `instanceId` so a
+* stale disconnect from an old instance can never clobber a row a different
+* instance now owns. The leader-only reaper deletes `ephemeral` rows past their
+* ttl via `reapEphemeralPastTtl`; `static` rows persist and read `unreachable`.
+*/
+var HostRosterStore = class {
+	db;
+	constructor(db) {
+		this.db = db;
+	}
+	/** Idempotent upsert on agent_id; stamps connected_instance_id + last_seen. */
+	async upsert(input) {
+		const labelsJson = JSON.stringify(input.labels);
+		await this.db.insertInto("host_roster").values({
+			agent_id: input.agentId,
+			token_id: input.tokenId,
+			lifecycle_class: input.lifecycleClass,
+			labels: labelsJson,
+			hostname: input.hostname,
+			platform: input.platform,
+			arch: input.arch,
+			connected_instance_id: input.instanceId,
+			last_seen: sql`now()`,
+			updated_at: sql`now()`
+		}).onConflict((oc) => oc.column("agent_id").doUpdateSet({
+			token_id: input.tokenId,
+			lifecycle_class: input.lifecycleClass,
+			labels: labelsJson,
+			hostname: input.hostname,
+			platform: input.platform,
+			arch: input.arch,
+			connected_instance_id: input.instanceId,
+			last_seen: sql`now()`,
+			updated_at: sql`now()`
+		})).execute();
+	}
+	/** Clear liveness on disconnect — but only if THIS instance still owns it. */
+	async markDisconnected(agentId, instanceId) {
+		await this.db.updateTable("host_roster").set({
+			connected_instance_id: null,
+			updated_at: sql`now()`
+		}).where("agent_id", "=", agentId).where("connected_instance_id", "=", instanceId).execute();
+	}
+	/** Coarse heartbeat stamp — same owner-guard as markDisconnected. */
+	async stampLastSeen(agentId, instanceId) {
+		await this.db.updateTable("host_roster").set({ last_seen: sql`now()` }).where("agent_id", "=", agentId).where("connected_instance_id", "=", instanceId).execute();
+	}
+	/** Operator pre-declare of a static host before its agent dials in. */
+	async declareStatic(input) {
+		await this.db.insertInto("host_roster").values({
+			agent_id: input.agentId,
+			token_id: null,
+			lifecycle_class: "static",
+			labels: JSON.stringify(input.labels),
+			hostname: input.hostname ?? null,
+			connected_instance_id: null,
+			last_seen: sql`now()`,
+			updated_at: sql`now()`
+		}).onConflict((oc) => oc.column("agent_id").doNothing()).execute();
+	}
+	async get(agentId) {
+		return await this.db.selectFrom("host_roster").selectAll().where("agent_id", "=", agentId).executeTakeFirst() ?? null;
+	}
+	async listAll() {
+		return this.db.selectFrom("host_roster").selectAll().orderBy("agent_id", "asc").execute();
+	}
+	/**
+	* Resolve every roster host matching a `runsOnAll` predicate (OR-of-AND
+	* include groups, minus exclude labels), tagged with its derived status. This
+	* is the host-fanout resolver: it returns declared-but-absent static hosts
+	* (status `unreachable`) so the caller can apply `onUnreachable` — the live
+	* registry alone cannot name an expected-but-absent host.
+	*/
+	async findMatching(include, exclude, graceMs) {
+		const rows = await this.db.selectFrom("host_roster").selectAll().execute();
+		const now = Date.now();
+		const out = [];
+		for (const row of rows) {
+			const labels = JSON.parse(row.labels);
+			const set = new Set(labels);
+			if (exclude.some((e) => matcherSatisfiedBy(e, set))) continue;
+			if (include.length && !include.some((grp) => grp.every((m) => matcherSatisfiedBy(m, set)))) continue;
+			out.push({
+				agentId: row.agent_id,
+				host: row.hostname ?? row.agent_id,
+				labels,
+				lifecycleClass: row.lifecycle_class,
+				connectedInstanceId: row.connected_instance_id,
+				status: deriveHostStatus(row, now, graceMs),
+				platform: row.platform,
+				arch: row.arch
+			});
+		}
+		out.sort((a, b) => a.agentId.localeCompare(b.agentId));
+		return out;
+	}
+	/**
+	* Count `static` (declared) hosts whose derived status is `unreachable` —
+	* the "declared-but-absent" alarm population. Reuses the single-source
+	* {@link deriveHostStatus} so the count never diverges from what
+	* `kici-admin host list` shows. A not-currently-connected static host reads
+	* `unreachable` regardless of grace (only the connected-but-stale case
+	* depends on `graceMs`).
+	*/
+	async countStaticUnreachable(graceMs) {
+		const rows = await this.db.selectFrom("host_roster").selectAll().where("lifecycle_class", "=", "static").execute();
+		const now = Date.now();
+		return rows.filter((r) => deriveHostStatus(r, now, graceMs) === "unreachable").length;
+	}
+	/** Delete ephemeral rows whose last_seen is older than ttl. Returns count. */
+	async reapEphemeralPastTtl(ttlMs) {
+		const res = await this.db.deleteFrom("host_roster").where("lifecycle_class", "=", "ephemeral").where("last_seen", "<", sql`now() - (${ttlMs}::text || ' milliseconds')::interval`).executeTakeFirst();
+		return Number(res.numDeletedRows ?? 0n);
+	}
+};
+//#endregion
+//#region src/cli/commands/host.ts
+/**
+* The CLI reads the roster DB directly (no full orchestrator config load), so
+* it sources the grace window from the same env var the orchestrator config
+* defaults from. Default mirrors `config.ts` rosterGraceMs (300_000).
+*/
+function rosterGraceMs() {
+	const v = Number(process.env.KICI_ROSTER_GRACE_MS);
+	return Number.isFinite(v) && v > 0 ? v : 3e5;
+}
+function formatHostTable(rows) {
+	if (rows.length === 0) return "No hosts in the roster.";
+	const header = "Agent ID | Class | Status | Instance | Last Seen | Labels";
+	const sep = "-".repeat(57);
+	const now = Date.now();
+	const grace = rosterGraceMs();
+	return [
+		header,
+		sep,
+		...rows.map((r) => {
+			const status = deriveHostStatus(r, now, grace);
+			const labels = JSON.parse(r.labels).join(",");
+			return `${r.agent_id} | ${r.lifecycle_class} | ${status} | ${r.connected_instance_id ?? "-"} | ${new Date(r.last_seen).toISOString()} | ${labels}`;
+		})
+	].join("\n");
+}
+function registerHostCommands(program) {
+	const host = program.command("host").description("Inspect and declare the host roster");
+	host.command("list").description("List all roster hosts").option("--json", "Output JSON").action(async (opts) => {
+		try {
+			const rows = await withDb((db) => new HostRosterStore(db).listAll());
+			if (opts.json) {
+				console.log(JSON.stringify(rows, null, 2));
+				return;
+			}
+			console.log(formatHostTable(rows));
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+	host.command("get").description("Show one roster host").requiredOption("--agent-id <id>", "Agent id").option("--json", "Output JSON").action(async (opts) => {
+		try {
+			const row = await withDb((db) => new HostRosterStore(db).get(opts.agentId));
+			if (!row) {
+				console.error(`No host found: ${opts.agentId}`);
+				process.exit(1);
+			}
+			console.log(opts.json ? JSON.stringify(row, null, 2) : formatHostTable([row]));
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+	host.command("declare").description("Pre-declare a static host before it connects").requiredOption("--agent-id <id>", "Agent id the host will register as").option("--labels <labels>", "Comma-separated labels", "").option("--hostname <name>", "Hostname").action(async (opts) => {
+		try {
+			const labels = opts.labels ? String(opts.labels).split(",").map((s) => s.trim()).filter(Boolean) : [];
+			await withDb((db) => new HostRosterStore(db).declareStatic({
+				agentId: opts.agentId,
+				labels,
+				hostname: opts.hostname
+			}));
+			console.log(`Declared static host: ${opts.agentId}`);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+}
 //#endregion
 //#region src/cli/commands/org-settings.ts
 function formatSettings(s, format) {
@@ -11448,6 +12555,8 @@ var init_execution_steps = __esmMin((() => {
 		enabled: true
 	};
 	ExecutionStepsAdapter = class {
+		kdb;
+		instanceId;
 		db = "orchestrator";
 		table = "execution_steps";
 		tenantColumn = "routing_key";
@@ -11603,6 +12712,8 @@ var init_execution_jobs = __esmMin((() => {
 		enabled: true
 	};
 	ExecutionJobsAdapter = class {
+		kdb;
+		instanceId;
 		db = "orchestrator";
 		table = "execution_jobs";
 		tenantColumn = "routing_key";
@@ -11771,6 +12882,8 @@ var init_execution_runs = __esmMin((() => {
 		enabled: true
 	};
 	ExecutionRunsAdapter = class {
+		kdb;
+		instanceId;
 		db = "orchestrator";
 		table = "execution_runs";
 		tenantColumn = "routing_key";
@@ -12002,6 +13115,8 @@ var init_secret_audit_log = __esmMin((() => {
 		enabled: true
 	};
 	SecretAuditLogAdapter = class {
+		kdb;
+		instanceId;
 		db = "orchestrator";
 		table = "secret_audit_log";
 		tenantColumn = "routing_key";
@@ -12255,6 +13370,8 @@ var init_access_log = __esmMin((() => {
 		enabled: true
 	};
 	AccessLogAdapter = class {
+		kdb;
+		instanceId;
 		db = "orchestrator";
 		table = "access_log";
 		tenantColumn = "org_id";
@@ -12510,6 +13627,8 @@ var init_event_log = __esmMin((() => {
 		enabled: true
 	};
 	EventLogAdapter = class {
+		kdb;
+		instanceId;
 		db = "orchestrator";
 		table = "event_log";
 		tenantColumn = "routing_key";
@@ -14590,6 +15709,7 @@ var FirecrackerApiError = class extends Error {
 * the `socketPath` option for HTTP-over-Unix-socket communication.
 */
 var FirecrackerApi = class {
+	socketPath;
 	constructor(socketPath) {
 		this.socketPath = socketPath;
 	}
@@ -16577,6 +17697,7 @@ async function writeConfigFile(path, config) {
 	await writeFile(path, stringify(config), "utf-8");
 }
 var JoinClient = class {
+	options;
 	constructor(options) {
 		this.options = options;
 		if (!options.platformUrl && !options.peerUrl) throw new Error("Either --platform or --peer must be specified");
@@ -16748,6 +17869,7 @@ function buildProgram() {
 	registerConfigCommands(program, getClient);
 	registerDbCommands(program, getClient);
 	registerSourceCommands(program, getClient);
+	registerRemoteSourceCommands(program);
 	registerWorkflowCommands(program, getClient);
 	registerRunsCommands(program, getClient);
 	registerEventLogCommands(program, getClient);
@@ -16761,6 +17883,7 @@ function buildProgram() {
 	registerScalerCommands(program);
 	registerAgentServiceCommands(program);
 	registerPeerCommands(program, getClient);
+	registerHostCommands(program);
 	registerOrgSettingsCommands(program, getClient);
 	registerClusterNameCommands(program, getClient);
 	registerMaintenanceCommands(program, getClient);
@@ -16779,8 +17902,27 @@ function buildProgram() {
 function runCli(argv = process.argv) {
 	buildProgram().parse(argv);
 }
-if (resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) runCli();
+/**
+* Canonicalize a path through any symlinks, falling back to a plain `resolve`
+* when the target does not exist on disk. The entry-point guard compares the
+* invoked script path against this module's own path; both sides must be fully
+* canonicalized or a symlinked invocation path silently fails the match. The
+* canonical example is the light-package launcher running
+* `node /tmp/.../kici-admin.cjs` on macOS, where `/tmp` is a symlink to
+* `/private/tmp`: `process.argv[1]` keeps the `/tmp` form while the bundle's
+* `import.meta.url` resolves to the real `/private/tmp` path, so an
+* un-canonicalized comparison is always false and the CLI exits 0 without
+* running any command.
+*/
+function canonicalize(p) {
+	try {
+		return realpathSync(resolve(p));
+	} catch {
+		return resolve(p);
+	}
+}
+if (canonicalize(process.argv[1] ?? "") === canonicalize(fileURLToPath(import.meta.url))) runCli();
 //#endregion
-export { buildProgram, runCli };
+export { buildProgram, canonicalize, runCli };
 
 //# sourceMappingURL=cli.js.map