@kici-dev/orchestrator 0.1.17 → 0.1.19

package/dist/cli.js

@@ -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";
@@ -979,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(),
@@ -1055,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),
 		/**
@@ -1550,8 +1554,8 @@ var init_client = __esmMin((() => {
 //#region src/db/migrations/001_initial.ts
 init_client();
 var _001_initial_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$37,
-	up: () => up$37
+	down: () => down$41,
+	up: () => up$41
 });
 /**
 * Squashed initial migration -- creates the complete Orchestrator database schema.
@@ -2243,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$37(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)
@@ -2265,7 +2269,7 @@ async function up$37(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$37(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",
@@ -2312,8 +2316,8 @@ async function down$37(db) {
 //#endregion
 //#region src/db/migrations/002_config_versions_key_version.ts
 var _002_config_versions_key_version_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$36,
-	up: () => up$36
+	down: () => down$40,
+	up: () => up$40
 });
 /**
 * Add key_version column to config_versions so that sensitive-field encryption
@@ -2327,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$36(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$36(db) {
+async function down$40(db) {
 	await sql`
     ALTER TABLE public.config_versions
       DROP COLUMN key_version
@@ -2342,8 +2346,8 @@ async function down$36(db) {
 //#endregion
 //#region src/db/migrations/003_access_log.ts
 var _003_access_log_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$35,
-	up: () => up$35
+	down: () => down$39,
+	up: () => up$39
 });
 /**
 * Access log: one row per read or orchestrator-admin mutation attributable
@@ -2367,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$35(db) {
+async function up$39(db) {
 	await sql`
     CREATE TABLE public.access_log (
       id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -2405,28 +2409,28 @@ async function up$35(db) {
       ON public.access_log (actor_type, actor_id, created_at DESC)
   `.execute(db);
 }
-async function down$35(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$34,
-	up: () => up$34
+	down: () => down$38,
+	up: () => up$38
 });
-async function up$34(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$34(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$33,
-	up: () => up$33
+	down: () => down$37,
+	up: () => up$37
 });
 /**
 * Cold-store chunk counter table.
@@ -2443,7 +2447,7 @@ var _005_cold_store_chunk_counter_exports = /* @__PURE__ */ __exportAll({
 *
 * sections 5 and 8.
 */
-async function up$33(db) {
+async function up$37(db) {
 	await sql`
     CREATE TABLE public.cold_store_chunk_counts (
       db                TEXT        NOT NULL,
@@ -2461,14 +2465,14 @@ async function up$33(db) {
       ON public.cold_store_chunk_counts (db, table_name)
   `.execute(db);
 }
-async function down$33(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$32,
-	up: () => up$32
+	down: () => down$36,
+	up: () => up$36
 });
 /**
 * `execution_runs` / `execution_jobs` / `execution_steps` cold-store
@@ -2504,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$32(db) {
+async function up$36(db) {
 	await sql`
     ALTER TABLE public.execution_runs
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2549,7 +2553,7 @@ async function up$32(db) {
       ON public.execution_steps (routing_key, created_at)
   `.execute(db);
 }
-async function down$32(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
@@ -2574,8 +2578,8 @@ async function down$32(db) {
 //#endregion
 //#region src/db/migrations/007_audit_logs_archived_at.ts
 var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$31,
-	up: () => up$31
+	down: () => down$35,
+	up: () => up$35
 });
 /**
 * `secret_audit_log` and `access_log` cold-store schema additions, plus
@@ -2615,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$31(db) {
+async function up$35(db) {
 	await sql`
     ALTER TABLE public.secret_audit_log
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2636,7 +2640,7 @@ async function up$31(db) {
       DROP COLUMN IF EXISTS expires_at
   `.execute(db);
 }
-async function down$31(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')
@@ -2664,8 +2668,8 @@ async function down$31(db) {
 //#endregion
 //#region src/db/migrations/008_event_log_archived_at.ts
 var _008_event_log_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$30,
-	up: () => up$30
+	down: () => down$34,
+	up: () => up$34
 });
 /**
 * `event_log` cold-store schema additions plus removal of the
@@ -2703,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$30(db) {
+async function up$34(db) {
 	await sql`
     ALTER TABLE public.event_log
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2719,7 +2723,7 @@ async function up$30(db) {
       DROP COLUMN IF EXISTS expires_at
   `.execute(db);
 }
-async function down$30(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')
@@ -2738,8 +2742,8 @@ async function down$30(db) {
 //#endregion
 //#region src/db/migrations/009_access_log_trigram.ts
 var _009_access_log_trigram_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$29,
-	up: () => up$29
+	down: () => down$33,
+	up: () => up$33
 });
 /**
 * Trigram (pg_trgm) index on access_log.error_message for the federated
@@ -2752,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$29(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
@@ -2761,14 +2765,14 @@ async function up$29(db) {
       WHERE error_message IS NOT NULL
   `.execute(db);
 }
-async function down$29(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$28,
-	up: () => up$28
+	down: () => down$32,
+	up: () => up$32
 });
 /**
 * Cold-store chunk index — Phase 2 (cold-store purge).
@@ -2800,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$28(db) {
+async function up$32(db) {
 	await sql`
     CREATE TABLE public.cold_store_chunks (
       db              TEXT        NOT NULL,
@@ -2827,14 +2831,14 @@ async function up$28(db) {
       ON public.cold_store_chunks (db, table_name, tenant_id, archived_at DESC)
   `.execute(db);
 }
-async function down$28(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$27,
-	up: () => up$27
+	down: () => down$31,
+	up: () => up$31
 });
 /**
 * Drop the `source_secrets_change_trigger` and the
@@ -2853,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$27(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$27(db) {
+async function down$31(db) {
 	await sql`
     CREATE OR REPLACE FUNCTION public.notify_source_secrets_change() RETURNS trigger
       LANGUAGE plpgsql
@@ -2896,8 +2900,8 @@ async function down$27(db) {
 //#endregion
 //#region src/db/migrations/012_peer_credentials_active_uniq.ts
 var _012_peer_credentials_active_uniq_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$26,
-	up: () => up$26
+	down: () => down$30,
+	up: () => up$30
 });
 /**
 * Add a partial unique index on `peer_credentials (instance_id) WHERE
@@ -2923,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$26(db) {
+async function up$30(db) {
 	await sql`
     UPDATE public.peer_credentials
     SET revoked_at = NOW()
@@ -2941,14 +2945,14 @@ async function up$26(db) {
       WHERE revoked_at IS NULL
   `.execute(db);
 }
-async function down$26(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$25,
-	up: () => up$25
+	down: () => down$29,
+	up: () => up$29
 });
 /**
 * Add `log_bytes BIGINT NOT NULL DEFAULT 0` columns to `execution_runs` and
@@ -2967,7 +2971,7 @@ var _013_execution_log_bytes_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent (`ADD COLUMN IF NOT EXISTS`).
 */
-async function up$25(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
@@ -2977,15 +2981,15 @@ async function up$25(db) {
       ADD COLUMN IF NOT EXISTS log_bytes BIGINT NOT NULL DEFAULT 0
   `.execute(db);
 }
-async function down$25(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$24,
-	up: () => up$24
+	down: () => down$28,
+	up: () => up$28
 });
 /**
 * Add lease + retry + DLQ columns to `kici_events` so the EventRouter can
@@ -3019,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$24(db) {
+async function up$28(db) {
 	await sql`
     ALTER TABLE public.kici_events
       ADD COLUMN IF NOT EXISTS claimed_at TIMESTAMPTZ,
@@ -3050,7 +3054,7 @@ async function up$24(db) {
       WHERE dlq_at IS NOT NULL
   `.execute(db);
 }
-async function down$24(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);
@@ -3068,8 +3072,8 @@ async function down$24(db) {
 //#endregion
 //#region src/db/migrations/015_org_settings_customer_scoped.ts
 var _015_org_settings_customer_scoped_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$23,
-	up: () => up$23
+	down: () => down$27,
+	up: () => up$27
 });
 /**
 * Org-scope `org_settings` and qualify each glob entry by source.
@@ -3097,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$23(db) {
+async function up$27(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3222,7 +3226,7 @@ async function up$23(db) {
 	await sql`DROP TABLE _org_settings_merged`.execute(db);
 	await sql`DROP TABLE _org_settings_stage`.execute(db);
 }
-async function down$23(db) {
+async function down$27(db) {
 	if (!(await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3247,8 +3251,8 @@ async function down$23(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$22,
-	up: () => up$22
+	down: () => down$26,
+	up: () => up$26
 });
 /**
 * Add `org_settings.allow_http_npm_registries boolean NOT NULL DEFAULT false`.
@@ -3261,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$22(db) {
+async function up$26(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3275,7 +3279,7 @@ async function up$22(db) {
       ADD COLUMN allow_http_npm_registries boolean NOT NULL DEFAULT false
   `.execute(db);
 }
-async function down$22(db) {
+async function down$26(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS allow_http_npm_registries
   `.execute(db);
@@ -3283,8 +3287,8 @@ async function down$22(db) {
 //#endregion
 //#region src/db/migrations/017_org_id_widen.ts
 var _017_org_id_widen_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$21,
-	up: () => up$21
+	down: () => down$25,
+	up: () => up$25
 });
 /**
 * Widen every orchestrator-side `org_id varchar(12)` column to
@@ -3324,17 +3328,17 @@ const ORG_ID_TABLES$1 = [
 	"held_runs",
 	"scoped_secrets"
 ];
-async function up$21(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$21(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$20,
-	up: () => up$20
+	down: () => down$24,
+	up: () => up$24
 });
 /**
 * Prefix every orchestrator-side tenant string with `org_` to align
@@ -3379,19 +3383,19 @@ const CUSTOMER_ID_TABLES = [
 	"workflow_registrations",
 	"org_settings"
 ];
-async function up$20(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$20(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$19,
-	up: () => up$19
+	down: () => down$23,
+	up: () => up$23
 });
 /**
 * Add a Postgres trigger on `generic_webhook_sources` that emits
@@ -3414,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$19(db) {
+async function up$23(db) {
 	await sql`
     CREATE FUNCTION public.notify_generic_sources_change() RETURNS trigger
       LANGUAGE plpgsql
@@ -3435,15 +3439,15 @@ async function up$19(db) {
       FOR EACH ROW EXECUTE FUNCTION public.notify_generic_sources_change()
   `.execute(db);
 }
-async function down$19(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$18,
-	up: () => up$18
+	down: () => down$22,
+	up: () => up$22
 });
 /**
 * Add `org_settings.dashboard_write_policy jsonb NOT NULL DEFAULT '{}'`.
@@ -3458,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$18(db) {
+async function up$22(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3472,7 +3476,7 @@ async function up$18(db) {
       ADD COLUMN dashboard_write_policy jsonb NOT NULL DEFAULT '{}'::jsonb
   `.execute(db);
 }
-async function down$18(db) {
+async function down$22(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS dashboard_write_policy
   `.execute(db);
@@ -3480,8 +3484,8 @@ async function down$18(db) {
 //#endregion
 //#region src/db/migrations/021_check_run_tracking.ts
 var _021_check_run_tracking_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$17,
-	up: () => up$17
+	down: () => down$21,
+	up: () => up$21
 });
 /**
 * Add `check_run_tracking` table for HA-safe check-run state persistence.
@@ -3505,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$17(db) {
+async function up$21(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.tables
@@ -3536,14 +3540,14 @@ async function up$17(db) {
       WHERE run_id IS NOT NULL
   `.execute(db);
 }
-async function down$17(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$16,
-	up: () => up$16
+	down: () => down$20,
+	up: () => up$20
 });
 /**
 * Add three tables persisting `ScalerManager` per-coord state:
@@ -3570,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$16(db) {
+async function up$20(db) {
 	const tableExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3620,7 +3624,7 @@ async function up$16(db) {
     `.execute(db);
 	}
 }
-async function down$16(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);
@@ -3628,8 +3632,8 @@ async function down$16(db) {
 //#endregion
 //#region src/db/migrations/023_dispatch_queue_recovery_deadline.ts
 var _023_dispatch_queue_recovery_deadline_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$15,
-	up: () => up$15
+	down: () => down$19,
+	up: () => up$19
 });
 /**
 * Add `dispatch_queue.recovery_deadline TIMESTAMPTZ` and
@@ -3653,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$15(db) {
+async function up$19(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3678,7 +3682,7 @@ async function up$15(db) {
       WHERE recovery_deadline IS NOT NULL
   `.execute(db);
 }
-async function down$15(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
@@ -3690,8 +3694,8 @@ async function down$15(db) {
 //#endregion
 //#region src/db/migrations/024_dispatch_queue_provisioning_error.ts
 var _024_dispatch_queue_provisioning_error_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$14,
-	up: () => up$14
+	down: () => down$18,
+	up: () => up$18
 });
 /**
 * Add `dispatch_queue.last_provisioning_error TEXT` recording the most
@@ -3707,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$14(db) {
+async function up$18(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3723,7 +3727,7 @@ async function up$14(db) {
         ADD COLUMN last_provisioning_error TEXT
     `.execute(db);
 }
-async function down$14(db) {
+async function down$18(db) {
 	await sql`
     ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS last_provisioning_error
   `.execute(db);
@@ -3731,8 +3735,8 @@ async function down$14(db) {
 //#endregion
 //#region src/db/migrations/025_init_failure.ts
 var _025_init_failure_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$13,
-	up: () => up$13
+	down: () => down$17,
+	up: () => up$17
 });
 /**
 * Add `init_failure jsonb` columns to `execution_runs` and `execution_jobs`.
@@ -3746,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$13(db) {
+async function up$17(db) {
 	const colExists = async (table, name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3766,7 +3770,7 @@ async function up$13(db) {
         ADD COLUMN init_failure JSONB DEFAULT NULL
     `.execute(db);
 }
-async function down$13(db) {
+async function down$17(db) {
 	await sql`
     ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS init_failure
   `.execute(db);
@@ -3777,8 +3781,8 @@ async function down$13(db) {
 //#endregion
 //#region src/db/migrations/026_event_log_lockfile_corrupt.ts
 var _026_event_log_lockfile_corrupt_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$12,
-	up: () => up$12
+	down: () => down$16,
+	up: () => up$16
 });
 /**
 * Extend the event_log.status CHECK constraint with 'lockfile_corrupt' so the
@@ -3787,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$12(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
@@ -3797,7 +3801,7 @@ async function up$12(db) {
     ])))
   `.execute(db);
 }
-async function down$12(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
@@ -3810,8 +3814,8 @@ async function down$12(db) {
 //#endregion
 //#region src/db/migrations/027_workflow_timeout.ts
 var _027_workflow_timeout_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$11,
-	up: () => up$11
+	down: () => down$15,
+	up: () => up$15
 });
 /**
 * Add `workflow_timeout_ms integer` to `execution_runs`.
@@ -3829,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$11(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$11(db) {
+async function down$15(db) {
 	await sql`
     ALTER TABLE public.execution_runs DROP COLUMN IF EXISTS workflow_timeout_ms
   `.execute(db);
@@ -3843,8 +3847,8 @@ async function down$11(db) {
 //#endregion
 //#region src/db/migrations/028_org_settings_user_cache.ts
 var _028_org_settings_user_cache_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$10,
-	up: () => up$10
+	down: () => down$14,
+	up: () => up$14
 });
 /**
 * Add `org_settings.user_cache_quota_bytes bigint` and
@@ -3873,7 +3877,7 @@ async function columnExists(db, column) {
     ) AS exists
   `.execute(db)).rows[0]?.exists ?? false;
 }
-async function up$10(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
@@ -3883,7 +3887,7 @@ async function up$10(db) {
         ADD COLUMN user_cache_ttl_ms bigint
     `.execute(db);
 }
-async function down$10(db) {
+async function down$14(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS user_cache_quota_bytes
   `.execute(db);
@@ -3894,8 +3898,8 @@ async function down$10(db) {
 //#endregion
 //#region src/db/migrations/029_dispatch_queue_attempts.ts
 var _029_dispatch_queue_attempts_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$9,
-	up: () => up$9
+	down: () => down$13,
+	up: () => up$13
 });
 /**
 * Add `dispatch_queue.dispatch_attempts INT NOT NULL DEFAULT 0`.
@@ -3909,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$9(db) {
+async function up$13(db) {
 	if (!((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3922,7 +3926,7 @@ async function up$9(db) {
         ADD COLUMN dispatch_attempts INT NOT NULL DEFAULT 0
     `.execute(db);
 }
-async function down$9(db) {
+async function down$13(db) {
 	await sql`
     ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS dispatch_attempts
   `.execute(db);
@@ -3930,8 +3934,8 @@ async function down$9(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$8,
-	up: () => up$8
+	down: () => down$12,
+	up: () => up$12
 });
 /**
 * held_runs.environment_id becomes nullable with ON DELETE SET NULL so
@@ -3942,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$8(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$8(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
@@ -3959,8 +3963,8 @@ async function down$8(db) {
 //#endregion
 //#region src/db/migrations/031_dispatch_queue_ack_deadline.ts
 var _031_dispatch_queue_ack_deadline_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$7,
-	up: () => up$7
+	down: () => down$11,
+	up: () => up$11
 });
 /**
 * Add `dispatch_queue.ack_deadline TIMESTAMPTZ` and
@@ -3977,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$7(db) {
+async function up$11(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -4002,7 +4006,7 @@ async function up$7(db) {
       WHERE ack_deadline IS NOT NULL
   `.execute(db);
 }
-async function down$7(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);
@@ -4010,8 +4014,8 @@ async function down$7(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$6,
-	up: () => up$6
+	down: () => down$10,
+	up: () => up$10
 });
 /**
 * Add `org_settings.dispatch_ack_timeout_ms BIGINT` (nullable).
@@ -4023,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$6(db) {
+async function up$10(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -4037,7 +4041,7 @@ async function up$6(db) {
       ADD COLUMN dispatch_ack_timeout_ms BIGINT
   `.execute(db);
 }
-async function down$6(db) {
+async function down$10(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS dispatch_ack_timeout_ms
   `.execute(db);
@@ -4045,8 +4049,8 @@ async function down$6(db) {
 //#endregion
 //#region src/db/migrations/033_org_settings_approval.ts
 var _033_org_settings_approval_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$5,
-	up: () => up$5
+	down: () => down$9,
+	up: () => up$9
 });
 /**
 * Add the two approval-policy columns to `org_settings`:
@@ -4063,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$5(db) {
+async function up$9(db) {
 	const colExists = async (column) => {
 		return (await sql`
       SELECT EXISTS (
@@ -4083,7 +4087,7 @@ async function up$5(db) {
         ADD COLUMN allow_self_approval BOOLEAN NOT NULL DEFAULT true
     `.execute(db);
 }
-async function down$5(db) {
+async function down$9(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS approval_expiry_seconds
   `.execute(db);
@@ -4094,8 +4098,8 @@ async function down$5(db) {
 //#endregion
 //#region src/db/migrations/034_held_runs_generalize.ts
 var _034_held_runs_generalize_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$4,
-	up: () => up$4
+	down: () => down$8,
+	up: () => up$8
 });
 /**
 * Generalize `held_runs` from an environment-only hold into the unified
@@ -4117,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$4(db) {
+async function up$8(db) {
 	const colExists = async (column) => {
 		return (await sql`
       SELECT EXISTS (
@@ -4150,7 +4154,7 @@ async function up$4(db) {
       ON public.held_run_approvals USING btree (held_run_id)
   `.execute(db);
 }
-async function down$4(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);
@@ -4160,8 +4164,8 @@ async function down$4(db) {
 //#endregion
 //#region src/db/migrations/035_pending_workflow_contexts.ts
 var _035_pending_workflow_contexts_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$3,
-	up: () => up$3
+	down: () => down$7,
+	up: () => up$7
 });
 /**
 * Pending workflow dispatch context — backs resume of a workflow whose install
@@ -4170,7 +4174,7 @@ var _035_pending_workflow_contexts_exports = /* @__PURE__ */ __exportAll({
 * wait-timer expiry, concurrency slot free). The row is deleted once the resume
 * dispatch has been kicked off.
 */
-async function up$3(db) {
+async function up$7(db) {
 	await sql`
     CREATE TABLE IF NOT EXISTS public.pending_workflow_contexts (
       run_id     text PRIMARY KEY,
@@ -4180,14 +4184,14 @@ async function up$3(db) {
     )
   `.execute(db);
 }
-async function down$3(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$2,
-	up: () => up$2
+	down: () => down$6,
+	up: () => up$6
 });
 /**
 * Add the `attestations` table for build-provenance bundles.
@@ -4200,7 +4204,7 @@ var _036_attestations_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: a re-run on a DB that already has the table is a no-op.
 */
-async function up$2(db) {
+async function up$6(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.tables
@@ -4226,14 +4230,14 @@ async function up$2(db) {
       ON public.attestations (run_id, job_id)
   `.execute(db);
 }
-async function down$2(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$1,
-	up: () => up$1
+	down: () => down$5,
+	up: () => up$5
 });
 /**
 * Replace the `generic_webhook_sources.provider_type` CHECK constraint so it
@@ -4250,7 +4254,7 @@ var _037_generic_sources_provider_type_local_exports = /* @__PURE__ */ __exportA
 * 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$1(db) {
+async function up$5(db) {
 	await sql`
     ALTER TABLE public.generic_webhook_sources
       DROP CONSTRAINT IF EXISTS generic_webhook_sources_provider_type_check
@@ -4266,7 +4270,7 @@ async function up$1(db) {
       CHECK (provider_type = ANY (ARRAY['generic'::text, 'local'::text]))
   `.execute(db);
 }
-async function down$1(db) {
+async function down$5(db) {
 	await sql`
     ALTER TABLE public.generic_webhook_sources
       DROP CONSTRAINT IF EXISTS generic_webhook_sources_provider_type_check
@@ -4285,8 +4289,8 @@ async function down$1(db) {
 //#endregion
 //#region src/db/migrations/038_remote_sources.ts
 var _038_remote_sources_exports = /* @__PURE__ */ __exportAll({
-	down: () => down,
-	up: () => up
+	down: () => down$4,
+	up: () => up$4
 });
 /**
 * `remote_sources` anchors a Platform-relayed `kici run remote` to its real
@@ -4298,7 +4302,7 @@ var _038_remote_sources_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: a re-run on a DB that already has the table is a no-op.
 */
-async function up(db) {
+async function up$4(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.tables
@@ -4317,10 +4321,200 @@ async function up(db) {
     )
   `.execute(db);
 }
-async function down(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() {
@@ -4362,7 +4556,11 @@ function createMigrationProvider() {
 			"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
+			"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
 		};
 	} };
 }
@@ -6631,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);
@@ -6958,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\\";
@@ -7107,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
 /**
@@ -7184,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.
@@ -7326,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]");
@@ -7462,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 [];
@@ -7469,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;
@@ -7534,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.
@@ -7553,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>`);
@@ -7772,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
@@ -7915,61 +8227,61 @@ var init_registry = __esmMin((() => {
 		rolldown: {
 			"linux-x64": {
 				name: "rolldown",
-				version: "1.1.0",
+				version: "1.1.1",
 				platform: "linux",
 				arch: "x64",
-				url: "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.1.0.tgz",
-				sha256: "07ccc910deab806eae00c93cfa633eeedfe5df92cabd0fc92111dd982ab3c324",
+				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.1.0",
+				version: "1.1.1",
 				platform: "linux",
 				arch: "arm64",
-				url: "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.1.0.tgz",
-				sha256: "e7e812642e292101c65703101e29622da59279c53cd68deefed2a356a76ceaf0",
+				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.1.0",
+				version: "1.1.1",
 				platform: "darwin",
 				arch: "x64",
-				url: "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.1.0.tgz",
-				sha256: "48f52e0b62d87117f96c7660e2838dded1d6a99f45d56ae192ab49475a8fa9d1",
+				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.1.0",
+				version: "1.1.1",
 				platform: "darwin",
 				arch: "arm64",
-				url: "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.1.0.tgz",
-				sha256: "c798f79bbcc28079af101ca323c194f2ad6472da0ae80721cc3eaa370e753f6a",
+				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.1.0",
+				version: "1.1.1",
 				platform: "win32",
 				arch: "x64",
-				url: "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.1.0.tgz",
-				sha256: "3457d231d8dcce922bf1cb8f696f04600378ce8e88c0898dba9999239d64dd4a",
+				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.1.0",
+				version: "1.1.1",
 				platform: "win32",
 				arch: "arm64",
-				url: "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.1.0.tgz",
-				sha256: "c8e9e9643f2e905ca0062d2e768c2966e48f0a47595c8c2b7658a085024c8ce3",
+				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"
 			}
@@ -8078,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("/");
@@ -8189,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
@@ -8341,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";
 }
@@ -8433,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
@@ -8567,7 +8908,8 @@ async function resolveUpgradeTarget(args) {
 				maxRetries: 5,
 				windowSeconds: 300
 			},
-			component
+			component,
+			instanceDir: resolved.instanceDir
 		},
 		installBase: resolved.manifest.installBase,
 		resolvedInstance: resolved
@@ -8721,6 +9063,36 @@ function resolveNpmSourceVersion(opts) {
 	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);
@@ -8750,7 +9122,7 @@ async function performVersionedUpgrade(component, opts) {
 			return;
 		}
 		if (!opts.from && !opts.url) {
-			await performNpmSourceUpgrade(config, resolvedInstance, manager, opts);
+			await performNpmSourceUpgrade(component, config, resolvedInstance, manager, opts);
 			return;
 		}
 		if (!opts.version) {
@@ -8859,18 +9231,30 @@ async function performVersionedUpgrade(component, opts) {
 * 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(config, resolvedInstance, manager, opts) {
-	const running = readKiciVersion();
-	const version = resolveNpmSourceVersion({
+async function performNpmSourceUpgrade(component, config, resolvedInstance, manager, opts) {
+	const invoked = readKiciVersion();
+	resolveNpmSourceVersion({
 		requested: opts.version,
-		running
+		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 ${version}.`);
+		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?")) {
@@ -8881,11 +9265,12 @@ async function performNpmSourceUpgrade(config, resolvedInstance, manager, opts)
 	console.log("Restarting service onto the npm-installed package...");
 	if ((await manager.status(config)).state === "running") await manager.stop(config);
 	await manager.start(config);
-	writeManifest(resolvedInstance.instanceDir, {
+	if (verdict.manifestVersion !== null) writeManifest(resolvedInstance.instanceDir, {
 		...resolvedInstance.manifest,
-		kiciVersion: version
+		kiciVersion: verdict.manifestVersion
 	});
-	console.log(`Upgrade complete: service "${config.name}" is now running version ${version}.`);
+	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.
@@ -9235,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);
@@ -9304,6 +9689,7 @@ function registerOrchestratorInstall(orchestrator) {
 				isUserLevel: userLevel,
 				user: opts.user,
 				component: "orchestrator",
+				instanceDir,
 				restartPolicy: DEFAULT_RESTART_POLICY
 			};
 			await manager.install(config);
@@ -9810,6 +10196,7 @@ function registerAgentInstall(agent) {
 				workingDirectory: configDir,
 				isUserLevel: userLevel,
 				component: "agent",
+				instanceDir,
 				restartPolicy: DEFAULT_RESTART_POLICY
 			};
 			await manager.install(config);
@@ -10602,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) {
@@ -14504,7 +15096,9 @@ function renderBootScript(cfg) {
 		"#!/usr/bin/env bash",
 		`# Generated by kici-admin firecracker --persist for bridge ${cfg.bridgeName}. Do not hand-edit.`,
 		"set -euo pipefail",
-		`printf '%s\\n' "${NM_CONF_CONTENT.replace(/\n/g, "\\n").replace(/"/g, "\\\"")}" > ${NM_CONF_PATH} || true`,
+		`cat > ${NM_CONF_PATH} <<'KICI_NM_EOF' || true`,
+		NM_CONF_CONTENT.replace(/\n$/, ""),
+		"KICI_NM_EOF",
 		"HOST_IFACE=$(ip -j route show default | sed -n 's/.*\"dev\":\"\\([^\"]*\\)\".*/\\1/p' | head -1)",
 		"if [ -z \"$HOST_IFACE\" ]; then echo \"no default-route iface\" >&2; exit 1; fi",
 		...lines,
@@ -17291,6 +17885,7 @@ function buildProgram() {
 	registerScalerCommands(program);
 	registerAgentServiceCommands(program);
 	registerPeerCommands(program, getClient);
+	registerHostCommands(program);
 	registerOrgSettingsCommands(program, getClient);
 	registerClusterNameCommands(program, getClient);
 	registerMaintenanceCommands(program, getClient);