@kici-dev/orchestrator 0.1.11 → 0.1.13

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";
@@ -6092,7 +6092,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 +6101,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 +6116,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,6 +6182,221 @@ function resolveUserLevel(opts) {
 	return !isRoot();
 }
 //#endregion
+//#region src/cli/service/instance/manifest.ts
+/**
+* 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.
+*/
+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));
+}
+/**
+* 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;
+}
+//#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.
@@ -6215,6 +6454,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 +6591,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 +6621,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 +6678,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 +6763,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 +6886,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 +7207,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 +7299,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 +7352,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 +7399,7 @@ function getRestartMode(config) {
 */
 function generateComposeYaml(config) {
 	const restartMode = getRestartMode(config);
-	return [
+	const lines = [
 		"# Generated by KiCI service installer",
 		`# Service: ${config.displayName}`,
 		"",
@@ -7043,20 +7413,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 +7459,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 +7483,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,976 +7585,1114 @@ 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
-* 4. Secrets encryption key
-* 5. Bootstrap admin token (for kici-admin authentication)
-* 6. Platform URL + token (if platform/hybrid mode)
-* 7. Webhook secret (if hybrid/independent mode)
+* Extract an archive (.tar.gz or .zip) to a destination directory.
+* Returns the name of the top-level directory inside the archive.
 */
-async function runOrchestratorWizard() {
-	console.log("");
-	console.log("KiCI orchestrator setup wizard");
-	console.log("==============================");
-	console.log("");
-	const mode = await promptSelect("Operating mode:", [
-		{
-			name: "Platform relay (recommended)",
-			value: "platform",
-			description: "Connect to KiCI Platform for webhook routing"
-		},
-		{
-			name: "Hybrid",
-			value: "hybrid",
-			description: "Platform relay + direct webhooks"
-		},
-		{
-			name: "Independent",
-			value: "independent",
-			description: "Self-hosted, no Platform dependency"
-		}
-	], "platform");
-	console.log("");
-	const databaseUrl = await promptDbUrl();
-	const port = await promptPort(4e3);
-	console.log("");
-	const generatedKey = randomBytes(32).toString("hex");
-	console.log(`Generated secrets key: ${generatedKey}`);
-	const useGenerated = await promptConfirm("Use this key?");
-	let secretsKey;
-	if (useGenerated) secretsKey = generatedKey;
-	else secretsKey = await promptSecret("Enter custom secrets encryption key (64 hex chars):");
-	console.log("");
-	const generatedAdminToken = randomBytes(32).toString("hex");
-	console.log(`Generated bootstrap admin token: ${generatedAdminToken}`);
-	const useGeneratedAdminToken = await promptConfirm("Use this token?");
-	let bootstrapAdminToken;
-	if (useGeneratedAdminToken) bootstrapAdminToken = generatedAdminToken;
-	else bootstrapAdminToken = await promptSecret("Enter custom bootstrap admin token:");
-	let platformUrl;
-	let platformToken;
-	if (mode === "platform" || mode === "hybrid") {
-		console.log("");
-		platformUrl = await promptUrl("Platform relay URL:", "wss://platform.kici.dev");
-		platformToken = await promptSecret("Platform authentication token:");
-	}
-	let source;
-	console.log("");
-	if (await promptConfirm("Add a GitHub App source?", false)) {
-		const sourceName = await input({ message: "Source name (e.g. main-org):" });
-		const appId = await input({
-			message: "GitHub App ID:",
-			validate: (v) => /^\d+$/.test(v.trim()) ? true : "Must be a numeric App ID"
-		});
-		const privateKeyPath = await input({
-			message: "Path to private key file (.pem):",
-			validate: (v) => v.trim() ? true : "Path is required"
-		});
-		const sourceWebhookSecret = await promptSecret("Webhook secret:");
-		let privateKey;
-		try {
-			privateKey = (await readFile(privateKeyPath.trim(), "utf-8")).trim();
-		} catch (err) {
-			throw new Error(`Failed to read private key from ${privateKeyPath}: ${err}`);
-		}
-		source = {
-			provider: "github",
-			name: sourceName.trim(),
-			appId: appId.trim(),
-			privateKey,
-			webhookSecret: sourceWebhookSecret
-		};
-	}
-	console.log("");
-	console.log("Configuration complete. Summary:");
-	console.log(`  Mode:     ${mode}`);
-	console.log(`  Database: ${databaseUrl.replace(/:[^@]*@/, ":***@")}`);
-	console.log(`  Port:     ${port}`);
-	console.log(`  Admin token: ${bootstrapAdminToken.slice(0, 8)}…`);
-	console.log(`  Platform:     ${platformUrl ?? "N/A"}`);
-	if (source) console.log(`  Source:   ${source.provider}:${source.appId} (${source.name})`);
-	console.log("");
-	return {
-		mode,
-		databaseUrl,
-		port,
-		secretsKey,
-		bootstrapAdminToken,
-		platformUrl,
-		platformToken,
-		source
-	};
+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];
 }
-var init_orchestrator_wizard = __esmMin((() => {
-	init_prompts();
-}));
-//#endregion
-//#region src/cli/commands/orchestrator-service/install.ts
 /**
-* Spin up a dev PostgreSQL container using Docker or Podman.
-* Returns the DATABASE_URL for the container.
+* List installed versions for a component by scanning the install base directory
+* for directories matching `{component}-{version}/`.
 */
-function startDevPostgres(containerName) {
-	const password = crypto.randomBytes(16).toString("hex");
-	const port = 15432;
-	let runtime = "podman";
-	try {
-		execSync("podman --version", { stdio: "ignore" });
-	} catch {
-		runtime = "docker";
+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 {
-			execSync("docker --version", { stdio: "ignore" });
+			return fs.readFileSync(versionFile, "utf-8").trim();
 		} catch {
-			throw new Error("Neither podman nor docker found. Install one to use --dev mode.");
+			return null;
 		}
 	}
+	const symlinkPath = path.join(installBase, component);
 	try {
-		if (execSync(`${runtime} ps -a --filter name=${containerName} --format "{{.Names}}"`, { encoding: "utf-8" }).trim()) {
-			console.log(`Dev PostgreSQL container "${containerName}" already exists.`);
-			console.log(`Remove it with: ${runtime} rm -f ${containerName}`);
-			throw new Error(`Container "${containerName}" already exists`);
-		}
+		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) {
-		if (err instanceof Error && err.message.includes("already exists")) throw err;
+		try {
+			fs.unlinkSync(tmpLink);
+		} catch {}
+		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" });
-	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) => {
-		try {
-			if (opts.wizard && opts.envFile) {
-				console.error("Error: Cannot use --wizard with --env-file");
+/**
+* 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);
 			}
-			const platform = detectPlatform(opts.platform);
-			const userLevel = resolveUserLevel(opts);
-			const serviceName = opts.name;
-			console.log(`Platform: ${platform}`);
-			console.log(`Privilege: ${userLevel ? "user" : "system"}`);
-			console.log(`Service name: ${serviceName}`);
-			const configDir = getConfigDir(serviceName, userLevel);
-			const logDir = getLogDir(serviceName, userLevel);
-			fs.mkdirSync(configDir, { recursive: true });
-			fs.mkdirSync(logDir, { recursive: true });
-			const envFilePath = path.join(configDir, `${serviceName}.env`);
-			let devDbUrl;
-			if (opts.dev) {
-				devDbUrl = startDevPostgres(`${serviceName}-dev-pg`);
-				console.log(`Dev PostgreSQL URL: ${devDbUrl}`);
-			}
-			if (opts.wizard) {
-				const { runOrchestratorWizard } = await Promise.resolve().then(() => (init_orchestrator_wizard(), orchestrator_wizard_exports));
-				const wizardConfig = await runOrchestratorWizard();
-				let envContent = "# KiCI orchestrator configuration (generated by setup wizard)\n";
-				envContent += `KICI_MODE=${wizardConfig.mode}\n`;
-				envContent += `KICI_DATABASE_URL=${wizardConfig.databaseUrl}\n`;
-				envContent += `KICI_PORT=${wizardConfig.port}\n`;
-				envContent += `KICI_SECRET_KEY=${wizardConfig.secretsKey}\n`;
-				envContent += `KICI_BOOTSTRAP_ADMIN_TOKEN=${wizardConfig.bootstrapAdminToken}\n`;
-				if (wizardConfig.platformUrl) envContent += `KICI_PLATFORM_URL=${wizardConfig.platformUrl}\n`;
-				if (wizardConfig.platformToken) envContent += `KICI_PLATFORM_TOKEN=${wizardConfig.platformToken}\n`;
-				fs.writeFileSync(envFilePath, envContent, "utf-8");
-				console.log(`Wrote wizard configuration to ${envFilePath}`);
-			} else if (opts.envFile) {
-				const source = path.resolve(opts.envFile);
-				if (!fs.existsSync(source)) {
-					console.error(`Error: env file not found: ${source}`);
-					process.exit(1);
-				}
-				fs.copyFileSync(source, envFilePath);
-				console.log(`Copied env file to ${envFilePath}`);
-			} else if (!fs.existsSync(envFilePath)) {
-				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}`);
+		} 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;
 			}
-			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);
 		}
-	});
+		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/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);
+//#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);
 }
-//#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);
-		}
+/** Prompt for a yes/no confirmation. */
+async function promptConfirm(message, defaultValue = true) {
+	return confirm({
+		message,
+		default: defaultValue
 	});
 }
-//#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);
-			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
-			};
-			await (await createServiceManager(platform)).stop(config);
-			console.log(`Orchestrator service "${serviceName}" stopped.`);
-		} catch (err) {
-			console.error(`Error: ${toErrorMessage(err)}`);
-			process.exit(1);
+/** 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;
 		}
 	});
 }
-//#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 = {
-				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.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);
+/** 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/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;
-			}
+//#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)
+* 7. Webhook secret (if hybrid/independent mode)
+*/
+async function runOrchestratorWizard() {
+	console.log("");
+	console.log("KiCI orchestrator setup wizard");
+	console.log("==============================");
+	console.log("");
+	const mode = await promptSelect("Operating mode:", [
+		{
+			name: "Platform relay (recommended)",
+			value: "platform",
+			description: "Connect to KiCI Platform for webhook routing"
+		},
+		{
+			name: "Hybrid",
+			value: "hybrid",
+			description: "Platform relay + direct webhooks"
+		},
+		{
+			name: "Independent",
+			value: "independent",
+			description: "Self-hosted, no Platform dependency"
 		}
-	} 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;
+	], "platform");
+	console.log("");
+	const databaseUrl = await promptDbUrl();
+	const port = await promptPort(4e3);
+	console.log("");
+	const generatedKey = randomBytes(32).toString("hex");
+	console.log(`Generated secrets key: ${generatedKey}`);
+	const useGenerated = await promptConfirm("Use this key?");
+	let secretsKey;
+	if (useGenerated) secretsKey = generatedKey;
+	else secretsKey = await promptSecret("Enter custom secrets encryption key (64 hex chars):");
+	console.log("");
+	const generatedAdminToken = randomBytes(32).toString("hex");
+	console.log(`Generated bootstrap admin token: ${generatedAdminToken}`);
+	const useGeneratedAdminToken = await promptConfirm("Use this token?");
+	let bootstrapAdminToken;
+	if (useGeneratedAdminToken) bootstrapAdminToken = generatedAdminToken;
+	else bootstrapAdminToken = await promptSecret("Enter custom bootstrap admin token:");
+	let platformUrl;
+	let platformToken;
+	if (mode === "platform" || mode === "hybrid") {
+		console.log("");
+		platformUrl = await promptUrl("Platform relay URL:", "wss://platform.kici.dev");
+		platformToken = await promptSecret("Platform authentication token:");
 	}
-}
-/** 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})`);
+	let source;
+	console.log("");
+	if (await promptConfirm("Add a GitHub App source?", false)) {
+		const sourceName = await input({ message: "Source name (e.g. main-org):" });
+		const appId = await input({
+			message: "GitHub App ID:",
+			validate: (v) => /^\d+$/.test(v.trim()) ? true : "Must be a numeric App ID"
+		});
+		const privateKeyPath = await input({
+			message: "Path to private key file (.pem):",
+			validate: (v) => v.trim() ? true : "Path is required"
+		});
+		const sourceWebhookSecret = await promptSecret("Webhook secret:");
+		let privateKey;
+		try {
+			privateKey = (await readFile(privateKeyPath.trim(), "utf-8")).trim();
+		} catch (err) {
+			throw new Error(`Failed to read private key from ${privateKeyPath}: ${err}`);
 		}
-		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)");
+		source = {
+			provider: "github",
+			name: sourceName.trim(),
+			appId: appId.trim(),
+			privateKey,
+			webhookSecret: sourceWebhookSecret
+		};
 	}
-	return lines.join("\n");
-}
-/** Build JSON output combining service + health data. */
-function buildJsonOutput$1(serviceStatus, health, serviceName) {
+	console.log("");
+	console.log("Configuration complete. Summary:");
+	console.log(`  Mode:     ${mode}`);
+	console.log(`  Database: ${databaseUrl.replace(/:[^@]*@/, ":***@")}`);
+	console.log(`  Port:     ${port}`);
+	console.log(`  Admin token: ${bootstrapAdminToken.slice(0, 8)}…`);
+	console.log(`  Platform:     ${platformUrl ?? "N/A"}`);
+	if (source) console.log(`  Source:   ${source.provider}:${source.appId} (${source.name})`);
+	console.log("");
 	return {
-		service: serviceName,
-		...serviceStatus,
-		health: health ?? void 0
+		mode,
+		databaseUrl,
+		port,
+		secretsKey,
+		bootstrapAdminToken,
+		platformUrl,
+		platformToken,
+		source
 	};
 }
-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) => {
+var init_orchestrator_wizard = __esmMin((() => {
+	init_prompts();
+}));
+//#endregion
+//#region src/cli/commands/orchestrator-service/install.ts
+/**
+* Spin up a dev PostgreSQL container using Docker or Podman.
+* Returns the DATABASE_URL for the container.
+*/
+function startDevPostgres(containerName) {
+	const password = crypto.randomBytes(16).toString("hex");
+	const port = 15432;
+	let runtime = "podman";
+	try {
+		execSync("podman --version", { stdio: "ignore" });
+	} catch {
+		runtime = "docker";
 		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);
+			execSync("docker --version", { stdio: "ignore" });
+		} catch {
+			throw new Error("Neither podman nor docker found. Install one to use --dev mode.");
 		}
-	});
+	}
+	try {
+		if (execSync(`${runtime} ps -a --filter name=${containerName} --format "{{.Names}}"`, { encoding: "utf-8" }).trim()) {
+			console.log(`Dev PostgreSQL container "${containerName}" already exists.`);
+			console.log(`Remove it with: ${runtime} rm -f ${containerName}`);
+			throw new Error(`Container "${containerName}" already exists`);
+		}
+	} catch (err) {
+		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" });
+	return `postgresql://postgres:${password}@localhost:${port}/kici`;
 }
-//#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) => {
+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)").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 {
-			const manager = await createServiceManager(detectPlatform(opts.platform));
-			const userLevel = !isRoot();
-			const configDir = getConfigDir(opts.name, userLevel);
+			if (opts.wizard && opts.envFile) {
+				console.error("Error: Cannot use --wizard with --env-file");
+				process.exit(1);
+			}
+			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 });
+			fs.mkdirSync(logDir, { recursive: true });
+			const envFilePath = path.join(configDir, `${serviceName}.env`);
+			let devDbUrl;
+			if (opts.dev) {
+				devDbUrl = startDevPostgres(`${serviceName}-dev-pg`);
+				console.log(`Dev PostgreSQL URL: ${devDbUrl}`);
+			}
+			if (opts.wizard) {
+				const { runOrchestratorWizard } = await Promise.resolve().then(() => (init_orchestrator_wizard(), orchestrator_wizard_exports));
+				const wizardConfig = await runOrchestratorWizard();
+				let envContent = "# KiCI orchestrator configuration (generated by setup wizard)\n";
+				envContent += `KICI_MODE=${wizardConfig.mode}\n`;
+				envContent += `KICI_DATABASE_URL=${wizardConfig.databaseUrl}\n`;
+				envContent += `KICI_PORT=${wizardConfig.port}\n`;
+				envContent += `KICI_SECRET_KEY=${wizardConfig.secretsKey}\n`;
+				envContent += `KICI_BOOTSTRAP_ADMIN_TOKEN=${wizardConfig.bootstrapAdminToken}\n`;
+				if (wizardConfig.platformUrl) envContent += `KICI_PLATFORM_URL=${wizardConfig.platformUrl}\n`;
+				if (wizardConfig.platformToken) envContent += `KICI_PLATFORM_TOKEN=${wizardConfig.platformToken}\n`;
+				fs.writeFileSync(envFilePath, envContent, "utf-8");
+				console.log(`Wrote wizard configuration to ${envFilePath}`);
+			} else if (opts.envFile) {
+				const source = path.resolve(opts.envFile);
+				if (!fs.existsSync(source)) {
+					console.error(`Error: env file not found: ${source}`);
+					process.exit(1);
+				}
+				fs.copyFileSync(source, envFilePath);
+				console.log(`Copied env file to ${envFilePath}`);
+			} else if (!fs.existsSync(envFilePath)) {
+				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: opts.name,
-				displayName: "KiCI orchestrator",
-				description: "KiCI orchestrator service",
-				executablePath: "",
-				envFilePath: path.join(configDir, `${opts.name}.env`),
+				name: serviceName,
+				displayName: "KiCI Orchestrator",
+				description: "KiCI CI/CD workflow orchestrator service",
+				executablePath,
+				args,
+				nodeBinDir: path.dirname(process.execPath),
+				envFilePath,
 				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
+				user: opts.user,
+				component: "orchestrator",
+				restartPolicy: DEFAULT_RESTART_POLICY
 			};
-			await manager.logs(config, logOptions);
+			await manager.install(config);
+			const manifestFile = writeManifest(instanceDir, {
+				component: "orchestrator",
+				name: serviceName,
+				platform,
+				isUserLevel: userLevel,
+				envFilePath,
+				configDir,
+				logDir,
+				installBase: getInstallBase(platform, serviceName),
+				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+				kiciVersion: process.env.npm_package_version ?? "unknown"
+			});
+			try {
+				appendIndexEntry(kiciRoot, {
+					component: "orchestrator",
+					name: serviceName,
+					platform,
+					isUserLevel: userLevel,
+					instanceDir
+				});
+			} catch (err) {
+				console.warn(`Warning: instance index append failed: ${err.message}`);
+			}
+			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 +8750,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 +8823,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: process.env.npm_package_version ?? "unknown"
+			});
+			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 +8866,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 +8919,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 +8963,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 +9002,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 +9045,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 +9105,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 +9147,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 +9191,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);
 	});
 }