@kici-dev/orchestrator 0.1.12 → 0.1.14

package/dist/cli.js

@@ -25,8 +25,8 @@ import path from "node:path";
 import archiver from "archiver";
 import JSZip from "jszip";
 import { fileURLToPath } from "node:url";
-import { confirm, input, password, select } from "@inquirer/prompts";
 import { pipeline } from "node:stream/promises";
+import { confirm, input, password, select } from "@inquirer/prompts";
 import "pg";
 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";
@@ -1517,8 +1517,8 @@ var init_client = __esmMin((() => {
 //#region src/db/migrations/001_initial.ts
 init_client();
 var _001_initial_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$23,
-	up: () => up$23
+	down: () => down$24,
+	up: () => up$24
 });
 /**
 * Squashed initial migration -- creates the complete Orchestrator database schema.
@@ -2210,7 +2210,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$23(db) {
+async function up$24(db) {
 	for (const stmt of DDL_STATEMENTS) await sql.raw(stmt).execute(db);
 	await sql`
     INSERT INTO cluster_meta (key, value)
@@ -2232,7 +2232,7 @@ async function up$23(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$23(db) {
+async function down$24(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",
@@ -2279,8 +2279,8 @@ async function down$23(db) {
 //#endregion
 //#region src/db/migrations/002_config_versions_key_version.ts
 var _002_config_versions_key_version_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$22,
-	up: () => up$22
+	down: () => down$23,
+	up: () => up$23
 });
 /**
 * Add key_version column to config_versions so that sensitive-field encryption
@@ -2294,13 +2294,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$22(db) {
+async function up$23(db) {
 	await sql`
     ALTER TABLE public.config_versions
       ADD COLUMN key_version integer NOT NULL DEFAULT 1
   `.execute(db);
 }
-async function down$22(db) {
+async function down$23(db) {
 	await sql`
     ALTER TABLE public.config_versions
       DROP COLUMN key_version
@@ -2309,8 +2309,8 @@ async function down$22(db) {
 //#endregion
 //#region src/db/migrations/003_access_log.ts
 var _003_access_log_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$21,
-	up: () => up$21
+	down: () => down$22,
+	up: () => up$22
 });
 /**
 * Access log: one row per read or orchestrator-admin mutation attributable
@@ -2334,7 +2334,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$21(db) {
+async function up$22(db) {
 	await sql`
     CREATE TABLE public.access_log (
       id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -2372,28 +2372,28 @@ async function up$21(db) {
       ON public.access_log (actor_type, actor_id, created_at DESC)
   `.execute(db);
 }
-async function down$21(db) {
+async function down$22(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$20,
-	up: () => up$20
+	down: () => down$21,
+	up: () => up$21
 });
-async function up$20(db) {
+async function up$21(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$20(db) {
+async function down$21(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$19,
-	up: () => up$19
+	down: () => down$20,
+	up: () => up$20
 });
 /**
 * Cold-store chunk counter table.
@@ -2410,7 +2410,7 @@ var _005_cold_store_chunk_counter_exports = /* @__PURE__ */ __exportAll({
 *
 * sections 5 and 8.
 */
-async function up$19(db) {
+async function up$20(db) {
 	await sql`
     CREATE TABLE public.cold_store_chunk_counts (
       db                TEXT        NOT NULL,
@@ -2428,14 +2428,14 @@ async function up$19(db) {
       ON public.cold_store_chunk_counts (db, table_name)
   `.execute(db);
 }
-async function down$19(db) {
+async function down$20(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$18,
-	up: () => up$18
+	down: () => down$19,
+	up: () => up$19
 });
 /**
 * `execution_runs` / `execution_jobs` / `execution_steps` cold-store
@@ -2471,7 +2471,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$18(db) {
+async function up$19(db) {
 	await sql`
     ALTER TABLE public.execution_runs
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2516,7 +2516,7 @@ async function up$18(db) {
       ON public.execution_steps (routing_key, created_at)
   `.execute(db);
 }
-async function down$18(db) {
+async function down$19(db) {
 	await sql`DROP INDEX IF EXISTS public.idx_execution_steps_routing_key_created`.execute(db);
 	await sql`
     ALTER TABLE public.execution_steps
@@ -2541,8 +2541,8 @@ async function down$18(db) {
 //#endregion
 //#region src/db/migrations/007_audit_logs_archived_at.ts
 var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$17,
-	up: () => up$17
+	down: () => down$18,
+	up: () => up$18
 });
 /**
 * `secret_audit_log` and `access_log` cold-store schema additions, plus
@@ -2582,7 +2582,7 @@ var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
 * `down()` would not have meaningful retention bounds. Acceptable for
 * staging.
 */
-async function up$17(db) {
+async function up$18(db) {
 	await sql`
     ALTER TABLE public.secret_audit_log
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2603,7 +2603,7 @@ async function up$17(db) {
       DROP COLUMN IF EXISTS expires_at
   `.execute(db);
 }
-async function down$17(db) {
+async function down$18(db) {
 	await sql`
     ALTER TABLE public.access_log
       ADD COLUMN expires_at TIMESTAMPTZ NOT NULL DEFAULT (now() + INTERVAL '90 days')
@@ -2631,8 +2631,8 @@ async function down$17(db) {
 //#endregion
 //#region src/db/migrations/008_event_log_archived_at.ts
 var _008_event_log_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$16,
-	up: () => up$16
+	down: () => down$17,
+	up: () => up$17
 });
 /**
 * `event_log` cold-store schema additions plus removal of the
@@ -2670,7 +2670,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$16(db) {
+async function up$17(db) {
 	await sql`
     ALTER TABLE public.event_log
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2686,7 +2686,7 @@ async function up$16(db) {
       DROP COLUMN IF EXISTS expires_at
   `.execute(db);
 }
-async function down$16(db) {
+async function down$17(db) {
 	await sql`
     ALTER TABLE public.event_log
       ADD COLUMN expires_at TIMESTAMPTZ NOT NULL DEFAULT (now() + INTERVAL '30 days')
@@ -2705,8 +2705,8 @@ async function down$16(db) {
 //#endregion
 //#region src/db/migrations/009_access_log_trigram.ts
 var _009_access_log_trigram_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$15,
-	up: () => up$15
+	down: () => down$16,
+	up: () => up$16
 });
 /**
 * Trigram (pg_trgm) index on access_log.error_message for the federated
@@ -2719,7 +2719,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$15(db) {
+async function up$16(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
@@ -2728,14 +2728,14 @@ async function up$15(db) {
       WHERE error_message IS NOT NULL
   `.execute(db);
 }
-async function down$15(db) {
+async function down$16(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$14,
-	up: () => up$14
+	down: () => down$15,
+	up: () => up$15
 });
 /**
 * Cold-store chunk index — Phase 2 (cold-store purge).
@@ -2767,7 +2767,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$14(db) {
+async function up$15(db) {
 	await sql`
     CREATE TABLE public.cold_store_chunks (
       db              TEXT        NOT NULL,
@@ -2794,14 +2794,14 @@ async function up$14(db) {
       ON public.cold_store_chunks (db, table_name, tenant_id, archived_at DESC)
   `.execute(db);
 }
-async function down$14(db) {
+async function down$15(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$13,
-	up: () => up$13
+	down: () => down$14,
+	up: () => up$14
 });
 /**
 * Drop the `source_secrets_change_trigger` and the
@@ -2820,11 +2820,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$13(db) {
+async function up$14(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$13(db) {
+async function down$14(db) {
 	await sql`
     CREATE OR REPLACE FUNCTION public.notify_source_secrets_change() RETURNS trigger
       LANGUAGE plpgsql
@@ -2863,8 +2863,8 @@ async function down$13(db) {
 //#endregion
 //#region src/db/migrations/012_peer_credentials_active_uniq.ts
 var _012_peer_credentials_active_uniq_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$12,
-	up: () => up$12
+	down: () => down$13,
+	up: () => up$13
 });
 /**
 * Add a partial unique index on `peer_credentials (instance_id) WHERE
@@ -2890,7 +2890,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$12(db) {
+async function up$13(db) {
 	await sql`
     UPDATE public.peer_credentials
     SET revoked_at = NOW()
@@ -2908,14 +2908,14 @@ async function up$12(db) {
       WHERE revoked_at IS NULL
   `.execute(db);
 }
-async function down$12(db) {
+async function down$13(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$11,
-	up: () => up$11
+	down: () => down$12,
+	up: () => up$12
 });
 /**
 * Add `log_bytes BIGINT NOT NULL DEFAULT 0` columns to `execution_runs` and
@@ -2934,7 +2934,7 @@ var _013_execution_log_bytes_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent (`ADD COLUMN IF NOT EXISTS`).
 */
-async function up$11(db) {
+async function up$12(db) {
 	await sql`
     ALTER TABLE public.execution_runs
       ADD COLUMN IF NOT EXISTS log_bytes BIGINT NOT NULL DEFAULT 0
@@ -2944,15 +2944,15 @@ async function up$11(db) {
       ADD COLUMN IF NOT EXISTS log_bytes BIGINT NOT NULL DEFAULT 0
   `.execute(db);
 }
-async function down$11(db) {
+async function down$12(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$10,
-	up: () => up$10
+	down: () => down$11,
+	up: () => up$11
 });
 /**
 * Add lease + retry + DLQ columns to `kici_events` so the EventRouter can
@@ -2986,7 +2986,7 @@ var _014_kici_events_lease_retry_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent (`ADD COLUMN IF NOT EXISTS` + `CREATE INDEX IF NOT EXISTS`).
 */
-async function up$10(db) {
+async function up$11(db) {
 	await sql`
     ALTER TABLE public.kici_events
       ADD COLUMN IF NOT EXISTS claimed_at TIMESTAMPTZ,
@@ -3017,7 +3017,7 @@ async function up$10(db) {
       WHERE dlq_at IS NOT NULL
   `.execute(db);
 }
-async function down$10(db) {
+async function down$11(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);
@@ -3035,8 +3035,8 @@ async function down$10(db) {
 //#endregion
 //#region src/db/migrations/015_org_settings_customer_scoped.ts
 var _015_org_settings_customer_scoped_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$9,
-	up: () => up$9
+	down: () => down$10,
+	up: () => up$10
 });
 /**
 * Org-scope `org_settings` and qualify each glob entry by source.
@@ -3064,7 +3064,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$9(db) {
+async function up$10(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3189,7 +3189,7 @@ async function up$9(db) {
 	await sql`DROP TABLE _org_settings_merged`.execute(db);
 	await sql`DROP TABLE _org_settings_stage`.execute(db);
 }
-async function down$9(db) {
+async function down$10(db) {
 	if (!(await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3214,8 +3214,8 @@ async function down$9(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$8,
-	up: () => up$8
+	down: () => down$9,
+	up: () => up$9
 });
 /**
 * Add `org_settings.allow_http_npm_registries boolean NOT NULL DEFAULT false`.
@@ -3228,7 +3228,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$8(db) {
+async function up$9(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3242,7 +3242,7 @@ async function up$8(db) {
       ADD COLUMN allow_http_npm_registries boolean NOT NULL DEFAULT false
   `.execute(db);
 }
-async function down$8(db) {
+async function down$9(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS allow_http_npm_registries
   `.execute(db);
@@ -3250,8 +3250,8 @@ async function down$8(db) {
 //#endregion
 //#region src/db/migrations/017_org_id_widen.ts
 var _017_org_id_widen_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$7,
-	up: () => up$7
+	down: () => down$8,
+	up: () => up$8
 });
 /**
 * Widen every orchestrator-side `org_id varchar(12)` column to
@@ -3291,17 +3291,17 @@ const ORG_ID_TABLES$1 = [
 	"held_runs",
 	"scoped_secrets"
 ];
-async function up$7(db) {
+async function up$8(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$7(db) {
+async function down$8(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$6,
-	up: () => up$6
+	down: () => down$7,
+	up: () => up$7
 });
 /**
 * Prefix every orchestrator-side tenant string with `org_` to align
@@ -3346,19 +3346,19 @@ const CUSTOMER_ID_TABLES = [
 	"workflow_registrations",
 	"org_settings"
 ];
-async function up$6(db) {
+async function up$7(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$6(db) {
+async function down$7(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$5,
-	up: () => up$5
+	down: () => down$6,
+	up: () => up$6
 });
 /**
 * Add a Postgres trigger on `generic_webhook_sources` that emits
@@ -3381,7 +3381,7 @@ var _019_generic_sources_change_notify_exports = /* @__PURE__ */ __exportAll({
 * (`notify_sources_change()` + `sources_change_trigger`, defined in
 * `001_initial.ts`).
 */
-async function up$5(db) {
+async function up$6(db) {
 	await sql`
     CREATE FUNCTION public.notify_generic_sources_change() RETURNS trigger
       LANGUAGE plpgsql
@@ -3402,15 +3402,15 @@ async function up$5(db) {
       FOR EACH ROW EXECUTE FUNCTION public.notify_generic_sources_change()
   `.execute(db);
 }
-async function down$5(db) {
+async function down$6(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$4,
-	up: () => up$4
+	down: () => down$5,
+	up: () => up$5
 });
 /**
 * Add `org_settings.dashboard_write_policy jsonb NOT NULL DEFAULT '{}'`.
@@ -3425,7 +3425,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$4(db) {
+async function up$5(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3439,7 +3439,7 @@ async function up$4(db) {
       ADD COLUMN dashboard_write_policy jsonb NOT NULL DEFAULT '{}'::jsonb
   `.execute(db);
 }
-async function down$4(db) {
+async function down$5(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS dashboard_write_policy
   `.execute(db);
@@ -3447,8 +3447,8 @@ async function down$4(db) {
 //#endregion
 //#region src/db/migrations/021_check_run_tracking.ts
 var _021_check_run_tracking_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$3,
-	up: () => up$3
+	down: () => down$4,
+	up: () => up$4
 });
 /**
 * Add `check_run_tracking` table for HA-safe check-run state persistence.
@@ -3472,7 +3472,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$3(db) {
+async function up$4(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.tables
@@ -3503,14 +3503,14 @@ async function up$3(db) {
       WHERE run_id IS NOT NULL
   `.execute(db);
 }
-async function down$3(db) {
+async function down$4(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$2,
-	up: () => up$2
+	down: () => down$3,
+	up: () => up$3
 });
 /**
 * Add three tables persisting `ScalerManager` per-coord state:
@@ -3537,7 +3537,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$2(db) {
+async function up$3(db) {
 	const tableExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3587,7 +3587,7 @@ async function up$2(db) {
     `.execute(db);
 	}
 }
-async function down$2(db) {
+async function down$3(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);
@@ -3595,8 +3595,8 @@ async function down$2(db) {
 //#endregion
 //#region src/db/migrations/023_dispatch_queue_recovery_deadline.ts
 var _023_dispatch_queue_recovery_deadline_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$1,
-	up: () => up$1
+	down: () => down$2,
+	up: () => up$2
 });
 /**
 * Add `dispatch_queue.recovery_deadline TIMESTAMPTZ` and
@@ -3620,7 +3620,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$1(db) {
+async function up$2(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3645,7 +3645,7 @@ async function up$1(db) {
       WHERE recovery_deadline IS NOT NULL
   `.execute(db);
 }
-async function down$1(db) {
+async function down$2(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
@@ -3657,8 +3657,8 @@ async function down$1(db) {
 //#endregion
 //#region src/db/migrations/024_dispatch_queue_provisioning_error.ts
 var _024_dispatch_queue_provisioning_error_exports = /* @__PURE__ */ __exportAll({
-	down: () => down,
-	up: () => up
+	down: () => down$1,
+	up: () => up$1
 });
 /**
 * Add `dispatch_queue.last_provisioning_error TEXT` recording the most
@@ -3674,7 +3674,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(db) {
+async function up$1(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3690,12 +3690,58 @@ async function up(db) {
         ADD COLUMN last_provisioning_error TEXT
     `.execute(db);
 }
-async function down(db) {
+async function down$1(db) {
 	await sql`
     ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS last_provisioning_error
   `.execute(db);
 }
 //#endregion
+//#region src/db/migrations/025_init_failure.ts
+var _025_init_failure_exports = /* @__PURE__ */ __exportAll({
+	down: () => down,
+	up: () => up
+});
+/**
+* Add `init_failure jsonb` columns to `execution_runs` and `execution_jobs`.
+*
+* Presence of this column on a row means the run/job never executed a step
+* because of an init-phase failure; absence (NULL) means a normal run.
+* Shape on the wire is `InitFailure` from `@kici-dev/engine`. The dashboard
+* reads this column directly so it can render the right banner without
+* round-tripping to the orchestrator (which may be offline).
+*
+* Idempotent: re-running on a DB that already has either column is a no-op
+* for that column.
+*/
+async function up(db) {
+	const colExists = async (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;
+	};
+	if (!await colExists("execution_runs", "init_failure")) await sql`
+      ALTER TABLE public.execution_runs
+        ADD COLUMN init_failure JSONB DEFAULT NULL
+    `.execute(db);
+	if (!await colExists("execution_jobs", "init_failure")) await sql`
+      ALTER TABLE public.execution_jobs
+        ADD COLUMN init_failure JSONB DEFAULT NULL
+    `.execute(db);
+}
+async function down(db) {
+	await sql`
+    ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS init_failure
+  `.execute(db);
+	await sql`
+    ALTER TABLE public.execution_runs DROP COLUMN IF EXISTS init_failure
+  `.execute(db);
+}
+//#endregion
 //#region src/db/migration-provider.ts
 function createMigrationProvider() {
 	return { async getMigrations() {
@@ -3723,7 +3769,8 @@ function createMigrationProvider() {
 			"021_check_run_tracking": _021_check_run_tracking_exports,
 			"022_scaler_manager_state": _022_scaler_manager_state_exports,
 			"023_dispatch_queue_recovery_deadline": _023_dispatch_queue_recovery_deadline_exports,
-			"024_dispatch_queue_provisioning_error": _024_dispatch_queue_provisioning_error_exports
+			"024_dispatch_queue_provisioning_error": _024_dispatch_queue_provisioning_error_exports,
+			"025_init_failure": _025_init_failure_exports
 		};
 	} };
 }
@@ -3865,7 +3912,7 @@ function registerDbCommands(program, getClient) {
 			process.exit(1);
 		}
 	});
-	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).").action(async (name, opts) => {
+	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 url = new URL(baseUrl);
@@ -3874,9 +3921,10 @@ function registerDbCommands(program, getClient) {
 			logInvocation(`ensure ${name}`, targetUrl);
 			const outcome = await ensureDatabase(targetUrl, {
 				owner: opts.owner,
-				revokeConnectFromPublic: !!opts.revokeConnectPublic
+				revokeConnectFromPublic: !!opts.revokeConnectPublic,
+				grantConnectToRoles: opts.grantConnectRole
 			});
-			const suffix = (opts.owner ? ` (owner=${opts.owner})` : "") + (opts.revokeConnectPublic ? " [revoked CONNECT from PUBLIC]" : "");
+			const suffix = (opts.owner ? ` (owner=${opts.owner})` : "") + (opts.revokeConnectPublic ? " [revoked CONNECT from PUBLIC]" : "") + (opts.grantConnectRole.length ? ` [granted CONNECT to: ${opts.grantConnectRole.join(", ")}]` : "");
 			console.log(`db ensure: ${name} — ${outcome}${suffix}`);
 		} catch (err) {
 			console.error(`Error: ${toErrorMessage(err)}`);
@@ -6092,7 +6140,8 @@ function isRoot() {
 	return typeof process.getuid === "function" && process.getuid() === 0;
 }
 /**
-* Get the configuration directory for a KiCI service.
+* Name-agnostic KiCI config root — the directory that contains every
+* per-instance config subdir for this privilege level.
 *
 * Paths follow platform conventions:
 * - System Linux/macOS: /etc/kici/
@@ -6100,8 +6149,11 @@ function isRoot() {
 * - User macOS: ~/Library/Application Support/kici/
 * - System Windows: C:\ProgramData\kici\
 * - User Windows: %LOCALAPPDATA%\kici\
+*
+* Used by the instance index (`<kiciRoot>/instances.json`) which lives
+* outside any per-instance subdir, and as the base for {@link getConfigDir}.
 */
-function getConfigDir(_serviceName, isUserLevel) {
+function kiciConfigRoot(isUserLevel) {
 	const plat = os.platform();
 	if (plat === "win32") {
 		if (isUserLevel) return (process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local")) + "\\kici\\";
@@ -6112,20 +6164,40 @@ function getConfigDir(_serviceName, isUserLevel) {
 	return path.join(os.homedir(), ".config", "kici") + "/";
 }
 /**
-* Get the log directory for a KiCI service.
+* Get the configuration directory for a specific KiCI service instance.
 *
-* Paths follow platform conventions:
-* - System Linux/macOS: /var/log/kici/
-* - User Linux: ~/.local/share/kici/logs/
-* - User macOS: ~/Library/Logs/kici/
-* - Windows: C:\ProgramData\kici\logs\
+* Returns `<kiciConfigRoot>/<serviceName>/`. The name-scoped subdir is the
+* folder-anchored home for everything belonging to one installed instance
+* (env file, generated unit references, future per-instance state).
+*
+* Examples:
+* - System Linux: /etc/kici/<name>/
+* - User Linux: ~/.config/kici/<name>/
+* - User macOS: ~/Library/Application Support/kici/<name>/
+* - System Windows: C:\ProgramData\kici\<name>\
+* - User Windows: %LOCALAPPDATA%\kici\<name>\
+*/
+function getConfigDir(serviceName, isUserLevel) {
+	const root = kiciConfigRoot(isUserLevel);
+	const sep = os.platform() === "win32" ? "\\" : "/";
+	return root + serviceName + sep;
+}
+/**
+* Get the log directory for a specific KiCI service instance.
+*
+* The per-platform layout matches the existing matrix; the service name is
+* injected as the per-instance segment so each instance has its own log dir:
+* - System Linux/macOS: /var/log/kici/<name>/
+* - User Linux: ~/.local/share/kici/<name>/logs/
+* - User macOS: ~/Library/Logs/kici/<name>/
+* - Windows: C:\ProgramData\kici\<name>\logs\
 */
-function getLogDir(_serviceName, isUserLevel) {
+function getLogDir(serviceName, isUserLevel) {
 	const plat = os.platform();
-	if (plat === "win32") return "C:\\ProgramData\\kici\\logs\\";
-	if (!isUserLevel) return "/var/log/kici/";
-	if (plat === "darwin") return path.join(os.homedir(), "Library", "Logs", "kici") + "/";
-	return path.join(os.homedir(), ".local", "share", "kici", "logs") + "/";
+	if (plat === "win32") return "C:\\ProgramData\\kici\\" + serviceName + "\\logs\\";
+	if (!isUserLevel) return "/var/log/kici/" + serviceName + "/";
+	if (plat === "darwin") return path.join(os.homedir(), "Library", "Logs", "kici", serviceName) + "/";
+	return path.join(os.homedir(), ".local", "share", "kici", serviceName, "logs") + "/";
 }
 /**
 * Get the cache directory for lazy dependency downloads.
@@ -6158,31 +6230,263 @@ function resolveUserLevel(opts) {
 	return !isRoot();
 }
 //#endregion
-//#region src/cli/service/systemd.ts
+//#region src/cli/service/instance/manifest.ts
 /**
-* systemd service manager implementation.
-*
-* Generates unit files and manages service lifecycle via systemctl,
-* journalctl, and loginctl commands. Supports both system-level
-* (/etc/systemd/system/) and user-level (~/.config/systemd/user/) services.
+* Instance manifest — the single source of truth for a folder-anchored
+* service install. Written by `install` into the deploy folder, read by
+* every lifecycle command to reconstruct the ServiceConfig.
 */
-var systemd_exports = /* @__PURE__ */ __exportAll({
-	SystemdServiceManager: () => SystemdServiceManager,
-	isLingerEnabled: () => isLingerEnabled
-});
+const REQUIRED_FIELDS = [
+	"component",
+	"name",
+	"platform",
+	"isUserLevel",
+	"envFilePath",
+	"configDir",
+	"logDir",
+	"installBase",
+	"createdAt",
+	"kiciVersion"
+];
+/** Per-component manifest filename. */
+function manifestFilename(component) {
+	return `.kici-${component}.json`;
+}
+/** Resolve the manifest path inside an instance directory. */
+function manifestPath(instanceDir, component) {
+	return path.join(instanceDir, manifestFilename(component));
+}
 /**
-* Check whether linger is already enabled for a user.
-*
-* Uses `loginctl show-user <user>` which is readable by any user. Returns
-* true if the user's `Linger` property reads `yes`. Returns false on any
-* parse failure, missing binary, or unknown user — the caller is expected
-* to attempt `enable-linger` in that case.
+* Read the manifest for `component` from `instanceDir`.
+* Returns null when the file does not exist; throws on parse or schema errors.
+*/
+function readManifest(instanceDir, component) {
+	const file = manifestPath(instanceDir, component);
+	if (!fs.existsSync(file)) return null;
+	const raw = fs.readFileSync(file, "utf-8");
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`Malformed instance manifest at ${file}: ${err.message}`);
+	}
+	if (!parsed || typeof parsed !== "object") throw new Error(`Invalid instance manifest at ${file}: not an object`);
+	for (const field of REQUIRED_FIELDS) if (!(field in parsed)) throw new Error(`Invalid instance manifest at ${file}: missing field "${field}"`);
+	return parsed;
+}
+/**
+* Write the manifest for `manifest.component` into `instanceDir`.
+* Returns the full path written.
+*/
+function writeManifest(instanceDir, manifest) {
+	fs.mkdirSync(instanceDir, { recursive: true });
+	const file = manifestPath(instanceDir, manifest.component);
+	fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+	return file;
+}
+/**
+* Read the running kici-admin's version from the orchestrator package.json.
 *
-* Exported (package-private) for testing.
+* `process.env.npm_package_version` is only populated under `npm run` and is
+* undefined when kici-admin runs as a globally-installed binary, which is the
+* actual install path. Reading from the package.json on disk is the only
+* reliable source.
 */
-function isLingerEnabled(user) {
+function readKiciVersion() {
 	try {
-		const out = execFileSync("loginctl", [
+		const pkgUrl = new URL("../../../../package.json", import.meta.url);
+		const pkg = JSON.parse(fs.readFileSync(fileURLToPath(pkgUrl), "utf-8"));
+		return typeof pkg.version === "string" ? pkg.version : "unknown";
+	} catch {
+		return "unknown";
+	}
+}
+//#endregion
+//#region src/cli/service/instance/index-file.ts
+/**
+* Instance index — a reconciled CACHE of all installed instances on the host.
+*
+* Lives at <kiciRoot>/instances.json, where kiciRoot is the name-agnostic
+* config root (~/.config/kici/ for user-level, /etc/kici/ for system). The
+* index is convenience: discovery is authoritative against the init system
+* (see resolve.ts#listInstances which reconciles this file against scans).
+*
+* Corrupt index → warn and treat as empty; the next install/uninstall
+* rewrites it cleanly.
+*/
+const FILE = "instances.json";
+/** Resolve <kiciRoot>/instances.json. */
+function indexPath(kiciRoot) {
+	return path.join(kiciRoot, FILE);
+}
+/** Read the index. Missing or corrupt → []. */
+function readIndex(kiciRoot) {
+	const file = indexPath(kiciRoot);
+	if (!fs.existsSync(file)) return [];
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+		if (!Array.isArray(parsed)) {
+			console.warn(`[kici] instance index at ${file} is invalid (not an array); ignoring`);
+			return [];
+		}
+		return parsed;
+	} catch (err) {
+		console.warn(`[kici] instance index at ${file} is corrupt (${err.message}); ignoring`);
+		return [];
+	}
+}
+/** Overwrite the index. */
+function writeIndex(kiciRoot, entries) {
+	fs.mkdirSync(kiciRoot, { recursive: true });
+	fs.writeFileSync(indexPath(kiciRoot), JSON.stringify(entries, null, 2) + "\n", "utf-8");
+}
+/**
+* Append an entry. Idempotent for an exact (component,name,instanceDir) match.
+* Throws on a (component,name) collision with a different instanceDir — the
+* caller must use a different name or pass --force to overwrite.
+*/
+function appendIndexEntry(kiciRoot, entry) {
+	const current = readIndex(kiciRoot);
+	const existing = current.find((e) => e.component === entry.component && e.name === entry.name);
+	if (existing) {
+		if (existing.instanceDir === entry.instanceDir) return;
+		throw new Error(`Already an ${entry.component} instance "${entry.name}" registered at ${existing.instanceDir}`);
+	}
+	writeIndex(kiciRoot, [...current, entry]);
+}
+/** Remove the matching entry (no-op when absent). */
+function removeIndexEntry(kiciRoot, key) {
+	const current = readIndex(kiciRoot);
+	const next = current.filter((e) => !(e.component === key.component && e.name === key.name));
+	if (next.length !== current.length) writeIndex(kiciRoot, next);
+}
+//#endregion
+//#region src/cli/service/instance/resolve.ts
+/**
+* resolveInstance — the single entry point every lifecycle command uses to
+* decide which installed service it's operating on.
+*
+* Priority:
+*   1. --instance-dir <path>       → read manifest at <path>
+*   2. --name <name>               → match against listInstances() result
+*   3. CWD manifest                → read ./.kici-<component>.json
+*   4. otherwise                   → refuse with a candidate list (throws)
+*
+* listInstances reconciles the on-disk index (cache) with the driver's
+* native scan (source of truth). The reconciled result is rewritten back to
+* the index to self-heal stale entries.
+*/
+/**
+* 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.
+*/
+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 idx = indexByName.get(s.name);
+		return {
+			...s,
+			component,
+			instanceDir: idx?.instanceDir,
+			source: idx ? "index+scan" : "scan"
+		};
+	});
+}
+/**
+* Resolve the target instance for the current lifecycle invocation.
+* Throws with a refusal/candidate-listing error when ambiguous.
+*/
+async function resolveInstance(args) {
+	const { component, opts, cwd, kiciRoot, manager, isUserLevel } = args;
+	if (opts.instanceDir) {
+		const dir = path.resolve(opts.instanceDir);
+		const m = readManifest(dir, component);
+		if (!m) throw new Error(`No ${component} manifest at ${manifestPath(dir, component)}. Did you install with --instance-dir ${dir}?`);
+		return {
+			manifest: m,
+			manifestPath: manifestPath(dir, component),
+			instanceDir: dir
+		};
+	}
+	if (opts.name) {
+		const candidates = await listInstances({
+			component,
+			isUserLevel,
+			kiciRoot,
+			manager
+		});
+		const match = candidates.find((c) => c.name === opts.name);
+		if (!match) throw new Error(formatNameNotFound(component, opts.name, candidates));
+		if (!match.instanceDir) throw new Error(`${component} instance "${opts.name}" exists in the init system but has no manifest. Pass --instance-dir <deploy folder> instead.`);
+		const manifest = readManifest(match.instanceDir, component);
+		if (!manifest) throw new Error(`Manifest for ${component} instance "${opts.name}" missing at ${manifestPath(match.instanceDir, component)}.`);
+		return {
+			manifest,
+			manifestPath: manifestPath(match.instanceDir, component),
+			instanceDir: match.instanceDir
+		};
+	}
+	const cwdManifest = readManifest(cwd, component);
+	if (cwdManifest) return {
+		manifest: cwdManifest,
+		manifestPath: manifestPath(cwd, component),
+		instanceDir: path.resolve(cwd)
+	};
+	const candidates = await listInstances({
+		component,
+		isUserLevel,
+		kiciRoot,
+		manager
+	});
+	throw new Error(formatRefusal(component, candidates));
+}
+/**
+* Format the refusal message and candidate table.
+*
+* When candidates is empty, returns the "no instances installed" guidance.
+* When candidates exist, lists them with their instanceDir (or "(no manifest)").
+*/
+function formatRefusal(component, candidates) {
+	if (candidates.length === 0) return `No ${component} instances installed on this host. Run \`kici-admin ${component} install --instance-dir <deploy folder>\` first.`;
+	return `No instance specified and no manifest in CWD. Candidates on this host:\n${candidates.map((c) => `  - ${c.name}  ${c.platform}  ${c.instanceDir ?? "(no manifest)"}`).join("\n")}\nPass --instance-dir <path> or --name <name>, or cd into the deploy folder.`;
+}
+function formatNameNotFound(component, name, candidates) {
+	return `${component} instance "${name}" not found. Installed:\n${candidates.length ? candidates.map((c) => `  - ${c.name}  ${c.platform}  ${c.instanceDir ?? "(no manifest)"}`).join("\n") : "  (none)"}`;
+}
+//#endregion
+//#region src/cli/service/systemd.ts
+/**
+* systemd service manager implementation.
+*
+* Generates unit files and manages service lifecycle via systemctl,
+* journalctl, and loginctl commands. Supports both system-level
+* (/etc/systemd/system/) and user-level (~/.config/systemd/user/) services.
+*/
+var systemd_exports = /* @__PURE__ */ __exportAll({
+	SystemdServiceManager: () => SystemdServiceManager,
+	isLingerEnabled: () => isLingerEnabled
+});
+/**
+* Check whether linger is already enabled for a user.
+*
+* Uses `loginctl show-user <user>` which is readable by any user. Returns
+* true if the user's `Linger` property reads `yes`. Returns false on any
+* parse failure, missing binary, or unknown user — the caller is expected
+* to attempt `enable-linger` in that case.
+*
+* Exported (package-private) for testing.
+*/
+function isLingerEnabled(user) {
+	try {
+		const out = execFileSync("loginctl", [
 			"show-user",
 			user,
 			"--property=Linger"
@@ -6215,6 +6519,7 @@ var init_systemd = __esmMin((() => {
 			const lines = [];
 			lines.push("[Unit]");
 			lines.push(`Description=${config.description}`);
+			if (config.component) lines.push(`X-KiCI-Component=${config.component}`);
 			lines.push("After=network.target postgresql.service");
 			lines.push("");
 			lines.push("[Service]");
@@ -6351,6 +6656,24 @@ var init_systemd = __esmMin((() => {
 		async isInstalled(config) {
 			return fs.existsSync(this.unitFilePath(config));
 		}
+		async list(isUserLevel) {
+			const unitDir = isUserLevel ? path.join(os.homedir(), ".config", "systemd", "user") : "/etc/systemd/system";
+			if (!fs.existsSync(unitDir)) return [];
+			const out = [];
+			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);
+				if (!m) continue;
+				out.push({
+					name: entry.replace(/\.service$/, ""),
+					platform: "systemd",
+					isUserLevel,
+					component: m[1]
+				});
+			}
+			return out;
+		}
 	};
 }));
 //#endregion
@@ -6363,6 +6686,10 @@ var init_systemd = __esmMin((() => {
 * user-level (~/Library/LaunchAgents/) agents.
 */
 var launchd_exports = /* @__PURE__ */ __exportAll({ LaunchdServiceManager: () => LaunchdServiceManager });
+/** Async sleep used to pace launchd bootout/bootstrap reconciliation. */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
 var LABEL_PREFIX, SYSTEM_LOG_DIR, LaunchdServiceManager;
 var init_launchd = __esmMin((() => {
 	LABEL_PREFIX = "dev.kici";
@@ -6416,6 +6743,10 @@ var init_launchd = __esmMin((() => {
 			lines.push("<dict>");
 			lines.push("  <key>Label</key>");
 			lines.push(`  <string>${this.escapeXml(label)}</string>`);
+			if (config.component) {
+				lines.push("  <key>KiCIComponent</key>");
+				lines.push(`  <string>${config.component}</string>`);
+			}
 			lines.push("  <key>ProgramArguments</key>");
 			lines.push("  <array>");
 			lines.push(`    <string>${this.escapeXml(config.executablePath)}</string>`);
@@ -6497,14 +6828,61 @@ var init_launchd = __esmMin((() => {
 				logDirectory
 			], { stdio: "inherit" });
 			fs.writeFileSync(plistFile, plistContent, "utf-8");
-			if (this.isLoaded(config)) try {
-				execFileSync("launchctl", ["bootout", this.domainTarget(config)], { stdio: "inherit" });
-			} catch {}
-			execFileSync("launchctl", [
-				"bootstrap",
-				this.domain(config),
-				plistFile
-			], { stdio: "inherit" });
+			if (this.isLoaded(config)) {
+				try {
+					execFileSync("launchctl", ["bootout", this.domainTarget(config)], { stdio: "inherit" });
+				} catch {}
+				await this.waitUntilUnloaded(config);
+			}
+			await this.bootstrapWithRetry(config, plistFile);
+		}
+		/**
+		* Poll until the service is no longer loaded in its target domain, or a
+		* short deadline elapses. `launchctl bootout` is asynchronous — it returns
+		* before launchd has finished releasing the service — so a bootstrap issued
+		* immediately afterward races the teardown and fails with EIO. Waiting for
+		* the unload to complete closes that race for the common case; the residual
+		* window is covered by bootstrapWithRetry.
+		*/
+		async waitUntilUnloaded(config) {
+			const deadline = Date.now() + 15e3;
+			while (this.isLoaded(config)) {
+				if (Date.now() >= deadline) return;
+				await sleep(500);
+			}
+		}
+		/**
+		* Bootstrap into the target domain, retrying on the transient EIO
+		* ("5: Input/output error") launchd returns when a just-removed service has
+		* not finished tearing down. A genuine, non-transient failure (bad plist,
+		* permission denied) is re-thrown on the first attempt. If a stale instance
+		* reappears between attempts, it is booted out before the next try.
+		*/
+		async bootstrapWithRetry(config, plistFile) {
+			const attempts = 5;
+			for (let attempt = 1; attempt <= attempts; attempt++) try {
+				execFileSync("launchctl", [
+					"bootstrap",
+					this.domain(config),
+					plistFile
+				], { stdio: [
+					"inherit",
+					"inherit",
+					"pipe"
+				] });
+				return;
+			} catch (err) {
+				const e = err;
+				const stderr = (e.stderr ?? "").toString();
+				if (!(e.status === 5 || /input\/output error|resource busy/i.test(stderr)) || attempt === attempts) {
+					if (stderr) process.stderr.write(stderr);
+					throw err;
+				}
+				if (this.isLoaded(config)) try {
+					execFileSync("launchctl", ["bootout", this.domainTarget(config)], { stdio: "inherit" });
+				} catch {}
+				await sleep(1e3 * attempt);
+			}
 		}
 		async uninstall(config) {
 			const plistFile = this.plistPath(config);
@@ -6573,6 +6951,30 @@ var init_launchd = __esmMin((() => {
 		async isInstalled(config) {
 			return fs.existsSync(this.plistPath(config));
 		}
+		async list(isUserLevel) {
+			const baseDir = isUserLevel ? path.join(os.homedir(), "Library", "LaunchAgents") : "/Library/LaunchDaemons";
+			if (!fs.existsSync(baseDir)) return [];
+			const out = [];
+			for (const entry of fs.readdirSync(baseDir)) {
+				if (typeof entry !== "string") continue;
+				if (!entry.endsWith(".plist")) continue;
+				let content;
+				try {
+					content = fs.readFileSync(path.join(baseDir, entry), "utf-8");
+				} catch {
+					continue;
+				}
+				const match = content.match(/<key>KiCIComponent<\/key>\s*<string>(orchestrator|agent)<\/string>/);
+				if (!match) continue;
+				out.push({
+					name: entry.replace(/\.plist$/, ""),
+					platform: "launchd",
+					isUserLevel,
+					component: match[1]
+				});
+			}
+			return out;
+		}
 	};
 }));
 //#endregion
@@ -6870,6 +7272,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;
+			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("/");
 			const resetSeconds = config.restartPolicy.windowSeconds;
@@ -6960,6 +7364,37 @@ var init_windows = __esmMin((() => {
 				return false;
 			}
 		}
+		async list(isUserLevel) {
+			let raw;
+			try {
+				raw = execSync("powershell -Command \"Get-CimInstance Win32_Service -Filter \\\"Name LIKE 'kici-%'\\\" | Select-Object Name,Description | ConvertTo-Json\"", { stdio: "pipe" }).toString();
+			} catch {
+				return [];
+			}
+			if (!raw.trim()) return [];
+			let parsed;
+			try {
+				parsed = JSON.parse(raw);
+			} catch {
+				return [];
+			}
+			const rows = Array.isArray(parsed) ? parsed : [parsed];
+			const out = [];
+			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)\]/);
+				if (!match) continue;
+				if (typeof r.Name !== "string") continue;
+				out.push({
+					name: r.Name,
+					platform: "windows",
+					isUserLevel,
+					component: match[1]
+				});
+			}
+			return out;
+		}
 	};
 }));
 //#endregion
@@ -6982,11 +7417,11 @@ var compose_exports = /* @__PURE__ */ __exportAll({ ComposeServiceManager: () =>
 function detectRuntime() {
 	try {
 		execSync("podman compose version", { stdio: "pipe" });
-		return "podman compose";
+		return "podman";
 	} catch {}
 	try {
 		execSync("docker compose version", { stdio: "pipe" });
-		return "docker compose";
+		return "docker";
 	} catch {}
 	throw new Error("No container runtime found. Install Docker or Podman with compose support.");
 }
@@ -7029,7 +7464,7 @@ function getRestartMode(config) {
 */
 function generateComposeYaml(config) {
 	const restartMode = getRestartMode(config);
-	return [
+	const lines = [
 		"# Generated by KiCI service installer",
 		`# Service: ${config.displayName}`,
 		"",
@@ -7043,20 +7478,25 @@ function generateComposeYaml(config) {
 		"    volumes:",
 		`      - ${config.workingDirectory}:${config.workingDirectory}`,
 		"    network_mode: host"
-	].join("\n") + "\n";
+	];
+	if (config.component) {
+		lines.push("    labels:");
+		lines.push(`      dev.kici.component: ${config.component}`);
+	}
+	return lines.join("\n") + "\n";
 }
 var ComposeServiceManager;
 var init_compose = __esmMin((() => {
 	ComposeServiceManager = class {
 		runtime = null;
-		/** Get the runtime command, detecting it if not already done. */
+		/** Get the runtime binary (`podman` or `docker`), detecting it if not already done. */
 		getRuntime() {
 			if (!this.runtime) this.runtime = detectRuntime();
 			return this.runtime;
 		}
 		/** Run a compose command for the given service config. */
 		runCompose(config, args) {
-			execSync(`${this.getRuntime()} -f "${getComposeFilePath(config)}" ${args}`, { stdio: "pipe" });
+			execSync(`${this.getRuntime()} compose -f "${getComposeFilePath(config)}" ${args}`, { stdio: "pipe" });
 		}
 		async install(config) {
 			this.getRuntime();
@@ -7084,7 +7524,7 @@ var init_compose = __esmMin((() => {
 		}
 		async status(config) {
 			try {
-				const output = execSync(`${this.getRuntime()} -f "${getComposeFilePath(config)}" ps --format json`, { stdio: "pipe" }).toString();
+				const output = execSync(`${this.getRuntime()} compose -f "${getComposeFilePath(config)}" ps --format json`, { stdio: "pipe" }).toString();
 				const data = JSON.parse(output);
 				const container = Array.isArray(data) ? data[0] : data;
 				if (!container) return { state: "stopped" };
@@ -7108,6 +7548,44 @@ var init_compose = __esmMin((() => {
 			const composeFile = getComposeFilePath(config);
 			return fs.existsSync(composeFile);
 		}
+		async list(isUserLevel) {
+			let runtime;
+			try {
+				runtime = this.getRuntime();
+			} catch {
+				return [];
+			}
+			let raw;
+			try {
+				raw = execSync(`${runtime} ps -a --filter label=dev.kici.component --format '{{json .}}'`, { encoding: "utf-8" }).toString();
+			} catch {
+				return [];
+			}
+			const out = [];
+			for (const line of raw.split("\n")) {
+				const trimmed = line.trim();
+				if (!trimmed) continue;
+				let row;
+				try {
+					row = JSON.parse(trimmed);
+				} catch {
+					continue;
+				}
+				if (!row || typeof row !== "object") continue;
+				const r = row;
+				const m = (typeof r.Labels === "string" ? r.Labels : "").match(/dev\.kici\.component=(orchestrator|agent)/);
+				if (!m) continue;
+				const name = typeof r.Names === "string" ? r.Names : String(r.Names ?? "");
+				if (!name) continue;
+				out.push({
+					name,
+					platform: "compose",
+					isUserLevel,
+					component: m[1]
+				});
+			}
+			return out;
+		}
 	};
 }));
 //#endregion
@@ -7172,93 +7650,511 @@ function resolveServiceExecutable(opts) {
 	};
 }
 //#endregion
-//#region src/cli/wizard/prompts.ts
+//#region src/cli/commands/shared/versioned-upgrade.ts
 /**
-* Shared prompt utilities for the setup wizards.
+* Shared versioned directory upgrade logic for kici-admin upgrade commands.
 *
-* Wraps @inquirer/prompts with consistent formatting and
-* validation for common input types (DB URLs, ports, etc.).
+* Implements the versioned directory layout:
+* - Extract new version alongside old versions
+* - Update symlink (Unix) or service registration (Windows) atomically
+* - Preserve old versions for rollback
+* - Optional cleanup of old versions
 */
-/** Prompt for a PostgreSQL database URL with validation. */
-async function promptDbUrl() {
-	return input({
-		message: "PostgreSQL database URL:",
-		validate: (value) => {
-			const v = value.trim();
-			if (!v.startsWith("postgresql://") && !v.startsWith("postgres://")) return "Must start with postgresql:// or postgres://";
-			return true;
-		}
-	});
-}
-/** Prompt for a port number with validation. */
-async function promptPort(defaultPort) {
-	const value = await input({
-		message: "Port:",
-		default: String(defaultPort),
-		validate: (value) => {
-			const n = parseInt(value.trim(), 10);
-			if (isNaN(n) || n < 1 || n > 65535) return "Must be a number between 1 and 65535";
-			return true;
-		}
-	});
-	return parseInt(value.trim(), 10);
-}
-/** Prompt for a yes/no confirmation. */
-async function promptConfirm(message, defaultValue = true) {
-	return confirm({
-		message,
-		default: defaultValue
+/**
+* Resolve the upgrade target via the folder-anchored model and build the
+* ServiceConfig + installBase the rest of the upgrade flow needs.
+*
+* Priority chain (delegated to {@link resolveInstance}):
+*   1. `opts.instanceDir` — read manifest at that path.
+*   2. `opts.name`        — match against listInstances() output.
+*   3. CWD manifest       — read `./.kici-<component>.json`.
+*   4. otherwise          — refuse with a candidate-list error.
+*
+* The returned `installBase` comes from the manifest, NEVER re-derived from
+* the service name. Instances installed with a non-default base must
+* continue to resolve to that base on upgrade.
+*/
+async function resolveUpgradeTarget(args) {
+	const { component, opts, manager, isUserLevel, kiciRoot } = args;
+	const resolved = await resolveInstance({
+		component,
+		opts: {
+			instanceDir: opts.instanceDir,
+			name: opts.name
+		},
+		cwd: process.cwd(),
+		kiciRoot,
+		manager,
+		isUserLevel
 	});
+	return {
+		config: {
+			name: resolved.manifest.name,
+			displayName: `KiCI ${component}`,
+			description: `KiCI ${component} service`,
+			executablePath: "",
+			envFilePath: resolved.manifest.envFilePath,
+			workingDirectory: resolved.manifest.configDir,
+			isUserLevel: resolved.manifest.isUserLevel,
+			restartPolicy: {
+				enabled: true,
+				delays: [
+					1,
+					5,
+					15,
+					30
+				],
+				maxRetries: 5,
+				windowSeconds: 300
+			},
+			component
+		},
+		installBase: resolved.manifest.installBase,
+		resolvedInstance: resolved
+	};
 }
-/** Prompt for a URL with http(s):// validation. */
-async function promptUrl(message, defaultValue) {
-	return input({
-		message,
-		default: defaultValue,
-		validate: (value) => {
-			const v = value.trim();
-			if (!v.startsWith("http://") && !v.startsWith("https://") && !v.startsWith("wss://") && !v.startsWith("ws://")) return "Must start with http://, https://, ws://, or wss://";
-			return true;
-		}
+/** Prompt the user for confirmation (returns true if yes). */
+async function confirm$2(message) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
 	});
-}
-/** Prompt for a secret/password (masked input). */
-async function promptSecret(message) {
-	return password({
-		message,
-		mask: "*",
-		validate: (value) => {
-			if (!value.trim()) return "This field is required";
-			return true;
-		}
+	return new Promise((resolve) => {
+		rl.question(`${message} [y/N] `, (answer) => {
+			rl.close();
+			resolve(answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes");
+		});
 	});
 }
-/** Prompt for a selection from a list of options. */
-async function promptSelect(message, choices, defaultValue) {
-	return select({
-		message,
-		choices,
-		default: defaultValue
-	});
+/** Download a file from a URL to a local path. */
+async function downloadArchive(url, destPath) {
+	console.log(`Downloading from ${url}...`);
+	const res = await fetch(url);
+	if (!res.ok || !res.body) throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+	const fileStream = createWriteStream(destPath);
+	await pipeline(res.body, fileStream);
+	console.log(`Downloaded to ${destPath}`);
 }
-var init_prompts = __esmMin((() => {}));
-//#endregion
-//#region src/cli/wizard/orchestrator-wizard.ts
 /**
-* Interactive wizard for orchestrator service setup.
+* Install base for a KiCI component instance.
 *
-* Walks the user through essential configuration (mode, DB URL,
-* port, secrets key) with sensible defaults. Returns a config
-* object that the install command uses to write the env file.
+* Name-scoped so that two instances of the same component (e.g. an org's
+* dogfood orchestrator and an E2E test orchestrator) own independent
+* versioned trees and symlinks. Per-platform bases:
+*   - systemd / compose: /opt/kici/<name>/
+*   - launchd:           /usr/local/kici/<name>/
+*   - windows:           C:\Program Files\KiCI\<name>\
 */
-var orchestrator_wizard_exports = /* @__PURE__ */ __exportAll({ runOrchestratorWizard: () => runOrchestratorWizard });
+function getInstallBase(platform, name) {
+	const sep = platform === "windows" ? "\\" : "/";
+	switch (platform) {
+		case "systemd":
+		case "compose": return `/opt/kici/${name}${sep}`;
+		case "launchd": return `/usr/local/kici/${name}${sep}`;
+		case "windows": return `C:\\Program Files\\KiCI\\${name}${sep}`;
+	}
+}
+/** Check if the platform is Windows. */
+function isWindows(platform) {
+	return platform === "windows";
+}
+/** Get the launcher script name for a component. */
+function getLauncherName(component, platform) {
+	const baseName = component === "orchestrator" ? "kici-orchestrator-standalone" : "kici-agent";
+	return isWindows(platform) ? `${baseName}.cmd` : baseName;
+}
 /**
-* Run the interactive orchestrator setup wizard.
-*
-* Asks only essential questions per the user decision:
-* 1. Mode (platform/hybrid/independent)
-* 2. Database URL
-* 3. Port
+* Extract an archive (.tar.gz or .zip) to a destination directory.
+* Returns the name of the top-level directory inside the archive.
+*/
+function extractArchive(archivePath, destDir) {
+	fs.mkdirSync(destDir, { recursive: true });
+	if (archivePath.endsWith(".zip")) if (os.platform() === "win32") execSync(`powershell -Command "Expand-Archive -Path '${archivePath}' -DestinationPath '${destDir}' -Force"`, { stdio: "inherit" });
+	else execSync(`unzip -o "${archivePath}" -d "${destDir}"`, { stdio: "inherit" });
+	else execSync(`tar -xzf "${archivePath}" -C "${destDir}"`, { stdio: "inherit" });
+	const dirs = fs.readdirSync(destDir).filter((e) => fs.statSync(path.join(destDir, e)).isDirectory());
+	if (dirs.length === 0) throw new Error("Archive does not contain a directory");
+	return dirs[0];
+}
+/**
+* List installed versions for a component by scanning the install base directory
+* for directories matching `{component}-{version}/`.
+*/
+function listInstalledVersions(installBase, component) {
+	if (!fs.existsSync(installBase)) return [];
+	const prefix = `${component}-`;
+	return fs.readdirSync(installBase).filter((entry) => {
+		if (!entry.startsWith(prefix)) return false;
+		const fullPath = path.join(installBase, entry);
+		return fs.statSync(fullPath).isDirectory();
+	}).map((entry) => entry.slice(prefix.length)).sort();
+}
+/**
+* Read the current symlink target to determine the active version.
+* Returns null if no symlink exists or on Windows.
+*/
+function getCurrentVersion(installBase, component, platform) {
+	if (isWindows(platform)) {
+		const versionFile = path.join(installBase, `${component}-current-version.txt`);
+		try {
+			return fs.readFileSync(versionFile, "utf-8").trim();
+		} catch {
+			return null;
+		}
+	}
+	const symlinkPath = path.join(installBase, component);
+	try {
+		const target = fs.readlinkSync(symlinkPath);
+		const prefix = `${component}-`;
+		if (target.startsWith(prefix)) return target.slice(prefix.length);
+		const basename = path.basename(target);
+		if (basename.startsWith(prefix)) return basename.slice(prefix.length);
+	} catch {}
+	return null;
+}
+/** Write the current version to a tracking file (used on Windows). */
+function writeCurrentVersion(installBase, component, version) {
+	const versionFile = path.join(installBase, `${component}-current-version.txt`);
+	fs.writeFileSync(versionFile, version, "utf-8");
+}
+/**
+* Update the symlink atomically on Unix.
+* Creates a temporary symlink then renames it over the existing one.
+*/
+function updateSymlinkAtomic(installBase, component, version) {
+	const symlinkPath = path.join(installBase, component);
+	const tmpLink = `${symlinkPath}.tmp.${Date.now()}`;
+	const target = `${component}-${version}`;
+	try {
+		fs.symlinkSync(target, tmpLink);
+		fs.renameSync(tmpLink, symlinkPath);
+	} catch (err) {
+		try {
+			fs.unlinkSync(tmpLink);
+		} catch {}
+		throw err;
+	}
+}
+/**
+* Perform a versioned directory upgrade for a KiCI component.
+*
+* Flow:
+* 1. Parse upgrade source (--from archive or --url)
+* 2. Determine install base by platform
+* 3. Extract new versioned directory
+* 4. Stop service
+* 5. Update symlink (Unix) or service registration (Windows)
+* 6. Start service
+*/
+async function performVersionedUpgrade(component, opts) {
+	try {
+		const platform = detectPlatform(opts.platform);
+		const manager = await createServiceManager(platform);
+		const userLevel = !isRoot();
+		const kiciRoot = kiciConfigRoot(userLevel);
+		const { config, installBase, resolvedInstance } = await resolveUpgradeTarget({
+			component,
+			opts: {
+				instanceDir: opts.instanceDir,
+				name: opts.name
+			},
+			manager,
+			isUserLevel: userLevel,
+			kiciRoot
+		});
+		if (!isWindows(platform) && !userLevel && !isRoot()) {
+			console.error("Error: root privileges required to upgrade system-level services");
+			process.exit(1);
+		}
+		if (opts.rollback) {
+			await handleRollback(component, platform, installBase, config, manager, opts);
+			return;
+		}
+		if (opts.cleanup) {
+			await handleCleanup(component, platform, installBase);
+			return;
+		}
+		if (!opts.from && !opts.url) {
+			console.error("Error: provide --from <archive-path> or --url <url> for the upgrade package");
+			process.exit(1);
+		}
+		if (!opts.version) {
+			console.error("Error: --version is required to specify the target version");
+			process.exit(1);
+		}
+		const version = opts.version;
+		const versionedDirName = `${component}-${version}`;
+		const versionedDirPath = path.join(installBase, versionedDirName);
+		if (fs.existsSync(versionedDirPath)) if (opts.force) {
+			console.log(`Removing existing directory ${versionedDirPath} (--force)`);
+			fs.rmSync(versionedDirPath, {
+				recursive: true,
+				force: true
+			});
+		} else {
+			console.error(`Error: version directory already exists: ${versionedDirPath}`);
+			console.error("Use --force to overwrite.");
+			process.exit(1);
+		}
+		if (!await manager.isInstalled(config)) {
+			console.error(`Error: service "${config.name}" is not installed`);
+			process.exit(1);
+		}
+		let archivePath;
+		const tmpDir = path.join(os.tmpdir(), `kici-upgrade-${Date.now()}`);
+		fs.mkdirSync(tmpDir, { recursive: true });
+		if (opts.from) {
+			archivePath = path.resolve(opts.from);
+			if (!fs.existsSync(archivePath)) {
+				console.error(`Error: archive not found at ${archivePath}`);
+				process.exit(1);
+			}
+		} else {
+			const ext = opts.url.endsWith(".zip") ? ".zip" : ".tar.gz";
+			archivePath = path.join(tmpDir, `${component}-${version}${ext}`);
+			await downloadArchive(opts.url, archivePath);
+		}
+		const currentVersion = getCurrentVersion(installBase, component, platform);
+		if (!opts.yes) {
+			console.log(`This will upgrade "${config.name}" to version ${version}:`);
+			if (currentVersion) console.log(`  Current version: ${currentVersion}`);
+			console.log(`  New version: ${version}`);
+			console.log(`  Install path: ${versionedDirPath}`);
+			console.log("  The service will be stopped during upgrade.");
+			console.log("");
+			if (!await confirm$2("Proceed with upgrade?")) {
+				console.log("Upgrade cancelled.");
+				return;
+			}
+		}
+		console.log("Extracting archive...");
+		const extractDir = path.join(tmpDir, "extract");
+		const extractedDirName = extractArchive(archivePath, extractDir);
+		fs.mkdirSync(installBase, { recursive: true });
+		const srcDir = path.join(extractDir, extractedDirName);
+		if (isWindows(platform)) execSync(`xcopy "${srcDir}" "${versionedDirPath}" /E /I /Q /Y`, { stdio: "inherit" });
+		else execSync(`cp -r "${srcDir}" "${versionedDirPath}"`, { stdio: "inherit" });
+		console.log(`Extracted to ${versionedDirPath}`);
+		console.log("Stopping service...");
+		if ((await manager.status(config)).state === "running") {
+			await manager.stop(config);
+			console.log("Service stopped.");
+		}
+		if (isWindows(platform)) {
+			const launcherPath = path.join(versionedDirPath, getLauncherName(component, platform));
+			config.executablePath = launcherPath;
+			await manager.uninstall(config);
+			await new Promise((r) => setTimeout(r, 2e3));
+			await manager.install(config);
+			writeCurrentVersion(installBase, component, version);
+			console.log(`Service registration updated to ${launcherPath}`);
+		} else {
+			updateSymlinkAtomic(installBase, component, version);
+			const symlinkPath = path.join(installBase, component);
+			console.log(`Symlink updated: ${symlinkPath} -> ${versionedDirName}`);
+			const launcherPath = path.join(symlinkPath, getLauncherName(component, platform));
+			if (fs.existsSync(launcherPath)) fs.chmodSync(launcherPath, 493);
+			config.executablePath = path.join(installBase, component, getLauncherName(component, platform));
+		}
+		console.log("Starting service...");
+		await manager.start(config);
+		console.log("Service started.");
+		writeManifest(resolvedInstance.instanceDir, {
+			...resolvedInstance.manifest,
+			kiciVersion: version
+		});
+		fs.rmSync(tmpDir, {
+			recursive: true,
+			force: true
+		});
+		console.log("");
+		if (currentVersion) {
+			console.log(`Upgrade complete: ${currentVersion} -> ${version}`);
+			console.log(`Previous version preserved at: ${path.join(installBase, `${component}-${currentVersion}`)}`);
+		} else console.log(`Upgrade to ${version} complete.`);
+	} catch (err) {
+		console.error(`Error: ${toErrorMessage(err)}`);
+		process.exit(1);
+	}
+}
+/**
+* Handle --rollback: switch symlink to the previous version and restart.
+*/
+async function handleRollback(component, platform, installBase, config, manager, opts) {
+	const versions = listInstalledVersions(installBase, component);
+	if (versions.length < 2) {
+		console.error("Error: no previous version available for rollback");
+		if (versions.length === 1) console.error(`Only version installed: ${versions[0]}`);
+		process.exit(1);
+	}
+	const currentVersion = getCurrentVersion(installBase, component, platform);
+	if (!currentVersion) {
+		console.error("Error: cannot determine current version (no symlink found)");
+		console.log("Available versions:");
+		for (const v of versions) console.log(`  ${component}-${v}/`);
+		process.exit(1);
+	}
+	const currentIdx = versions.indexOf(currentVersion);
+	let previousVersion;
+	if (currentIdx > 0) previousVersion = versions[currentIdx - 1];
+	else if (versions.length >= 2) previousVersion = versions[1];
+	else {
+		console.error("Error: no alternative version available for rollback");
+		process.exit(1);
+		return;
+	}
+	if (!opts.yes) {
+		console.log(`Rolling back "${config.name}":`);
+		console.log(`  Current version: ${currentVersion}`);
+		console.log(`  Rollback to: ${previousVersion}`);
+		console.log("");
+		if (!await confirm$2("Proceed with rollback?")) {
+			console.log("Rollback cancelled.");
+			return;
+		}
+	}
+	console.log("Stopping service...");
+	if ((await manager.status(config)).state === "running") {
+		await manager.stop(config);
+		console.log("Service stopped.");
+	}
+	if (isWindows(platform)) {
+		const launcherPath = path.join(installBase, `${component}-${previousVersion}`, getLauncherName(component, platform));
+		config.executablePath = launcherPath;
+		await manager.uninstall(config);
+		await manager.install(config);
+		writeCurrentVersion(installBase, component, previousVersion);
+		console.log(`Service registration updated to ${launcherPath}`);
+	} else {
+		updateSymlinkAtomic(installBase, component, previousVersion);
+		console.log(`Symlink updated: ${path.join(installBase, component)} -> ${component}-${previousVersion}`);
+	}
+	console.log("Starting service...");
+	await manager.start(config);
+	console.log("Service started.");
+	console.log("");
+	console.log(`Rollback complete: ${currentVersion} -> ${previousVersion}`);
+}
+/**
+* Handle --cleanup: remove all versioned directories except the current
+* and previous versions.
+*/
+async function handleCleanup(component, platform, installBase) {
+	const versions = listInstalledVersions(installBase, component);
+	if (versions.length <= 2) {
+		console.log("Nothing to clean up (2 or fewer versions installed).");
+		return;
+	}
+	const currentVersion = getCurrentVersion(installBase, component, platform);
+	const currentIdx = currentVersion ? versions.indexOf(currentVersion) : versions.length - 1;
+	const previousIdx = currentIdx > 0 ? currentIdx - 1 : -1;
+	const toRemove = versions.filter((_, i) => i !== currentIdx && i !== previousIdx);
+	if (toRemove.length === 0) {
+		console.log("Nothing to clean up.");
+		return;
+	}
+	console.log("The following versions will be removed:");
+	for (const v of toRemove) console.log(`  ${component}-${v}/`);
+	if (currentVersion) console.log(`\nKeeping: ${component}-${currentVersion}/ (current)`);
+	if (previousIdx >= 0) console.log(`Keeping: ${component}-${versions[previousIdx]}/ (previous)`);
+	for (const v of toRemove) {
+		const dirPath = path.join(installBase, `${component}-${v}`);
+		fs.rmSync(dirPath, {
+			recursive: true,
+			force: true
+		});
+		console.log(`Removed ${dirPath}`);
+	}
+	console.log(`\nCleanup complete. Removed ${toRemove.length} old version(s).`);
+}
+//#endregion
+//#region src/cli/wizard/prompts.ts
+/**
+* Shared prompt utilities for the setup wizards.
+*
+* Wraps @inquirer/prompts with consistent formatting and
+* validation for common input types (DB URLs, ports, etc.).
+*/
+/** Prompt for a PostgreSQL database URL with validation. */
+async function promptDbUrl() {
+	return input({
+		message: "PostgreSQL database URL:",
+		validate: (value) => {
+			const v = value.trim();
+			if (!v.startsWith("postgresql://") && !v.startsWith("postgres://")) return "Must start with postgresql:// or postgres://";
+			return true;
+		}
+	});
+}
+/** Prompt for a port number with validation. */
+async function promptPort(defaultPort) {
+	const value = await input({
+		message: "Port:",
+		default: String(defaultPort),
+		validate: (value) => {
+			const n = parseInt(value.trim(), 10);
+			if (isNaN(n) || n < 1 || n > 65535) return "Must be a number between 1 and 65535";
+			return true;
+		}
+	});
+	return parseInt(value.trim(), 10);
+}
+/** Prompt for a yes/no confirmation. */
+async function promptConfirm(message, defaultValue = true) {
+	return confirm({
+		message,
+		default: defaultValue
+	});
+}
+/** Prompt for a URL with http(s):// validation. */
+async function promptUrl(message, defaultValue) {
+	return input({
+		message,
+		default: defaultValue,
+		validate: (value) => {
+			const v = value.trim();
+			if (!v.startsWith("http://") && !v.startsWith("https://") && !v.startsWith("wss://") && !v.startsWith("ws://")) return "Must start with http://, https://, ws://, or wss://";
+			return true;
+		}
+	});
+}
+/** Prompt for a secret/password (masked input). */
+async function promptSecret(message) {
+	return password({
+		message,
+		mask: "*",
+		validate: (value) => {
+			if (!value.trim()) return "This field is required";
+			return true;
+		}
+	});
+}
+/** Prompt for a selection from a list of options. */
+async function promptSelect(message, choices, defaultValue) {
+	return select({
+		message,
+		choices,
+		default: defaultValue
+	});
+}
+var init_prompts = __esmMin((() => {}));
+//#endregion
+//#region src/cli/wizard/orchestrator-wizard.ts
+/**
+* Interactive wizard for orchestrator service setup.
+*
+* Walks the user through essential configuration (mode, DB URL,
+* port, secrets key) with sensible defaults. Returns a config
+* object that the install command uses to write the env file.
+*/
+var orchestrator_wizard_exports = /* @__PURE__ */ __exportAll({ runOrchestratorWizard: () => runOrchestratorWizard });
+/**
+* Run the interactive orchestrator setup wizard.
+*
+* Asks only essential questions per the user decision:
+* 1. Mode (platform/hybrid/independent)
+* 2. Database URL
+* 3. Port
 * 4. Secrets encryption key
 * 5. Bootstrap admin token (for kici-admin authentication)
 * 6. Platform URL + token (if platform/hybrid mode)
@@ -7390,11 +8286,22 @@ function startDevPostgres(containerName) {
 		if (err instanceof Error && err.message.includes("already exists")) throw err;
 	}
 	console.log(`Starting dev PostgreSQL container "${containerName}" on port ${port}...`);
-	execSync(`${runtime} run -d --name ${containerName} -p ${port}:5432 -e POSTGRES_PASSWORD=${password} -e POSTGRES_DB=kici postgres:18-trixie`, { stdio: "inherit" });
+	const tmpEnvFile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "kici-dev-pg-")), "postgres.env");
+	try {
+		fs.writeFileSync(tmpEnvFile, `POSTGRES_PASSWORD=${password}\n`, { mode: 384 });
+		execSync(`${runtime} run -d --name ${containerName} -p ${port}:5432 --env-file ${tmpEnvFile} -e POSTGRES_DB=kici postgres:18-trixie`, { stdio: "inherit" });
+	} finally {
+		try {
+			fs.rmSync(path.dirname(tmpEnvFile), {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+	}
 	return `postgresql://postgres:${password}@localhost:${port}/kici`;
 }
 function registerOrchestratorInstall(orchestrator) {
-	orchestrator.command("install").description("Install the orchestrator as a system service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--env-file <path>", "Path to existing env/config file to use").option("--binary <path>", "Path to orchestrator binary (default: current executable)").option("--dev", "Dev mode: spin up PostgreSQL container on port 15432").option("--wizard", "Interactive wizard for guided setup").option("--name <name>", "Service name", "kici-orchestrator").option("--system", "Install as system-level service (requires root)").option("--user-level", "Install as user-level service (no root required)").option("--user <name>", "Run the service as the named user (system-level launchd only; sets UserName in plist so the daemon drops privileges)").action(async (opts) => {
+	orchestrator.command("install").description("Install the orchestrator as a system service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--env-file <path>", "Path to existing env/config file to use").option("--binary <path>", "Path to orchestrator binary (default: current executable)").option("--dev", "Dev mode: spin up PostgreSQL container on port 15432").option("--wizard", "Interactive wizard for guided setup").option("--name <name>", "Service name", "kici-orchestrator").option("--system", "Install as system-level service (requires root)").option("--user-level", "Install as user-level service (no root required)").option("--user <name>", "Run the service as the named user (system-level launchd only; sets UserName in plist so the daemon drops privileges)").option("--instance-dir <path>", "Deploy folder; the instance manifest is written here (default: current working directory)").option("--force", "Overwrite an existing same-named foreign instance").action(async (opts) => {
 		try {
 			if (opts.wizard && opts.envFile) {
 				console.error("Error: Cannot use --wizard with --env-file");
@@ -7403,9 +8310,24 @@ function registerOrchestratorInstall(orchestrator) {
 			const platform = detectPlatform(opts.platform);
 			const userLevel = resolveUserLevel(opts);
 			const serviceName = opts.name;
+			const instanceDir = path.resolve(opts.instanceDir ?? process.cwd());
+			const kiciRoot = kiciConfigRoot(userLevel);
 			console.log(`Platform: ${platform}`);
 			console.log(`Privilege: ${userLevel ? "user" : "system"}`);
 			console.log(`Service name: ${serviceName}`);
+			console.log(`Instance dir: ${instanceDir}`);
+			const manager = await createServiceManager(platform);
+			const existing = (await listInstances({
+				component: "orchestrator",
+				isUserLevel: userLevel,
+				kiciRoot,
+				manager
+			})).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.`);
+				process.exit(1);
+			}
 			const configDir = getConfigDir(serviceName, userLevel);
 			const logDir = getLogDir(serviceName, userLevel);
 			fs.mkdirSync(configDir, { recursive: true });
@@ -7441,707 +8363,412 @@ function registerOrchestratorInstall(orchestrator) {
 				let envContent = `# KiCI orchestrator configuration\n# See docs for all available options\n`;
 				if (devDbUrl) envContent += `KICI_DATABASE_URL=${devDbUrl}\n`;
 				fs.writeFileSync(envFilePath, envContent, "utf-8");
-				console.log(`Created env file at ${envFilePath}`);
-			} else if (devDbUrl) {
-				fs.appendFileSync(envFilePath, `\nKICI_DATABASE_URL=${devDbUrl}\n`);
-				console.log(`Appended KICI_DATABASE_URL to ${envFilePath}`);
-			}
-			const entryScript = opts.binary ? void 0 : fileURLToPath(import.meta.resolve(`@kici-dev/orchestrator/${selectServerEntry(fs.readFileSync(envFilePath, "utf-8"))}`));
-			const { executablePath, args } = resolveServiceExecutable({
-				binary: opts.binary ? path.resolve(opts.binary) : void 0,
-				nodePath: process.execPath,
-				entryScript
-			});
-			if (userLevel) try {
-				const envContent = fs.readFileSync(envFilePath, "utf-8");
-				if (envContent.includes("firecracker") || envContent.includes("FIRECRACKER")) {
-					console.warn("\nWARNING: Firecracker scaler requires root privileges.");
-					console.warn("The service is being installed at user level. Firecracker will not work.");
-					console.warn("Re-run as root (sudo) to install a system-level service.\n");
-				}
-			} catch {}
-			const config = {
-				name: serviceName,
-				displayName: "KiCI Orchestrator",
-				description: "KiCI CI/CD workflow orchestrator service",
-				executablePath,
-				args,
-				nodeBinDir: path.dirname(process.execPath),
-				envFilePath,
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				user: opts.user,
-				restartPolicy: DEFAULT_RESTART_POLICY
-			};
-			await (await createServiceManager(platform)).install(config);
-			console.log(`\nOrchestrator service "${serviceName}" installed successfully.`);
-			console.log(`  Config: ${envFilePath}`);
-			console.log(`  Logs:   ${logDir}`);
-			console.log(`\nNext steps:`);
-			console.log(`  1. Edit ${envFilePath} with your configuration`);
-			console.log(`  2. Run \`kici-admin orchestrator start\` to start the service`);
-		} catch (err) {
-			console.error(`Error: ${toErrorMessage(err)}`);
-			process.exit(1);
-		}
-	});
-}
-//#endregion
-//#region src/cli/commands/orchestrator-service/uninstall.ts
-function registerOrchestratorUninstall(orchestrator) {
-	orchestrator.command("uninstall").description("Remove the orchestrator service registration").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--name <name>", "Service name", "kici-orchestrator").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
-		try {
-			const platform = detectPlatform(opts.platform);
-			const userLevel = resolveUserLevel(opts);
-			const serviceName = opts.name;
-			const configDir = getConfigDir(serviceName, userLevel);
-			const logDir = getLogDir(serviceName, userLevel);
-			const config = {
-				name: serviceName,
-				displayName: "KiCI Orchestrator",
-				description: "KiCI CI/CD workflow orchestrator service",
-				executablePath: "",
-				envFilePath: `${configDir}${serviceName}.env`,
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: DEFAULT_RESTART_POLICY
-			};
-			const manager = await createServiceManager(platform);
-			if (!await manager.isInstalled(config)) {
-				console.log(`Service "${serviceName}" is not installed.`);
-				process.exit(0);
-			}
-			try {
-				if ((await manager.status(config)).state === "running") {
-					console.log(`Stopping service "${serviceName}"...`);
-					await manager.stop(config);
-				}
-			} catch {}
-			await manager.uninstall(config);
-			console.log(`\nOrchestrator service "${serviceName}" uninstalled.`);
-			console.log(`\nThe following files were preserved for manual cleanup:`);
-			console.log(`  Config: ${configDir}`);
-			console.log(`  Logs:   ${logDir}`);
-			console.log(`  Database: check your DATABASE_URL in the env file`);
-		} catch (err) {
-			console.error(`Error: ${toErrorMessage(err)}`);
-			process.exit(1);
-		}
-	});
-}
-//#endregion
-//#region src/cli/commands/orchestrator-service/start.ts
-function registerOrchestratorStart(orchestrator) {
-	orchestrator.command("start").description("Start the orchestrator service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--name <name>", "Service name", "kici-orchestrator").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
-		try {
-			const platform = detectPlatform(opts.platform);
-			const userLevel = resolveUserLevel(opts);
-			const serviceName = opts.name;
-			const configDir = getConfigDir(serviceName, userLevel);
-			const config = {
-				name: serviceName,
-				displayName: "KiCI Orchestrator",
-				description: "KiCI CI/CD workflow orchestrator service",
-				executablePath: "",
-				envFilePath: path.join(configDir, `${serviceName}.env`),
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: DEFAULT_RESTART_POLICY
-			};
-			const manager = await createServiceManager(platform);
-			if (!await manager.isInstalled(config)) {
-				console.error(`Error: service "${serviceName}" is not installed.`);
-				console.error(`Run \`kici-admin orchestrator install\` first.`);
-				process.exit(1);
-			}
-			await manager.start(config);
-			console.log(`Orchestrator service "${serviceName}" started.`);
-		} catch (err) {
-			console.error(`Error: ${toErrorMessage(err)}`);
-			process.exit(1);
-		}
-	});
-}
-//#endregion
-//#region src/cli/commands/orchestrator-service/stop.ts
-function registerOrchestratorStop(orchestrator) {
-	orchestrator.command("stop").description("Stop the orchestrator service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--name <name>", "Service name", "kici-orchestrator").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
-		try {
-			const platform = detectPlatform(opts.platform);
-			const userLevel = resolveUserLevel(opts);
-			const serviceName = opts.name;
-			const configDir = getConfigDir(serviceName, userLevel);
+				console.log(`Created env file at ${envFilePath}`);
+			} else if (devDbUrl) {
+				fs.appendFileSync(envFilePath, `\nKICI_DATABASE_URL=${devDbUrl}\n`);
+				console.log(`Appended KICI_DATABASE_URL to ${envFilePath}`);
+			}
+			const entryScript = opts.binary ? void 0 : fileURLToPath(import.meta.resolve(`@kici-dev/orchestrator/${selectServerEntry(fs.readFileSync(envFilePath, "utf-8"))}`));
+			const { executablePath, args } = resolveServiceExecutable({
+				binary: opts.binary ? path.resolve(opts.binary) : void 0,
+				nodePath: process.execPath,
+				entryScript
+			});
+			if (userLevel) try {
+				const envContent = fs.readFileSync(envFilePath, "utf-8");
+				if (envContent.includes("firecracker") || envContent.includes("FIRECRACKER")) {
+					console.warn("\nWARNING: Firecracker scaler requires root privileges.");
+					console.warn("The service is being installed at user level. Firecracker will not work.");
+					console.warn("Re-run as root (sudo) to install a system-level service.\n");
+				}
+			} catch {}
 			const config = {
 				name: serviceName,
 				displayName: "KiCI Orchestrator",
 				description: "KiCI CI/CD workflow orchestrator service",
-				executablePath: "",
-				envFilePath: `${configDir}${serviceName}.env`,
+				executablePath,
+				args,
+				nodeBinDir: path.dirname(process.execPath),
+				envFilePath,
 				workingDirectory: configDir,
 				isUserLevel: userLevel,
+				user: opts.user,
+				component: "orchestrator",
 				restartPolicy: DEFAULT_RESTART_POLICY
 			};
-			await (await createServiceManager(platform)).stop(config);
-			console.log(`Orchestrator service "${serviceName}" stopped.`);
-		} catch (err) {
-			console.error(`Error: ${toErrorMessage(err)}`);
-			process.exit(1);
-		}
-	});
-}
-//#endregion
-//#region src/cli/commands/orchestrator-service/restart.ts
-function registerOrchestratorRestart(orchestrator) {
-	orchestrator.command("restart").description("Restart the orchestrator service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--name <name>", "Service name", "kici-orchestrator").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
-		try {
-			const platform = detectPlatform(opts.platform);
-			const userLevel = resolveUserLevel(opts);
-			const serviceName = opts.name;
-			const configDir = getConfigDir(serviceName, userLevel);
-			const config = {
+			await manager.install(config);
+			const manifestFile = writeManifest(instanceDir, {
+				component: "orchestrator",
 				name: serviceName,
-				displayName: "KiCI Orchestrator",
-				description: "KiCI CI/CD workflow orchestrator service",
-				executablePath: "",
-				envFilePath: `${configDir}${serviceName}.env`,
-				workingDirectory: configDir,
+				platform,
 				isUserLevel: userLevel,
-				restartPolicy: DEFAULT_RESTART_POLICY
-			};
-			const manager = await createServiceManager(platform);
-			if (!await manager.isInstalled(config)) {
-				console.error(`Error: service "${serviceName}" is not installed.`);
-				console.error(`Run \`kici-admin orchestrator install\` first.`);
-				process.exit(1);
-			}
-			await manager.restart(config);
-			console.log(`Orchestrator service "${serviceName}" restarted.`);
-		} catch (err) {
-			console.error(`Error: ${toErrorMessage(err)}`);
-			process.exit(1);
-		}
-	});
-}
-//#endregion
-//#region src/cli/commands/orchestrator-service/status.ts
-/** Read the port from the env file in the config directory. */
-function readPortFromEnv$1(configDir, serviceName) {
-	const envPath = path.join(configDir, `${serviceName}.env`);
-	if (!fs.existsSync(envPath)) return 4e3;
-	try {
-		const content = fs.readFileSync(envPath, "utf-8");
-		for (const line of content.split("\n")) {
-			const trimmed = line.trim();
-			if (trimmed.startsWith("#") || !trimmed.includes("=")) continue;
-			const [key, ...rest] = trimmed.split("=");
-			if (key?.trim() === "KICI_PORT") {
-				const val = rest.join("=").trim().replace(/^["']|["']$/g, "");
-				const parsed = parseInt(val, 10);
-				if (!isNaN(parsed)) return parsed;
+				envFilePath,
+				configDir,
+				logDir,
+				installBase: getInstallBase(platform, serviceName),
+				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+				kiciVersion: readKiciVersion()
+			});
+			try {
+				appendIndexEntry(kiciRoot, {
+					component: "orchestrator",
+					name: serviceName,
+					platform,
+					isUserLevel: userLevel,
+					instanceDir
+				});
+			} catch (err) {
+				console.warn(`Warning: instance index append failed: ${err.message}`);
 			}
-		}
-	} catch {}
-	return 4e3;
-}
-/** Query orchestrator health API. */
-async function queryHealth$1(port) {
-	try {
-		const controller = new AbortController();
-		const timeout = setTimeout(() => controller.abort(), 3e3);
-		const res = await fetch(`http://localhost:${port}/health`, { signal: controller.signal });
-		clearTimeout(timeout);
-		if (!res.ok) return null;
-		return await res.json();
-	} catch {
-		return null;
-	}
-}
-/** Format the status output as a readable table. */
-function formatStatus$1(serviceStatus, health, serviceName) {
-	const lines = [];
-	lines.push(`Service: ${serviceName}`);
-	lines.push(`State:   ${serviceStatus.state}`);
-	if (serviceStatus.pid) lines.push(`PID:     ${serviceStatus.pid}`);
-	if (serviceStatus.uptime != null) lines.push(`Uptime:  ${formatUptime(serviceStatus.uptime)}`);
-	if (serviceStatus.startedAt) lines.push(`Started: ${serviceStatus.startedAt}`);
-	if (health) {
-		lines.push("");
-		lines.push("--- KiCI orchestrator ---");
-		if (health.mode) lines.push(`Mode:       ${health.mode}`);
-		if (health.port) lines.push(`Port:       ${health.port}`);
-		if (health.database) lines.push(`Database:   ${health.database}`);
-		if (health.platformRelay) lines.push(`Platform relay: ${health.platformRelay}`);
-		if (health.agents != null) lines.push(`Agents:     ${health.agents}`);
-		if (health.scaler) {
-			const s = health.scaler;
-			lines.push(`Scaler:     ${s.type ?? "none"} (warm: ${s.warm ?? 0}, max: ${s.max ?? 0})`);
-		}
-		if (health.jobs) lines.push(`Jobs:       ${health.jobs.pending ?? 0} pending, ${health.jobs.running ?? 0} running`);
-	} else if (serviceStatus.state === "running") {
-		lines.push("");
-		lines.push("(Could not reach health API)");
-	}
-	return lines.join("\n");
-}
-/** Build JSON output combining service + health data. */
-function buildJsonOutput$1(serviceStatus, health, serviceName) {
-	return {
-		service: serviceName,
-		...serviceStatus,
-		health: health ?? void 0
-	};
-}
-function registerStatusCommand(parent) {
-	parent.command("status").description("Show orchestrator service status and health information").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--name <name>", "Service name", "kici-orchestrator").option("--json", "Output as JSON").action(async (opts) => {
-		try {
-			const manager = await createServiceManager(detectPlatform(opts.platform));
-			const userLevel = !isRoot();
-			const configDir = getConfigDir(opts.name, userLevel);
-			const config = {
-				name: opts.name,
-				displayName: "KiCI orchestrator",
-				description: "KiCI orchestrator service",
-				executablePath: "",
-				envFilePath: path.join(configDir, `${opts.name}.env`),
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: {
-					enabled: true,
-					delays: [
-						1,
-						5,
-						15,
-						30
-					],
-					maxRetries: 5,
-					windowSeconds: 300
-				}
-			};
-			const serviceStatus = await manager.status(config);
-			let health = null;
-			if (serviceStatus.state === "running") health = await queryHealth$1(readPortFromEnv$1(configDir, opts.name));
-			if (opts.json) console.log(JSON.stringify(buildJsonOutput$1(serviceStatus, health, opts.name), null, 2));
-			else console.log(formatStatus$1(serviceStatus, health, opts.name));
-		} catch (err) {
-			console.error(`Error: ${toErrorMessage(err)}`);
-			process.exit(1);
-		}
-	});
-}
-//#endregion
-//#region src/cli/commands/orchestrator-service/logs.ts
-function registerLogsCommand(parent) {
-	parent.command("logs").description("Tail and follow orchestrator service logs").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--name <name>", "Service name", "kici-orchestrator").option("--since <duration>", "Show logs since duration (e.g. 1h, 30m)").option("--level <level>", "Filter by log level (error|warn|info)").option("--json", "Output as structured JSON").option("--no-follow", "Snapshot mode (do not tail)").action(async (opts) => {
-		try {
-			const manager = await createServiceManager(detectPlatform(opts.platform));
-			const userLevel = !isRoot();
-			const configDir = getConfigDir(opts.name, userLevel);
-			const config = {
-				name: opts.name,
-				displayName: "KiCI orchestrator",
-				description: "KiCI orchestrator service",
-				executablePath: "",
-				envFilePath: path.join(configDir, `${opts.name}.env`),
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: {
-					enabled: true,
-					delays: [
-						1,
-						5,
-						15,
-						30
-					],
-					maxRetries: 5,
-					windowSeconds: 300
-				}
-			};
-			const logOptions = {
-				since: opts.since,
-				level: opts.level,
-				json: opts.json,
-				follow: opts.follow
-			};
-			await manager.logs(config, logOptions);
+			console.log(`\nOrchestrator service "${serviceName}" installed successfully.`);
+			console.log(`  Config:   ${envFilePath}`);
+			console.log(`  Logs:     ${logDir}`);
+			console.log(`  Manifest: ${manifestFile}`);
+			console.log(`\nNext steps:`);
+			console.log(`  1. Edit ${envFilePath} with your configuration`);
+			console.log(`  2. Run \`kici-admin orchestrator start\` to start the service`);
 		} catch (err) {
 			console.error(`Error: ${toErrorMessage(err)}`);
 			process.exit(1);
 		}
-	});
-}
-//#endregion
-//#region src/cli/commands/shared/versioned-upgrade.ts
-/**
-* Shared versioned directory upgrade logic for kici-admin upgrade commands.
-*
-* Implements the versioned directory layout:
-* - Extract new version alongside old versions
-* - Update symlink (Unix) or service registration (Windows) atomically
-* - Preserve old versions for rollback
-* - Optional cleanup of old versions
-*/
-/** Prompt the user for confirmation (returns true if yes). */
-async function confirm$2(message) {
-	const rl = createInterface({
-		input: process.stdin,
-		output: process.stdout
-	});
-	return new Promise((resolve) => {
-		rl.question(`${message} [y/N] `, (answer) => {
-			rl.close();
-			resolve(answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes");
-		});
-	});
-}
-/** Download a file from a URL to a local path. */
-async function downloadArchive(url, destPath) {
-	console.log(`Downloading from ${url}...`);
-	const res = await fetch(url);
-	if (!res.ok || !res.body) throw new Error(`Download failed: ${res.status} ${res.statusText}`);
-	const fileStream = createWriteStream(destPath);
-	await pipeline(res.body, fileStream);
-	console.log(`Downloaded to ${destPath}`);
-}
-/**
-* Get the install base directory for the current platform.
-*
-* - Linux (systemd): /opt/kici/
-* - macOS (launchd): /usr/local/kici/
-* - Windows: C:\Program Files\KiCI\
-* - Compose: /opt/kici/ (default)
-*/
-function getInstallBase(platform) {
-	switch (platform) {
-		case "systemd":
-		case "compose": return "/opt/kici/";
-		case "launchd": return "/usr/local/kici/";
-		case "windows": return "C:\\Program Files\\KiCI\\";
-	}
-}
-/** Check if the platform is Windows. */
-function isWindows(platform) {
-	return platform === "windows";
-}
-/** Get the launcher script name for a component. */
-function getLauncherName(component, platform) {
-	const baseName = component === "orchestrator" ? "kici-orchestrator-standalone" : "kici-agent";
-	return isWindows(platform) ? `${baseName}.cmd` : baseName;
-}
-/**
-* Extract an archive (.tar.gz or .zip) to a destination directory.
-* Returns the name of the top-level directory inside the archive.
-*/
-function extractArchive(archivePath, destDir) {
-	fs.mkdirSync(destDir, { recursive: true });
-	if (archivePath.endsWith(".zip")) if (os.platform() === "win32") execSync(`powershell -Command "Expand-Archive -Path '${archivePath}' -DestinationPath '${destDir}' -Force"`, { stdio: "inherit" });
-	else execSync(`unzip -o "${archivePath}" -d "${destDir}"`, { stdio: "inherit" });
-	else execSync(`tar -xzf "${archivePath}" -C "${destDir}"`, { stdio: "inherit" });
-	const dirs = fs.readdirSync(destDir).filter((e) => fs.statSync(path.join(destDir, e)).isDirectory());
-	if (dirs.length === 0) throw new Error("Archive does not contain a directory");
-	return dirs[0];
-}
-/**
-* List installed versions for a component by scanning the install base directory
-* for directories matching `{component}-{version}/`.
-*/
-function listInstalledVersions(installBase, component) {
-	if (!fs.existsSync(installBase)) return [];
-	const prefix = `${component}-`;
-	return fs.readdirSync(installBase).filter((entry) => {
-		if (!entry.startsWith(prefix)) return false;
-		const fullPath = path.join(installBase, entry);
-		return fs.statSync(fullPath).isDirectory();
-	}).map((entry) => entry.slice(prefix.length)).sort();
-}
-/**
-* Read the current symlink target to determine the active version.
-* Returns null if no symlink exists or on Windows.
-*/
-function getCurrentVersion(installBase, component, platform) {
-	if (isWindows(platform)) {
-		const versionFile = path.join(installBase, `${component}-current-version.txt`);
-		try {
-			return fs.readFileSync(versionFile, "utf-8").trim();
-		} catch {
-			return null;
-		}
-	}
-	const symlinkPath = path.join(installBase, component);
-	try {
-		const target = fs.readlinkSync(symlinkPath);
-		const prefix = `${component}-`;
-		if (target.startsWith(prefix)) return target.slice(prefix.length);
-		const basename = path.basename(target);
-		if (basename.startsWith(prefix)) return basename.slice(prefix.length);
-	} catch {}
-	return null;
-}
-/** Write the current version to a tracking file (used on Windows). */
-function writeCurrentVersion(installBase, component, version) {
-	const versionFile = path.join(installBase, `${component}-current-version.txt`);
-	fs.writeFileSync(versionFile, version, "utf-8");
+	});
 }
-/**
-* Update the symlink atomically on Unix.
-* Creates a temporary symlink then renames it over the existing one.
-*/
-function updateSymlinkAtomic(installBase, component, version) {
-	const symlinkPath = path.join(installBase, component);
-	const tmpLink = `${symlinkPath}.tmp.${Date.now()}`;
-	const target = `${component}-${version}`;
-	try {
-		fs.symlinkSync(target, tmpLink);
-		fs.renameSync(tmpLink, symlinkPath);
-	} catch (err) {
+//#endregion
+//#region src/cli/commands/orchestrator-service/uninstall.ts
+function registerOrchestratorUninstall(orchestrator) {
+	orchestrator.command("uninstall").description("Remove the orchestrator service registration").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--instance-dir <path>", "Deploy folder of the instance to uninstall").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
 		try {
-			fs.unlinkSync(tmpLink);
-		} catch {}
-		throw err;
-	}
-}
-/**
-* Perform a versioned directory upgrade for a KiCI component.
-*
-* Flow:
-* 1. Parse upgrade source (--from archive or --url)
-* 2. Determine install base by platform
-* 3. Extract new versioned directory
-* 4. Stop service
-* 5. Update symlink (Unix) or service registration (Windows)
-* 6. Start service
-*/
-async function performVersionedUpgrade(component, opts) {
-	try {
-		const platform = detectPlatform(opts.platform);
-		const manager = await createServiceManager(platform);
-		const userLevel = !isRoot();
-		const configDir = getConfigDir(opts.name, userLevel);
-		const installBase = getInstallBase(platform);
-		const config = {
-			name: opts.name,
-			displayName: `KiCI ${component}`,
-			description: `KiCI ${component} service`,
-			executablePath: "",
-			envFilePath: path.join(configDir, `${opts.name}.env`),
-			workingDirectory: configDir,
-			isUserLevel: userLevel,
-			restartPolicy: {
-				enabled: true,
-				delays: [
-					1,
-					5,
-					15,
-					30
-				],
-				maxRetries: 5,
-				windowSeconds: 300
+			const platform = detectPlatform(opts.platform);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "orchestrator",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
+			const config = {
+				name: resolved.manifest.name,
+				displayName: "KiCI Orchestrator",
+				description: "KiCI CI/CD workflow orchestrator service",
+				executablePath: "",
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "orchestrator"
+			};
+			if (!await manager.isInstalled(config)) console.log(`Service "${config.name}" is not installed.`);
+			else {
+				try {
+					if ((await manager.status(config)).state === "running") {
+						console.log(`Stopping service "${config.name}"...`);
+						await manager.stop(config);
+					}
+				} catch {}
+				await manager.uninstall(config);
 			}
-		};
-		if (!isWindows(platform) && !userLevel && !isRoot()) {
-			console.error("Error: root privileges required to upgrade system-level services");
-			process.exit(1);
-		}
-		if (opts.rollback) {
-			await handleRollback(component, platform, installBase, config, manager, opts);
-			return;
-		}
-		if (opts.cleanup) {
-			await handleCleanup(component, platform, installBase);
-			return;
-		}
-		if (!opts.from && !opts.url) {
-			console.error("Error: provide --from <archive-path> or --url <url> for the upgrade package");
-			process.exit(1);
-		}
-		if (!opts.version) {
-			console.error("Error: --version is required to specify the target version");
+			removeIndexEntry(kiciRoot, {
+				component: "orchestrator",
+				name: config.name
+			});
+			console.log(`\nOrchestrator service "${config.name}" uninstalled.`);
+			console.log(`Manifest preserved at ${resolved.manifestPath} — delete manually if no longer needed.`);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
 			process.exit(1);
 		}
-		const version = opts.version;
-		const versionedDirName = `${component}-${version}`;
-		const versionedDirPath = path.join(installBase, versionedDirName);
-		if (fs.existsSync(versionedDirPath)) if (opts.force) {
-			console.log(`Removing existing directory ${versionedDirPath} (--force)`);
-			fs.rmSync(versionedDirPath, {
-				recursive: true,
-				force: true
+	});
+}
+//#endregion
+//#region src/cli/commands/orchestrator-service/start.ts
+function registerOrchestratorStart(orchestrator) {
+	orchestrator.command("start").description("Start the orchestrator service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--instance-dir <path>", "Deploy folder of the instance to start").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
+		try {
+			const platform = detectPlatform(opts.platform);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "orchestrator",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
 			});
-		} else {
-			console.error(`Error: version directory already exists: ${versionedDirPath}`);
-			console.error("Use --force to overwrite.");
+			const config = {
+				name: resolved.manifest.name,
+				displayName: "KiCI Orchestrator",
+				description: "KiCI CI/CD workflow orchestrator service",
+				executablePath: "",
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "orchestrator"
+			};
+			if (!await manager.isInstalled(config)) {
+				console.error(`Error: service "${config.name}" is not installed.`);
+				console.error(`Run \`kici-admin orchestrator install\` first.`);
+				process.exit(1);
+			}
+			await manager.start(config);
+			console.log(`Orchestrator service "${config.name}" started.`);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
 			process.exit(1);
 		}
-		if (!await manager.isInstalled(config)) {
-			console.error(`Error: service "${opts.name}" is not installed`);
+	});
+}
+//#endregion
+//#region src/cli/commands/orchestrator-service/stop.ts
+function registerOrchestratorStop(orchestrator) {
+	orchestrator.command("stop").description("Stop the orchestrator service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--instance-dir <path>", "Deploy folder of the instance to stop").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
+		try {
+			const platform = detectPlatform(opts.platform);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "orchestrator",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
+			const config = {
+				name: resolved.manifest.name,
+				displayName: "KiCI Orchestrator",
+				description: "KiCI CI/CD workflow orchestrator service",
+				executablePath: "",
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "orchestrator"
+			};
+			await manager.stop(config);
+			console.log(`Orchestrator service "${config.name}" stopped.`);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
 			process.exit(1);
 		}
-		let archivePath;
-		const tmpDir = path.join(os.tmpdir(), `kici-upgrade-${Date.now()}`);
-		fs.mkdirSync(tmpDir, { recursive: true });
-		if (opts.from) {
-			archivePath = path.resolve(opts.from);
-			if (!fs.existsSync(archivePath)) {
-				console.error(`Error: archive not found at ${archivePath}`);
+	});
+}
+//#endregion
+//#region src/cli/commands/orchestrator-service/restart.ts
+function registerOrchestratorRestart(orchestrator) {
+	orchestrator.command("restart").description("Restart the orchestrator service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--instance-dir <path>", "Deploy folder of the instance to restart").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
+		try {
+			const platform = detectPlatform(opts.platform);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "orchestrator",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
+			const config = {
+				name: resolved.manifest.name,
+				displayName: "KiCI Orchestrator",
+				description: "KiCI CI/CD workflow orchestrator service",
+				executablePath: "",
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "orchestrator"
+			};
+			if (!await manager.isInstalled(config)) {
+				console.error(`Error: service "${config.name}" is not installed.`);
+				console.error(`Run \`kici-admin orchestrator install\` first.`);
 				process.exit(1);
 			}
-		} else {
-			const ext = opts.url.endsWith(".zip") ? ".zip" : ".tar.gz";
-			archivePath = path.join(tmpDir, `${component}-${version}${ext}`);
-			await downloadArchive(opts.url, archivePath);
+			await manager.restart(config);
+			console.log(`Orchestrator service "${config.name}" restarted.`);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
 		}
-		const currentVersion = getCurrentVersion(installBase, component, platform);
-		if (!opts.yes) {
-			console.log(`This will upgrade "${opts.name}" to version ${version}:`);
-			if (currentVersion) console.log(`  Current version: ${currentVersion}`);
-			console.log(`  New version: ${version}`);
-			console.log(`  Install path: ${versionedDirPath}`);
-			console.log("  The service will be stopped during upgrade.");
-			console.log("");
-			if (!await confirm$2("Proceed with upgrade?")) {
-				console.log("Upgrade cancelled.");
-				return;
+	});
+}
+//#endregion
+//#region src/cli/commands/orchestrator-service/status.ts
+/** Read the port from the service's env file (path from the manifest). */
+function readPortFromEnvFile$1(envFilePath) {
+	if (!fs.existsSync(envFilePath)) return 4e3;
+	try {
+		const content = fs.readFileSync(envFilePath, "utf-8");
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			if (trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+			const [key, ...rest] = trimmed.split("=");
+			if (key?.trim() === "KICI_PORT") {
+				const val = rest.join("=").trim().replace(/^["']|["']$/g, "");
+				const parsed = parseInt(val, 10);
+				if (!isNaN(parsed)) return parsed;
 			}
 		}
-		console.log("Extracting archive...");
-		const extractDir = path.join(tmpDir, "extract");
-		const extractedDirName = extractArchive(archivePath, extractDir);
-		fs.mkdirSync(installBase, { recursive: true });
-		const srcDir = path.join(extractDir, extractedDirName);
-		if (isWindows(platform)) execSync(`xcopy "${srcDir}" "${versionedDirPath}" /E /I /Q /Y`, { stdio: "inherit" });
-		else execSync(`cp -r "${srcDir}" "${versionedDirPath}"`, { stdio: "inherit" });
-		console.log(`Extracted to ${versionedDirPath}`);
-		console.log("Stopping service...");
-		if ((await manager.status(config)).state === "running") {
-			await manager.stop(config);
-			console.log("Service stopped.");
-		}
-		if (isWindows(platform)) {
-			const launcherPath = path.join(versionedDirPath, getLauncherName(component, platform));
-			config.executablePath = launcherPath;
-			await manager.uninstall(config);
-			await new Promise((r) => setTimeout(r, 2e3));
-			await manager.install(config);
-			writeCurrentVersion(installBase, component, version);
-			console.log(`Service registration updated to ${launcherPath}`);
-		} else {
-			updateSymlinkAtomic(installBase, component, version);
-			const symlinkPath = path.join(installBase, component);
-			console.log(`Symlink updated: ${symlinkPath} -> ${versionedDirName}`);
-			const launcherPath = path.join(symlinkPath, getLauncherName(component, platform));
-			if (fs.existsSync(launcherPath)) fs.chmodSync(launcherPath, 493);
-			config.executablePath = path.join(installBase, component, getLauncherName(component, platform));
-		}
-		console.log("Starting service...");
-		await manager.start(config);
-		console.log("Service started.");
-		fs.rmSync(tmpDir, {
-			recursive: true,
-			force: true
-		});
-		console.log("");
-		if (currentVersion) {
-			console.log(`Upgrade complete: ${currentVersion} -> ${version}`);
-			console.log(`Previous version preserved at: ${path.join(installBase, `${component}-${currentVersion}`)}`);
-		} else console.log(`Upgrade to ${version} complete.`);
-	} catch (err) {
-		console.error(`Error: ${toErrorMessage(err)}`);
-		process.exit(1);
+	} catch {}
+	return 4e3;
+}
+/** Query orchestrator health API. */
+async function queryHealth$1(port) {
+	try {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 3e3);
+		const res = await fetch(`http://localhost:${port}/health`, { signal: controller.signal });
+		clearTimeout(timeout);
+		if (!res.ok) return null;
+		return await res.json();
+	} catch {
+		return null;
 	}
 }
-/**
-* Handle --rollback: switch symlink to the previous version and restart.
-*/
-async function handleRollback(component, platform, installBase, config, manager, opts) {
-	const versions = listInstalledVersions(installBase, component);
-	if (versions.length < 2) {
-		console.error("Error: no previous version available for rollback");
-		if (versions.length === 1) console.error(`Only version installed: ${versions[0]}`);
-		process.exit(1);
-	}
-	const currentVersion = getCurrentVersion(installBase, component, platform);
-	if (!currentVersion) {
-		console.error("Error: cannot determine current version (no symlink found)");
-		console.log("Available versions:");
-		for (const v of versions) console.log(`  ${component}-${v}/`);
-		process.exit(1);
-	}
-	const currentIdx = versions.indexOf(currentVersion);
-	let previousVersion;
-	if (currentIdx > 0) previousVersion = versions[currentIdx - 1];
-	else if (versions.length >= 2) previousVersion = versions[1];
-	else {
-		console.error("Error: no alternative version available for rollback");
-		process.exit(1);
-		return;
-	}
-	if (!opts.yes) {
-		console.log(`Rolling back "${opts.name}":`);
-		console.log(`  Current version: ${currentVersion}`);
-		console.log(`  Rollback to: ${previousVersion}`);
-		console.log("");
-		if (!await confirm$2("Proceed with rollback?")) {
-			console.log("Rollback cancelled.");
-			return;
+/** Format the status output as a readable table. */
+function formatStatus$1(serviceStatus, health, serviceName) {
+	const lines = [];
+	lines.push(`Service: ${serviceName}`);
+	lines.push(`State:   ${serviceStatus.state}`);
+	if (serviceStatus.pid) lines.push(`PID:     ${serviceStatus.pid}`);
+	if (serviceStatus.uptime != null) lines.push(`Uptime:  ${formatUptime(serviceStatus.uptime)}`);
+	if (serviceStatus.startedAt) lines.push(`Started: ${serviceStatus.startedAt}`);
+	if (health) {
+		lines.push("");
+		lines.push("--- KiCI orchestrator ---");
+		if (health.mode) lines.push(`Mode:       ${health.mode}`);
+		if (health.port) lines.push(`Port:       ${health.port}`);
+		if (health.database) lines.push(`Database:   ${health.database}`);
+		if (health.platformRelay) lines.push(`Platform relay: ${health.platformRelay}`);
+		if (health.agents != null) lines.push(`Agents:     ${health.agents}`);
+		if (health.scaler) {
+			const s = health.scaler;
+			lines.push(`Scaler:     ${s.type ?? "none"} (warm: ${s.warm ?? 0}, max: ${s.max ?? 0})`);
 		}
+		if (health.jobs) lines.push(`Jobs:       ${health.jobs.pending ?? 0} pending, ${health.jobs.running ?? 0} running`);
+	} else if (serviceStatus.state === "running") {
+		lines.push("");
+		lines.push("(Could not reach health API)");
 	}
-	console.log("Stopping service...");
-	if ((await manager.status(config)).state === "running") {
-		await manager.stop(config);
-		console.log("Service stopped.");
-	}
-	if (isWindows(platform)) {
-		const launcherPath = path.join(installBase, `${component}-${previousVersion}`, getLauncherName(component, platform));
-		config.executablePath = launcherPath;
-		await manager.uninstall(config);
-		await manager.install(config);
-		writeCurrentVersion(installBase, component, previousVersion);
-		console.log(`Service registration updated to ${launcherPath}`);
-	} else {
-		updateSymlinkAtomic(installBase, component, previousVersion);
-		console.log(`Symlink updated: ${path.join(installBase, component)} -> ${component}-${previousVersion}`);
-	}
-	console.log("Starting service...");
-	await manager.start(config);
-	console.log("Service started.");
-	console.log("");
-	console.log(`Rollback complete: ${currentVersion} -> ${previousVersion}`);
+	return lines.join("\n");
 }
-/**
-* Handle --cleanup: remove all versioned directories except the current
-* and previous versions.
-*/
-async function handleCleanup(component, platform, installBase) {
-	const versions = listInstalledVersions(installBase, component);
-	if (versions.length <= 2) {
-		console.log("Nothing to clean up (2 or fewer versions installed).");
-		return;
-	}
-	const currentVersion = getCurrentVersion(installBase, component, platform);
-	const currentIdx = currentVersion ? versions.indexOf(currentVersion) : versions.length - 1;
-	const previousIdx = currentIdx > 0 ? currentIdx - 1 : -1;
-	const toRemove = versions.filter((_, i) => i !== currentIdx && i !== previousIdx);
-	if (toRemove.length === 0) {
-		console.log("Nothing to clean up.");
-		return;
-	}
-	console.log("The following versions will be removed:");
-	for (const v of toRemove) console.log(`  ${component}-${v}/`);
-	if (currentVersion) console.log(`\nKeeping: ${component}-${currentVersion}/ (current)`);
-	if (previousIdx >= 0) console.log(`Keeping: ${component}-${versions[previousIdx]}/ (previous)`);
-	for (const v of toRemove) {
-		const dirPath = path.join(installBase, `${component}-${v}`);
-		fs.rmSync(dirPath, {
-			recursive: true,
-			force: true
-		});
-		console.log(`Removed ${dirPath}`);
-	}
-	console.log(`\nCleanup complete. Removed ${toRemove.length} old version(s).`);
+/** Build JSON output combining service + health data. */
+function buildJsonOutput$1(serviceStatus, health, serviceName) {
+	return {
+		service: serviceName,
+		...serviceStatus,
+		health: health ?? void 0
+	};
+}
+function registerStatusCommand(parent) {
+	parent.command("status").description("Show orchestrator service status and health information").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--instance-dir <path>", "Deploy folder of the instance to inspect").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").option("--json", "Output as JSON").action(async (opts) => {
+		try {
+			const platform = detectPlatform(opts.platform);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "orchestrator",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
+			const config = {
+				name: resolved.manifest.name,
+				displayName: "KiCI Orchestrator",
+				description: "KiCI CI/CD workflow orchestrator service",
+				executablePath: "",
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "orchestrator"
+			};
+			const serviceStatus = await manager.status(config);
+			let health = null;
+			if (serviceStatus.state === "running") health = await queryHealth$1(readPortFromEnvFile$1(config.envFilePath));
+			if (opts.json) console.log(JSON.stringify(buildJsonOutput$1(serviceStatus, health, config.name), null, 2));
+			else console.log(formatStatus$1(serviceStatus, health, config.name));
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+}
+//#endregion
+//#region src/cli/commands/orchestrator-service/logs.ts
+function registerLogsCommand(parent) {
+	parent.command("logs").description("Tail and follow orchestrator service logs").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--instance-dir <path>", "Deploy folder of the instance whose logs to read").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").option("--since <duration>", "Show logs since duration (e.g. 1h, 30m)").option("--level <level>", "Filter by log level (error|warn|info)").option("--json", "Output as structured JSON").option("--no-follow", "Snapshot mode (do not tail)").action(async (opts) => {
+		try {
+			const platform = detectPlatform(opts.platform);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "orchestrator",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
+			const config = {
+				name: resolved.manifest.name,
+				displayName: "KiCI Orchestrator",
+				description: "KiCI CI/CD workflow orchestrator service",
+				executablePath: "",
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "orchestrator"
+			};
+			const logOptions = {
+				since: opts.since,
+				level: opts.level,
+				json: opts.json,
+				follow: opts.follow
+			};
+			await manager.logs(config, logOptions);
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
 }
 //#endregion
 //#region src/cli/commands/orchestrator-service/upgrade.ts
 function registerUpgradeCommand(parent) {
-	parent.command("upgrade").description("Upgrade orchestrator to a new version using versioned directory layout").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--name <name>", "Service name", "kici-orchestrator").option("--from <path>", "Path to package archive (.tar.gz or .zip)").option("--url <url>", "URL to download package archive from").option("--version <version>", "Target version string (e.g., 0.3.0)").option("--yes", "Skip confirmation prompt").option("--force", "Overwrite existing versioned directory").option("--cleanup", "Remove old versions (keeps current and previous)").option("--rollback", "Roll back to the previous version").action(async (opts) => {
+	parent.command("upgrade").description("Upgrade orchestrator to a new version using versioned directory layout").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--instance-dir <path>", "Deploy folder of the instance to upgrade").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--from <path>", "Path to package archive (.tar.gz or .zip)").option("--url <url>", "URL to download package archive from").option("--version <version>", "Target version string (e.g., 0.3.0)").option("--yes", "Skip confirmation prompt").option("--force", "Overwrite existing versioned directory").option("--cleanup", "Remove old versions (keeps current and previous)").option("--rollback", "Roll back to the previous version").action(async (opts) => {
 		await performVersionedUpgrade("orchestrator", opts);
 	});
 }
@@ -8199,18 +8826,33 @@ var init_agent_wizard = __esmMin((() => {
 //#endregion
 //#region src/cli/commands/agent-service/install.ts
 function registerAgentInstall(agent) {
-	agent.command("install").description("Install the agent as a system service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--env-file <path>", "Path to existing env/config file to use").option("--binary <path>", "Path to agent binary (default: current executable)").option("--name <name>", "Service name", "kici-agent").option("--orchestrator-url <url>", "URL of the orchestrator to connect to").option("--token <token>", "Agent authentication token").option("--labels <labels>", "Comma-separated agent labels for routing").option("--wizard", "Interactive wizard for guided setup").action(async (opts) => {
+	agent.command("install").description("Install the agent as a system service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--env-file <path>", "Path to existing env/config file to use").option("--binary <path>", "Path to agent binary (default: current executable)").option("--name <name>", "Service name", "kici-agent").option("--orchestrator-url <url>", "URL of the orchestrator to connect to").option("--token <token>", "Agent authentication token").option("--labels <labels>", "Comma-separated agent labels for routing").option("--wizard", "Interactive wizard for guided setup").option("--system", "Install as system-level service (requires root)").option("--user-level", "Install as user-level service (no root required)").option("--instance-dir <path>", "Deploy folder; the instance manifest is written here (default: current working directory)").option("--force", "Overwrite an existing same-named foreign instance").action(async (opts) => {
 		try {
 			if (opts.wizard && opts.envFile) {
 				console.error("Error: Cannot use --wizard with --env-file");
 				process.exit(1);
 			}
 			const platform = detectPlatform(opts.platform);
-			const userLevel = !isRoot();
+			const userLevel = resolveUserLevel(opts);
 			const serviceName = opts.name;
+			const instanceDir = path.resolve(opts.instanceDir ?? process.cwd());
+			const kiciRoot = kiciConfigRoot(userLevel);
 			console.log(`Platform: ${platform}`);
 			console.log(`Privilege: ${userLevel ? "user" : "system"}`);
 			console.log(`Service name: ${serviceName}`);
+			console.log(`Instance dir: ${instanceDir}`);
+			const manager = await createServiceManager(platform);
+			const existing = (await listInstances({
+				component: "agent",
+				isUserLevel: userLevel,
+				kiciRoot,
+				manager
+			})).find((c) => c.name === serviceName);
+			if (existing && existing.instanceDir !== instanceDir && !opts.force) {
+				const at = existing.instanceDir ?? "(no manifest)";
+				console.error(`Error: an agent instance "${serviceName}" is already installed at ${at}. Pass a different --name, a different --instance-dir, or --force to overwrite.`);
+				process.exit(1);
+			}
 			const configDir = getConfigDir(serviceName, userLevel);
 			const logDir = getLogDir(serviceName, userLevel);
 			fs.mkdirSync(configDir, { recursive: true });
@@ -8257,12 +8899,37 @@ function registerAgentInstall(agent) {
 				envFilePath,
 				workingDirectory: configDir,
 				isUserLevel: userLevel,
+				component: "agent",
 				restartPolicy: DEFAULT_RESTART_POLICY
 			};
-			await (await createServiceManager(platform)).install(config);
+			await manager.install(config);
+			const manifestFile = writeManifest(instanceDir, {
+				component: "agent",
+				name: serviceName,
+				platform,
+				isUserLevel: userLevel,
+				envFilePath,
+				configDir,
+				logDir,
+				installBase: getInstallBase(platform, serviceName),
+				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+				kiciVersion: readKiciVersion()
+			});
+			try {
+				appendIndexEntry(kiciRoot, {
+					component: "agent",
+					name: serviceName,
+					platform,
+					isUserLevel: userLevel,
+					instanceDir
+				});
+			} catch (err) {
+				console.warn(`Warning: instance index append failed: ${err.message}`);
+			}
 			console.log(`\nAgent service "${serviceName}" installed successfully.`);
-			console.log(`  Config: ${envFilePath}`);
-			console.log(`  Logs:   ${logDir}`);
+			console.log(`  Config:   ${envFilePath}`);
+			console.log(`  Logs:     ${logDir}`);
+			console.log(`  Manifest: ${manifestFile}`);
 			console.log(`\nNext steps:`);
 			console.log(`  1. Edit ${envFilePath} with your configuration`);
 			console.log(`  2. Run \`kici-admin agent start\` to start the service`);
@@ -8275,39 +8942,50 @@ function registerAgentInstall(agent) {
 //#endregion
 //#region src/cli/commands/agent-service/uninstall.ts
 function registerAgentUninstall(agent) {
-	agent.command("uninstall").description("Remove the agent service registration").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--name <name>", "Service name", "kici-agent").action(async (opts) => {
+	agent.command("uninstall").description("Remove the agent service registration").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--instance-dir <path>", "Deploy folder of the instance to uninstall").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
 		try {
 			const platform = detectPlatform(opts.platform);
-			const userLevel = !isRoot();
-			const serviceName = opts.name;
-			const configDir = getConfigDir(serviceName, userLevel);
-			const logDir = getLogDir(serviceName, userLevel);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "agent",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
 			const config = {
-				name: serviceName,
+				name: resolved.manifest.name,
 				displayName: "KiCI Agent",
 				description: "KiCI CI/CD workflow execution agent service",
 				executablePath: "",
-				envFilePath: `${configDir}${serviceName}.env`,
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: DEFAULT_RESTART_POLICY
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "agent"
 			};
-			const manager = await createServiceManager(platform);
-			if (!await manager.isInstalled(config)) {
-				console.log(`Service "${serviceName}" is not installed.`);
-				process.exit(0);
+			if (!await manager.isInstalled(config)) console.log(`Service "${config.name}" is not installed.`);
+			else {
+				try {
+					if ((await manager.status(config)).state === "running") {
+						console.log(`Stopping service "${config.name}"...`);
+						await manager.stop(config);
+					}
+				} catch {}
+				await manager.uninstall(config);
 			}
-			try {
-				if ((await manager.status(config)).state === "running") {
-					console.log(`Stopping service "${serviceName}"...`);
-					await manager.stop(config);
-				}
-			} catch {}
-			await manager.uninstall(config);
-			console.log(`\nAgent service "${serviceName}" uninstalled.`);
-			console.log(`\nThe following files were preserved for manual cleanup:`);
-			console.log(`  Config: ${configDir}`);
-			console.log(`  Logs:   ${logDir}`);
+			removeIndexEntry(kiciRoot, {
+				component: "agent",
+				name: config.name
+			});
+			console.log(`\nAgent service "${config.name}" uninstalled.`);
+			console.log(`Manifest preserved at ${resolved.manifestPath} — delete manually if no longer needed.`);
 		} catch (err) {
 			console.error(`Error: ${toErrorMessage(err)}`);
 			process.exit(1);
@@ -8317,30 +8995,41 @@ function registerAgentUninstall(agent) {
 //#endregion
 //#region src/cli/commands/agent-service/start.ts
 function registerAgentStart(agent) {
-	agent.command("start").description("Start the agent service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--name <name>", "Service name", "kici-agent").action(async (opts) => {
+	agent.command("start").description("Start the agent service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--instance-dir <path>", "Deploy folder of the instance to start").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
 		try {
 			const platform = detectPlatform(opts.platform);
-			const userLevel = !isRoot();
-			const serviceName = opts.name;
-			const configDir = getConfigDir(serviceName, userLevel);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "agent",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
 			const config = {
-				name: serviceName,
+				name: resolved.manifest.name,
 				displayName: "KiCI Agent",
 				description: "KiCI CI/CD workflow execution agent service",
 				executablePath: "",
-				envFilePath: path.join(configDir, `${serviceName}.env`),
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: DEFAULT_RESTART_POLICY
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "agent"
 			};
-			const manager = await createServiceManager(platform);
 			if (!await manager.isInstalled(config)) {
-				console.error(`Error: service "${serviceName}" is not installed.`);
+				console.error(`Error: service "${config.name}" is not installed.`);
 				console.error(`Run \`kici-admin agent install\` first.`);
 				process.exit(1);
 			}
 			await manager.start(config);
-			console.log(`Agent service "${serviceName}" started.`);
+			console.log(`Agent service "${config.name}" started.`);
 		} catch (err) {
 			console.error(`Error: ${toErrorMessage(err)}`);
 			process.exit(1);
@@ -8350,24 +9039,36 @@ function registerAgentStart(agent) {
 //#endregion
 //#region src/cli/commands/agent-service/stop.ts
 function registerAgentStop(agent) {
-	agent.command("stop").description("Stop the agent service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--name <name>", "Service name", "kici-agent").action(async (opts) => {
+	agent.command("stop").description("Stop the agent service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--instance-dir <path>", "Deploy folder of the instance to stop").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
 		try {
 			const platform = detectPlatform(opts.platform);
-			const userLevel = !isRoot();
-			const serviceName = opts.name;
-			const configDir = getConfigDir(serviceName, userLevel);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "agent",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
 			const config = {
-				name: serviceName,
+				name: resolved.manifest.name,
 				displayName: "KiCI Agent",
 				description: "KiCI CI/CD workflow execution agent service",
 				executablePath: "",
-				envFilePath: `${configDir}${serviceName}.env`,
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: DEFAULT_RESTART_POLICY
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "agent"
 			};
-			await (await createServiceManager(platform)).stop(config);
-			console.log(`Agent service "${serviceName}" stopped.`);
+			await manager.stop(config);
+			console.log(`Agent service "${config.name}" stopped.`);
 		} catch (err) {
 			console.error(`Error: ${toErrorMessage(err)}`);
 			process.exit(1);
@@ -8377,30 +9078,41 @@ function registerAgentStop(agent) {
 //#endregion
 //#region src/cli/commands/agent-service/restart.ts
 function registerAgentRestart(agent) {
-	agent.command("restart").description("Restart the agent service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--name <name>", "Service name", "kici-agent").action(async (opts) => {
+	agent.command("restart").description("Restart the agent service").option("--platform <type>", "Service platform (systemd, launchd, windows, compose)").option("--instance-dir <path>", "Deploy folder of the instance to restart").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").action(async (opts) => {
 		try {
 			const platform = detectPlatform(opts.platform);
-			const userLevel = !isRoot();
-			const serviceName = opts.name;
-			const configDir = getConfigDir(serviceName, userLevel);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "agent",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
 			const config = {
-				name: serviceName,
+				name: resolved.manifest.name,
 				displayName: "KiCI Agent",
 				description: "KiCI CI/CD workflow execution agent service",
 				executablePath: "",
-				envFilePath: `${configDir}${serviceName}.env`,
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: DEFAULT_RESTART_POLICY
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "agent"
 			};
-			const manager = await createServiceManager(platform);
 			if (!await manager.isInstalled(config)) {
-				console.error(`Error: service "${serviceName}" is not installed.`);
+				console.error(`Error: service "${config.name}" is not installed.`);
 				console.error(`Run \`kici-admin agent install\` first.`);
 				process.exit(1);
 			}
 			await manager.restart(config);
-			console.log(`Agent service "${serviceName}" restarted.`);
+			console.log(`Agent service "${config.name}" restarted.`);
 		} catch (err) {
 			console.error(`Error: ${toErrorMessage(err)}`);
 			process.exit(1);
@@ -8409,12 +9121,11 @@ function registerAgentRestart(agent) {
 }
 //#endregion
 //#region src/cli/commands/agent-service/status.ts
-/** Read port from agent env file. */
-function readPortFromEnv(configDir, serviceName) {
-	const envPath = path.join(configDir, `${serviceName}.env`);
-	if (!fs.existsSync(envPath)) return 4001;
+/** Read the port from the agent's env file (path from the manifest). */
+function readPortFromEnvFile(envFilePath) {
+	if (!fs.existsSync(envFilePath)) return 4001;
 	try {
-		const content = fs.readFileSync(envPath, "utf-8");
+		const content = fs.readFileSync(envFilePath, "utf-8");
 		for (const line of content.split("\n")) {
 			const trimmed = line.trim();
 			if (trimmed.startsWith("#") || !trimmed.includes("=")) continue;
@@ -8470,36 +9181,39 @@ function buildJsonOutput(serviceStatus, health, serviceName) {
 	};
 }
 function registerAgentStatusCommand(parent) {
-	parent.command("status").description("Show agent service status and health information").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--name <name>", "Service name", "kici-agent").option("--json", "Output as JSON").action(async (opts) => {
+	parent.command("status").description("Show agent service status and health information").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--instance-dir <path>", "Deploy folder of the instance to inspect").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").option("--json", "Output as JSON").action(async (opts) => {
 		try {
-			const manager = await createServiceManager(detectPlatform(opts.platform));
-			const userLevel = !isRoot();
-			const configDir = getConfigDir(opts.name, userLevel);
+			const platform = detectPlatform(opts.platform);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "agent",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
 			const config = {
-				name: opts.name,
-				displayName: "KiCI agent",
-				description: "KiCI agent service",
+				name: resolved.manifest.name,
+				displayName: "KiCI Agent",
+				description: "KiCI CI/CD workflow execution agent service",
 				executablePath: "",
-				envFilePath: path.join(configDir, `${opts.name}.env`),
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: {
-					enabled: true,
-					delays: [
-						1,
-						5,
-						15,
-						30
-					],
-					maxRetries: 5,
-					windowSeconds: 300
-				}
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "agent"
 			};
 			const serviceStatus = await manager.status(config);
 			let health = null;
-			if (serviceStatus.state === "running") health = await queryHealth(readPortFromEnv(configDir, opts.name));
-			if (opts.json) console.log(JSON.stringify(buildJsonOutput(serviceStatus, health, opts.name), null, 2));
-			else console.log(formatStatus(serviceStatus, health, opts.name));
+			if (serviceStatus.state === "running") health = await queryHealth(readPortFromEnvFile(config.envFilePath));
+			if (opts.json) console.log(JSON.stringify(buildJsonOutput(serviceStatus, health, config.name), null, 2));
+			else console.log(formatStatus(serviceStatus, health, config.name));
 		} catch (err) {
 			console.error(`Error: ${toErrorMessage(err)}`);
 			process.exit(1);
@@ -8509,30 +9223,33 @@ function registerAgentStatusCommand(parent) {
 //#endregion
 //#region src/cli/commands/agent-service/logs.ts
 function registerAgentLogsCommand(parent) {
-	parent.command("logs").description("Tail and follow agent service logs").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--name <name>", "Service name", "kici-agent").option("--since <duration>", "Show logs since duration (e.g. 1h, 30m)").option("--level <level>", "Filter by log level (error|warn|info)").option("--json", "Output as structured JSON").option("--no-follow", "Snapshot mode (do not tail)").action(async (opts) => {
+	parent.command("logs").description("Tail and follow agent service logs").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--instance-dir <path>", "Deploy folder of the instance whose logs to read").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--system", "Operate against the system-level service (requires root)").option("--user-level", "Operate against the user-level service").option("--since <duration>", "Show logs since duration (e.g. 1h, 30m)").option("--level <level>", "Filter by log level (error|warn|info)").option("--json", "Output as structured JSON").option("--no-follow", "Snapshot mode (do not tail)").action(async (opts) => {
 		try {
-			const manager = await createServiceManager(detectPlatform(opts.platform));
-			const userLevel = !isRoot();
-			const configDir = getConfigDir(opts.name, userLevel);
+			const platform = detectPlatform(opts.platform);
+			const userLevel = resolveUserLevel(opts);
+			const manager = await createServiceManager(platform);
+			const kiciRoot = kiciConfigRoot(userLevel);
+			const resolved = await resolveInstance({
+				component: "agent",
+				opts: {
+					instanceDir: opts.instanceDir,
+					name: opts.name
+				},
+				cwd: process.cwd(),
+				kiciRoot,
+				manager,
+				isUserLevel: userLevel
+			});
 			const config = {
-				name: opts.name,
-				displayName: "KiCI agent",
-				description: "KiCI agent service",
+				name: resolved.manifest.name,
+				displayName: "KiCI Agent",
+				description: "KiCI CI/CD workflow execution agent service",
 				executablePath: "",
-				envFilePath: path.join(configDir, `${opts.name}.env`),
-				workingDirectory: configDir,
-				isUserLevel: userLevel,
-				restartPolicy: {
-					enabled: true,
-					delays: [
-						1,
-						5,
-						15,
-						30
-					],
-					maxRetries: 5,
-					windowSeconds: 300
-				}
+				envFilePath: resolved.manifest.envFilePath,
+				workingDirectory: resolved.manifest.configDir,
+				isUserLevel: resolved.manifest.isUserLevel,
+				restartPolicy: DEFAULT_RESTART_POLICY,
+				component: "agent"
 			};
 			const logOptions = {
 				since: opts.since,
@@ -8550,7 +9267,7 @@ function registerAgentLogsCommand(parent) {
 //#endregion
 //#region src/cli/commands/agent-service/upgrade.ts
 function registerAgentUpgradeCommand(parent) {
-	parent.command("upgrade").description("Upgrade agent to a new version using versioned directory layout").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--name <name>", "Service name", "kici-agent").option("--from <path>", "Path to package archive (.tar.gz or .zip)").option("--url <url>", "URL to download package archive from").option("--version <version>", "Target version string (e.g., 0.3.0)").option("--yes", "Skip confirmation prompt").option("--force", "Overwrite existing versioned directory").option("--cleanup", "Remove old versions (keeps current and previous)").option("--rollback", "Roll back to the previous version").action(async (opts) => {
+	parent.command("upgrade").description("Upgrade agent to a new version using versioned directory layout").option("--platform <type>", "Service platform (systemd|launchd|windows|compose)").option("--instance-dir <path>", "Deploy folder of the instance to upgrade").option("--name <name>", "Service name (no default — must resolve via flag/CWD)").option("--from <path>", "Path to package archive (.tar.gz or .zip)").option("--url <url>", "URL to download package archive from").option("--version <version>", "Target version string (e.g., 0.3.0)").option("--yes", "Skip confirmation prompt").option("--force", "Overwrite existing versioned directory").option("--cleanup", "Remove old versions (keeps current and previous)").option("--rollback", "Roll back to the previous version").action(async (opts) => {
 		await performVersionedUpgrade("agent", opts);
 	});
 }