@kici-dev/orchestrator 0.11.0 → 0.12.0

package/dist/cli.js

@@ -6,7 +6,7 @@ import path, { dirname, join, resolve } from "node:path";
 import * as fs$1 from "node:fs";
 import fs, { chmodSync, closeSync, constants, createReadStream, createWriteStream, existsSync, mkdirSync, mkdtempSync, openSync, promises, readFileSync, realpathSync, rmSync, statSync, unwatchFile, watchFile, writeFileSync } from "node:fs";
 import { Command, Option } from "commander";
-import { AgentPlatform, BaseColdStore, ChunkLru, addLogsToArchive, chunkObjectKey, clearDispatchQueueDirect, computeChunkId, computeMigrationsHash, createContextTemplateDirect, createDb, createDbRole, createLogger, createPool, createReadOnlyDbUser, createS3Client, decodeChunk, decrypt, deleteContextDirect, deriveKey, diagnoseExitCode, dropAndCreateDatabase, emitKiciEventDirect, encodeKeySegment, encrypt, ensureDatabase, formatBytes, formatUptime, isSchemaCurrent, kiciMkdtemp, listCheckRunTrackingDirect, listContextsDirect, listExecutionRunsDirect, listQueueDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, parseManifest, prunePeerCredentialsDirect, purgeContextsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, registerWorkflowManualDirect, resetRaftStateDirect, seedContextBindingDirect, seedContextDirect, serializeError, setContextPolicyDirect, setContextSecretDirect, sha256, showContextDirect, showExecutionRunDirect, showQueueEntryDirect, showRegistrationDirect, splitAgentPlatform, storeMigrationContentHash, tablePrefix, toErrorMessage } from "@kici-dev/shared";
+import { AgentPlatform, BaseColdStore, ChunkLru, ReadinessStatus, addLogsToArchive, chunkObjectKey, clearDispatchQueueDirect, computeChunkId, computeMigrationsHash, createContextTemplateDirect, createDb, createDbRole, createLogger, createPool, createReadOnlyDbUser, createS3Client, decodeChunk, decrypt, deleteContextDirect, deriveKey, diagnoseExitCode, dropAndCreateDatabase, emitKiciEventDirect, encodeKeySegment, encrypt, ensureDatabase, formatBytes, formatUptime, isSchemaCurrent, kiciMkdtemp, listCheckRunTrackingDirect, listContextsDirect, listExecutionRunsDirect, listQueueDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, parseManifest, prunePeerCredentialsDirect, purgeContextsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, registerWorkflowManualDirect, resetRaftStateDirect, seedContextBindingDirect, seedContextDirect, serializeError, setContextPolicyDirect, setContextSecretDirect, sha256, showContextDirect, showExecutionRunDirect, showQueueEntryDirect, showRegistrationDirect, splitAgentPlatform, storeMigrationContentHash, tablePrefix, toErrorMessage } from "@kici-dev/shared";
 import { AccessLogSource, ApprovalDecision, CiTrustLevel, ContextType, ExecutionJobStatus, ForkPolicy, HoldType, KICI_AGENT_ENV_PREFIX, KNOWN_ROLES, MIN_APPROVAL_EXPIRY_SECONDS, MinimumTrustSchema, OrchestratorMode, PLATFORM_CONNECTED_MODES, PRIVILEGED_ROOT_LABEL, RuntimeFact, SECONDS_PER_HOUR, ScalerBackendType, ScalerEventType, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES, WS_MAX_PAYLOAD_BYTES, accessLogWarmSqlCase, agentLabelOf, assertValidSecretKey, attestationVerifyStatusSchema, canonicalizeLabel, canonicalizeLabels, canonicalizeMatcher, derivePlatformTaints, flattenActor, getAccessLogColdDays, getSecretAuditLogColdDays, matcherSatisfiedBy, minAccessLogWarmDays, minSecretAuditLogWarmDays, parseHostPropertyAssignments, platformToTaints, resolveHeldRunId, resolveRoleLabels, runtimeLabel, scalerAgentLabels, scalerPlatformSchema, secretAuditLogWarmSqlCase, shouldRecordAccess, shouldRecordSecretResolve } from "@kici-dev/engine";
 import crypto$1, { createDecipheriv, createHash, createHmac, createPublicKey, generateKeyPairSync, hkdfSync, randomBytes, randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
@@ -14,17 +14,18 @@ import { sql } from "kysely";
 import { access, chmod, constants as constants$1, copyFile, link, mkdir, open, readFile, readdir, readlink, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { parse } from "yaml";
 import { z } from "zod";
+import { AGENT_DEFAULT_PORT, LOGGER_ENV_VARS, ORCHESTRATOR_DEFAULT_PORT, defineEnv, validateUnknownKiciVars } from "@kici-dev/shared/env";
 import os, { hostname, platform, tmpdir, uptime, default as os$1 } from "node:os";
 import { getDatabaseCollationDrift, refreshDatabaseCollationVersion, reindexDatabaseConcurrently } from "@kici-dev/shared/db-collation";
 import { Migrator } from "kysely/migration";
 import { exec, execFile, execFileSync, execSync, spawn, spawnSync } from "node:child_process";
 import { promisify } from "node:util";
+import { SERVICE_ENV_FILE_VAR } from "@kici-dev/shared/service-env-file";
 import "jsonpath-plus";
 import { makeTempDir, withTempDir } from "@kici-dev/shared/tmp";
 import { Octokit } from "@octokit/rest";
 import { createAppAuth } from "@octokit/auth-app";
 import http, { createServer } from "node:http";
-import { LOGGER_ENV_VARS, defineEnv, validateUnknownKiciVars } from "@kici-dev/shared/env";
 import { CopyObjectCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
 import { Upload } from "@aws-sdk/lib-storage";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
@@ -43,6 +44,7 @@ import { CLI_INDEPENDENT_ONLY_OPERATIONS, DASHBOARD_WRITE_OPERATIONS, DASHBOARD_
 import { CLUSTER_NAME_FORMAT_MESSAGE } from "@kici-dev/engine/protocol/cluster-name";
 import { BASELINE_CHAIN, JOB_NETWORK_SUBNET, METADATA_RANGE, RFC1918_RANGES, addHostIsolationRules, addIsolationRules, deleteForwardRules, ensureKiciTable, listForwardRules, listIsolationRules, parseHostAccess, parseRuleHandles, readForwardChain, removeIsolationRules, validateNftablesAvailability } from "@kici-dev/shared/net";
 import { ImagePullPolicy, ensureRuntimeVolume, injectedAgentCommand, pullImageIfMissing, runtimeInjectBind } from "@kici-dev/shared/container-runtime";
+import { isIP } from "node:net";
 import { StringDecoder } from "node:string_decoder";
 import { PassThrough } from "node:stream";
 import Docker from "dockerode";
@@ -1025,13 +1027,13 @@ var PgSecretStore = class PgSecretStore {
 //#endregion
 //#region src/cold-store/load-access-log-range.ts
 /**
-* Read-through helper for `access_log` (Orchestrator) — Phase D.
+* Read-through helper for `access_log` (Orchestrator).
 *
 * Unlike `audit_log` and `secret_audit_log`, the `access_log` callers
 * (dashboard "Data access" tab, admin HTTP route, `kici-admin
 * access-log list` CLI) all use the same cursor-based pagination
-* already implemented by `AccessLogWriter.query()`. Phase D's design
-* §7 row 11 classifies access_log as "paginated/transparent" — there
+* already implemented by `AccessLogWriter.query()`. access_log is
+* "paginated/transparent" — there
 * is NO `--include-archived` flag. The helper merges cold rows
 * automatically when pagination crosses the warm cutoff or the caller
 * supplies a `from` timestamp older than warm.
@@ -1211,9 +1213,9 @@ var init_load_access_log_range = __esmMin((() => {
 //#endregion
 //#region src/cold-store/load-secret-audit-log-range.ts
 /**
-* Read-through helper for `secret_audit_log` (Orchestrator) — Phase D.
+* Read-through helper for `secret_audit_log` (Orchestrator).
 *
-* Mirrors the Phase B/C reader pattern. Wraps `AuditLogger.query()`'s
+* Mirrors the execution-table reader pattern. Wraps `AuditLogger.query()`'s
 * existing offset/limit shape; cold-store rows are fetched only when
 * `includeArchived === true`.
 *
@@ -2306,7 +2308,7 @@ var init_schema = __esmMin((() => {
 		instanceId: z.string().default(() => randomUUID()),
 		mode: OrchestratorMode.default("platform"),
 		databaseUrl: z.string().default(""),
-		port: z.coerce.number().default(4e3),
+		port: z.coerce.number().default(ORCHESTRATOR_DEFAULT_PORT),
 		basePath: z.string().default("/"),
 		tlsCertPath: z.string().optional(),
 		scalerConfigPath: z.string().optional(),
@@ -3743,12 +3745,10 @@ var _005_cold_store_chunk_counter_exports = /* @__PURE__ */ __exportAll({
 * `kici-admin cold-store list-chunks` CLI can report totals without
 * issuing S3 LIST calls (expensive + rate-limited).
 *
-* Phase A creates the table empty; the cold-store archiver
-* (Phase B+) updates it transactionally with every successful chunk
+* The table starts empty; the cold-store archiver
+* updates it transactionally with every successful chunk
 * write via `INSERT ... ON CONFLICT (db, table_name, tenant_id) DO
 * UPDATE SET chunk_count = chunk_count + EXCLUDED.chunk_count, ...`.
-*
-* sections 5 and 8.
 */
 async function up$146(db) {
 	await sql`
@@ -3781,12 +3781,12 @@ var _006_runs_jobs_steps_archived_at_exports = /* @__PURE__ */ __exportAll({
 * `execution_runs` / `execution_jobs` / `execution_steps` cold-store
 * schema additions.
 *
-* Phase C of the cold-storage archival system. See
+* Part of the cold-storage archival system.
 *
 * Each table gets `archived_at TIMESTAMPTZ NULL` and
 * `archive_object_key TEXT NULL` (set inside the archive tx before the
-* DELETE; survivors carry NULL — same pattern as Phase B's migration
-* 004 for `run_events`).
+* DELETE; survivors carry NULL — the same pattern `run_events` carries
+* in the Platform's schema).
 *
 * Tenant column denormalization: the orchestrator side partitions by
 * `routing_key`, but only `execution_runs` carries the column today.
@@ -3795,7 +3795,7 @@ var _006_runs_jobs_steps_archived_at_exports = /* @__PURE__ */ __exportAll({
 * denormalize `routing_key` onto both tables and backfill from the
 * existing run rows. Backfill is one-shot inside this migration. New
 * inserts must populate the column going forward (enforced at the
-* application layer in the same phase).
+* application layer).
 *
 * The denormalized column is left NULLable for safety: if an insert
 * site is missed in the rollout, the row still lands in PG; the
@@ -3888,13 +3888,12 @@ var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
 * `secret_audit_log` and `access_log` cold-store schema additions, plus
 * the removal of `access_log`'s `expires_at`-based hard delete.
 *
-* Phase D of the cold-storage archival system. See
+* Part of the cold-storage archival system.
 *
 * Both tables get the same `archived_at TIMESTAMPTZ NULL` /
-* `archive_object_key TEXT NULL` pair that Phase B added to `run_events`
-* (`packages/platform/src/db/migrations/004_run_events_archived_at.ts`)
-* and Phase C added to `execution_runs` / `execution_jobs` /
-* `execution_steps` (`006_runs_jobs_steps_archived_at.ts`). Set inside
+* `archive_object_key TEXT NULL` pair that `run_events` carries
+* (in the Platform's schema) and that `execution_runs` / `execution_jobs` /
+* `execution_steps` got in `006_runs_jobs_steps_archived_at.ts`. Set inside
 * the archive transaction before the DELETE; survivors carry NULL.
 *
 * `secret_audit_log` gets a composite
@@ -3908,7 +3907,7 @@ var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
 * (range scans use either direction).
 *
 * Drops `access_log.expires_at` column and `access_log_expires_idx`.
-* Until Phase D, `expires_at` powered a 90-day hard-delete sweep in
+* Before this migration, `expires_at` powered a 90-day hard-delete sweep in
 * `packages/orchestrator/src/audit/access-log.ts:cleanup` (called from
 * `packages/orchestrator/src/queue/cleanup.ts:runCleanup` step 5). With
 * cold-store, `access_log` rows older than 30 days are archived rather
@@ -3916,11 +3915,9 @@ var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
 * column would mean either (a) double-evicting rows or (b) silently
 * mismatching the new contract. Drop it.
 *
-* Per the project's "no backward compatibility (pre-release)" rule,
 * `down()` recreates `expires_at` with a default of `now() + 90 days`
 * — best effort; rows inserted between `up()` and a hypothetical
-* `down()` would not have meaningful retention bounds. Acceptable for
-* staging.
+* `down()` would not have meaningful retention bounds.
 */
 async function up$144(db) {
 	await sql`
@@ -3978,13 +3975,11 @@ var _008_event_log_archived_at_exports = /* @__PURE__ */ __exportAll({
 * `event_log` cold-store schema additions plus removal of the
 * `expires_at`-based 30-day hard delete.
 *
-* Phase E of the cold-storage archival system. See
-*  §10
-* Phase E.
+* Part of the cold-storage archival system.
 *
 * Adds the same `archived_at TIMESTAMPTZ NULL` /
-* `archive_object_key TEXT NULL` pair Phase D added on this side
-* (`007_audit_logs_archived_at.ts`). Set inside the archive
+* `archive_object_key TEXT NULL` pair
+* `007_audit_logs_archived_at.ts` added on this side. Set inside the archive
 * transaction before the DELETE; survivors carry NULL.
 *
 * Adds `idx_event_log_routing_received` on `(routing_key, received_at)`
@@ -3995,7 +3990,7 @@ var _008_event_log_archived_at_exports = /* @__PURE__ */ __exportAll({
 * archiver scan.
 *
 * Drops `event_log.expires_at` and the matching
-* `event_log_expires_at_idx` index. Until Phase E, `expires_at`
+* `event_log_expires_at_idx` index. Before this migration, `expires_at`
 * powered the 30-day hard-delete sweep in
 * `packages/orchestrator/src/webhook/event-log.ts:cleanup`, called
 * from `packages/orchestrator/src/queue/cleanup.ts:runCleanup` step 4
@@ -4078,7 +4073,7 @@ var _010_cold_store_chunks_exports = /* @__PURE__ */ __exportAll({
 	up: () => up$141
 });
 /**
-* Cold-store chunk index — Phase 2 (cold-store purge).
+* Cold-store chunk index (cold-store purge).
 *
 * One row per archived chunk that the GC sweep can later purge from S3.
 * Inserted inside the same transaction as `markArchivedAndDelete` so a
@@ -4103,7 +4098,7 @@ var _010_cold_store_chunks_exports = /* @__PURE__ */ __exportAll({
 *   uses this to issue `DeleteObject` directly without recomputing the
 *   key from the prefix.
 *
-* Pre-Phase-2 chunks (v1 manifest) are NOT in this table — they live
+* V1-manifest chunks are NOT in this table — they live
 * forever. Adapters that don't opt into per-bucket archival via
 * `coldTtlDays` don't insert here either.
 */
@@ -4219,13 +4214,11 @@ var _012_peer_credentials_active_uniq_exports = /* @__PURE__ */ __exportAll({
 * nothing and both `INSERT`s succeeded, leaving 2+ ACTIVE rows for the same
 * `instance_id`. The peer's local credential file then ended up holding a
 * hash that a later concurrent `save()` had revoked, causing an endless
-* "Peer HMAC proof invalid" loop. See
-*  for the
-* full incident write-up (DB rows + log evidence from real staging deploys).
+* "Peer HMAC proof invalid" loop.
 *
 * The `up()` first dedupes any pre-existing duplicates (revoke all but the
 * newest active row per `instance_id`) — required because earlier migrations
-* predate the constraint and existing staging DBs already have the dupes.
+* predate the constraint and existing databases may already hold the dupes.
 *
 * `down()` only drops the index; it does NOT undo the dedupe (there's no
 * safe way to recreate revoked rows, and the dedupe is monotonic).
@@ -4563,8 +4556,8 @@ var _016_org_settings_allow_http_npm_exports = /* @__PURE__ */ __exportAll({
 * Operators flip this on a per-org basis to permit `http://` (non-HTTPS)
 * registry URLs in workflow `registries:` declarations. By default only
 * `https://` registries are accepted, with an automatic exemption for
-* loopback / `*.local` / private link-local hosts so dev fixtures
-* (Verdaccio at `http://verdaccio.local:4873`) keep working.
+* loopback / `*.local` / private link-local hosts so a local registry
+* (for example `http://registry.local:4873`) keeps working.
 *
 * Idempotent: a re-run on a DB that already has the column is a no-op.
 */
@@ -4609,8 +4602,7 @@ var _017_org_id_widen_exports = /* @__PURE__ */ __exportAll({
 * They are orphans by design — once Platform's migration runs, the
 * dashboard queries the orchestrator API with the new prefixed IDs
 * and the orchestrator's `WHERE org_id = $1` filter naturally hides
-* the old rows. Staging E2E regenerates fresh rows during the next
-* test run.
+* the old rows. New activity writes fresh rows under the prefixed IDs.
 *
 * Tables widened: `access_log`, `environment_bindings`,
 * `environment_source_overrides`, `environment_variables`,
@@ -4652,7 +4644,7 @@ var _018_org_id_prefix_backfill_exports = /* @__PURE__ */ __exportAll({
 * orphaned and regenerated on the next deploy. That works for
 * historical artefacts (execution_runs, event_log, access_log) but
 * NOT for tenant-state tables the orchestrator needs to recognise the
-* staging org at routing time (`sources`, `generic_webhook_sources`,
+* tenant's org at routing time (`sources`, `generic_webhook_sources`,
 * `workflow_registrations`, `org_settings`) and the env-config tables
 * referenced from runtime requests (`environments`,
 * `environment_bindings`, `environment_source_overrides`,
@@ -5907,7 +5899,7 @@ var _045_host_properties_exports = /* @__PURE__ */ __exportAll({
 *   the separate queryable host-vars dimension.
 *
 * Idempotent (`ADD COLUMN IF NOT EXISTS`): re-running on a DB that already has
-* the column is a no-op. Staging data is preserved (additive column).
+* the column is a no-op. Existing data is preserved (additive column).
 */
 async function up$106(db) {
 	await sql`ALTER TABLE public.host_roster
@@ -5933,7 +5925,7 @@ var _046_join_token_consumed_by_instance_exports = /* @__PURE__ */ __exportAll({
 *   join token already in its env — no operator action, no cluster redeploy.
 *
 * Idempotent (`ADD COLUMN IF NOT EXISTS`): re-running on a DB that already has
-* the column is a no-op. Staging data is preserved (additive nullable column).
+* the column is a no-op. Existing data is preserved (additive nullable column).
 */
 async function up$105(db) {
 	await sql`ALTER TABLE public.join_tokens
@@ -5959,8 +5951,7 @@ var _047_needs_run_on_exports = /* @__PURE__ */ __exportAll({
 * - Drop `if_failed`.
 *
 * Idempotent: column-exists guarded so re-running on a DB that already has
-* `run_on` (and no `if_failed`) is a no-op. Existing rows are preserved
-* (staging data is not dropped).
+* `run_on` (and no `if_failed`) is a no-op. Existing rows are preserved.
 */
 const ALL_TERMINAL_JSON = JSON.stringify([
 	"success",
@@ -6032,7 +6023,7 @@ var _048_host_reboot_pending_exports = /* @__PURE__ */ __exportAll({
 * (3) clears on the next reconnect (down-then-up), releasing the held job. NULL
 * = no reboot pending.
 *
-* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so existing data is
 * preserved.
 */
 async function up$103(db) {
@@ -6055,7 +6046,7 @@ var _049_held_runs_payload_exports = /* @__PURE__ */ __exportAll({
 * the dashboard approval queue and the CLI render the computed diff the
 * operator approves. NULL for every non-drift hold.
 *
-* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so existing data is
 * preserved.
 */
 async function up$102(db) {
@@ -6081,7 +6072,7 @@ var _050_sources_slug_exports = /* @__PURE__ */ __exportAll({
 * hasn't populated it yet (manual `--app-id` flow whose initial fetch failed,
 * or a row created before the rollout).
 *
-* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so existing data is
 * preserved.
 */
 async function up$101(db) {
@@ -6109,7 +6100,7 @@ var _051_binding_host_pattern_exports = /* @__PURE__ */ __exportAll({
 *   distinct per-host selectors.
 *
 * Idempotent: re-running on a DB that already has the column / index is a no-op.
-* Additive — staging data is preserved.
+* Additive — existing data is preserved.
 */
 async function up$100(db) {
 	await sql`ALTER TABLE public.environment_bindings
@@ -6145,7 +6136,7 @@ var _052_host_reach_metadata_exports = /* @__PURE__ */ __exportAll({
 *
 * All nullable: a host with no reach metadata simply cannot be bootstrapped and
 * behaves exactly as before. Idempotent (`ADD COLUMN IF NOT EXISTS`); additive,
-* so staging data is preserved.
+* so existing data is preserved.
 */
 async function up$99(db) {
 	await sql`ALTER TABLE public.host_roster
@@ -6177,7 +6168,7 @@ var _053_agent_token_single_use_exports = /* @__PURE__ */ __exportAll({
 *   default for every existing static / ephemeral token, which stay reusable
 *   until expiry).
 *
-* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so existing data is
 * preserved.
 */
 async function up$98(db) {
@@ -6202,7 +6193,7 @@ var _054_local_working_tree_exports = /* @__PURE__ */ __exportAll({
 *   lock file). The dashboard renders a "Local machine" badge for these runs
 *   and avoids building an external repository link from the repo identifier.
 *
-* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive with a default, so staging
+* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive with a default, so existing
 * data is preserved.
 */
 async function up$97(db) {
@@ -6230,7 +6221,7 @@ var _055_agent_token_mandatory_labels_exports = /* @__PURE__ */ __exportAll({
 *   agent accepts any job its advertised labels match), so every existing token
 *   stays unconfined until re-minted.
 *
-* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so existing data is
 * preserved.
 */
 async function up$96(db) {
@@ -6257,7 +6248,7 @@ var _056_execution_jobs_environments_exports = /* @__PURE__ */ __exportAll({
 *   fully-resolved list when a deferred-init agent eval resolves dynamic
 *   elements. NULL = the job binds no environment.
 *
-* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so existing data is
 * preserved.
 */
 async function up$95(db) {
@@ -6568,7 +6559,7 @@ var _064_execution_jobs_skipped_environments_exports = /* @__PURE__ */ __exportA
 * - `execution_jobs.env_warning text NULL` — the user-visible warning naming the
 *   skipped environments, surfaced on the dashboard run view. NULL = no warning.
 *
-* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+* Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so existing data is
 * preserved.
 */
 async function up$87(db) {
@@ -10951,11 +10942,10 @@ var AccessLogWriter = class {
 		}).execute();
 	}
 	/**
-	* Phase D: delegates to `loadAccessLogRange` so cold-store rows are
+	* Delegates to `loadAccessLogRange` so cold-store rows are
 	* merged transparently when pagination crosses the warm cutoff. The
 	* caller-visible `{items, nextCursor}` shape is preserved. NO
-	* --include-archived flag — access_log is "paginated/transparent"
-	* per design §7 row 11.
+	* --include-archived flag — access_log is "paginated/transparent".
 	*/
 	async query(filter) {
 		const limit = Math.max(1, Math.min(filter.limit ?? 50, 200));
@@ -11758,7 +11748,7 @@ function uninstallBackupTimer(platform, config, io = defaultTimerIo) {
 }
 //#endregion
 //#region src/cli/service/types.ts
-var DEFAULT_RESTART_POLICY;
+var DEFAULT_RESTART_POLICY, SERVICE_TEXT;
 var init_types$1 = __esmMin((() => {
 	DEFAULT_RESTART_POLICY = {
 		enabled: true,
@@ -11771,6 +11761,16 @@ var init_types$1 = __esmMin((() => {
 		maxRetries: 5,
 		windowSeconds: 300
 	};
+	SERVICE_TEXT = {
+		orchestrator: {
+			displayName: "KiCI Orchestrator",
+			description: "KiCI CI/CD workflow orchestrator service"
+		},
+		agent: {
+			displayName: "KiCI Agent",
+			description: "KiCI CI/CD workflow execution agent service"
+		}
+	};
 }));
 //#endregion
 //#region src/cli/service/privilege.ts
@@ -11847,6 +11847,148 @@ var init_privilege = __esmMin((() => {
 	init_platform_detect();
 }));
 //#endregion
+//#region src/cli/service/windows-acl.ts
+/**
+* Restricting a Windows service's env file to the service account and to
+* Administrators.
+*
+* Node maps a file mode onto Windows by toggling the read-only attribute and
+* changes no ACL, so ENV_FILE_MODE protects nothing there. The instance folder
+* under C:\ProgramData\kici\ inherits read access for BUILTIN\Users from
+* C:\ProgramData. Its ACL is replaced with full control for LocalSystem (the
+* account the shawl service runs as) and Administrators, inherited by
+* everything created in it: the env file, the temporary file a secure write
+* stages it through, and the service logs are unreadable to other accounts
+* from the moment they exist.
+*
+* Every call passes `/L` and none recurses, so icacls acts on the folder and on
+* the env file themselves and never on what a link there points at. A
+* recursive `/reset` or `/setowner` descends into the target of a junction or
+* of a symbolic link, even with `/L`, and rewrites the ACL of the files there.
+* The new folder ACL still reaches every entry that inherits from the folder.
+*/
+/**
+* The icacls in the Windows system folder, which also holds the cmd.exe that
+* COMSPEC names. A bare `icacls` would also be looked up in the current
+* folder, and the install runs elevated.
+*/
+function icaclsPath() {
+	const comspec = process.env.COMSPEC;
+	const systemDir = comspec && /(^|\\)cmd\.exe$/i.test(comspec) ? path.win32.dirname(comspec) : "C:\\Windows\\System32";
+	return path.win32.join(systemDir, "icacls.exe");
+}
+/**
+* The icacls arguments that remove every inherited ACE from `dir` and grant
+* full control, inherited by files and folders, to LocalSystem and
+* Administrators. SIDs rather than names, so a localized Windows resolves them.
+*/
+function restrictDirArgs(dir) {
+	return [
+		dir,
+		"/inheritance:r",
+		"/grant:r",
+		`*${LOCAL_SYSTEM_SID}:(OI)(CI)F`,
+		`*${ADMINISTRATORS_SID}:(OI)(CI)F`,
+		"/L",
+		"/Q"
+	];
+}
+/** The icacls arguments that reset `file` to inherit only from its folder. */
+function resetFileArgs(file) {
+	return [
+		file,
+		"/reset",
+		"/L",
+		"/Q"
+	];
+}
+/**
+* Restrict the folder that holds `envFilePath`, then reset an existing env
+* file to inherit only from it, which also drops any explicit ACE on the file.
+* Run it before the first secret is written into the folder.
+*/
+function restrictEnvFileAccess(envFilePath, run = runIcacls, exists = fs.existsSync) {
+	const dir = path.win32.dirname(envFilePath);
+	try {
+		run(restrictDirArgs(dir));
+		if (exists(envFilePath)) run(resetFileArgs(envFilePath));
+	} catch (err) {
+		throw new Error(`could not restrict access to ${dir}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+	}
+}
+var LOCAL_SYSTEM_SID, ADMINISTRATORS_SID, runIcacls;
+var init_windows_acl = __esmMin((() => {
+	LOCAL_SYSTEM_SID = "S-1-5-18";
+	ADMINISTRATORS_SID = "S-1-5-32-544";
+	runIcacls = (args) => {
+		execFileSync(icaclsPath(), args, { stdio: "pipe" });
+	};
+}));
+//#endregion
+//#region src/cli/service/windows-env-file.ts
+/**
+* Whether a Windows service launch runs a release that reads KICI_ENV_FILE.
+*
+* A Windows service is registered with the path of its env file in
+* KICI_ENV_FILE, never with the values in the file: any local account reads the
+* command line of a service with `sc.exe qc`. A release from before
+* KICI_ENV_FILE ignores the path and starts without its configuration, and the
+* only registration that would run it puts the values back on the command line.
+* So every command that registers a Windows service, or switches one to another
+* release, refuses such a release before it changes anything.
+*/
+/** Whether `file` holds `marker`, or undefined when it cannot be read. */
+function fileHolds(file, marker) {
+	let content;
+	try {
+		content = fs.readFileSync(file);
+	} catch {
+		return;
+	}
+	return content.includes(marker);
+}
+/**
+* The file that names a launch's release: the npm entry among its arguments,
+* or else the executable itself.
+*/
+function launchedRelease(launch) {
+	return launch.args?.find((arg) => PACKAGE_ENTRY.test(arg)) ?? launch.executablePath;
+}
+/**
+* Whether the process a Windows service launch starts reads KICI_ENV_FILE.
+*
+* A KiCI package runs as `<dir>\<name>.cmd` beside its bundle
+* `<dir>\lib\<name>.cjs`, which names KICI_ENV_FILE when the release reads it.
+* An npm install runs node with the `@kici-dev/<component>/dist/<entry>.js`
+* entry, which then imports the env-file loader. Any other launch, such as a
+* batch file with no KiCI bundle beside it or a custom executable, is taken to
+* read it.
+*/
+function launchReadsEnvFile(launch) {
+	const { executablePath } = launch;
+	if (/\.(cmd|bat)$/i.test(executablePath)) {
+		const { dir, name } = path.win32.parse(executablePath);
+		const sep = executablePath.includes("\\") ? "\\" : "/";
+		return fileHolds(`${dir}${sep}lib${sep}${name}.cjs`, BUNDLE_MARKER) ?? true;
+	}
+	const entry = launchedRelease(launch);
+	return PACKAGE_ENTRY.test(entry) ? fileHolds(entry, ENTRY_MARKER) ?? true : true;
+}
+/**
+* Why a Windows service may not run `release`, a release from before
+* KICI_ENV_FILE, and what the operator can do instead.
+*/
+function envFileRefusal(release, envFilePath) {
+	return `${release} predates KICI_ENV_FILE, so a Windows service can run it only with the values of ${envFilePath} on its command line, where any local account can read them with sc.exe qc. Use a release that reads KICI_ENV_FILE. To run that release anyway, uninstall the service and install it with the kici-admin of that release.`;
+}
+var ENV_FILE_LOADER_EXPORT, BUNDLE_MARKER, ENTRY_MARKER, PACKAGE_ENTRY;
+var init_windows_env_file = __esmMin((() => {
+	ENV_FILE_LOADER_EXPORT = "./load-service-env-file";
+	BUNDLE_MARKER = SERVICE_ENV_FILE_VAR;
+	ENTRY_MARKER = "@kici-dev/shared/load-service-env-file";
+	PACKAGE_ENTRY = /[/\\]@kici-dev[/\\](?:orchestrator|agent)[/\\]dist[/\\](?:server|standalone)\.js$/;
+}));
+//#endregion
 //#region src/cli/service/instance/types.ts
 /** Narrow an arbitrary string to a Component. */
 function isComponent(value) {
@@ -11857,6 +11999,81 @@ var init_types = __esmMin((() => {
 	COMPONENTS = ["orchestrator", "agent"];
 }));
 //#endregion
+//#region src/cli/service/image-digests.ts
+/**
+* Resolves the customer installer's image reference from the digest record
+* shipped with this package (installer-image-digests.json at the package root).
+*
+* Emits a manifest-list-digest-pinned ref so a `docker`/`podman pull` verifies
+* the image hash — a registry that serves substituted bits fails the pull. When
+* the record is missing (a dev tree that never ran a release) or lacks the
+* image, falls back to the moving `:latest` tag and warns.
+*
+* The record resolves relative to this module's directory and works for both
+* layouts: the source tree (`src/cli/service/` → the JSON is three dirs up at
+* the package root) and the single-file bundle (`dist/cli.js` → one dir up).
+*/
+/**
+* Climb from a starting directory looking for installer-image-digests.json.
+* Works for the source layout (src/cli/service → 3 up) and the single-file
+* bundle layout (dist → 1 up).
+*/
+function findRecordFile(startDir) {
+	let dir = startDir;
+	for (let i = 0; i < 6; i++) {
+		const candidate = path.join(dir, RECORD_FILENAME);
+		if (existsSync(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/** The published image a component runs, whatever the service is named. */
+function installerImageName(component) {
+	return `kici-${component}`;
+}
+/**
+* The recorded release and digest of an installer image, or null when the
+* record is missing, unreadable, or does not hold the image.
+*/
+function recordedImage(name, opts) {
+	const file = opts.filePath ?? findRecordFile(import.meta.dirname);
+	if (!file || !existsSync(file)) return null;
+	try {
+		const rec = JSON.parse(readFileSync(file, "utf8"));
+		const digest = rec.images?.[name];
+		return digest && rec.version ? {
+			version: rec.version,
+			digest
+		} : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* The release {@link resolveImageRef} pins `name` at, or null when it falls
+* back to the moving `:latest` tag.
+*/
+function pinnedImageVersion(name, opts = {}) {
+	return recordedImage(name, opts)?.version ?? null;
+}
+/**
+* Resolve `quay.io/kici-dev/<name>:<version>@sha256:<digest>` for an installer
+* image. Falls back to `:latest` (with a warning) when no recorded digest exists.
+*/
+function resolveImageRef(name, opts = {}) {
+	const pinned = recordedImage(name, opts);
+	if (pinned) return `${QUAY_PREFIX}/${name}:${pinned.version}@${pinned.digest}`;
+	console.warn(`[kici] no recorded manifest-list digest for ${name}; pinning the mutable :latest tag. Reinstall from a released kici-admin to get a digest-pinned image.`);
+	return `${QUAY_PREFIX}/${name}:latest`;
+}
+var QUAY_PREFIX, RECORD_FILENAME;
+var init_image_digests = __esmMin((() => {
+	QUAY_PREFIX = "quay.io/kici-dev";
+	RECORD_FILENAME = "installer-image-digests.json";
+}));
+//#endregion
 //#region src/cli/service/instance/manifest.ts
 /**
 * Instance manifest — the single source of truth for a folder-anchored
@@ -11947,6 +12164,90 @@ function resolveVersionFromLaunchSpec(spec, component) {
 	}
 	return null;
 }
+/**
+* The version of the launcher a service definition starts, or null when the
+* launch command does not show one.
+*
+* An npm-installed entry script names its version in its package.json
+* ({@link resolveVersionFromLaunchSpec}). A launcher under the instance's
+* install base resolves into the `<component>-<version>` folder an archive
+* upgrade extracted: through the `<component>` symlink on Linux and macOS, or
+* directly where Windows registers it. A `--binary` anywhere else shows none.
+*/
+function resolveLauncherVersion(spec, component, installBase) {
+	const fromPackage = resolveVersionFromLaunchSpec(spec, component);
+	if (fromPackage) return fromPackage;
+	let base;
+	try {
+		base = fs.realpathSync(installBase);
+	} catch {
+		return null;
+	}
+	const prefix = `${component}-`;
+	for (const token of [spec.execPath, ...spec.args]) {
+		if (!path.isAbsolute(token)) continue;
+		let real;
+		try {
+			real = fs.realpathSync(token);
+		} catch {
+			continue;
+		}
+		const [folder = "", ...rest] = path.relative(base, real).split(path.sep);
+		if (rest.length > 0 && folder.startsWith(prefix) && folder.length > prefix.length) return folder.slice(prefix.length);
+	}
+	return null;
+}
+/**
+* Write the manifest `install` built into `instanceDir`.
+*
+* A first install writes `fresh` as it is. A re-install of the same instance
+* (the folder holds a readable manifest of this component and name) updates
+* that manifest: it keeps what the instance recorded over time — `createdAt`,
+* the `migrationHeads` the rollback schema guard reads, and any field a newer
+* CLI wrote — and takes every other field from `fresh`. Its `kiciVersion` is
+* the version of the launcher `launch` starts; when the launcher shows none,
+* the recorded version stands, because the CLI that ran `install` need not
+* be the version the service runs. A compose service runs the image its
+* compose file pins, whatever `launch` names, so a compose re-install records
+* the release of that image (`opts.digestRecordPath` overrides the digest
+* record it reads, for tests).
+*
+* A manifest that cannot be read, or that names another instance, is
+* replaced, and the result carries a warning.
+*/
+function writeInstallManifest(instanceDir, fresh, launch, opts = {}) {
+	let existing;
+	try {
+		existing = readManifest(instanceDir, fresh.component);
+	} catch (err) {
+		return {
+			file: writeManifest(instanceDir, fresh),
+			manifest: fresh,
+			warning: `${err.message}. install replaced it, so the migration heads it recorded, if any, are lost.`
+		};
+	}
+	if (!existing) return {
+		file: writeManifest(instanceDir, fresh),
+		manifest: fresh
+	};
+	if (existing.name !== fresh.name) return {
+		file: writeManifest(instanceDir, fresh),
+		manifest: fresh,
+		warning: `${manifestPath(instanceDir, fresh.component)} described the instance "${existing.name}". It now describes "${fresh.name}".`
+	};
+	const launcherVersion = fresh.platform === "compose" ? pinnedImageVersion(installerImageName(fresh.component), { filePath: opts.digestRecordPath }) : resolveLauncherVersion(launch, fresh.component, fresh.installBase);
+	const manifest = {
+		...existing,
+		...fresh,
+		createdAt: existing.createdAt,
+		kiciVersion: launcherVersion ?? existing.kiciVersion
+	};
+	if (existing.migrationHeads) manifest.migrationHeads = existing.migrationHeads;
+	return {
+		file: writeManifest(instanceDir, manifest),
+		manifest
+	};
+}
 function resolveNpmInstallTarget(spec, component, opts) {
 	const entryRe = new RegExp(`[/\\\\]@kici-dev[/\\\\]${component}[/\\\\]dist[/\\\\](?:server|standalone)\\.js$`);
 	const entry = [spec.execPath, ...spec.args].find((a) => entryRe.test(a));
@@ -11982,6 +12283,7 @@ function firstGlobalPackage(entry) {
 }
 var REQUIRED_FIELDS;
 var init_manifest = __esmMin((() => {
+	init_image_digests();
 	REQUIRED_FIELDS = [
 		"component",
 		"name",
@@ -12549,6 +12851,43 @@ var init_systemd = __esmMin((() => {
 	};
 }));
 //#endregion
+//#region src/cli/service/shutdown-grace.ts
+/**
+* Seconds an init system must wait after SIGTERM before it SIGKILLs the service.
+*
+* The runtime defaults are shorter than either component's own graceful-shutdown
+* budget: Compose waits 10s, launchd's default ExitTimeOut is 5s, and shawl's
+* default `--stop-timeout` on Windows is 3s. A teardown that
+* takes longer is killed partway through: the orchestrator never broadcasts
+* `peer.leaving` and never closes its agent sockets, and the agent never
+* finishes draining. That window is reached exactly when it matters most — the
+* orchestrator's scaler stops each managed agent with its own grace, so an
+* orchestrator with agents in flight routinely needs more than 10s.
+*
+* Each value is its component's force-exit budget plus headroom, so the
+* process always reaches its own timer first and the runtime's kill stays the
+* last resort it is meant to be:
+* - orchestrator: 30s (`setupGracefulShutdown` default) plus up to 2s of log
+*   file flush -> 45s
+* - agent: 10s plus a ~1s abort delay in its `onForceExit` -> 20s
+*
+* An unrecognised component gets the larger value: over-waiting costs a few
+* seconds on shutdown, under-waiting corrupts it.
+*/
+function shutdownGraceSeconds(config) {
+	return (config.component ?? (config.name === "kici-agent" ? "agent" : "orchestrator")) === "agent" ? 20 : 45;
+}
+/**
+* Seconds a `stop` waits for the init system to report the service stopped.
+*
+* The init system kills the process once its grace elapses, so a service still
+* running after the grace plus this margin is hung, not slow.
+*/
+function stopWaitSeconds(config) {
+	return shutdownGraceSeconds(config) + 15;
+}
+var init_shutdown_grace = __esmMin((() => {}));
+//#endregion
 //#region src/cli/service/launchd.ts
 /**
 * launchd service manager implementation.
@@ -12571,14 +12910,19 @@ function stripLabelPrefix(label) {
 	return label;
 }
 /** Async sleep used to pace launchd bootout/bootstrap reconciliation. */
-function sleep(ms) {
+function sleep$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-var LABEL_PREFIX, KNOWN_LABEL_PREFIXES, SYSTEM_LOG_DIR, LaunchdServiceManager;
+var LABEL_PREFIX, KNOWN_LABEL_PREFIXES, SYSTEM_LOG_DIR, KICI_COMPONENT_MARKER, PRINT_NO_SUCH_SERVICE, PRINT_NO_SUCH_DOMAIN, FAILED_BOOTOUT_SETTLE_MS, LaunchdServiceManager;
 var init_launchd = __esmMin((() => {
+	init_shutdown_grace();
 	LABEL_PREFIX = "dev.kici";
 	KNOWN_LABEL_PREFIXES = ["dev.kici.", "com.kici."];
 	SYSTEM_LOG_DIR = "/var/log/kici";
+	KICI_COMPONENT_MARKER = /<key>KiCIComponent<\/key>\s*<string>(orchestrator|agent)<\/string>/;
+	PRINT_NO_SUCH_SERVICE = 113;
+	PRINT_NO_SUCH_DOMAIN = 112;
+	FAILED_BOOTOUT_SETTLE_MS = 5e3;
 	LaunchdServiceManager = class {
 		platform = "launchd";
 		/** Build the launchd label for a service. */
@@ -12590,11 +12934,51 @@ var init_launchd = __esmMin((() => {
 			if (config.isUserLevel) return path.join(os.homedir(), "Library", "Logs", "kici");
 			return SYSTEM_LOG_DIR;
 		}
-		/** Resolve the plist file path based on service level. */
-		plistPath(config) {
-			const filename = `${this.label(config)}.plist`;
-			if (config.isUserLevel) return path.join(os.homedir(), "Library", "LaunchAgents", filename);
-			return path.join("/Library", "LaunchDaemons", filename);
+		/** The directory launchd loads this service level's plists from. */
+		plistDir(isUserLevel) {
+			return isUserLevel ? path.join(os.homedir(), "Library", "LaunchAgents") : path.join("/Library", "LaunchDaemons");
+		}
+		/** The job `install` writes: `dev.kici.<name>`. */
+		installJob(config) {
+			const label = this.label(config);
+			return {
+				label,
+				plistPath: path.join(this.plistDir(config.isUserLevel), `${label}.plist`)
+			};
+		}
+		/**
+		* An installed job for this name under another label: a `com.kici.<name>`
+		* plist, or a plist named after the service itself — each one `list()`
+		* reports as this instance. Only a plist that carries the KiCI component
+		* marker counts, and the job is addressed by the Label the plist declares.
+		*/
+		otherLabelJob(config) {
+			const prefixes = [...KNOWN_LABEL_PREFIXES.filter((p) => p !== `${LABEL_PREFIX}.`), ""];
+			for (const prefix of prefixes) {
+				const stem = `${prefix}${config.name}`;
+				if (stripLabelPrefix(stem) !== config.name) continue;
+				const plistPath = path.join(this.plistDir(config.isUserLevel), `${stem}.plist`);
+				if (!fs.existsSync(plistPath)) continue;
+				const content = fs.readFileSync(plistPath, "utf-8");
+				if (!KICI_COMPONENT_MARKER.test(content)) continue;
+				const label = content.match(/<key>Label<\/key>\s*<string>([^<]+)<\/string>/);
+				return {
+					label: label ? this.unescapeXml(label[1]) : stem,
+					plistPath
+				};
+			}
+			return null;
+		}
+		/**
+		* The job a lifecycle command acts on: the `dev.kici.<name>` plist when it
+		* is installed, otherwise a job this name was installed under with another
+		* label, so every instance `list()` reports can be stopped, started and
+		* removed. With neither installed, the `dev.kici.<name>` job.
+		*/
+		resolveJob(config) {
+			const job = this.installJob(config);
+			if (fs.existsSync(job.plistPath)) return job;
+			return this.otherLabelJob(config) ?? job;
 		}
 		/** Parse a .env file into key-value pairs. */
 		parseEnvFile(envFilePath) {
@@ -12650,11 +13034,18 @@ var init_launchd = __esmMin((() => {
 			lines.push(`  <string>${this.escapeXml(config.workingDirectory)}</string>`);
 			lines.push("  <key>RunAtLoad</key>");
 			lines.push("  <true/>");
-			lines.push("  <key>KeepAlive</key>");
-			lines.push("  <true/>");
-			if (config.restartPolicy.enabled && config.restartPolicy.delays.length > 0) {
-				lines.push("  <key>ThrottleInterval</key>");
-				lines.push(`  <integer>${config.restartPolicy.delays[0]}</integer>`);
+			lines.push("  <key>ExitTimeOut</key>");
+			lines.push(`  <integer>${shutdownGraceSeconds(config)}</integer>`);
+			if (config.restartPolicy.enabled) {
+				lines.push("  <key>KeepAlive</key>");
+				lines.push("  <dict>");
+				lines.push("    <key>SuccessfulExit</key>");
+				lines.push("    <false/>");
+				lines.push("  </dict>");
+				if (config.restartPolicy.delays.length > 0) {
+					lines.push("  <key>ThrottleInterval</key>");
+					lines.push(`  <integer>${config.restartPolicy.delays[0]}</integer>`);
+				}
 			}
 			lines.push("  <key>StandardOutPath</key>");
 			lines.push(`  <string>${this.escapeXml(path.join(logDirectory, `${config.name}.out.log`))}</string>`);
@@ -12690,30 +13081,48 @@ var init_launchd = __esmMin((() => {
 		* domain from the plist's filesystem location, but they fail silently on
 		* headless macOS hosts where no GUI session exists (the `gui/<uid>` domain
 		* is not available without a console login). The modern `bootstrap` /
-		* `bootout` / `kickstart` / `kill` verbs take the domain explicitly, so a
+		* `bootout` / `kickstart` / `print` verbs take the domain explicitly, so a
 		* system-level LaunchDaemon loads regardless of whether anyone is logged
 		* in at the console — exactly what we need for headless deploy targets.
 		*/
 		domain(config) {
 			return config.isUserLevel ? `gui/${os.userInfo().uid}` : "system";
 		}
-		/** `<domain>/<label>` — the target string for kickstart/kill/print/enable. */
-		domainTarget(config) {
-			return `${this.domain(config)}/${this.label(config)}`;
+		/** `<domain>/<label>` — the target string for bootout/kickstart/print. */
+		domainTarget(config, job) {
+			return `${this.domain(config)}/${job.label}`;
 		}
-		/** Is the service currently loaded in its target domain? */
-		isLoaded(config) {
+		/**
+		* `launchctl print <domain>/<label>`: the job's description while it is
+		* loaded, or null when launchd reports it not loaded. Unlike `launchctl
+		* list`, which lists only the caller's own domain, this reads a system
+		* daemon without root. Any other failure throws, so a job that could not be
+		* inspected is never mistaken for a stopped one.
+		*/
+		printJob(config, job) {
 			try {
-				execFileSync("launchctl", ["print", this.domainTarget(config)], { stdio: "ignore" });
-				return true;
-			} catch {
-				return false;
+				return execFileSync("launchctl", ["print", this.domainTarget(config, job)], {
+					encoding: "utf-8",
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					]
+				});
+			} catch (err) {
+				const status = err.status;
+				if (status === PRINT_NO_SUCH_SERVICE || status === PRINT_NO_SUCH_DOMAIN) return null;
+				throw err;
 			}
 		}
+		/** Is the job currently loaded in its target domain? */
+		isLoaded(config, job) {
+			return this.printJob(config, job) !== null;
+		}
 		async install(config) {
-			const plistFile = this.plistPath(config);
+			const job = this.installJob(config);
 			const plistContent = this.generatePlist(config);
-			fs.mkdirSync(path.dirname(plistFile), { recursive: true });
+			fs.mkdirSync(path.dirname(job.plistPath), { recursive: true });
 			const logDirectory = this.logDir(config);
 			fs.mkdirSync(logDirectory, { recursive: true });
 			if (!config.isUserLevel && config.user) execFileSync("chown", [
@@ -12721,44 +13130,51 @@ var init_launchd = __esmMin((() => {
 				`${config.user}:staff`,
 				logDirectory
 			], { stdio: "inherit" });
-			fs.writeFileSync(plistFile, plistContent, "utf-8");
-			if (this.isLoaded(config)) {
-				try {
-					execFileSync("launchctl", ["bootout", this.domainTarget(config)], { stdio: "inherit" });
-				} catch {}
-				await this.waitUntilUnloaded(config);
+			const otherJob = this.otherLabelJob(config);
+			if (otherJob) {
+				await this.unload(config, otherJob);
+				fs.unlinkSync(otherJob.plistPath);
 			}
-			await this.bootstrapWithRetry(config, plistFile);
+			fs.writeFileSync(job.plistPath, plistContent, "utf-8");
+			await this.unload(config, job);
+			await this.bootstrapWithRetry(config, job, { replaceLoaded: true });
 		}
 		/**
-		* 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
+		* Poll until the job is no longer loaded in its target domain, or the
+		* deadline elapses. Resolves true once the job has left the domain,
+		* false on timeout. `launchctl bootout` is asynchronous — it returns before
+		* launchd has finished releasing the job — 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);
+		async waitUntilUnloaded(config, job, timeoutMs) {
+			const deadline = Date.now() + timeoutMs;
+			while (this.isLoaded(config, job)) {
+				if (Date.now() >= deadline) return false;
+				await sleep$1(500);
 			}
+			return true;
 		}
 		/**
 		* 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.
+		* permission denied) is re-thrown on the first attempt.
+		*
+		* launchd answers a bootstrap of a job that is already loaded with the same
+		* EIO. With `replaceLoaded` (install, which just wrote a new plist) such a
+		* job is booted out before the next try. Without it (start), a job that
+		* another caller loaded meanwhile is the outcome start wanted: RunAtLoad has
+		* started it, so the call succeeds and leaves it running.
 		*/
-		async bootstrapWithRetry(config, plistFile) {
+		async bootstrapWithRetry(config, job, opts) {
 			const attempts = 5;
 			for (let attempt = 1; attempt <= attempts; attempt++) try {
 				execFileSync("launchctl", [
 					"bootstrap",
 					this.domain(config),
-					plistFile
+					job.plistPath
 				], { stdio: [
 					"inherit",
 					"inherit",
@@ -12766,66 +13182,92 @@ var init_launchd = __esmMin((() => {
 				] });
 				return;
 			} catch (err) {
+				if (!opts.replaceLoaded && this.isLoaded(config, job)) return;
 				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" });
+				if (opts.replaceLoaded && this.isLoaded(config, job)) try {
+					execFileSync("launchctl", ["bootout", this.domainTarget(config, job)], { stdio: "inherit" });
 				} catch {}
-				await sleep(1e3 * attempt);
+				await sleep$1(1e3 * attempt);
 			}
 		}
 		async uninstall(config) {
-			const plistFile = this.plistPath(config);
+			const job = this.resolveJob(config);
 			try {
-				execFileSync("launchctl", ["bootout", this.domainTarget(config)], { stdio: "inherit" });
+				execFileSync("launchctl", ["bootout", this.domainTarget(config, job)], { stdio: [
+					"inherit",
+					"inherit",
+					"pipe"
+				] });
 			} catch {}
 			try {
-				fs.unlinkSync(plistFile);
+				fs.unlinkSync(job.plistPath);
 			} catch {}
 		}
 		async start(config) {
-			execFileSync("launchctl", [
-				"kickstart",
-				"-k",
-				this.domainTarget(config)
-			], { stdio: "inherit" });
+			const job = this.resolveJob(config);
+			if (!this.isLoaded(config, job)) {
+				await this.bootstrapWithRetry(config, job, { replaceLoaded: false });
+				return;
+			}
+			execFileSync("launchctl", ["kickstart", this.domainTarget(config, job)], { stdio: "inherit" });
 		}
 		async stop(config) {
-			execFileSync("launchctl", [
-				"kill",
-				"TERM",
-				this.domainTarget(config)
-			], { stdio: "inherit" });
+			const job = this.resolveJob(config);
+			if (!this.isLoaded(config, job) && !fs.existsSync(job.plistPath)) throw new Error(`launchd job ${job.label} is not installed: no job is loaded and ${job.plistPath} does not exist.`);
+			await this.unload(config, job);
+		}
+		/**
+		* Boot the job out of its domain and wait until launchd has finished the
+		* teardown. Does nothing when no job is loaded.
+		*/
+		async unload(config, job) {
+			if (!this.isLoaded(config, job)) return;
+			let bootoutError;
+			try {
+				execFileSync("launchctl", ["bootout", this.domainTarget(config, job)], { stdio: [
+					"inherit",
+					"inherit",
+					"pipe"
+				] });
+			} catch (err) {
+				bootoutError = err;
+			}
+			if (bootoutError !== void 0) {
+				if (await this.waitUntilUnloaded(config, job, FAILED_BOOTOUT_SETTLE_MS)) return;
+				const stderr = String(bootoutError.stderr ?? "");
+				if (stderr) process.stderr.write(stderr);
+				throw bootoutError;
+			}
+			const timeoutSeconds = stopWaitSeconds(config);
+			if (!await this.waitUntilUnloaded(config, job, timeoutSeconds * 1e3)) throw new Error(`launchd job ${job.label} is still loaded ${timeoutSeconds}s after launchctl bootout. Its process may be hung — inspect it with \`launchctl print ${this.domainTarget(config, job)}\`.`);
 		}
 		async restart(config) {
 			await this.stop(config);
 			await this.start(config);
 		}
 		async status(config) {
-			const label = this.label(config);
+			const job = this.resolveJob(config);
+			let description;
 			try {
-				const output = execFileSync("launchctl", ["list"], { encoding: "utf-8" });
-				for (const line of output.split("\n")) {
-					if (!line.includes(label)) continue;
-					const parts = line.trim().split("	");
-					if (parts.length >= 3) {
-						const pidStr = parts[0];
-						const exitCode = parseInt(parts[1], 10);
-						const pid = pidStr !== "-" ? parseInt(pidStr, 10) : void 0;
-						if (pid && pid > 0) return {
-							state: "running",
-							pid
-						};
-						if (exitCode !== 0) return { state: "failed" };
-						return { state: "stopped" };
-					}
-				}
-			} catch {}
-			return { state: "unknown" };
+				description = this.printJob(config, job);
+			} catch {
+				return { state: "unknown" };
+			}
+			if (description === null) return fs.existsSync(job.plistPath) ? { state: "stopped" } : { state: "unknown" };
+			const pid = description.match(/^\tpid = (\d+)$/m);
+			if (pid) return {
+				state: "running",
+				pid: parseInt(pid[1], 10)
+			};
+			const lastExit = description.match(/^\tlast exit code = (-?\d+)/m);
+			if (lastExit && parseInt(lastExit[1], 10) !== 0) return { state: "failed" };
+			if (/^\tlast terminating signal = /m.test(description)) return { state: "failed" };
+			return { state: "stopped" };
 		}
 		async logs(config, options) {
 			const logDirectory = this.logDir(config);
@@ -12843,10 +13285,10 @@ var init_launchd = __esmMin((() => {
 			});
 		}
 		async isInstalled(config) {
-			return fs.existsSync(this.plistPath(config));
+			return fs.existsSync(this.resolveJob(config).plistPath);
 		}
 		async list(isUserLevel) {
-			const baseDir = isUserLevel ? path.join(os.homedir(), "Library", "LaunchAgents") : "/Library/LaunchDaemons";
+			const baseDir = this.plistDir(isUserLevel);
 			if (!fs.existsSync(baseDir)) return [];
 			const out = [];
 			for (const entry of fs.readdirSync(baseDir)) {
@@ -12859,7 +13301,7 @@ var init_launchd = __esmMin((() => {
 					if (err?.code === "ENOENT") continue;
 					throw new Error(`could not read the launchd job at ${path.join(baseDir, entry)}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
 				}
-				const match = content.match(/<key>KiCIComponent<\/key>\s*<string>(orchestrator|agent)<\/string>/);
+				const match = content.match(KICI_COMPONENT_MARKER);
 				if (!match) continue;
 				const dirMatch = content.match(/<key>KiCIInstanceDir<\/key>\s*<string>([^<]+)<\/string>/);
 				out.push({
@@ -12875,7 +13317,7 @@ var init_launchd = __esmMin((() => {
 		async readLaunchSpec(config) {
 			let content;
 			try {
-				content = fs.readFileSync(this.plistPath(config), "utf-8");
+				content = fs.readFileSync(this.resolveJob(config).plistPath, "utf-8");
 			} catch {
 				return null;
 			}
@@ -13144,12 +13586,75 @@ function parseStateCode(output) {
 	const match = output.match(/STATE\s*:\s*(\d+)/);
 	return match ? parseInt(match[1], 10) : void 0;
 }
-var SERVICE_REGISTRY_PROBE_TIMEOUT_MS, WindowsServiceManager;
+/** Async sleep used to pace the `sc.exe query` polls. */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** A `.cmd` or `.bat` file, which Windows runs through cmd.exe. */
+function isBatchFile(executablePath) {
+	return /\.(cmd|bat)$/i.test(executablePath);
+}
+/**
+* The cmd.exe that COMSPEC names, as Node itself uses to run a shell on Windows.
+* A COMSPEC that names another shell is not used: the wrapper arguments are
+* cmd.exe's.
+*/
+function cmdExePath() {
+	const comspec = process.env.COMSPEC;
+	return comspec && /(^|\\)cmd\.exe$/i.test(comspec) ? comspec : "C:\\Windows\\System32\\cmd.exe";
+}
+/**
+* Throw when cmd.exe would read part of `token` as syntax.
+*
+* shawl quotes a token on cmd.exe's command line only when it contains a space
+* or a tab. Inside quotes cmd.exe reads `&`, `|`, `<`, `>`, `(`, `)` and the
+* `,` `;` `=` delimiters as text; outside quotes it reads them as syntax. `%`
+* and `^` change even inside quotes (`call` expands `%` again and doubles `^`),
+* and a `"` ends the quoting.
+*/
+function assertCmdSafe(token) {
+	const found = (/[ \t]/.test(token) ? /["%^]/ : /["%^&|<>(),;=]/).exec(token);
+	if (found) throw new Error(`cannot run "${token}" as a Windows service: it contains "${found[0]}", which cmd.exe reads as syntax when it runs the batch file. Install from a path without it.`);
+}
+/**
+* The command shawl registers for the service: the executable and its
+* arguments, with a batch file run through cmd.exe ({@link BATCH_WRAPPER_ARGS}).
+*/
+function serviceCommand(config) {
+	const command = [config.executablePath, ...config.args ?? []];
+	if (!isBatchFile(config.executablePath)) return command;
+	command.forEach(assertCmdSafe);
+	return [
+		cmdExePath(),
+		...BATCH_WRAPPER_ARGS,
+		...command,
+		BATCH_STDIN
+	];
+}
+/** The launch command inside a {@link serviceCommand}: a batch file's cmd.exe wrapper removed. */
+function unwrapServiceCommand(tokens) {
+	const [exe, ...rest] = tokens;
+	return exe !== void 0 && /(^|\\)cmd\.exe$/i.test(exe) && BATCH_WRAPPER_ARGS.every((arg, i) => rest[i]?.toLowerCase() === arg) && rest.at(-1) === BATCH_STDIN && rest.length > BATCH_WRAPPER_ARGS.length + 1 ? rest.slice(BATCH_WRAPPER_ARGS.length, -1) : tokens;
+}
+var SERVICE_REGISTRY_PROBE_TIMEOUT_MS, ERROR_SERVICE_NOT_ACTIVE, ERROR_SERVICE_CANNOT_ACCEPT_CTRL, BATCH_WRAPPER_ARGS, BATCH_STDIN, WindowsServiceManager;
 var init_windows = __esmMin((() => {
 	init_downloader();
 	init_registry();
 	init_platform_detect();
+	init_shutdown_grace();
+	init_windows_acl();
+	init_windows_env_file();
 	SERVICE_REGISTRY_PROBE_TIMEOUT_MS = 1e4;
+	ERROR_SERVICE_NOT_ACTIVE = 1062;
+	ERROR_SERVICE_CANNOT_ACCEPT_CTRL = 1061;
+	BATCH_WRAPPER_ARGS = [
+		"/d",
+		"/e:on",
+		"/v:off",
+		"/c",
+		"call"
+	];
+	BATCH_STDIN = "<NUL";
 	WindowsServiceManager = class {
 		platform = "windows";
 		/**
@@ -13191,13 +13696,24 @@ var init_windows = __esmMin((() => {
 				return false;
 			}
 		}
+		/** The service's STATE code from `sc.exe query`, or undefined when the query fails. */
+		queryStateCode(name) {
+			try {
+				return parseStateCode(execSync(`sc.exe query ${name}`, { stdio: "pipe" }).toString());
+			} catch {
+				return;
+			}
+		}
 		async install(config) {
+			const command = serviceCommand(config);
+			if (!launchReadsEnvFile(config)) throw new Error(`cannot register ${config.name}: ` + envFileRefusal(launchedRelease(config), config.envFilePath));
+			const envDir = path.dirname(config.envFilePath);
+			fs.mkdirSync(envDir, { recursive: true });
+			if (!config.isUserLevel) restrictEnvFileAccess(config.envFilePath);
 			if (this.serviceExists(config.name)) await this.uninstall(config);
 			const depMeta = getDepMetadata("shawl");
 			const depPath = await ensureDep(depMeta, getCacheDir());
 			const shawlExe = path.join(depPath, depMeta.extractPath);
-			const envDir = path.dirname(config.envFilePath);
-			fs.mkdirSync(envDir, { recursive: true });
 			const cwd = config.workingDirectory.replace(/\\+$/, "");
 			const logDir = path.join(envDir, "logs");
 			fs.mkdirSync(logDir, { recursive: true });
@@ -13209,23 +13725,12 @@ var init_windows = __esmMin((() => {
 				"--cwd",
 				`"${cwd}"`,
 				"--log-dir",
-				`"${logDir.replace(/\\+$/, "")}"`
+				`"${logDir.replace(/\\+$/, "")}"`,
+				"--stop-timeout",
+				String(shutdownGraceSeconds(config) * 1e3)
 			];
-			if (fs.existsSync(config.envFilePath)) {
-				const envContent = fs.readFileSync(config.envFilePath, "utf-8");
-				for (const line of envContent.split("\n")) {
-					const trimmed = line.trim();
-					if (trimmed && !trimmed.startsWith("#") && trimmed.includes("=")) {
-						const eqIdx = trimmed.indexOf("=");
-						if (trimmed.slice(0, eqIdx) === "PATH") {
-							const dirs = trimmed.slice(eqIdx + 1).split(";").filter(Boolean);
-							for (const dir of dirs) cmdParts.push("--path-prepend", `"${dir.replace(/\\+$/, "")}"`);
-						} else cmdParts.push("--env", `"${trimmed}"`);
-					}
-				}
-			}
-			cmdParts.push("--", `"${config.executablePath}"`);
-			for (const arg of config.args ?? []) cmdParts.push(`"${arg}"`);
+			cmdParts.push("--env", `"${SERVICE_ENV_FILE_VAR}=${config.envFilePath}"`);
+			cmdParts.push("--", ...command.map((token) => `"${token}"`));
 			const cmd = cmdParts.join(" ");
 			execSync(cmd, { stdio: "pipe" });
 			const dirSuffix = config.component && config.instanceDir ? ` [KiCI-DIR:${config.instanceDir}]` : "";
@@ -13237,60 +13742,55 @@ var init_windows = __esmMin((() => {
 			execSync(`sc.exe failure ${config.name} reset= ${resetSeconds} actions= ${actions}`, { stdio: "pipe" });
 		}
 		async uninstall(config) {
+			const waitSeconds = stopWaitSeconds(config);
 			try {
 				execSync(`sc.exe stop ${config.name}`, { stdio: "pipe" });
-				await new Promise((r) => setTimeout(r, 3e3));
 			} catch {}
+			const stopDeadline = Date.now() + waitSeconds * 1e3;
+			while (Date.now() < stopDeadline) {
+				const stateCode = this.queryStateCode(config.name);
+				if (stateCode === 1 || stateCode === void 0) break;
+				await sleep(500);
+			}
 			execSync(`sc.exe delete ${config.name}`, { stdio: "pipe" });
-			const deadline = Date.now() + 3e4;
-			while (Date.now() < deadline) try {
-				execSync(`sc.exe query ${config.name}`, { stdio: "pipe" });
-				await new Promise((r) => setTimeout(r, 1e3));
-			} catch {
-				return;
+			const deadline = Date.now() + waitSeconds * 1e3;
+			while (Date.now() < deadline) {
+				if (!this.serviceExists(config.name)) return;
+				await sleep(1e3);
 			}
-			throw new Error(`Service ${config.name} still exists after 30s. The process may be hung — check Task Manager and kill manually if needed.`);
+			throw new Error(`Service ${config.name} still exists ${waitSeconds}s after sc.exe delete. The process may be hung — check Task Manager and kill manually if needed.`);
 		}
 		async start(config) {
-			const deadline = Date.now() + 3e4;
+			const deadline = Date.now() + stopWaitSeconds(config) * 1e3;
 			while (Date.now() < deadline) {
-				let stateCode;
-				try {
-					stateCode = parseStateCode(execSync(`sc.exe query ${config.name}`, { stdio: "pipe" }).toString());
-				} catch {
-					stateCode = void 0;
-				}
+				const stateCode = this.queryStateCode(config.name);
 				if (stateCode === 4) return;
 				if (stateCode === 1) break;
-				await new Promise((r) => setTimeout(r, 500));
+				await sleep(500);
 			}
 			execSync(`sc.exe start ${config.name}`, { stdio: "pipe" });
 		}
 		async stop(config) {
-			execSync(`sc.exe stop ${config.name}`, { stdio: "pipe" });
-			const deadline = Date.now() + 3e4;
-			while (Date.now() < deadline) {
-				let stateCode;
-				try {
-					stateCode = parseStateCode(execSync(`sc.exe query ${config.name}`, { stdio: "pipe" }).toString());
-				} catch {
-					stateCode = void 0;
-				}
-				if (stateCode === 1) return;
-				await new Promise((r) => setTimeout(r, 500));
-			}
-			throw new Error(`Service ${config.name} did not reach STOPPED state within 30s after sc.exe stop. A subsequent start would fail with error 1056 — the service may be hung.`);
-		}
-		async restart(config) {
 			try {
 				execSync(`sc.exe stop ${config.name}`, { stdio: "pipe" });
-			} catch {}
-			const deadline = Date.now() + 3e4;
+			} catch (err) {
+				const status = err?.status;
+				if (status !== ERROR_SERVICE_NOT_ACTIVE && status !== ERROR_SERVICE_CANNOT_ACCEPT_CTRL) throw err;
+				const stateCode = this.queryStateCode(config.name);
+				if (stateCode === 1) return;
+				if (status !== ERROR_SERVICE_CANNOT_ACCEPT_CTRL || stateCode !== 3) throw err;
+			}
+			const waitSeconds = stopWaitSeconds(config);
+			const deadline = Date.now() + waitSeconds * 1e3;
 			while (Date.now() < deadline) {
-				if (parseStateCode(execSync(`sc.exe query ${config.name}`, { stdio: "pipe" }).toString()) === 1) break;
-				await new Promise((r) => setTimeout(r, 500));
+				if (this.queryStateCode(config.name) === 1) return;
+				await sleep(500);
 			}
-			execSync(`sc.exe start ${config.name}`, { stdio: "pipe" });
+			throw new Error(`Service ${config.name} did not reach STOPPED state within ${waitSeconds}s after sc.exe stop. A subsequent start would fail with error 1056 — the service may be hung.`);
+		}
+		async restart(config) {
+			await this.stop(config);
+			await this.start(config);
 		}
 		async status(config) {
 			try {
@@ -13359,18 +13859,38 @@ var init_windows = __esmMin((() => {
 			}
 			return out;
 		}
-		async readLaunchSpec(config) {
-			let raw;
+		/**
+		* The command line a service is registered with.
+		*
+		* `sc.exe qc` answers most registrations, but it fails (error 1734) once the
+		* line is longer than about 4000 characters, as an older CLI's registration
+		* with every env-file value on it can be. It also prints in the console code
+		* page, so a path outside ASCII, such as one under the profile of a user
+		* named Jürgen, decodes to U+FFFD. In either case the registry value it reads
+		* (`ImagePath`) is read through PowerShell, printed as UTF-8.
+		*/
+		registeredCommandLine(name) {
 			try {
-				raw = execSync(`sc.exe qc ${config.name}`, { stdio: "pipe" }).toString();
+				const line = execSync(`sc.exe qc ${name}`, { stdio: "pipe" }).toString().match(/BINARY_PATH_NAME\s*:\s*(.+)/)?.[1]?.trim();
+				if (line && !line.includes("�")) return line;
+			} catch {}
+			const key = `HKLM:\\SYSTEM\\CurrentControlSet\\Services\\${name.replace(/'/g, "''")}`;
+			try {
+				return execSync(`powershell -NoProfile -NonInteractive -Command "[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding \$false; (Get-ItemProperty -LiteralPath '${key}').ImagePath"`, { stdio: "pipe" }).toString("utf-8").replace(/^\uFEFF/, "").trim() || null;
 			} catch {
 				return null;
 			}
-			const m = raw.match(/BINARY_PATH_NAME\s*:\s*(.+)/);
-			if (!m) return null;
-			const sep = m[1].indexOf(" -- ");
+		}
+		async readLaunchSpec(config) {
+			const line = this.registeredCommandLine(config.name);
+			if (line === null) return null;
+			const parts = [...line.matchAll(/"([^"]*)"|(\S+)/g)].map((t) => ({
+				text: t[1] ?? t[2],
+				quoted: t[1] !== void 0
+			}));
+			const sep = parts.findIndex((p) => !p.quoted && p.text === "--");
 			if (sep === -1) return null;
-			const tokens = [...m[1].slice(sep + 4).matchAll(/"([^"]*)"|(\S+)/g)].map((t) => t[1] ?? t[2]);
+			const tokens = unwrapServiceCommand(parts.slice(sep + 1).map((p) => p.text));
 			if (tokens.length === 0 || !tokens[0]) return null;
 			return {
 				execPath: tokens[0],
@@ -13395,56 +13915,6 @@ function composeFilePath(envFilePath, serviceName) {
 }
 var init_compose_path = __esmMin((() => {}));
 //#endregion
-//#region src/cli/service/image-digests.ts
-/**
-* Resolves the customer installer's image reference from the digest record
-* shipped with this package (installer-image-digests.json at the package root).
-*
-* Emits a manifest-list-digest-pinned ref so a `docker`/`podman pull` verifies
-* the image hash — a registry that serves substituted bits fails the pull. When
-* the record is missing (a dev tree that never ran a release) or lacks the
-* image, falls back to the moving `:latest` tag and warns.
-*
-* The record resolves relative to this module's directory and works for both
-* layouts: the source tree (`src/cli/service/` → the JSON is three dirs up at
-* the package root) and the single-file bundle (`dist/cli.js` → one dir up).
-*/
-/**
-* Climb from a starting directory looking for installer-image-digests.json.
-* Works for the source layout (src/cli/service → 3 up) and the single-file
-* bundle layout (dist → 1 up).
-*/
-function findRecordFile(startDir) {
-	let dir = startDir;
-	for (let i = 0; i < 6; i++) {
-		const candidate = path.join(dir, RECORD_FILENAME);
-		if (existsSync(candidate)) return candidate;
-		const parent = path.dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	return null;
-}
-/**
-* Resolve `quay.io/kici-dev/<name>:<version>@sha256:<digest>` for an installer
-* image. Falls back to `:latest` (with a warning) when no recorded digest exists.
-*/
-function resolveImageRef(name, opts = {}) {
-	const file = opts.filePath ?? findRecordFile(import.meta.dirname);
-	if (file && existsSync(file)) try {
-		const rec = JSON.parse(readFileSync(file, "utf8"));
-		const digest = rec.images?.[name];
-		if (digest && rec.version) return `${QUAY_PREFIX}/${name}:${rec.version}@${digest}`;
-	} catch {}
-	console.warn(`[kici] no recorded manifest-list digest for ${name}; pinning the mutable :latest tag. Reinstall from a released kici-admin to get a digest-pinned image.`);
-	return `${QUAY_PREFIX}/${name}:latest`;
-}
-var QUAY_PREFIX, RECORD_FILENAME;
-var init_image_digests = __esmMin((() => {
-	QUAY_PREFIX = "quay.io/kici-dev";
-	RECORD_FILENAME = "installer-image-digests.json";
-}));
-//#endregion
 //#region src/cli/service/compose.ts
 /**
 * Docker/Podman Compose service manager.
@@ -13553,29 +14023,6 @@ function getRestartMode(config) {
 	return "unless-stopped";
 }
 /**
-* Seconds a runtime must wait after SIGTERM before it SIGKILLs the container.
-*
-* Compose defaults this to 10s, which is shorter than either component's own
-* graceful-shutdown budget, so a teardown that takes longer than 10s is killed
-* partway through: the orchestrator never broadcasts `peer.leaving` and never
-* closes its agent sockets, and the agent never finishes draining. That window
-* is reached exactly when it matters most — the orchestrator's scaler stops
-* each managed agent container with its own grace, so an orchestrator with
-* agents in flight routinely needs more than 10s.
-*
-* Each value is its component's force-exit budget plus headroom, so the
-* process always reaches its own timer first and the runtime's kill stays the
-* last resort it is meant to be:
-* - orchestrator: 30s (`setupGracefulShutdown` default) -> 45s
-* - agent: 10s plus a ~1s abort delay in its `onForceExit` -> 20s
-*
-* An unrecognised component gets the larger value: over-waiting costs a few
-* seconds on shutdown, under-waiting corrupts it.
-*/
-function stopGracePeriodSeconds(config) {
-	return (config.component ?? (config.name === "kici-agent" ? "agent" : "orchestrator")) === "agent" ? 20 : 45;
-}
-/**
 * Generate compose YAML content for a service.
 *
 * Uses a manual YAML builder to avoid adding a YAML library dependency.
@@ -13583,25 +14030,24 @@ function stopGracePeriodSeconds(config) {
 * restart policy, and volume mounts.
 *
 * The `image:` line is pinned by manifest-list digest via `resolveImageRef`
-* (`quay.io/kici-dev/<service-name>:<version>@sha256:<digest>`), falling back
-* to the mutable `:latest` tag only when no recorded digest ships with this
-* package. Source of truth for the publish targets:
-* packages/ci/src/publish-images.ts. See
-* .claude/rules/container-publish-registry.md — Quay is the sole registry for
-* public KiCI images we publish.
+* (`quay.io/kici-dev/kici-<component>:<version>@sha256:<digest>`, whatever the
+* service is named), falling back to the mutable `:latest` tag only when no
+* recorded digest ships with this package. Quay is the only registry the KiCI
+* images are published to.
 */
 function generateComposeYaml(config) {
 	const restartMode = getRestartMode(config);
+	const image = config.component ? installerImageName(config.component) : config.name;
 	const lines = [
 		"# Generated by KiCI service installer",
 		`# Service: ${config.displayName}`,
 		"",
 		"services:",
 		`  ${config.name}:`,
-		`    image: ${resolveImageRef(config.name)}`,
+		`    image: ${resolveImageRef(image)}`,
 		`    container_name: ${config.name}`,
 		`    restart: ${restartMode}`,
-		`    stop_grace_period: ${stopGracePeriodSeconds(config)}s`,
+		`    stop_grace_period: ${shutdownGraceSeconds(config)}s`,
 		"    env_file:",
 		`      - ${config.envFilePath}`,
 		"    volumes:",
@@ -13619,6 +14065,7 @@ var RUNTIME_PROBE_TIMEOUT_MS, ComposeServiceManager;
 var init_compose = __esmMin((() => {
 	init_compose_path();
 	init_image_digests();
+	init_shutdown_grace();
 	RUNTIME_PROBE_TIMEOUT_MS = 1e4;
 	ComposeServiceManager = class {
 		platform = "compose";
@@ -13773,11 +14220,14 @@ var init_compose = __esmMin((() => {
 var service_exports = /* @__PURE__ */ __exportAll({
 	COMPONENTS: () => COMPONENTS,
 	DEFAULT_RESTART_POLICY: () => DEFAULT_RESTART_POLICY,
+	ENV_FILE_LOADER_EXPORT: () => ENV_FILE_LOADER_EXPORT,
 	InstanceNotFoundError: () => InstanceNotFoundError,
+	SERVICE_TEXT: () => SERVICE_TEXT,
 	appendIndexEntry: () => appendIndexEntry,
 	candidatePlatforms: () => candidatePlatforms,
 	createServiceManager: () => createServiceManager,
 	detectPlatform: () => detectPlatform,
+	envFileRefusal: () => envFileRefusal,
 	formatRefusal: () => formatRefusal,
 	getCacheDir: () => getCacheDir,
 	getConfigDir: () => getConfigDir,
@@ -13786,6 +14236,8 @@ var service_exports = /* @__PURE__ */ __exportAll({
 	isComponent: () => isComponent,
 	isRoot: () => isRoot,
 	kiciConfigRoot: () => kiciConfigRoot,
+	launchReadsEnvFile: () => launchReadsEnvFile,
+	launchedRelease: () => launchedRelease,
 	listInstances: () => listInstances,
 	manifestFilename: () => manifestFilename,
 	manifestPath: () => manifestPath,
@@ -13795,10 +14247,13 @@ var service_exports = /* @__PURE__ */ __exportAll({
 	removeIndexEntry: () => removeIndexEntry,
 	resolveInstance: () => resolveInstance,
 	resolveInstanceTarget: () => resolveInstanceTarget,
+	resolveLauncherVersion: () => resolveLauncherVersion,
 	resolveNpmInstallTarget: () => resolveNpmInstallTarget,
 	resolveUserLevel: () => resolveUserLevel,
 	resolveVersionFromLaunchSpec: () => resolveVersionFromLaunchSpec,
+	restrictEnvFileAccess: () => restrictEnvFileAccess,
 	writeIndex: () => writeIndex,
+	writeInstallManifest: () => writeInstallManifest,
 	writeManifest: () => writeManifest
 });
 /**
@@ -13836,6 +14291,8 @@ var init_service = __esmMin((() => {
 	init_types$1();
 	init_platform_detect();
 	init_privilege();
+	init_windows_acl();
+	init_windows_env_file();
 	init_types();
 	init_manifest();
 	init_index_file();
@@ -15187,7 +15644,7 @@ function startManifestLoopback(opts) {
 * blocked launcher) just falls back to copy-paste.
 *
 * `KICI_BROWSER_CMD` overrides the launcher: `none` suppresses it entirely
-* (E2E / headless capture), any other value is run with `{url}` substituted —
+* (automated tests / headless capture), any other value is run with `{url}` substituted —
 * mirroring the `kici login` convention.
 */
 function openBrowserBestEffort(url) {
@@ -16267,10 +16724,9 @@ function registerRemoteSourceCommands(program) {
 * Workflow registration commands for kici-admin.
 *
 * Provides operator-facing read access to the workflow_registrations table
-* via the orchestrator's admin HTTP API. This is the dogfooded replacement
-* for "let me just psql the registration table" — every CLI subcommand here
-* goes through AdminApiClient and the existing /api/v1/admin/registrations
-* route.
+* via the orchestrator's admin HTTP API. Use it instead of querying the
+* registration table with psql: every CLI subcommand here goes through
+* AdminApiClient and the existing /api/v1/admin/registrations route.
 *
 *   workflow list                List registered workflows (table or JSON)
 *
@@ -16353,7 +16809,7 @@ function renderTable$3(headers, rows) {
 */
 function registerWorkflowCommands(program, getClient) {
 	const wf = program.command("workflow").description("Inspect workflow registrations");
-	wf.command("list").description("List workflow registrations (dogfooded via /api/v1/admin/registrations)").option("--org <orgId>", "Filter by customer/org id (server param: customerId)").option("--routing-key <key>", "Filter by routing key, e.g. github:42").option("--repo <ownerRepo>", "Filter by repo identifier (owner/repo)").option("--trigger-type <type>", "Filter by trigger type, e.g. webhook, push, schedule").option("--event <eventName>", "Filter by webhook event name (scans lock_entry.triggers)").option("--json", "Emit raw JSON instead of a table").action(async (opts) => {
+	wf.command("list").description("List workflow registrations (admin API: /api/v1/admin/registrations)").option("--org <orgId>", "Filter by customer/org id (server param: customerId)").option("--routing-key <key>", "Filter by routing key, e.g. github:42").option("--repo <ownerRepo>", "Filter by repo identifier (owner/repo)").option("--trigger-type <type>", "Filter by trigger type, e.g. webhook, push, schedule").option("--event <eventName>", "Filter by webhook event name (scans lock_entry.triggers)").option("--json", "Emit raw JSON instead of a table").action(async (opts) => {
 		try {
 			const path = `/api/v1/admin/registrations${buildQueryString({
 				org: opts.org,
@@ -16477,7 +16933,7 @@ function emptyStepLogNote(stepIndex, logs) {
 */
 function registerRunsCommands(program, getClient) {
 	const runs = program.command("runs").description("Inspect execution runs, jobs, and steps");
-	runs.command("list").description("List execution runs (dogfooded via /api/v1/admin/runs)").option("--status <statuses>", "Filter by run status. Accepts a single value or a comma-separated list (e.g. success,failed)").option("--workflow-name <name>", "Filter by workflow name").option("--repo <ownerRepo>", "Filter by repo identifier (owner/repo)").option("--since <iso8601>", "Only include runs with created_at strictly later than this ISO-8601 timestamp").option("--count", "Return only the count of matching runs, skipping the row listing").option("--limit <n>", "Max results (default 20, max 100)", "20").option("--offset <n>", "Skip first N results", "0").option("--json", "Emit raw JSON instead of a table").action(async (opts) => {
+	runs.command("list").description("List execution runs (admin API: /api/v1/admin/runs)").option("--status <statuses>", "Filter by run status. Accepts a single value or a comma-separated list (e.g. success,failed)").option("--workflow-name <name>", "Filter by workflow name").option("--repo <ownerRepo>", "Filter by repo identifier (owner/repo)").option("--since <iso8601>", "Only include runs with created_at strictly later than this ISO-8601 timestamp").option("--count", "Return only the count of matching runs, skipping the row listing").option("--limit <n>", "Max results (default 20, max 100)", "20").option("--offset <n>", "Skip first N results", "0").option("--json", "Emit raw JSON instead of a table").action(async (opts) => {
 		try {
 			if (opts.count) {
 				const data = await getClient().countRuns({
@@ -16680,7 +17136,7 @@ function registerRunsCommands(program, getClient) {
 			process.exit(1);
 		}
 	});
-	runs.command("jobs <runId>").description("List jobs for a run (dogfooded via /api/v1/admin/runs/:runId/jobs)").option("--include-steps", "Embed step list inside each job (default false)").option("--json", "Emit raw JSON instead of a table").action(async (runId, opts) => {
+	runs.command("jobs <runId>").description("List jobs for a run (admin API: /api/v1/admin/runs/:runId/jobs)").option("--include-steps", "Embed step list inside each job (default false)").option("--json", "Emit raw JSON instead of a table").action(async (runId, opts) => {
 		try {
 			const response = await getClient().getRunJobs(runId, { includeSteps: Boolean(opts.includeSteps) });
 			if (opts.json) {
@@ -16734,7 +17190,7 @@ function registerRunsCommands(program, getClient) {
 			process.exit(1);
 		}
 	});
-	runs.command("logs <runId>").description("Print a page of a step log (dogfooded via /api/v1/admin/runs/:runId/jobs/:jobId/steps/:i/logs)").requiredOption("--job <jobId>", "Job id (the dispatch_queue row id for an eval round)").option("--step <n>", "Step index (default 0; -1 is the job setup log)", "0").option("--limit <n>", "Max lines to return (default 500, server caps at 2000)", "500").option("--cursor <c>", "Line-offset cursor from a previous page").option("--json", "Emit raw JSON instead of plain lines").action(async (runId, opts) => {
+	runs.command("logs <runId>").description("Print a page of a step log (admin API: /api/v1/admin/runs/:runId/jobs/:jobId/steps/:i/logs)").requiredOption("--job <jobId>", "Job id (the dispatch_queue row id for an eval round)").option("--step <n>", "Step index (default 0; -1 is the job setup log)", "0").option("--limit <n>", "Max lines to return (default 500, server caps at 2000)", "500").option("--cursor <c>", "Line-offset cursor from a previous page").option("--json", "Emit raw JSON instead of plain lines").action(async (runId, opts) => {
 		try {
 			const params = new URLSearchParams({ limit: String(opts.limit) });
 			if (opts.cursor) params.set("cursor", String(opts.cursor));
@@ -16844,6 +17300,8 @@ function clusterSentinelKey(prefix) {
 * Provider configuration (GitHub Apps, etc.) is managed via the `sources` table
 * and PgSecretStore, not through config. See SourceStore and SourceManager.
 */
+/** How long the database pool waits for a connection when `KICI_DB_POOL_ACQUIRE_TIMEOUT_MS` is unset. */
+const DB_POOL_ACQUIRE_TIMEOUT_DEFAULT_MS = 5e3;
 /**
 * Default for `sealed_secrets_retry_backoff_ms`: how long a coordinator stops
 * offering a queued job it put back because it could not open its seal. The
@@ -16854,7 +17312,7 @@ const DEFAULT_SEALED_SECRETS_RETRY_BACKOFF_MS = 6e4;
 const PLATFORM_CONNECTED_MODES_TEXT = `${PLATFORM_CONNECTED_MODES.slice(0, -1).join(", ")}, or ${PLATFORM_CONNECTED_MODES[PLATFORM_CONNECTED_MODES.length - 1]}`;
 const baseSchema = z.object({
 	mode: OrchestratorMode.default("platform"),
-	port: z.coerce.number().default(4e3),
+	port: z.coerce.number().default(ORCHESTRATOR_DEFAULT_PORT),
 	/**
 	* Address the HTTP + WebSocket listener binds. Defaults to every interface,
 	* matching the Platform's own `KICI_HOST`, because a real orchestrator
@@ -16931,7 +17389,7 @@ const baseSchema = z.object({
 	orchestratorUrl: z.string().optional(),
 	databaseUrl: z.string().default(""),
 	dbPoolMax: z.coerce.number().int().positive().default(20),
-	dbPoolAcquireTimeoutMs: z.coerce.number().int().nonnegative().default(5e3),
+	dbPoolAcquireTimeoutMs: z.coerce.number().int().nonnegative().default(DB_POOL_ACQUIRE_TIMEOUT_DEFAULT_MS),
 	dbStatementTimeoutMs: z.coerce.number().int().nonnegative().default(3e4),
 	lockfileCacheMax: z.coerce.number().default(500),
 	lockfileCacheTtlMs: z.coerce.number().default(36e5),
@@ -17220,7 +17678,7 @@ const configSchema = baseSchema.superRefine((data, ctx) => {
 const packagingConfigSchema = baseSchema.superRefine(refineStorageShape);
 /**
 * Env-var definition for the orchestrator. Exported so the docs generator and
-* the deploy-stg pre-validator can re-parse without going through process.env.
+* config pre-validation can re-parse without going through process.env.
 *
 * Note: passes the inner `baseSchema` (a ZodObject) so describe() can walk
 * `.shape`, but uses the outer `configSchema` (with .superRefine) as the parser
@@ -17468,8 +17926,8 @@ const COLD_STORE_ENV_VARS = [
 	"KICI_COLD_STORE_EVENT_LOG_ENABLED"
 ];
 /**
-* Deployment-identity env vars injected by the installer (and the staging
-* deploy) so the orchestrator can report its own deployment shape in
+* Deployment-identity env vars injected by the installer (or other deploy
+* tooling) so the orchestrator can report its own deployment shape in
 * `source.register`. Read directly from `process.env` by the deployment reader,
 * not threaded through the AppConfig schema — registered here so the
 * unknown-KICI_* validator at boot doesn't reject them.
@@ -17847,7 +18305,8 @@ var S3CacheStorage = class {
 * Signature input: `${method}:${key}:${expiresUnixMs}` with HMAC-SHA256 keyed
 * by a per-orchestrator-process secret (random 32-byte hex at boot, persists
 * for the lifetime of the process). Tokens become invalid on orchestrator
-* restart — fine for the filesystem backend's E2E / single-host use case.
+* restart — fine for the filesystem backend's single-host / test-sandbox use
+* case.
 */
 /** Default URL lifetime: 1 hour (matches S3 backend's PUT-URL lifetime). */
 const DEFAULT_SIGN_URL_TTL_MS = 36e5;
@@ -17883,7 +18342,7 @@ function signToken(secret, method, key, ttlMs = DEFAULT_SIGN_URL_TTL_MS) {
 * are replaced by HMAC-signed `http://<orchUrl>/api/v1/cache/blob/...` URLs
 * — see `sign-url.ts` for the token mechanics and `app.ts` for the route.
 *
-* Intended for single-host deployments and E2E sandboxes where standing up
+* Intended for single-host deployments and test sandboxes where standing up
 * an S3-compatible service is overkill. Production should still use S3.
 *
 * Metadata is co-located as a sibling JSON file (`<key>.meta.json`) so the
@@ -18153,7 +18612,7 @@ function createCacheStorage(config) {
 //#region src/provenance/trust-root.ts
 /**
 * Derive the JWKS URI for a provenance OIDC issuer. Identical to the Platform's
-* own derivation (`packages/platform/src/dashboard/routes/runs.ts`) so a bundle
+* own derivation so a bundle
 * verified client-side and at ingest resolve the same key set.
 */
 function deriveJwksUri(issuer) {
@@ -18662,7 +19121,7 @@ var OrchestratorSigningKeyRepo = class {
 * The in-memory private key is imported NON-EXTRACTABLE (`extractable: false`),
 * so once loaded the raw private material can never be read back out of the
 * process — the only export path is the public JWK. This is what makes the
-* private key "non-exportable by design" (design spec § A / § H).
+* private key "non-exportable by design".
 */
 /** AAD binding the wrapped private JWK to its purpose (AES-GCM authenticated data). */
 const SIGNING_KEY_AAD = "orchestrator-signing-key";
@@ -18775,8 +19234,7 @@ var DbSigner = class DbSigner {
 //#region src/cli/commands/signing-key.ts
 /**
 * `kici-admin signing-key` — orchestrator-owned provenance signing key
-* management (orchestrator DB plane; classified `kici-admin` per
-* .claude/rules/platform-admin.md).
+* management (orchestrator DB plane, so it belongs to `kici-admin`).
 *
 *   signing-key list                      List keys (kid / status / created_at).
 *                                         Reads the database when a database URL
@@ -19317,6 +19775,41 @@ function encryptPrivateKey(privateKey, secretKey) {
 }
 createLogger({ prefix: "job-secret-seal" });
 runtimeLabel(RuntimeFact.enum.docker), runtimeLabel(RuntimeFact.enum.podman);
+//#endregion
+//#region src/helpers/run-detached.ts
+/**
+* Running work that nothing awaits.
+*
+* A promise that nobody awaits and nobody catches becomes an unhandled
+* rejection when it fails, and the orchestrator's shutdown hook treats an
+* unhandled rejection as fatal: one failed query in a timer tick or a message
+* handler would stop the whole process. `runDetached` runs such work and logs
+* its failure instead. ESLint's `no-floating-promises` (with `ignoreVoid:
+* false`) refuses a bare or `void`-ed promise anywhere in this package, so
+* detached work runs through here or carries its own `.catch`.
+*/
+/**
+* Run `work` without waiting for it. A throw, or a rejection of the promise it
+* returns, is logged at error level as `<task> failed` with `context` and the
+* error message, and goes no further. `context` is read when the failure is
+* logged, so the work may fill it in while it runs.
+*/
+function runDetached(logger, task, work, context = {}) {
+	const fail = (err) => {
+		logger.error(`${task} failed`, {
+			...context,
+			error: toErrorMessage(err)
+		});
+	};
+	let outcome;
+	try {
+		outcome = work();
+	} catch (err) {
+		fail(err);
+		return;
+	}
+	Promise.resolve(outcome).catch(fail);
+}
 createLogger({ prefix: "instance-heartbeat" });
 createLogger({ prefix: "job-queue" });
 /**
@@ -19485,7 +19978,7 @@ function renderTable$1(headers, rows) {
 }
 function registerEventLogCommands(program, getClient) {
 	const eventLog = program.command("event-log").description("Inspect the inbound webhook delivery log");
-	eventLog.command("list").description("List inbound webhook deliveries (dogfooded via /api/v1/admin/event-log)").option("--org <orgId>", "Filter by org/tenant ID").option("--routing-key <key>", "Filter by routing key (e.g. github:42)").option("--event <type>", "Filter by event type (e.g. push, pull_request)").option("--action <action>", "Filter by event action (e.g. opened, closed, synchronize for pull_request)").option("--status <s>", "Filter by outcome status (received|shed|processed|duplicate|lockfile_missing|lockfile_corrupt|failed)").option("--from <ts>", "ISO timestamp lower bound (inclusive)").option("--to <ts>", "ISO timestamp upper bound (exclusive)").option("--delivery-id <substr>", "Substring filter on delivery_id").option("--limit <n>", "Max results (default 50, max 200)", "50").option("--offset <n>", "Skip first N results", "0").option("--include-archived", "Merge cold-store archived rows into the result (requires --routing-key for cold scoping)").option("--json", "Emit raw JSON instead of a table").action(async (opts) => {
+	eventLog.command("list").description("List inbound webhook deliveries (admin API: /api/v1/admin/event-log)").option("--org <orgId>", "Filter by org/tenant ID").option("--routing-key <key>", "Filter by routing key (e.g. github:42)").option("--event <type>", "Filter by event type (e.g. push, pull_request)").option("--action <action>", "Filter by event action (e.g. opened, closed, synchronize for pull_request)").option("--status <s>", "Filter by outcome status (received|shed|processed|duplicate|lockfile_missing|lockfile_corrupt|failed)").option("--from <ts>", "ISO timestamp lower bound (inclusive)").option("--to <ts>", "ISO timestamp upper bound (exclusive)").option("--delivery-id <substr>", "Substring filter on delivery_id").option("--limit <n>", "Max results (default 50, max 200)", "50").option("--offset <n>", "Skip first N results", "0").option("--include-archived", "Merge cold-store archived rows into the result (requires --routing-key for cold scoping)").option("--json", "Emit raw JSON instead of a table").action(async (opts) => {
 		try {
 			const response = await getClient().listEventLog({
 				orgId: opts.org,
@@ -19599,7 +20092,7 @@ function renderTable(headers, rows) {
 }
 function registerAccessLogCommands(program, getClient) {
 	const accessLog = program.command("access-log").description("Inspect the read / admin-mutation access log");
-	accessLog.command("list").description("List access-log rows (dogfooded via /api/v1/admin/access-log)").option("--org-id <orgId>", "Filter by org/tenant ID").option("--actor-type <t>", "Filter by actor type (user|api_key|service_account|platform_operator|system)").option("--actor-id <id>", "Filter by actor id (zsub, keyId, service_account id, ...)").option("--action <action>", "Filter by dotted action (e.g. run.detail.read, run.cancel)").option("--source <s>", "Filter by source (platform_proxy|admin_http|admin_cli)").option("--outcome <o>", "Filter by outcome (allowed|denied|error)").option("--target-type <t>", "Filter by target type (run|step|event_log|secret_scope|...)").option("--target-id <id>", "Filter by target id").option("--from <ts>", "ISO timestamp lower bound (inclusive)").option("--to <ts>", "ISO timestamp upper bound (exclusive)").option("--q <text>", "Filter by substring of error_message (trigram-indexed full-text search)").option("--agent-label <label>", "Filter by exact agent label").option("--agent-only", "Only agent-attributed rows").option("--limit <n>", "Max results (default 50, max 200)", "50").option("--cursor <c>", "Opaque cursor from a previous nextCursor").option("--json", "Emit raw JSON instead of a table").action(async (opts) => {
+	accessLog.command("list").description("List access-log rows (admin API: /api/v1/admin/access-log)").option("--org-id <orgId>", "Filter by org/tenant ID").option("--actor-type <t>", "Filter by actor type (user|api_key|service_account|platform_operator|system)").option("--actor-id <id>", "Filter by actor id (zsub, keyId, service_account id, ...)").option("--action <action>", "Filter by dotted action (e.g. run.detail.read, run.cancel)").option("--source <s>", "Filter by source (platform_proxy|admin_http|admin_cli)").option("--outcome <o>", "Filter by outcome (allowed|denied|error)").option("--target-type <t>", "Filter by target type (run|step|event_log|secret_scope|...)").option("--target-id <id>", "Filter by target id").option("--from <ts>", "ISO timestamp lower bound (inclusive)").option("--to <ts>", "ISO timestamp upper bound (exclusive)").option("--q <text>", "Filter by substring of error_message (trigram-indexed full-text search)").option("--agent-label <label>", "Filter by exact agent label").option("--agent-only", "Only agent-attributed rows").option("--limit <n>", "Max results (default 50, max 200)", "50").option("--cursor <c>", "Opaque cursor from a previous nextCursor").option("--json", "Emit raw JSON instead of a table").action(async (opts) => {
 		try {
 			const response = await getClient().listAccessLog({
 				orgId: opts.orgId,
@@ -20268,6 +20761,16 @@ function registerInspectBundleCommand(program) {
 //#endregion
 //#region src/cli/service/entrypoint.ts
 /**
+* Resolves the command a service unit should run.
+*
+* A `npm install -g kici-admin` install exposes only the `kici-admin` /
+* `kici-agent` CLI bins — the long-running orchestrator and agent servers are
+* separate module entry points (`dist/server.js` / `dist/standalone.js`) that
+* must be launched with `node <script>`. These helpers turn an install's
+* options into the `{ executablePath, args }` pair the platform service
+* managers write into the unit's run command.
+*/
+/**
 * Pick the orchestrator server entry from an env file's `KICI_MODE`.
 * `independent` runs the standalone server; `platform` / `hybrid` / unset run
 * the Platform-connected server.
@@ -20292,6 +20795,34 @@ function resolveServiceExecutable(opts) {
 		args: [opts.entryScript]
 	};
 }
+/**
+* The path of a server entry script installed beside this CLI, for a service
+* that runs `node <script>`. `resolve` is the calling module's
+* `import.meta.resolve`, or undefined where the CLI has none: a kici-admin from a
+* standalone package is a single CommonJS bundle that carries no orchestrator
+* or agent server. Either way the error names `--binary`, the launcher the
+* service runs instead.
+*/
+function resolveServerScript(specifier, component, resolve) {
+	let cause = NO_RESOLVER;
+	if (resolve) try {
+		return fileURLToPath(resolve(specifier));
+	} catch (err) {
+		cause = err instanceof Error ? err.message : String(err);
+	}
+	throw new Error(missingServerMessage(component, specifier, cause));
+}
+/**
+* Refuse an install without `--binary` on a kici-admin that cannot resolve
+* installed packages, before the wizard runs or any file is written.
+*/
+function assertServerResolvable(component, binary, resolve) {
+	if (binary === void 0 && resolve === void 0) throw new Error(missingServerMessage(component, `@kici-dev/${component}`, NO_RESOLVER));
+}
+const NO_RESOLVER = "this kici-admin cannot resolve installed packages";
+function missingServerMessage(component, specifier, cause) {
+	return `kici-admin cannot find the ${component} server (${specifier}): ${cause}. Pass --binary with the path of the ${component} launcher, such as the one in a standalone ${component} package.`;
+}
 //#endregion
 //#region src/cli/service/deploy-env.ts
 init_compose_path();
@@ -20370,6 +20901,11 @@ async function waitForQuiesce(poll, opts) {
 	}
 }
 /**
+* What a version switch prints when it cannot read the live migration ledger,
+* so it could not compare the schema to the recorded head.
+*/
+const SCHEMA_NOT_CHECKED = "The running service could not be reached, so the schema was not checked.";
+/**
 * The last applied migration reported by a running service.
 *
 * Returns null when nothing has been applied — a fresh database — which the
@@ -20389,17 +20925,18 @@ function migrationsAfter(rows, head) {
 * Decide whether the version pointer may move.
 *
 * Three outcomes, and the middle one is the compatibility shim: an instance
-* installed before `migrationHeads` existed has no recorded head, and refusing
-* there would break the documented `--rollback` on exactly the installs that
-* predate the guard. So an unknown head warns loudly and falls through to the
-* existing confirmation prompt; the map is populated at the next version
-* change, arming the guard one upgrade later.
+* installed before `migrationHeads` existed, or one whose upgrade away from the
+* target ran without admin access, has no recorded head, and refusing there
+* would break the documented `--rollback` on exactly those installs. So an
+* unknown head warns loudly and falls through to the existing confirmation
+* prompt; the map is populated at the next version change with admin access,
+* arming the guard one upgrade later.
 */
 function schemaGuardVerdict(input) {
 	const { targetVersion, recordedHead, liveRows } = input;
 	if (!recordedHead) return {
 		kind: "unknown-head",
-		message: `WARNING: no migration head is recorded for ${targetVersion}.\n  This instance was installed before the schema guard existed, so it cannot be\n  checked whether the database is ahead of that version. If it is, the older\n  binary will refuse to boot with "corrupted migrations" and restart in a loop.\n  Take a dump first ("kici-admin db backup"). If the switch does loop, start the\n  older version with KICI_AUTO_MIGRATE=false — it boots only if every newer\n  migration was purely additive.\n  The head is recorded from this version change on, so the guard is armed for\n  the next one.`
+		message: `WARNING: no migration head is recorded for ${targetVersion}.\n  Either this instance was installed before the schema guard existed, or the\n  upgrade away from ${targetVersion} ran without admin access (KICI_ADMIN_TOKEN).\n  So it cannot be checked whether the database is ahead of that version. If it\n  is, the older binary will refuse to boot with "corrupted migrations" and\n  restart in a loop.\n  Take a dump first ("kici-admin db backup"). If the switch does loop, start the\n  older version with KICI_AUTO_MIGRATE=false — it boots only if every newer\n  migration was purely additive.\n  A version change with admin access records the head, which arms the guard\n  for the next one.`
 	};
 	const live = appliedHead(liveRows);
 	if (live === null || live === recordedHead) return { kind: "ok" };
@@ -20486,8 +21023,7 @@ async function resolveUpgradeTarget(args) {
 	return {
 		config: {
 			name: resolved.manifest.name,
-			displayName: `KiCI ${component}`,
-			description: `KiCI ${component} service`,
+			...SERVICE_TEXT[component],
 			executablePath: "",
 			envFilePath: resolved.manifest.envFilePath,
 			workingDirectory: resolved.manifest.configDir,
@@ -20522,8 +21058,8 @@ async function downloadArchive(url, destPath) {
 * Install base for a KiCI component instance.
 *
 * 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:
+* production orchestrator and a test orchestrator on the same host) 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>\
@@ -20575,10 +21111,73 @@ function checkPickFlagConflicts(opts) {
 	if (conflicts.length === 0) return null;
 	return `--pick cannot be combined with ${conflicts.join(", ")}. --pick activates an already-installed version; it never downloads or takes an explicit version.`;
 }
+/**
+* Point the Windows service at `launcherPath`. sc.exe has no "update binary
+* path", so `install` replaces the registration: it checks the new launch
+* command first, then removes the old service and waits until it is gone
+* before it creates the new one. A launch command it refuses leaves the old
+* registration in place.
+*/
+async function reregisterWindowsService(manager, config, launcherPath) {
+	config.executablePath = launcherPath;
+	await manager.install(config);
+}
 /** Check if the platform is Windows. */
 function isWindows(platform) {
 	return platform === "windows";
 }
+/**
+* Refuse to point a Windows service at a release from before KICI_ENV_FILE.
+* Every caller runs it before it stops the service, so a refused switch leaves
+* the service registered and running as it was.
+*/
+function assertWindowsLaunchReadsEnvFile(args) {
+	if (launchReadsEnvFile(args.launch)) return;
+	throw new Error(`refusing to ${args.action}: ${envFileRefusal(args.release, args.config.envFilePath)} The service was not changed.`);
+}
+/**
+* Stop the service, register it again on Windows, then start it: the restart
+* every npm-source upgrade ends with.
+*
+* `npm install -g` replaces the package in place, so the launch command the
+* service runs (`spec`, read back from its registration) stays valid. On
+* Windows the registration around that command (the service wrapper's
+* arguments, the description, the recovery settings) is whatever the CLI that
+* installed it wrote, so `install` writes the current one, as the archive
+* upgrade does. A launch command that names a file that does not exist was
+* read back wrong, so it is not registered: the service restarts as it was,
+* with a warning. systemd and launchd keep their unit as it is.
+*/
+async function restartOntoInstalledPackage(args) {
+	const { manager, config, platform, spec } = args;
+	const component = config.component ?? "orchestrator";
+	const read = spec ? {
+		executablePath: spec.execPath,
+		args: spec.args
+	} : null;
+	const launch = read && fs.existsSync(read.executablePath) && fs.existsSync(launchedRelease(read)) ? read : null;
+	if (isWindows(platform) && launch) assertWindowsLaunchReadsEnvFile({
+		launch,
+		release: launchedRelease(launch),
+		action: `restart "${config.name}" onto the installed package`,
+		config
+	});
+	if ((await manager.status(config)).state === "running") await manager.stop(config);
+	if (isWindows(platform)) {
+		if (launch) {
+			try {
+				await manager.install({
+					...config,
+					...launch
+				});
+			} catch (err) {
+				throw new Error(`could not register the service again: ${toErrorMessage(err)}. Run \`kici-admin ${component} install\` for it.`, { cause: err });
+			}
+			console.log("Service registration rewritten from the current installer.");
+		} else console.warn(`Warning: the service was not registered again, because its launch command could not be read, or names a file that does not exist. Run \`kici-admin ${component} install\` for it to apply the current registration.`);
+	}
+	await manager.start(config);
+}
 /** Get the launcher script name for a component. */
 function getLauncherName(component, platform) {
 	const baseName = component === "orchestrator" ? "kici-orchestrator-standalone" : "kici-agent";
@@ -20599,6 +21198,45 @@ function extractArchive(archivePath, destDir) {
 	return dirs[0];
 }
 /**
+* Extract a release archive into `tmpDir` and return the release folder in it.
+* On Windows a release from before KICI_ENV_FILE is refused here, before
+* anything is copied into the install base or the service is stopped.
+*/
+function extractRelease(args) {
+	const { archivePath, tmpDir, component, platform, version, config } = args;
+	const extractDir = path.join(tmpDir, "extract");
+	const srcDir = path.join(extractDir, extractArchive(archivePath, extractDir));
+	if (isWindows(platform)) assertWindowsLaunchReadsEnvFile({
+		launch: { executablePath: path.join(srcDir, getLauncherName(component, platform)) },
+		release: `version ${version}`,
+		action: `upgrade "${config.name}" to ${version}`,
+		config
+	});
+	return srcDir;
+}
+/**
+* Put the release in `archivePath` at `versionedDirPath`. The release is
+* extracted and checked first ({@link extractRelease}); only then is a folder
+* already at `versionedDirPath` removed, which the caller allows with
+* `--force`, and the release copied in. A refused release leaves the install
+* base as it was.
+*/
+function installRelease(args) {
+	const { installBase, versionedDirPath, platform } = args;
+	const srcDir = extractRelease(args);
+	if (fs.existsSync(versionedDirPath)) {
+		console.log(`Removing existing directory ${versionedDirPath} (--force)`);
+		fs.rmSync(versionedDirPath, {
+			recursive: true,
+			force: true
+		});
+	}
+	fs.mkdirSync(installBase, { recursive: true });
+	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}`);
+}
+/**
 * List installed versions for a component by scanning the install base directory
 * for directories matching `{component}-{version}/`.
 */
@@ -20747,18 +21385,87 @@ function planNpmSourceUpgrade(opts) {
 		version: requestedVersion
 	};
 }
+/**
+* The cmd.exe command line for npm on Windows. npm is a batch file there, which
+* Node.js starts only through a shell, and Node.js joins the parts of a shell
+* command with spaces and quotes none of them. The standard Node.js install is
+* under `C:\Program Files`, so the npm path is quoted here. An argument with a
+* character outside those of a package name, a version or a flag is refused
+* rather than handed to cmd.exe.
+*/
+function windowsShellCommand(cmd, args) {
+	if (cmd.includes("\"")) throw new Error(`cannot run "${cmd}" through cmd.exe: the path holds a double quote`);
+	for (const arg of args) if (!/^[A-Za-z0-9@/._+-]+$/.test(arg)) throw new Error(`cannot pass "${arg}" to npm: it holds a character cmd.exe reads as syntax`);
+	return [`"${cmd}"`, ...args].join(" ");
+}
 const defaultSpawnRunner = (cmd, args, opts) => {
-	const r = spawnSync(cmd, args, {
+	const env = opts?.env ?? process.env;
+	const r = process.platform === "win32" ? spawnSync(windowsShellCommand(cmd, args), {
+		encoding: "utf-8",
+		shell: true,
+		env
+	}) : spawnSync(cmd, args, {
 		encoding: "utf-8",
-		shell: process.platform === "win32",
-		env: opts?.env ?? process.env
+		env
 	});
 	return {
 		status: r.status,
+		stdout: r.stdout ?? "",
 		stderr: (r.stderr ?? "") + (r.error ? String(r.error) : "")
 	};
 };
 /**
+* The environment npm runs in: the unit's pinned node first on PATH, because
+* npm derives its global prefix from the node that runs it.
+*/
+function npmEnv(target) {
+	const pinnedBinDir = path.dirname(target.nodeExecPath);
+	return {
+		...process.env,
+		PATH: `${pinnedBinDir}${path.delimiter}${process.env.PATH ?? ""}`
+	};
+}
+/**
+* Whether `version` of the KiCI packages reads KICI_ENV_FILE, asked of the
+* registry the unit's npm installs from. A release that reads it publishes the
+* env-file loader in `@kici-dev/shared`, which every KiCI package of the same
+* version depends on.
+*/
+function npmReleaseReadsEnvFile(target, version, run = defaultSpawnRunner) {
+	const res = run(target.npmPath, [
+		"view",
+		`@kici-dev/shared@${version}`,
+		"exports",
+		"--json"
+	], { env: npmEnv(target) });
+	if (res.status !== 0) return {
+		ok: false,
+		error: res.stderr.trim() || `npm view exited with ${res.status}`
+	};
+	const out = res.stdout.trim();
+	if (!out) return {
+		ok: true,
+		reads: false
+	};
+	let exportsMap;
+	try {
+		exportsMap = JSON.parse(out);
+	} catch {
+		return {
+			ok: false,
+			error: `npm view printed no JSON: ${out.slice(0, 200)}`
+		};
+	}
+	if (Array.isArray(exportsMap)) return {
+		ok: false,
+		error: `npm matched more than one version of @kici-dev/shared for ${version}; pass an exact --version`
+	};
+	return {
+		ok: true,
+		reads: typeof exportsMap === "object" && exportsMap !== null && "./load-service-env-file" in exportsMap
+	};
+}
+/**
 * Install `<owningPackage>@<version>` globally under the unit's own pinned node,
 * so it lands in exactly the global prefix the unit's ExecStart resolves from.
 *
@@ -20773,16 +21480,11 @@ const defaultSpawnRunner = (cmd, args, opts) => {
 * `run` seam is injected in tests.
 */
 function installGlobalPackage(target, version, run = defaultSpawnRunner) {
-	const pinnedBinDir = path.dirname(target.nodeExecPath);
-	const env = {
-		...process.env,
-		PATH: `${pinnedBinDir}${path.delimiter}${process.env.PATH ?? ""}`
-	};
 	const res = run(target.npmPath, [
 		"install",
 		"-g",
 		`${target.owningPackage}@${version}`
-	], { env });
+	], { env: npmEnv(target) });
 	return {
 		ok: res.status === 0,
 		stderr: res.stderr
@@ -20891,18 +21593,10 @@ async function performVersionedUpgrade(component, opts, hooks = {}) {
 		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 (fs.existsSync(versionedDirPath) && !opts.force) {
+			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`);
@@ -20935,13 +21629,21 @@ async function performVersionedUpgrade(component, opts, hooks = {}) {
 			}
 		}
 		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}`);
+		try {
+			installRelease({
+				archivePath,
+				tmpDir,
+				installBase,
+				versionedDirPath,
+				component,
+				platform,
+				version,
+				config
+			});
+		} catch (err) {
+			await cleanupTmpDir();
+			throw err;
+		}
 		const preStopHeads = await runPreStopSafety({
 			component,
 			opts,
@@ -20955,10 +21657,7 @@ async function performVersionedUpgrade(component, opts, hooks = {}) {
 		}
 		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);
+			await reregisterWindowsService(manager, config, launcherPath);
 			writeCurrentVersion(installBase, component, version);
 			console.log(`Service registration updated to ${launcherPath}`);
 		} else {
@@ -21023,17 +21722,36 @@ async function performNpmSourceUpgrade(component, config, resolvedInstance, mana
 		process.exit(1);
 	}
 	if (action.kind === "restart-only") {
-		await restartOnlyUpgrade(component, config, resolvedInstance, manager, action.verdict, opts);
+		await restartOnlyUpgrade({
+			component,
+			config,
+			resolvedInstance,
+			manager,
+			verdict: action.verdict,
+			opts,
+			platform,
+			spec
+		});
 		return;
 	}
-	await performSelfDrivingInstall(component, config, resolvedInstance, manager, action, opts);
+	await performSelfDrivingInstall({
+		component,
+		config,
+		resolvedInstance,
+		manager,
+		action,
+		opts,
+		platform,
+		spec
+	});
 }
 /**
 * Restart-only path: the operator pre-installed `@kici-dev/<pkg>@<version>` (or
 * kici-admin) themselves. Verify the unit will launch the invoking CLI's version,
 * restart onto it, and persist the manifest version.
 */
-async function restartOnlyUpgrade(component, config, resolvedInstance, manager, verdict, opts) {
+async function restartOnlyUpgrade(args) {
+	const { config, resolvedInstance, manager, verdict, opts, platform, spec } = args;
 	if (!verdict.ok) {
 		console.error(`Error: ${verdict.reason}`);
 		process.exit(1);
@@ -21048,8 +21766,12 @@ async function restartOnlyUpgrade(component, config, resolvedInstance, manager,
 		}
 	}
 	console.log("Restarting service onto the npm-installed package...");
-	if ((await manager.status(config)).state === "running") await manager.stop(config);
-	await manager.start(config);
+	await restartOntoInstalledPackage({
+		manager,
+		config,
+		platform,
+		spec
+	});
 	if (verdict.manifestVersion !== null) writeManifest(resolvedInstance.instanceDir, {
 		...resolvedInstance.manifest,
 		kiciVersion: verdict.manifestVersion
@@ -21062,8 +21784,15 @@ async function restartOnlyUpgrade(component, config, resolvedInstance, manager,
 * pinned node/npm, restart, and verify the unit now launches the requested
 * version.
 */
-async function performSelfDrivingInstall(component, config, resolvedInstance, manager, action, opts) {
+async function performSelfDrivingInstall(args) {
+	const { component, config, resolvedInstance, manager, action, opts, platform, spec } = args;
 	const { target, version } = action;
+	if (isWindows(platform)) {
+		const release = `${target.owningPackage}@${version}`;
+		const verdict = npmReleaseReadsEnvFile(target, version, args.run);
+		if (!verdict.ok) throw new Error(`could not check whether ${release} reads KICI_ENV_FILE: ${verdict.error}. The service and the installed package were not changed.`);
+		if (!verdict.reads) throw new Error(`refusing to install ${release} for "${config.name}": ${envFileRefusal(release, config.envFilePath)} The service and the installed package were not changed.`);
+	}
 	if (!opts.yes) {
 		console.log(`This will install ${target.owningPackage}@${version} using ${target.npmPath}`);
 		console.log(`  (node runtime: ${target.nodeExecPath}), then restart "${config.name}".`);
@@ -21074,7 +21803,7 @@ async function performSelfDrivingInstall(component, config, resolvedInstance, ma
 		}
 	}
 	console.log(`Installing ${target.owningPackage}@${version} under the unit's runtime...`);
-	const result = installGlobalPackage(target, version);
+	const result = installGlobalPackage(target, version, args.run);
 	if (!result.ok) {
 		const hint = /EACCES|permission denied|EPERM/i.test(result.stderr) ? " The unit's global prefix is not writable — re-run with privileges matching the unit's runtime." : "";
 		console.error(`Error: npm install failed for ${target.owningPackage}@${version}.${hint}`);
@@ -21082,8 +21811,12 @@ async function performSelfDrivingInstall(component, config, resolvedInstance, ma
 		process.exit(1);
 	}
 	console.log("Restarting service onto the freshly-installed package...");
-	if ((await manager.status(config)).state === "running") await manager.stop(config);
-	await manager.start(config);
+	await restartOntoInstalledPackage({
+		manager,
+		config,
+		platform,
+		spec
+	});
 	const newSpec = await manager.readLaunchSpec(config);
 	const launched = newSpec ? resolveVersionFromLaunchSpec(newSpec, component) : null;
 	if (launched !== version) {
@@ -21146,14 +21879,6 @@ async function handlePick(component, platform, installBase, config, manager, res
 	console.log(`Switched: ${current ?? "(unknown)"} -> ${target}`);
 }
 /**
-* Stop the service, switch the active version pointer to an already-installed
-* versioned directory (atomic symlink on Unix; uninstall→install + version file
-* on Windows), restart, and persist the new `kiciVersion` into the manifest.
-*
-* Shared by `--rollback` (switch to the previous version) and `--pick` (switch
-* to any chosen installed version).
-*/
-/**
 * Refuse a version switch whose target cannot boot against the current schema.
 *
 * `--rollback` and `--pick` both flip a version pointer, and the previous
@@ -21171,7 +21896,7 @@ async function assertSchemaAllowsSwitch(args) {
 	const rows = await readLiveMigrationRows(hooks.migrationStatus);
 	if (rows === null) {
 		console.log("");
-		console.log("  !!  The running service could not be reached, so the schema was not checked.");
+		console.log(`  !!  ${SCHEMA_NOT_CHECKED}`);
 		console.log("");
 		return yes ? true : confirm$1("Proceed with the switch anyway?");
 	}
@@ -21213,8 +21938,23 @@ async function assertSchemaAllowsSwitch(args) {
 	}
 	return true;
 }
+/**
+* Stop the service, switch the active version pointer to an already-installed
+* versioned directory (atomic symlink on Unix; re-registration + version file
+* on Windows), restart, and persist the new `kiciVersion` into the manifest.
+*
+* Shared by `--rollback` (switch to the previous version) and `--pick` (switch
+* to any chosen installed version).
+*/
 async function switchToInstalledVersion(args) {
 	const { component, platform, installBase, config, manager, resolvedInstance, targetVersion } = args;
+	const launcherPath = path.join(installBase, `${component}-${targetVersion}`, getLauncherName(component, platform));
+	if (isWindows(platform)) assertWindowsLaunchReadsEnvFile({
+		launch: { executablePath: launcherPath },
+		release: `version ${targetVersion}`,
+		action: `switch "${config.name}" to ${targetVersion}`,
+		config
+	});
 	if (!await assertSchemaAllowsSwitch({
 		component,
 		targetVersion,
@@ -21232,10 +21972,7 @@ async function switchToInstalledVersion(args) {
 		console.log("Service stopped.");
 	}
 	if (isWindows(platform)) {
-		const launcherPath = path.join(installBase, `${component}-${targetVersion}`, getLauncherName(component, platform));
-		config.executablePath = launcherPath;
-		await manager.uninstall(config);
-		await manager.install(config);
+		await reregisterWindowsService(manager, config, launcherPath);
 		writeCurrentVersion(installBase, component, targetVersion);
 		console.log(`Service registration updated to ${launcherPath}`);
 	} else {
@@ -21898,6 +22635,8 @@ Token vocabulary:
   \`kici-admin join\` to add another orchestrator as a peer to an existing cluster.
 `).option("--platform <type>", "Force the service platform (systemd, launchd, windows, compose). Default: detected from the host").option("--mode <mode>", `Operating mode written to the env file (${OrchestratorMode.options.join(", ")}). Naming it with --env-file overwrites the copied file's own KICI_MODE; omitting it leaves that value alone`, DEFAULT_INSTALL_MODE).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", "Run the interactive setup wizard (default on an interactive terminal)").option("--no-wizard", "Skip the wizard and write a stub env file to edit by hand").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, command) => {
 		try {
+			const resolveModule = typeof import.meta.resolve === "function" ? (specifier) => import.meta.resolve(specifier) : void 0;
+			assertServerResolvable("orchestrator", opts.binary, resolveModule);
 			if (opts.wizard === true && opts.envFile) {
 				console.error("Error: Cannot use --wizard with --env-file");
 				process.exit(1);
@@ -21930,7 +22669,7 @@ Token vocabulary:
 			})).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}.\n\nUpgrading this service? Don't re-run install — installing again is for first-time\nsetup, not upgrades. For an npm-global install run \`npm install -g kici-admin@latest\`\nthen \`kici-admin orchestrator restart\`; for a versioned-directory install run\n\`kici-admin orchestrator upgrade\`.\n\nInstalling a second, separate instance? Pass a different --name or --instance-dir,\nor --force to take over this one.`);
+				console.error(`Error: an orchestrator instance "${serviceName}" is already installed at ${at}.\n\nUpgrading this service? Don't re-run install — installing again is for first-time\nsetup, not upgrades. For an npm-global install run\n\`kici-admin orchestrator upgrade --version <version>\`; for a versioned-directory install\nrun \`kici-admin orchestrator upgrade --from <archive> --version <version>\`.\n\nInstalling a second, separate instance? Pass a different --name or --instance-dir,\nor --force to take over this one.`);
 				process.exit(1);
 			}
 			const configDir = getConfigDir(serviceName, userLevel);
@@ -21938,6 +22677,7 @@ Token vocabulary:
 			fs.mkdirSync(configDir, { recursive: true });
 			fs.mkdirSync(logDir, { recursive: true });
 			const envFilePath = path.join(configDir, `${serviceName}.env`);
+			if (platform === "windows" && !userLevel) restrictEnvFileAccess(envFilePath);
 			let devDbUrl;
 			if (opts.dev) {
 				devDbUrl = startDevPostgres(`${serviceName}-dev-pg`);
@@ -21971,7 +22711,7 @@ Token vocabulary:
 				envFilePath
 			});
 			fs.writeFileSync(envFilePath, upsertDeployEnvLines(fs.readFileSync(envFilePath, "utf-8"), deployLines), "utf-8");
-			const entryScript = opts.binary ? void 0 : fileURLToPath(import.meta.resolve(`@kici-dev/orchestrator/${selectServerEntry(fs.readFileSync(envFilePath, "utf-8"))}`));
+			const entryScript = opts.binary ? void 0 : resolveServerScript(`@kici-dev/orchestrator/${selectServerEntry(fs.readFileSync(envFilePath, "utf-8"))}`, "orchestrator", resolveModule);
 			const { executablePath, args } = resolveServiceExecutable({
 				binary: opts.binary ? path.resolve(opts.binary) : void 0,
 				nodePath: process.execPath,
@@ -21987,8 +22727,7 @@ Token vocabulary:
 			} catch {}
 			const config = {
 				name: serviceName,
-				displayName: "KiCI Orchestrator",
-				description: "KiCI CI/CD workflow orchestrator service",
+				...SERVICE_TEXT.orchestrator,
 				executablePath,
 				args,
 				nodeBinDir: path.dirname(process.execPath),
@@ -22001,7 +22740,7 @@ Token vocabulary:
 				restartPolicy: DEFAULT_RESTART_POLICY
 			};
 			await manager.install(config);
-			const manifestFile = writeManifest(instanceDir, {
+			const { file: manifestFile, warning: manifestWarning } = writeInstallManifest(instanceDir, {
 				component: "orchestrator",
 				name: serviceName,
 				platform,
@@ -22012,7 +22751,11 @@ Token vocabulary:
 				installBase: getInstallBase(platform, serviceName),
 				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 				kiciVersion: readKiciVersion()
+			}, {
+				execPath: executablePath,
+				args
 			});
+			if (manifestWarning) console.warn(`Warning: ${manifestWarning}`);
 			try {
 				appendIndexEntry(kiciRoot, {
 					component: "orchestrator",
@@ -22229,23 +22972,135 @@ function registerOrchestratorRestart(orchestrator) {
 	});
 }
 //#endregion
-//#region src/cli/commands/orchestrator-service/status.ts
-init_service();
-init_compose_path();
-/** Read the env file, or empty content when it is missing or unreadable. */
-function readEnvContent(envFilePath) {
+//#region src/cli/commands/service-health.ts
+/**
+* Reads a locally installed KiCI service's health endpoints and formats what
+* they report. `kici-admin orchestrator status` and `kici-admin agent status`
+* both render through here, so the two sections agree on layout and on how a
+* missing field is handled.
+*/
+/** How long a health request waits unless the caller passes its own timeout. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 3e3;
+/** Hex digits of a bundle hash to show: the length the build prints in its `deps:` line. */
+const SHORT_HASH_LENGTH = 12;
+/** Bind addresses that mean "every interface", reached on `localhost`. */
+const WILDCARD_HOSTS = /* @__PURE__ */ new Set([
+	"",
+	"0.0.0.0",
+	"::",
+	"[::]"
+]);
+/**
+* Read the env file, or empty content when it is missing or unreadable. A file
+* this account may not read is reported: the port and address the caller then
+* falls back to may not be the ones the service uses. On Windows only
+* LocalSystem and Administrators can read a service's env file.
+*/
+function readEnvContent(envFilePath, warn = console.warn) {
 	try {
-		return fs.existsSync(envFilePath) ? fs.readFileSync(envFilePath, "utf-8") : "";
-	} catch {
+		return fs.readFileSync(envFilePath, "utf-8");
+	} catch (err) {
+		const code = err.code;
+		if (code === "EACCES" || code === "EPERM") warn(`Warning: cannot read ${envFilePath} (${code}), so the default port and address are used. Run the command as an administrator, or as an account that can read the file.`);
 		return "";
 	}
 }
-/** Read the port from the service's env file (path from the manifest). */
-function readPortFromEnvFile$1(envFilePath) {
-	const value = readEnvValue(readEnvContent(envFilePath), "KICI_PORT");
-	const parsed = value === void 0 ? NaN : parseInt(value, 10);
-	return isNaN(parsed) ? 4e3 : parsed;
+/**
+* Where the service answers, read from its env file: `KICI_PORT` (or
+* `defaultPort`), `KICI_HOST` and `KICI_BASE_PATH`. A service bound to every
+* interface is reached on `localhost`; one bound to a single address is reached
+* there. The agent reads none of the last two, so its env file never sets them.
+*/
+function readLocalEndpoint(envContent, defaultPort) {
+	const portValue = readEnvValue(envContent, "KICI_PORT");
+	const port = portValue === void 0 ? NaN : parseInt(portValue, 10);
+	const bindHost = readEnvValue(envContent, "KICI_HOST")?.trim() ?? "";
+	const trimmedPath = (readEnvValue(envContent, "KICI_BASE_PATH")?.trim() ?? "").replace(/^\/+|\/+$/g, "");
+	return {
+		host: WILDCARD_HOSTS.has(bindHost) ? "localhost" : bindHost,
+		port: isNaN(port) ? defaultPort : port,
+		pathPrefix: trimmedPath === "" ? "" : `/${trimmedPath}`
+	};
+}
+/** The URL of `pathname` on `endpoint`, with an IPv6 host bracketed. */
+function localUrl(endpoint, pathname) {
+	return `http://${endpoint.host.includes(":") && !endpoint.host.startsWith("[") ? `[${endpoint.host}]` : endpoint.host}:${endpoint.port}${endpoint.pathPrefix}${pathname}`;
+}
+/**
+* GET a JSON body from a service on this host. `acceptStatuses` names the
+* non-2xx codes whose body is still an answer: `/ready` returns its checks
+* with a 503 when one fails. Returns null when nothing answers in time.
+*/
+async function fetchLocalJson(endpoint, pathname, opts = {}) {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+	try {
+		const res = await fetch(localUrl(endpoint, pathname), { signal: controller.signal });
+		if (!res.ok && !(opts.acceptStatuses ?? []).includes(res.status)) return null;
+		return await res.json();
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+/**
+* A `/health` body with its deprecated `buildCommit` replaced by its version.
+* A service older than this CLI reports a commit ID from KiCI's private
+* repository there, which a reader cannot resolve; `--json` keeps the key, a
+* string as before, and carries the release version in it. A body that reports
+* no `buildCommit` comes back unchanged.
+*/
+function hideBuildCommit(health) {
+	if (!("buildCommit" in health)) return health;
+	return {
+		...health,
+		buildCommit: health.version ?? "unknown"
+	};
 }
+/**
+* Rows for the build fingerprint and process uptime of a `/health` body. A
+* field the body lacks is skipped, so a service older than this CLI renders
+* the fields it does report. The version line never shows `buildCommit`
+* (see {@link hideBuildCommit}).
+*/
+function buildInfoRows(health) {
+	const rows = [];
+	if (health.version) rows.push(["Version", health.buildDate ? `${health.version} (built ${health.buildDate})` : health.version]);
+	if (health.sdkVersion) rows.push(["SDK", health.sdkBundleHash ? `${health.sdkVersion} (bundle ${health.sdkBundleHash.slice(0, SHORT_HASH_LENGTH)})` : health.sdkVersion]);
+	if (typeof health.uptime === "number") rows.push(["Uptime", formatUptime(Math.floor(health.uptime))]);
+	return rows;
+}
+/**
+* A status section: a blank separator line, the heading, then one line per
+* row with each value starting at `valueColumn`. A body with no field this CLI
+* recognises still gets a line saying so, so the heading never stands alone.
+*/
+function formatHealthSection(heading, rows, valueColumn) {
+	return [
+		"",
+		heading,
+		...(rows.length > 0 ? rows : [["Health", "answered, with no fields this CLI recognises"]]).map(([label, value]) => `${label}:`.padEnd(valueColumn) + value)
+	];
+}
+//#endregion
+//#region src/cli/commands/orchestrator-service/status.ts
+init_service();
+init_compose_path();
+/** Time `/ready` gets beyond the database-pool acquire timeout, for its query and its response. */
+const READINESS_MARGIN_MS = 3e3;
+/**
+* How long to wait for `/ready`. Its database check waits up to the pool's
+* acquire timeout before it reports `database: false`, so the wait covers that
+* timeout plus a margin. An acquire timeout of 0 lets the pool wait without
+* limit; the default then bounds the wait.
+*/
+function readinessTimeoutMs(envContent) {
+	const configured = Number(readEnvValue(envContent, "KICI_DB_POOL_ACQUIRE_TIMEOUT_MS"));
+	return (Number.isFinite(configured) && configured > 0 ? configured : DB_POOL_ACQUIRE_TIMEOUT_DEFAULT_MS) + READINESS_MARGIN_MS;
+}
+/** Column the values of the orchestrator section start at. */
+const VALUE_COLUMN$1 = 12;
 /** The scaler config the env file names, by path first and directory second. */
 function readScalerConfig(envContent) {
 	return readEnvValue(envContent, "KICI_SCALER_CONFIG_PATH") ?? readEnvValue(envContent, "KICI_SCALER_CONFIG_DIR");
@@ -22266,21 +23121,14 @@ function formatConfigPaths(args) {
 	if (args.platform === "compose") lines.push(`Compose file:  ${composeFilePath(args.envFilePath, args.serviceName)}`);
 	return lines;
 }
-/** 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;
-	}
+/** `yes` when every readiness check passed, otherwise `no` and the failing checks. */
+function formatReadiness(readiness) {
+	if (readiness.status === ReadinessStatus.Ready) return "yes";
+	const failing = Object.entries(readiness.checks ?? {}).filter(([, passed]) => !passed).map(([name]) => name);
+	return failing.length > 0 ? `no (failing: ${failing.join(", ")})` : "no";
 }
 /** Format the status output as a readable table. */
-function formatStatus$1(serviceStatus, health, serviceName) {
+function formatStatus$1(serviceStatus, health, readiness, serviceName) {
 	const lines = [];
 	lines.push(`Service: ${serviceName}`);
 	lines.push(`State:   ${serviceStatus.state}`);
@@ -22288,18 +23136,11 @@ function formatStatus$1(serviceStatus, health, serviceName) {
 	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`);
+		const rows = [];
+		if (health.status) rows.push(["Health", health.status]);
+		rows.push(["Ready", readiness ? formatReadiness(readiness) : "unknown (/ready did not answer)"]);
+		rows.push(...buildInfoRows(health));
+		lines.push(...formatHealthSection("--- KiCI orchestrator ---", rows, VALUE_COLUMN$1));
 	} else if (serviceStatus.state === "running") {
 		lines.push("");
 		lines.push("(Could not reach health API)");
@@ -22307,12 +23148,13 @@ function formatStatus$1(serviceStatus, health, serviceName) {
 	return lines.join("\n");
 }
 /** Build JSON output combining service + health data. */
-function buildJsonOutput$1(serviceStatus, health, serviceName, configPaths) {
+function buildJsonOutput$1(serviceStatus, health, readiness, serviceName, configPaths) {
 	return {
 		service: serviceName,
 		...serviceStatus,
 		configPaths,
-		health: health ?? void 0
+		health: health ? hideBuildCommit(health) : void 0,
+		readiness: readiness ?? void 0
 	};
 }
 function registerStatusCommand(parent) {
@@ -22351,14 +23193,21 @@ function registerStatusCommand(parent) {
 				envContent
 			});
 			let health = null;
-			if (serviceStatus.state === "running") health = await queryHealth$1(readPortFromEnvFile$1(config.envFilePath));
+			let readiness = null;
+			if (serviceStatus.state === "running") {
+				const endpoint = readLocalEndpoint(envContent, ORCHESTRATOR_DEFAULT_PORT);
+				[health, readiness] = await Promise.all([fetchLocalJson(endpoint, "/health"), fetchLocalJson(endpoint, "/ready", {
+					acceptStatuses: [503],
+					timeoutMs: readinessTimeoutMs(envContent)
+				})]);
+			}
 			const jsonConfigPaths = { envFile: config.envFilePath };
 			const scalerPath = readScalerConfig(envContent);
 			if (scalerPath) jsonConfigPaths.scalerConfig = scalerPath;
 			if (installPlatform === "compose") jsonConfigPaths.composeFile = composeFilePath(config.envFilePath, config.name);
-			if (opts.json) console.log(JSON.stringify(buildJsonOutput$1(serviceStatus, health, config.name, jsonConfigPaths), null, 2));
+			if (opts.json) console.log(JSON.stringify(buildJsonOutput$1(serviceStatus, health, readiness, config.name, jsonConfigPaths), null, 2));
 			else {
-				console.log(formatStatus$1(serviceStatus, health, config.name));
+				console.log(formatStatus$1(serviceStatus, health, readiness, config.name));
 				console.log("");
 				console.log(configPathLines.join("\n"));
 			}
@@ -22525,6 +23374,26 @@ function resolveDatabaseUrl$2(envFilePath, readFile) {
 	return url;
 }
 //#endregion
+//#region src/agent-packaging/node-runtime-members.ts
+/**
+* The members of an official Node.js Linux or macOS archive that a KiCI payload
+* vendors, relative to the archive's `node-v<version>-<os>-<arch>/` directory:
+* the `node` binary, the `npm` and `npx` launchers, and the bundled npm package.
+* With them in place, the agent's `resolveNpm()` finds
+* `<nodeDir>/../lib/node_modules/npm/bin/npm-cli.js` beside the vendored `node`,
+* so the builder role needs no npm on the host.
+*
+* This module has no imports so that repository tooling can read the list:
+* `scripts/lib/node-dist.mjs` (the standalone package builder) keeps its own
+* copy, and its test pins the two lists equal.
+*/
+const NODE_RUNTIME_MEMBERS = [
+	"bin/node",
+	"bin/npm",
+	"bin/npx",
+	"lib/node_modules/npm"
+];
+//#endregion
 //#region src/agent-packaging/node-binary.ts
 /**
 * Fetch a Node dist URL, retrying transient failures. The runtime download is a
@@ -22583,12 +23452,7 @@ async function downloadNodeBinary(opts) {
 	const archivePath = path.join(prefixDir, filename);
 	writeFileSync(archivePath, buf);
 	const inner = `node-v${opts.version}-${nodeOs}-${nodeArch}`;
-	const members = [
-		`${inner}/bin/node`,
-		`${inner}/bin/npm`,
-		`${inner}/bin/npx`,
-		`${inner}/lib/node_modules/npm`
-	];
+	const members = NODE_RUNTIME_MEMBERS.map((member) => `${inner}/${member}`);
 	const out = $.sync({
 		nothrow: true,
 		stdio: "pipe"
@@ -22807,7 +23671,7 @@ init_manifest();
 const ALL_PLATFORMS = AgentPlatform.options;
 /** The orchestrator's own version (single-version invariant) = the packaged agent version. */
 function resolveKiciVersion() {
-	return "0.11.0";
+	return "0.12.0";
 }
 /** Parse the --platform value: default set | single | CSV | `all`. */
 function parsePlatforms(raw) {
@@ -22991,6 +23855,17 @@ function registerOrchestratorServiceCommands(program, getClient, tryGetClient) {
 	registerOrchestratorDrain(orchestrator, getClient);
 }
 //#endregion
+//#region src/cli/commands/agent-service/agent-env.ts
+/** Render the env file, one `KEY=value` line per field that was given. */
+function renderAgentEnvFile(fields) {
+	const lines = [fields.header];
+	if (fields.orchestratorUrl) lines.push(`KICI_ORCHESTRATOR_URL=${fields.orchestratorUrl}`);
+	if (fields.token) lines.push(`KICI_AGENT_TOKEN=${fields.token}`);
+	if (fields.labels && fields.labels.length > 0) lines.push(`KICI_LABELS=${fields.labels.join(",")}`);
+	if (fields.port !== void 0) lines.push(`KICI_PORT=${fields.port}`);
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
 //#region src/cli/wizard/agent-wizard.ts
 var agent_wizard_exports = /* @__PURE__ */ __exportAll({ runAgentWizard: () => runAgentWizard });
 /**
@@ -23011,13 +23886,13 @@ async function runAgentWizard() {
 	const agentToken = await promptSecret("Agent authentication token:");
 	console.log("");
 	const labels = (await input({
-		message: "Agent labels (comma-separated, empty = accept all jobs):",
+		message: "Agent labels (comma-separated; empty = only the kici:* labels every agent reports):",
 		default: ""
 	})).split(",").map((l) => l.trim()).filter(Boolean);
 	console.log("");
 	console.log("Configuration complete. Summary:");
 	console.log(`  Orchestrator: ${orchestratorUrl}`);
-	console.log(`  Labels:       ${labels.length > 0 ? labels.join(", ") : "(none - accepts all jobs)"}`);
+	console.log(`  Labels:       ${labels.length > 0 ? labels.join(", ") : "(none; only the kici:* labels every agent reports)"}`);
 	console.log("");
 	return {
 		orchestratorUrl,
@@ -23031,13 +23906,26 @@ var init_agent_wizard = __esmMin((() => {
 //#endregion
 //#region src/cli/commands/agent-service/install.ts
 init_service();
+/** `--port` as a TCP port number; exits with an error for anything else. */
+function parsePort(value) {
+	if (value === void 0) return void 0;
+	const port = /^\d+$/.test(value) ? Number(value) : NaN;
+	if (!(port >= 1 && port <= 65535)) {
+		console.error(`Error: --port must be a TCP port between 1 and 65535 (got "${value}")`);
+		process.exit(1);
+	}
+	return port;
+}
 function registerAgentInstall(agent) {
-	agent.command("install").description("Install the agent as a system service").option("--platform <type>", "Force the service platform (systemd, launchd, windows, compose). Default: detected from the host").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) => {
+	agent.command("install").description("Install the agent as a system service").option("--platform <type>", "Force the service platform (systemd, launchd, windows, compose). Default: detected from the host").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("--port <port>", `HTTP port for the agent's health and metrics endpoints; each agent on one host needs its own (default: ${AGENT_DEFAULT_PORT})`).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 {
+			const resolveModule = typeof import.meta.resolve === "function" ? (specifier) => import.meta.resolve(specifier) : void 0;
+			assertServerResolvable("agent", opts.binary, resolveModule);
 			if (opts.wizard && opts.envFile) {
 				console.error("Error: Cannot use --wizard with --env-file");
 				process.exit(1);
 			}
+			const port = parsePort(opts.port);
 			const platform = detectPlatform(opts.platform);
 			const userLevel = resolveUserLevel(opts);
 			const serviceName = opts.name;
@@ -23063,14 +23951,17 @@ function registerAgentInstall(agent) {
 			fs.mkdirSync(configDir, { recursive: true });
 			fs.mkdirSync(logDir, { recursive: true });
 			const envFilePath = path.join(configDir, `${serviceName}.env`);
+			if (platform === "windows" && !userLevel) restrictEnvFileAccess(envFilePath);
 			if (opts.wizard) {
 				const { runAgentWizard } = await Promise.resolve().then(() => (init_agent_wizard(), agent_wizard_exports));
 				const wizardConfig = await runAgentWizard();
-				let envContent = "# KiCI agent configuration (generated by setup wizard)\n";
-				envContent += `KICI_ORCHESTRATOR_URL=${wizardConfig.orchestratorUrl}\n`;
-				envContent += `KICI_AGENT_TOKEN=${wizardConfig.agentToken}\n`;
-				if (wizardConfig.labels.length > 0) envContent += `KICI_AGENT_LABELS=${wizardConfig.labels.join(",")}\n`;
-				writeFileSecurelySync(envFilePath, envContent, 384);
+				writeFileSecurelySync(envFilePath, renderAgentEnvFile({
+					header: "# KiCI agent configuration (generated by setup wizard)",
+					orchestratorUrl: wizardConfig.orchestratorUrl,
+					token: wizardConfig.agentToken,
+					labels: wizardConfig.labels,
+					port
+				}), 384);
 				console.log(`Wrote wizard configuration to ${envFilePath}`);
 			} else if (opts.envFile) {
 				const source = path.resolve(opts.envFile);
@@ -23081,15 +23972,17 @@ function registerAgentInstall(agent) {
 				copyFileSecurelySync(source, envFilePath, 384);
 				console.log(`Copied env file to ${envFilePath}`);
 			} else if (!fs.existsSync(envFilePath)) {
-				let envContent = `# KiCI agent configuration\n`;
-				if (opts.orchestratorUrl) envContent += `KICI_ORCHESTRATOR_URL=${opts.orchestratorUrl}\n`;
-				if (opts.token) envContent += `KICI_AGENT_TOKEN=${opts.token}\n`;
-				if (opts.labels) envContent += `KICI_AGENT_LABELS=${opts.labels}\n`;
-				writeFileSecurelySync(envFilePath, envContent, 384);
+				writeFileSecurelySync(envFilePath, renderAgentEnvFile({
+					header: "# KiCI agent configuration",
+					orchestratorUrl: opts.orchestratorUrl,
+					token: opts.token,
+					labels: opts.labels?.split(",").map((l) => l.trim()).filter(Boolean),
+					port
+				}), 384);
 				console.log(`Created env file at ${envFilePath}`);
 			}
 			if (fs.existsSync(envFilePath)) fs.chmodSync(envFilePath, 384);
-			const entryScript = opts.binary ? void 0 : fileURLToPath(import.meta.resolve("@kici-dev/agent/server"));
+			const entryScript = opts.binary ? void 0 : resolveServerScript("@kici-dev/agent/server", "agent", resolveModule);
 			const { executablePath, args } = resolveServiceExecutable({
 				binary: opts.binary ? path.resolve(opts.binary) : void 0,
 				nodePath: process.execPath,
@@ -23097,8 +23990,7 @@ function registerAgentInstall(agent) {
 			});
 			const config = {
 				name: serviceName,
-				displayName: "KiCI Agent",
-				description: "KiCI CI/CD workflow execution agent service",
+				...SERVICE_TEXT.agent,
 				executablePath,
 				args,
 				nodeBinDir: path.dirname(process.execPath),
@@ -23110,7 +24002,7 @@ function registerAgentInstall(agent) {
 				restartPolicy: DEFAULT_RESTART_POLICY
 			};
 			await manager.install(config);
-			const manifestFile = writeManifest(instanceDir, {
+			const { file: manifestFile, warning: manifestWarning } = writeInstallManifest(instanceDir, {
 				component: "agent",
 				name: serviceName,
 				platform,
@@ -23121,7 +24013,11 @@ function registerAgentInstall(agent) {
 				installBase: getInstallBase(platform, serviceName),
 				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 				kiciVersion: readKiciVersion()
+			}, {
+				execPath: executablePath,
+				args
 			});
+			if (manifestWarning) console.warn(`Warning: ${manifestWarning}`);
 			try {
 				appendIndexEntry(kiciRoot, {
 					component: "agent",
@@ -23333,37 +24229,8 @@ function registerAgentRestart(agent) {
 //#endregion
 //#region src/cli/commands/agent-service/status.ts
 init_service();
-/** 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(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_AGENT_PORT" || key?.trim() === "KICI_PORT") {
-				const val = rest.join("=").trim().replace(/^["']|["']$/g, "");
-				const parsed = parseInt(val, 10);
-				if (!isNaN(parsed)) return parsed;
-			}
-		}
-	} catch {}
-	return 4001;
-}
-/** Query agent health API. */
-async function queryHealth(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;
-	}
-}
+/** Column the values of the agent section start at. */
+const VALUE_COLUMN = 14;
 function formatStatus(serviceStatus, health, serviceName) {
 	const lines = [];
 	lines.push(`Service: ${serviceName}`);
@@ -23372,13 +24239,12 @@ function formatStatus(serviceStatus, health, serviceName) {
 	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 agent ---");
-		if (health.labels && health.labels.length > 0) lines.push(`Labels:       ${health.labels.join(", ")}`);
-		else lines.push("Labels:       (none - accepts all jobs)");
-		if (health.orchestratorConnection) lines.push(`Orchestrator: ${health.orchestratorConnection}`);
-		if (health.currentJob) lines.push(`Current job:  ${health.currentJob.id ?? "unknown"} (${health.currentJob.workflow ?? ""})`);
-		else lines.push("Current job:  idle");
+		const rows = [];
+		if (health.agentId) rows.push(["Agent ID", health.agentId]);
+		if (typeof health.connected === "boolean") rows.push(["Orchestrator", health.connected ? "connected" : "disconnected"]);
+		if (typeof health.activeJobs === "number") rows.push(["Active jobs", String(health.activeJobs)]);
+		rows.push(...buildInfoRows(health));
+		lines.push(...formatHealthSection("--- KiCI agent ---", rows, VALUE_COLUMN));
 	} else if (serviceStatus.state === "running") {
 		lines.push("");
 		lines.push("(Could not reach agent health API)");
@@ -23389,7 +24255,7 @@ function buildJsonOutput(serviceStatus, health, serviceName) {
 	return {
 		service: serviceName,
 		...serviceStatus,
-		health: health ?? void 0
+		health: health ? hideBuildCommit(health) : void 0
 	};
 }
 function registerAgentStatusCommand(parent) {
@@ -23421,7 +24287,7 @@ function registerAgentStatusCommand(parent) {
 			};
 			const serviceStatus = await manager.status(config);
 			let health = null;
-			if (serviceStatus.state === "running") health = await queryHealth(readPortFromEnvFile(config.envFilePath));
+			if (serviceStatus.state === "running") health = await fetchLocalJson(readLocalEndpoint(readEnvContent(config.envFilePath), AGENT_DEFAULT_PORT), "/health");
 			if (opts.json) console.log(JSON.stringify(buildJsonOutput(serviceStatus, health, config.name), null, 2));
 			else console.log(formatStatus(serviceStatus, health, config.name));
 		} catch (err) {
@@ -26258,7 +27124,7 @@ function registerClusterNameCommands(program, getClient) {
 * (`cluster_meta.cluster_id`) and the durable S3 sentinel
 * (`<prefix>/.kici-cluster-id`).
 *
-* Used by `kici-admin cluster reconcile-identity` and the staging deploy's
+* Used by `kici-admin cluster reconcile-identity`, which a deploy can run as a
 * pre-orchestrator-start self-heal step. Talks DB + S3 directly (never the
 * orchestrator HTTP admin API) so it works while the orchestrator process is
 * down — which is exactly when a "Cluster identity mismatch" boot failure needs
@@ -26455,9 +27321,8 @@ function registerClusterCommands(program) {
 *
 *   Direct-DB mode: activated when `--database-url` is passed (or
 *   KICI_DATABASE_URL / DATABASE_URL is set). Opens its own pool and runs the
-*   SQL directly. Used by e2e/helpers/deploy.ts during warm-start cleanup,
-*   when the orchestrator is deliberately stopped so a stale scoped-secret
-*   can't crash it on boot.
+*   SQL directly. Use it for cleanup while the orchestrator is deliberately
+*   stopped, so a stale scoped-secret can't crash it on boot.
 */
 function resolveDirectDbUrl$5(explicit) {
 	return explicit ?? process.env.KICI_DATABASE_URL ?? null;
@@ -27489,7 +28354,7 @@ function registerEventDlqCommands(program, getClient) {
 * Contract:
 *   - tenant column: `routing_key` (denormalized in migration 006)
 *   - partition column: `created_at`
-*   - warm TTL: 30 days (design §5 matrix row 9)
+*   - warm TTL: 30 days
 *   - eligibility: created_at < cutoff (steps are append-only and have no
 *     terminal-status predicate — there is no UPDATE statement against
 *     `execution_steps` in the orchestrator codebase, so age alone is
@@ -27647,7 +28512,7 @@ var init_execution_steps = __esmMin((() => {
 * Contract:
 *   - tenant column: `routing_key` (denormalized in migration 006)
 *   - partition column: `created_at`
-*   - warm TTL: 30 days (design §5 matrix row 8)
+*   - warm TTL: 30 days
 *   - eligibility: terminal job status AND no live steps remain for this
 *     (run, job)
 *
@@ -27822,7 +28687,7 @@ var init_execution_jobs = __esmMin((() => {
 * Contract:
 *   - tenant column: `routing_key`
 *   - partition column: `created_at`
-*   - warm TTL: 30 days (design §5 matrix row 7)
+*   - warm TTL: 30 days
 *   - eligibility: terminal run status AND no live jobs reference this run
 *
 * Order: registered LAST in the orchestrator cold-store. Within one
@@ -27940,7 +28805,7 @@ var init_execution_runs = __esmMin((() => {
 			return row.created_at;
 		}
 		/**
-		* Phase F — natural-key extractor used by `replayRow` so callers
+		* Natural-key extractor used by `replayRow` so callers
 		* (the rerun pipeline) can locate the chunk holding a given UUID
 		* `run_id` without knowing the internal SERIAL `id` returned by
 		* `rowId()`.
@@ -27949,10 +28814,10 @@ var init_execution_runs = __esmMin((() => {
 			return row.run_id;
 		}
 		/**
-		* Phase F — replay a chunk's `execution_runs` rows back into
+		* Replay a chunk's `execution_runs` rows back into
 		* Orchestrator PG. Mirrors the Platform-side replayInsert; the
 		* audit row goes to `access_log` (not `audit_log`) because the
-		* orchestrator's audit surface is access_log per design §8.
+		* orchestrator's audit surface is access_log.
 		*
 		* Idempotent on duplicate replays via `ON CONFLICT (run_id) DO
 		* NOTHING`. Decrements `cold_store_chunk_counts` (floored at 0).
@@ -28051,8 +28916,8 @@ var init_execution_runs = __esmMin((() => {
 * Contract:
 *   - tenant column: `routing_key` (NULL → synthetic `__orchestrator__`)
 *   - partition column: `timestamp`
-*   - warm TTL: 90 days (longer window than other audit tables — design
-*     §5 matrix row 10. Volume is low, forensic value is high)
+*   - warm TTL: 90 days (longer window than other audit tables — volume is
+*     low, forensic value is high)
 *
 * Synthetic tenant: rows without `routing_key` (e.g. orchestrator-level
 * key rotations done before any source is bound) collapse to a single
@@ -28185,7 +29050,7 @@ var init_secret_audit_log = __esmMin((() => {
 			return row.timestamp;
 		}
 		/**
-		* Phase 2 — per-row cold-retention TTL. Sampled `resolve` /
+		* Per-row cold-retention TTL. Sampled `resolve` /
 		* `resolve_named` rows get 180d cold; mutations get `'forever'`. The
 		* denied-outcome override promotes to 730d (forensic).
 		*
@@ -28299,7 +29164,7 @@ var init_secret_audit_log = __esmMin((() => {
 * Contract:
 *   - tenant column: `org_id` (NULL → synthetic `__orchestrator__`)
 *   - partition column: `created_at`
-*   - warm TTL: 30 days (design §5 matrix row 11)
+*   - warm TTL: 30 days
 *
 * Replaces the previous 90-day `expires_at`-based hard delete (removed
 * by migration 007). Rows older than 30 days now live in S3
@@ -28440,7 +29305,7 @@ var init_access_log = __esmMin((() => {
 			return row.created_at;
 		}
 		/**
-		* Phase 2 — per-row cold-retention TTL. Mirrors the warm-side override
+		* Per-row cold-retention TTL. Mirrors the warm-side override
 		* layering: outcome=denied/error → 730d (forensic), platform_operator →
 		* `'forever'` (compliance), otherwise per-action map. The framework
 		* groups rows by `coldDaysToBucket(coldTtlDays(row))` at archive time.
@@ -28545,27 +29410,21 @@ var init_access_log = __esmMin((() => {
 //#endregion
 //#region src/cold-store/tables/event-log.ts
 /**
-* `event_log` cold-store adapter (Orchestrator side) —.
-*
-*  §2 row 6
-* and §10.
+* `event_log` cold-store adapter (Orchestrator side).
 *
 * Contract:
 *   - tenant column: `routing_key` (NOT NULL on this side — no
 *     synthetic-tenant fallback like access_log / secret_audit_log)
 *   - partition column: `received_at`
-*   - warm TTL: 30 days (replaces the previous 30-day hard delete in
-*     `packages/orchestrator/src/webhook/event-log.ts:cleanup` +
-*     `packages/orchestrator/src/queue/cleanup.ts:runCleanup` step 4)
+*   - warm TTL: 30 days (rows are archived, not hard-deleted)
 *
 * Per-row payload retention: rows on this table carry a `payload_key`
 * pointing at a gzipped webhook body in object storage (LogStorage).
 * Cold-store packages the row metadata — including `payload_key` —
 * but does NOT touch the body the key points to. The body remains in
 * S3 indefinitely so the dashboard delivery-detail page resolves
-* payload reads identically for hot and cold rows. The pre-Phase-E
-* cleanup that deleted both the row and the payload blob in
-* lock-step is retired.
+* payload reads identically for hot and cold rows. Nothing deletes the
+* row and the payload blob in lock-step.
 *
 * Recursive write: archiving event_log rows writes one access_log
 * audit row per chunk (the orchestrator's audit surface). The new
@@ -28707,17 +29566,15 @@ var init_event_log = __esmMin((() => {
 /**
 * Orchestrator-side cold-store.
 *
-* Extends BaseColdStore with orchestrator-specific table adapters.
-* Phase A registered no adapters; Phase C added execution_runs /
-* execution_jobs / execution_steps. Phase D adds secret_audit_log
-* and access_log.
+* Extends BaseColdStore with orchestrator-specific table adapters:
+* execution_runs / execution_jobs / execution_steps, secret_audit_log,
+* access_log and event_log.
 */
 /**
 * Build the orchestrator cold-store config from env vars. Reads
-* `KICI_COLD_STORE_*` vars mirrored with the Platform side. YAML
-* integration (per the design doc) lands in a follow-up commit that
-* wires the `coldStore` section of the orchestrator config schema;
-* Phase A ships the env-var path only.
+* `KICI_COLD_STORE_*` vars mirrored with the Platform side. The
+* orchestrator config schema has no `coldStore` section, so env vars are
+* the only input.
 */
 function readOrchestratorColdStoreConfig(env = process.env) {
 	const enabled = env.KICI_COLD_STORE_ENABLED === "true";
@@ -28810,7 +29667,7 @@ var init_orchestrator_cold_store = __esmMin((() => {
 			this.registerAdapter(new EventLogAdapter(deps.kdb, deps.instanceId, { overrides: deps.config.tables.event_log ?? deps.config.tables["event_log"] }));
 		}
 		/**
-		* Phase 2 — query the orchestrator's `cold_store_chunks` table for
+		* Query the orchestrator's `cold_store_chunks` table for
 		* chunks past their per-row cold-retention horizon. See the matching
 		* Platform-side method for the full rationale.
 		*/
@@ -28843,7 +29700,7 @@ var init_orchestrator_cold_store = __esmMin((() => {
 			}));
 		}
 		/**
-		* Phase 2 — per-chunk advisory lock keyed on
+		* Per-chunk advisory lock keyed on
 		* `hashtext('cold-store-purge|orchestrator|<table>|<chunkId>')`.
 		*/
 		async withPurgeLock(args, fn) {
@@ -28866,8 +29723,7 @@ var init_orchestrator_cold_store = __esmMin((() => {
 /**
 * Implementations for `kici-admin cold-store` subcommands.
 *
-* Mirrors the Platform-side implementation in
-* `packages/platform/src/admin/cold-store-commands.ts` — same shape,
+* Mirrors the Platform-side implementation — same shape,
 * just builds an `OrchestratorColdStore` against the orchestrator
 * Postgres + S3 instead of a `PlatformColdStore`.
 *
@@ -29737,7 +30593,7 @@ function registerCacheCommands(program, deps = {
 *
 * A leaf module on purpose: it imports nothing, so an out-of-package consumer
 * can read the constant without pulling the orchestrator runtime graph in with
-* it. The NetworkManager drift watchdog (`hack/lib/nm-watchdog.ts`) derives its
+* it. A NetworkManager drift watchdog derives its
 * expected-pattern set from here rather than re-typing the patterns — a second
 * copy desyncs silently the moment a pattern is added. `host-network.ts`
 * re-exports it and renders `NM_CONF_CONTENT` from it, so the drop-in and the
@@ -29805,9 +30661,9 @@ function bridgePrefix(bridgeName) {
 * serializes them.
 *
 * The command list NEVER deletes the table. It is a self-heal — `ensureHostReady`
-* runs it whenever `verifyBridge` reports unhealthy, which happens on any of
-* four conditions none of which knows how many VMs are live — so dropping the
-* table would leave every running VM fail-open, with full RFC1918 and
+* runs it whenever `verifyBridge` reports unhealthy, and none of the
+* conditions it checks says how many VMs are live — so dropping the table
+* would leave every running VM fail-open, with full RFC1918 and
 * cloud-metadata reach, until it was destroyed. Instead the baseline lives in
 * its own regular chain (`baseline`, see {@link BASELINE_CHAIN}) that is flushed
 * and refilled, and the hooked `forward` chain keeps its per-VM rules
@@ -29937,10 +30793,9 @@ const NM_CONF_CONTENT = [
 	"#",
 	"# The `+=` append operator is mandatory: NM merges conf.d drop-ins last-wins",
 	"# per key, so a bare `unmanaged-devices=` here would be silently clobbered by",
-	"# (or would silently clobber) any other drop-in's unmanaged-devices line — e.g.",
-	"# the wifi drop-in from @kici-dev/util-linux-management. `+=` accumulates",
-	"# across files so every drop-in survives. See",
-	"# .claude/rules/networkmanager-unmanaged.md.",
+	"# (or would silently clobber) any other drop-in's unmanaged-devices line, such",
+	"# as a wifi drop-in another tool installs. `+=` accumulates across files so",
+	"# every drop-in survives.",
 	"[keyfile]",
 	...FIRECRACKER_NET_INTERFACES.map((p) => `unmanaged-devices+=interface-name:${p}`),
 	""
@@ -30128,6 +30983,7 @@ async function verifyBridge(cfg, opts = {}) {
 	} catch {
 		misses.push(`could not read chain ip ${cfg.table} forward`);
 	}
+	const { natPresent, baselineRulesPresent } = await checkSubnetRules(cfg, runner, misses);
 	try {
 		const { stdout } = await runner({
 			bin: "ip",
@@ -30146,7 +31002,7 @@ async function verifyBridge(cfg, opts = {}) {
 	} catch {
 		misses.push(`could not read enslaved links on ${cfg.bridgeName}`);
 	}
-	const healthy = bridgeExists && bridgeUp && addrPresent && tablePresent && baselineChainPresent && tapIsolationPresent;
+	const healthy = bridgeExists && bridgeUp && addrPresent && tablePresent && baselineChainPresent && natPresent && baselineRulesPresent && tapIsolationPresent;
 	return {
 		bridgeName: cfg.bridgeName,
 		bridgeExists,
@@ -30154,6 +31010,8 @@ async function verifyBridge(cfg, opts = {}) {
 		addrPresent,
 		tablePresent,
 		baselineChainPresent,
+		natPresent,
+		baselineRulesPresent,
 		tapIsolationPresent,
 		healthy,
 		detail: healthy ? "healthy" : misses.join("; ")
@@ -30183,6 +31041,146 @@ function forwardEndsInBaselineJump(nftJson) {
 	});
 }
 /**
+* Check the two chains that carry this bridge's subnet: the `postrouting` NAT
+* that gives its guests internet egress, and the `baseline` rules that isolate
+* them.
+*
+* The table, its chains and the tail jump can all be in place while neither
+* rule set serves this subnet: a second bridge provisioned into the same table
+* flushes both chains and refills them with its own subnet. Every guest on this
+* bridge then loses internet access — no name resolves — and a check that stops
+* at the chain layout still reads the host as healthy, so the self-heal never
+* runs.
+*/
+async function checkSubnetRules(cfg, runner, misses) {
+	let subnet;
+	try {
+		subnet = cidrToNetwork(cfg.bridgeCidr);
+	} catch (err) {
+		misses.push(`invalid bridge CIDR ${cfg.bridgeCidr}: ${toErrorMessage(err)}`);
+		return {
+			natPresent: false,
+			baselineRulesPresent: false
+		};
+	}
+	const listChain = async (chain) => {
+		try {
+			const { stdout } = await runner({
+				bin: "nft",
+				args: [
+					"-j",
+					"list",
+					"chain",
+					"ip",
+					cfg.table,
+					chain
+				]
+			});
+			return stdout;
+		} catch {
+			misses.push(`could not read chain ip ${cfg.table} ${chain}`);
+			return null;
+		}
+	};
+	const postrouting = await listChain("postrouting");
+	const natPresent = postrouting !== null && postroutingMasqueradesSubnet(postrouting, subnet);
+	if (postrouting !== null && !natPresent) misses.push(`ip ${cfg.table} postrouting does not masquerade ${subnet}`);
+	const baseline = await listChain(BASELINE_CHAIN);
+	const baselineRulesPresent = baseline !== null && baselineHoldsBridgeRules(baseline, cfg);
+	if (baseline !== null && !baselineRulesPresent) misses.push(`ip ${cfg.table} ${BASELINE_CHAIN} does not hold the ${subnet} rules`);
+	return {
+		natPresent,
+		baselineRulesPresent
+	};
+}
+const RULE_VERDICTS = [
+	"accept",
+	"drop",
+	"masquerade"
+];
+/** An nft JSON address operand as `a.b.c.d` or `a.b.c.d/len`; null for any other operand. */
+function nftAddress(operand) {
+	if (typeof operand === "string") return operand;
+	const prefix = operand?.prefix;
+	return typeof prefix?.addr === "string" && typeof prefix.len === "number" ? `${prefix.addr}/${prefix.len}` : null;
+}
+/** The rules of a `nft -j list chain` listing, in chain order; null when it does not parse. */
+function listedRuleShapes(nftJson) {
+	let parsed;
+	try {
+		parsed = JSON.parse(nftJson);
+	} catch {
+		return null;
+	}
+	const entries = parsed?.nftables;
+	if (!Array.isArray(entries)) return null;
+	const shapes = [];
+	for (const entry of entries) {
+		const expr = entry.rule?.expr;
+		if (!Array.isArray(expr)) continue;
+		const shape = {
+			saddr: null,
+			daddr: null,
+			verdict: null
+		};
+		for (const node of expr) {
+			const match = node.match;
+			const positive = match?.op === void 0 || match.op === "==";
+			const payload = match && positive ? match.left?.payload : void 0;
+			if (payload?.protocol === "ip" && payload.field === "saddr") shape.saddr = nftAddress(match.right);
+			else if (payload?.protocol === "ip" && payload.field === "daddr") shape.daddr = nftAddress(match.right);
+			shape.verdict = RULE_VERDICTS.find((v) => v in node) ?? shape.verdict;
+		}
+		shapes.push(shape);
+	}
+	return shapes;
+}
+/** The shape of one `nft add rule` token list the provisioner builds. */
+function commandRuleShape(tokens) {
+	const shape = {
+		saddr: null,
+		daddr: null,
+		verdict: null
+	};
+	for (let i = 0; i + 2 < tokens.length; i++) {
+		if (tokens[i] !== "ip") continue;
+		if (tokens[i + 1] === "saddr") shape.saddr = tokens[i + 2];
+		if (tokens[i + 1] === "daddr") shape.daddr = tokens[i + 2];
+	}
+	shape.verdict = RULE_VERDICTS.find((v) => v === tokens.at(-1)) ?? null;
+	return shape;
+}
+/** `<daddr> <verdict>` for every subnet-scoped accept or drop, in chain order (`*`: any daddr). */
+function subnetVerdicts(rules, subnet) {
+	return rules.filter((r) => r.saddr === subnet && (r.verdict === "accept" || r.verdict === "drop")).map((r) => `${r.daddr ?? "*"} ${r.verdict}`);
+}
+/**
+* True when a `nft -j list chain … postrouting` listing masquerades traffic
+* whose source is `subnet` (the network CIDR, e.g. `10.0.0.0/24`).
+*/
+function postroutingMasqueradesSubnet(nftJson, subnet) {
+	return (listedRuleShapes(nftJson) ?? []).some((r) => r.saddr === subnet && r.verdict === "masquerade");
+}
+/**
+* True when a `nft -j list chain … baseline` listing holds this bridge's
+* subnet-scoped accepts and drops exactly as {@link buildBridgeCommands} writes
+* them, in the same order.
+*
+* Order is part of the check: the internet accept is terminal, so ahead of the
+* RFC1918 and metadata drops it would let the guests reach every private range.
+*/
+function baselineHoldsBridgeRules(nftJson, cfg) {
+	const listed = listedRuleShapes(nftJson);
+	if (listed === null) return false;
+	const subnet = cidrToNetwork(cfg.bridgeCidr);
+	const want = subnetVerdicts(buildBridgeCommands({
+		...cfg,
+		hostIface: cfg.hostIface ?? "egress"
+	}).filter((c) => c.bin === "nft" && c.args[0] === "add" && c.args[1] === "rule" && c.args[3] === BASELINE_CHAIN).map((c) => commandRuleShape(c.args.slice(4))), subnet);
+	const got = subnetVerdicts(listed, subnet);
+	return want.length === got.length && want.every((v, i) => v === got[i]);
+}
+/**
 * Names of the kici-* TAPs enslaved to the bridge that are NOT port-isolated,
 * read from `ip -d -j link show master <bridge>`.
 *
@@ -30348,7 +31346,7 @@ function registerProvision(group) {
 //#endregion
 //#region src/cli/commands/firecracker/verify.ts
 function registerVerify(group) {
-	group.command("verify").description("Check a Firecracker host bridge is up with its addr + nft table").requiredOption("--bridge <name>", "bridge interface name").requiredOption("--cidr <cidr>", "gateway IP + prefix").option("--table <name>", "nft table name", "kici").option("--sudo", "wrap privileged commands with sudo -n").action(async (opts) => {
+	group.command("verify").description("Check a Firecracker host bridge: its addr, nft table, and subnet NAT + isolation rules").requiredOption("--bridge <name>", "bridge interface name").requiredOption("--cidr <cidr>", "gateway IP + prefix").option("--table <name>", "nft table name", "kici").option("--sudo", "wrap privileged commands with sudo -n").action(async (opts) => {
 		const cfg = optionsToConfig(opts);
 		const h = await verifyBridge(cfg, { requireSudo: opts.sudo });
 		if (h.healthy) {
@@ -30427,6 +31425,57 @@ function isNodeError(err) {
 	return err instanceof Error && "code" in err;
 }
 z.enum(["hook", "sweep"]);
+//#endregion
+//#region src/scaler/firecracker-extra-hosts.ts
+/**
+* A Firecracker scaler's `extraHosts`: the `host:address` mappings the rootfs
+* `/init` appends to each guest's `/etc/hosts`.
+*
+* An entry is `host:address`, the form the container backend documents for the
+* same field; the container runtimes accept more (`host=address`, bracketed
+* IPv6), a Firecracker scaler does not. `host-gateway` stands for the bridge
+* gateway, the address a microVM reaches its host at. A guest carries no
+* mapping unless the scaler configures one.
+*/
+/** The address keyword for the bridge gateway, as the container runtimes spell it. */
+const HOST_GATEWAY = "host-gateway";
+/**
+* An RFC 1123 hostname: dot-separated labels of letters, digits and inner
+* hyphens. Nothing else can reach the guest's `/etc/hosts`, so an entry can
+* never add a second line or a second name there.
+*/
+const HOSTNAME = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$/;
+/**
+* Parse one `host:address` entry. The host ends at the first colon, so an
+* IPv6 address keeps its own colons. Throws on a malformed entry.
+*/
+function parseExtraHost(entry) {
+	const sep = entry.indexOf(":");
+	const host = sep === -1 ? "" : entry.slice(0, sep);
+	const address = sep === -1 ? "" : entry.slice(sep + 1);
+	if (host === "" || address === "") throw new Error(`extraHosts entry "${entry}" must be host:address`);
+	if (!HOSTNAME.test(host)) throw new Error(`extraHosts entry "${entry}": "${host}" is not a valid hostname`);
+	if (address !== "host-gateway" && isIP(address) === 0) throw new Error(`extraHosts entry "${entry}": the address must be an IP address or ${HOST_GATEWAY}`);
+	return {
+		host,
+		address
+	};
+}
+/**
+* The MMDS value the rootfs `/init` reads: `host:address` pairs joined by
+* commas, with `host-gateway` replaced by `gateway`. `undefined` when the
+* scaler configures no mapping, so the guest gets none. Throws on a malformed
+* entry, and on `host-gateway` when `gateway` is not an IP address.
+*/
+function renderGuestExtraHosts(entries, gateway) {
+	if (!entries || entries.length === 0) return void 0;
+	return entries.map((entry) => {
+		const { host, address } = parseExtraHost(entry);
+		if (address !== "host-gateway") return `${host}:${address}`;
+		if (isIP(gateway) === 0) throw new Error(`extraHosts entry "${entry}": the bridge gateway "${gateway}" is not an IP address`);
+		return `${host}:${gateway}`;
+	}).join(",");
+}
 /**
 * Zod schema for a single resource spec (cpus + memory).
 *
@@ -30569,6 +31618,12 @@ const scalerEntrySchema = z.object({
 		"auto"
 	]).default("auto"),
 	orchestratorUrl: z.string().optional(),
+	/**
+	* Extra `host:address` name mappings for spawned agents. A container scaler
+	* passes them to the runtime; a Firecracker scaler writes them into each
+	* guest's `/etc/hosts`, with `host-gateway` resolved to the bridge gateway.
+	* None by default.
+	*/
 	extraHosts: z.array(z.string()).optional(),
 	networkIsolation: z.boolean().default(true),
 	warmPool: warmPoolSchema,
@@ -30714,6 +31769,17 @@ const scalerEntrySchema = z.object({
 			message: `Firecracker scaler "${data.name}" requires a 'gid' field`,
 			path: ["gid"]
 		});
+		(data.extraHosts ?? []).forEach((entry, i) => {
+			try {
+				parseExtraHost(entry);
+			} catch (err) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: `Firecracker scaler "${data.name}" extraHosts[${i}]: ${toErrorMessage(err)}`,
+					path: ["extraHosts", i]
+				});
+			}
+		});
 		data.labelSets.forEach((ls, i) => {
 			if (!ls.rootfsPath) ctx.addIssue({
 				code: z.ZodIssueCode.custom,
@@ -31579,19 +32645,12 @@ const POSIX_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 * Interface-name pattern for per-VM TAP devices.
 * Matches what {@link generateTapName} produces — `kici-` plus the LAST 8
 * characters of the VM id, which for a scaler-minted id is 8 lowercase hex.
+* The orphan sweep considers only names of this shape, so the default bridge
+* (`kici-br0`) and any other operator interface outside it are never
+* candidates. The scaler's configured bridge is skipped by name as well, in
+* case an operator named it in this shape: deleting it kills every running VM.
 */
 const VM_TAP_PATTERN = /^kici-[0-9a-f]{8}$/;
-/**
-* Infrastructure interfaces that share the `kici-` prefix but must NEVER be
-* deleted by the orphan sweep. Bridges (kici-br0/kici-br1) carry all VM
-* traffic; kici-m01 is the staging metadata interface. Losing any of these
-* kills all running VMs.
-*/
-const PROTECTED_INTERFACES = [
-	"kici-br0",
-	"kici-br1",
-	"kici-m01"
-];
 /** Convert a dotted IPv4 netmask ('255.255.255.0') to a CIDR prefix length (24). */
 function netmaskToPrefix(netmask) {
 	return netmask.split(".").map((o) => Number(o).toString(2).padStart(8, "0")).join("").split("1").length - 1;
@@ -31626,6 +32685,8 @@ var FirecrackerScalerBackend = class FirecrackerScalerBackend {
 	bridgeName;
 	cidr;
 	gateway;
+	/** The MMDS `kici-extra-hosts` value, or undefined when the scaler maps no host. */
+	guestExtraHosts;
 	/** Host services the orchestrator directed agents at, as `hostAccess` entries. */
 	hostServices;
 	netmask;
@@ -31660,6 +32721,7 @@ var FirecrackerScalerBackend = class FirecrackerScalerBackend {
 		this.bridgeName = options.bridgeName;
 		this.cidr = options.cidr;
 		this.gateway = options.gateway;
+		this.guestExtraHosts = renderGuestExtraHosts(options.extraHosts, options.gateway);
 		this.hostServices = options.hostServices;
 		this.netmask = options.netmask;
 		this.table = options.table ?? "kici";
@@ -31754,7 +32816,7 @@ var FirecrackerScalerBackend = class FirecrackerScalerBackend {
 		});
 		let alloc;
 		const onSpawnAbort = () => {
-			this.abandonSpawn(agentId, alloc, "spawn aborted (deadline or shutdown)");
+			this.abandonSpawnDetached(agentId, alloc, "spawn aborted (deadline or shutdown)");
 		};
 		signal?.addEventListener("abort", onSpawnAbort, { once: true });
 		try {
@@ -31893,8 +32955,8 @@ var FirecrackerScalerBackend = class FirecrackerScalerBackend {
 				"kici-agent-id": agentId,
 				"kici-labels": fullLabels.join(","),
 				"kici-scaler-managed": "1",
-				"kici-gateway-ip": this.gateway,
 				...agentToken ? { "kici-agent-token": agentToken } : {},
+				...this.guestExtraHosts ? { "kici-extra-hosts": this.guestExtraHosts } : {},
 				...matchedLabelSet.backpressureMode ? { "kici-backpressure-mode": matchedLabelSet.backpressureMode } : {},
 				...Object.keys(acceptedEnv).length > 0 ? { "kici-env": acceptedEnv } : {}
 			} } });
@@ -31930,6 +32992,13 @@ var FirecrackerScalerBackend = class FirecrackerScalerBackend {
 			logger$2.warn(`Cleanup after abandoned spawn ${agentId} failed: ${toErrorMessage(err)}`);
 		}
 	}
+	/**
+	* {@link abandonSpawn} from a path that cannot await it (an abort listener, a
+	* process exit handler). A failure is logged.
+	*/
+	abandonSpawnDetached(agentId, alloc, reason) {
+		runDetached(logger$2, "Abandoned spawn teardown", () => this.abandonSpawn(agentId, alloc, reason), { agentId });
+	}
 	getScalerContext(agentId) {
 		const managed = this.agents.get(agentId);
 		if (!managed) return void 0;
@@ -32307,7 +33376,7 @@ var FirecrackerScalerBackend = class FirecrackerScalerBackend {
 				}
 				for (const name of ifaceNames) {
 					if (!VM_TAP_PATTERN.test(name)) continue;
-					if (PROTECTED_INTERFACES.includes(name)) continue;
+					if (name === this.bridgeName) continue;
 					if (allocatedTapsBefore.has(name)) continue;
 					if (allocatedTapsAfter.has(name)) continue;
 					if (trackedTapDevices.has(name)) continue;
@@ -32366,9 +33435,9 @@ var FirecrackerScalerBackend = class FirecrackerScalerBackend {
 	/**
 	* Default interval for periodic orphan sweeps (15 minutes).
 	*
-	* Long-running orchestrators need in-process orphan sweeps because the
-	* external kici-leak-sweep timer skips TAP cleanup while a staging
-	* orchestrator is active (to avoid racing spawns). Without this, leaked
+	* Long-running orchestrators need in-process orphan sweeps because a
+	* host-level cleanup job skips TAP cleanup while an orchestrator is active
+	* (to avoid racing spawns). Without this, leaked
 	* TAPs accumulate until the orchestrator restarts — which can be weeks.
 	*/
 	static ORPHAN_SWEEP_INTERVAL_MS = 9e5;
@@ -32765,8 +33834,8 @@ var FirecrackerScalerBackend = class FirecrackerScalerBackend {
 		this.tailAbortControllers.set(agentId, abortController);
 		const signal = abortController.signal;
 		const output = process.stdout;
-		this.tailAndForward(serialLogPath, agentId, "firecracker-serial", signal, output);
-		this.tailAndForward(vmmLogPath, agentId, "firecracker-vmm", signal, output);
+		runDetached(logger$2, "Serial console tail", () => this.tailAndForward(serialLogPath, agentId, "firecracker-serial", signal, output), { agentId });
+		runDetached(logger$2, "VMM log tail", () => this.tailAndForward(vmmLogPath, agentId, "firecracker-vmm", signal, output), { agentId });
 		child.on("exit", (code, sig) => {
 			setTimeout(() => {
 				abortController.abort();
@@ -32780,7 +33849,7 @@ var FirecrackerScalerBackend = class FirecrackerScalerBackend {
 						signal: sig,
 						failureType
 					}), agentId, output, void 0, "firecracker-serial");
-					this.abandonSpawn(agentId, alloc, `jailer exited during boot (code ${code}${sig ? `, signal ${sig}` : ""}, ${failureType})`);
+					this.abandonSpawnDetached(agentId, alloc, `jailer exited during boot (code ${code}${sig ? `, signal ${sig}` : ""}, ${failureType})`);
 				}
 			}, 500);
 		});
@@ -33694,7 +34763,7 @@ function registerScalerCommands(program) {
 				process.exit(1);
 			}
 			const scalerConfig = await loadScalerConfig(scalerConfigPath, scalerConfigDir);
-			const port = local.server?.port ?? Number(process.env.KICI_PORT ?? "4000");
+			const port = local.server?.port ?? Number(process.env.KICI_PORT ?? ORCHESTRATOR_DEFAULT_PORT);
 			const basePath = local.server?.basePath ?? process.env.KICI_BASE_PATH ?? "/";
 			if ((opts.force ? false : await isOrchestratorHealthy(port, basePath)) && !opts.force) {
 				const msg = "orchestrator is up and reaps orphans itself; pass --force to reap anyway";
@@ -33995,7 +35064,7 @@ Token vocabulary:
 * where no bundler substituted the constant — the same shape `server.ts` and
 * `standalone.ts` use for `ORCHESTRATOR_VERSION`.
 */
-const CLI_VERSION = "0.11.0";
+const CLI_VERSION = "0.12.0";
 /**
 * Build the kici-admin Commander program with every command group registered.
 * Exported so the surface registry can walk the real command tree without