@cleocode/cleo 2026.6.13 → 2026.6.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "2026.6.13",
+  "version": "2026.6.15",
   "description": "CLEO CLI — the assembled product consuming @cleocode/core",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -12,6 +12,7 @@
     "ct": "bin/cleo.js"
   },
   "dependencies": {
+    "@earendil-works/pi-tui": "^0.79.1",
     "check-disk-space": "^3.4.0",
     "citty": "^0.2.1",
     "graphology": "^0.26.0",
@@ -30,17 +31,17 @@
     "tree-sitter-rust": "0.23.1",
     "tree-sitter-typescript": "^0.23.2",
     "yaml": "^2.8.3",
-    "@cleocode/animations": "2026.6.13",
-    "@cleocode/cant": "2026.6.13",
-    "@cleocode/core": "2026.6.13",
-    "@cleocode/contracts": "2026.6.13",
-    "@cleocode/caamp": "2026.6.13",
-    "@cleocode/lafs": "2026.6.13",
-    "@cleocode/nexus": "2026.6.13",
-    "@cleocode/playbooks": "2026.6.13",
-    "@cleocode/runtime": "2026.6.13",
-    "@cleocode/paths": "2026.6.13",
-    "@cleocode/worktree": "2026.6.13"
+    "@cleocode/caamp": "2026.6.15",
+    "@cleocode/core": "2026.6.15",
+    "@cleocode/lafs": "2026.6.15",
+    "@cleocode/contracts": "2026.6.15",
+    "@cleocode/cant": "2026.6.15",
+    "@cleocode/animations": "2026.6.15",
+    "@cleocode/nexus": "2026.6.15",
+    "@cleocode/playbooks": "2026.6.15",
+    "@cleocode/runtime": "2026.6.15",
+    "@cleocode/worktree": "2026.6.15",
+    "@cleocode/paths": "2026.6.15"
   },
   "engines": {
     "node": ">=24.16.0"
@@ -55,7 +56,8 @@
     "bin",
     "scripts",
     "templates",
-    "assets"
+    "assets",
+    "studio-dist"
   ],
   "devDependencies": {
     "@types/node-cron": "^3.0.11",
@@ -71,7 +73,7 @@
     "gen:manifest": "node scripts/generate-command-manifest.mjs",
     "prebuild": "node scripts/generate-command-manifest.mjs",
     "build": "tsc",
-    "postbuild": "node scripts/assert-shebang.mjs",
+    "postbuild": "node scripts/assert-shebang.mjs && node scripts/copy-studio-dist.mjs",
     "pretypecheck": "node scripts/generate-command-manifest.mjs",
     "typecheck": "tsc --noEmit",
     "test": "cd ../.. && vitest run packages/cleo/src",

package/scripts/copy-studio-dist.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * copy-studio-dist.mjs — postbuild step for @cleocode/cleo (T11979).
+ *
+ * Copies the Studio adapter-node build output from
+ * `packages/studio/build/` into `packages/cleo/studio-dist/` so the
+ * published @cleocode/cleo tarball contains a batteries-included Studio
+ * bundle that the gateway can serve at `/studio` with zero repo checkout.
+ *
+ * Resolution order for the Studio build source:
+ *   1. `CLEO_STUDIO_BUILD_DIR` environment variable (CI override).
+ *   2. `<monorepo-root>/packages/studio/build` (standard monorepo layout).
+ *
+ * When the source directory does not exist, the script exits successfully
+ * with a warning — a missing Studio build is not a hard build failure in
+ * dev checkouts where Studio has not been built yet. CI must explicitly
+ * build Studio before building the cleo package (see the wave-based build
+ * script at `build.mjs`).
+ *
+ * @task T11979
+ * @epic T11261
+ */
+
+import { cp, mkdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// packages/cleo/scripts → packages/cleo
+const cleoPackageDir = resolve(__dirname, '..');
+// packages/cleo → monorepo root
+const monorepoRoot = resolve(cleoPackageDir, '..', '..');
+
+const srcDir =
+  process.env['CLEO_STUDIO_BUILD_DIR'] ??
+  join(monorepoRoot, 'packages', 'studio', 'build');
+
+const destDir = join(cleoPackageDir, 'studio-dist');
+
+if (!existsSync(srcDir)) {
+  console.warn(
+    `[copy-studio-dist] Studio build not found at ${srcDir}. ` +
+      'Run `pnpm --filter @cleocode/studio run build` first. ' +
+      'Skipping studio-dist copy (bundle will be absent from the tarball).',
+  );
+  process.exit(0);
+}
+
+// Clean the destination directory so stale assets do not accumulate.
+await rm(destDir, { recursive: true, force: true });
+await mkdir(destDir, { recursive: true });
+
+await cp(srcDir, destDir, { recursive: true });
+
+// Quick sanity check: the adapter-node index.js must be present.
+const indexJs = join(destDir, 'index.js');
+if (!existsSync(indexJs)) {
+  console.error(
+    `[copy-studio-dist] ERROR: ${indexJs} not found after copy. ` +
+      'The Studio build may be incomplete (client-only, no server).',
+  );
+  process.exit(1);
+}
+
+const clientDir = join(destDir, 'client');
+if (!existsSync(clientDir)) {
+  console.warn(
+    `[copy-studio-dist] Warning: studio-dist/client/ not found. ` +
+      'Gateway static serving at /studio will fall back to the absent-bundle 503.',
+  );
+}
+
+console.log(`[copy-studio-dist] Copied ${srcDir} → ${destDir}`);

package/scripts/install-daemon-service.mjs

@@ -229,7 +229,26 @@ function isWSL() {
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Environment variable that disables daemon auto-start (CI/container path). */
+/**
+ * Environment variable that disables daemon auto-start for the duration of a
+ * single install invocation (CI/container path).
+ *
+ * Unlike `daemon.autoStart = false` in the global config, this env var is NOT
+ * persisted — it must be set on every install invocation. For a durable
+ * opt-out that survives upgrades, set `daemon.autoStart = false` in the CLEO
+ * global config file (printed path: `~/.local/share/cleo/config.json` on
+ * Linux / `~/Library/Application Support/cleo/config.json` on macOS):
+ *
+ *   ```json
+ *   { "daemon": { "autoStart": false } }
+ *   ```
+ *
+ * Priority (highest wins):
+ *   1. CLEO_DAEMON_DISABLE=1        — env override (non-persistent; CI/container)
+ *   2. daemon.autoStart === false   — config-file opt-out (persistent across upgrades)
+ *   3. systemd/launchd enabled state — operator's prior `disable` is respected on upgrade
+ *   4. Default: enable+start on first install; keep-enabled on upgrade where enabled
+ */
 const DAEMON_DISABLE_ENV = 'CLEO_DAEMON_DISABLE';
 
 /**
@@ -308,6 +327,246 @@ function runBin(bin, args) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Config helpers — daemon.autoStart persistent opt-out (T11984)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read `daemon.autoStart` from the CLEO global config file.
+ *
+ * This is a minimal, tolerant JSON read — it does NOT import compiled core
+ * because postinstall runs before the package's own TypeScript is compiled.
+ * If the config file is absent, unreadable, or missing the key, returns
+ * `true` (the safe default: honour existing enable/start logic).
+ *
+ * Config file location: `{cleoHome}/config.json`
+ *   Linux:  ~/.local/share/cleo/config.json
+ *   macOS:  ~/Library/Application Support/cleo/config.json
+ *   Windows: %LOCALAPPDATA%\cleo\Data\config.json
+ *
+ * @returns {boolean} `false` only when `daemon.autoStart` is explicitly set
+ *   to `false` in the global config. Returns `true` in all other cases.
+ */
+function readGlobalAutoStart() {
+  try {
+    const paths = getPlatformPaths();
+    const configPath = join(paths.data, 'config.json');
+    if (!existsSync(configPath)) return true;
+    const raw = readFileSync(configPath, 'utf8');
+    const cfg = JSON.parse(raw);
+    // Explicit false opt-out only — missing key = default true.
+    if (
+      cfg !== null &&
+      typeof cfg === 'object' &&
+      typeof cfg.daemon === 'object' &&
+      cfg.daemon !== null &&
+      cfg.daemon.autoStart === false
+    ) {
+      return false;
+    }
+    return true;
+  } catch {
+    // Config unreadable or malformed JSON — safe default: allow auto-start.
+    return true;
+  }
+}
+
+/**
+ * Decide what action the postinstall hook should take for daemon activation.
+ *
+ * This is a pure function (no side-effects, no I/O) that implements the
+ * operator-state-respecting decision table. It can be unit-tested in
+ * isolation without systemd or launchd being present.
+ *
+ * Decision table:
+ *
+ * | firstInstall | isEnabledState     | autoStartConfig | envDisable | action              |
+ * |:------------:|:------------------:|:---------------:|:----------:|:--------------------|
+ * | any          | any                | any             | true       | 'skip'              |
+ * | any          | any                | false           | false      | 'skip'              |
+ * | true         | 'not-found'/other  | true            | false      | 'enable-and-start'  |
+ * | false        | 'enabled'          | true            | false      | 'restart-if-changed'|
+ * | false        | 'disabled'         | true            | false      | 'leave-disabled'    |
+ * | false        | 'masked'           | true            | false      | 'leave-disabled'    |
+ * | false        | other/unknown      | true            | false      | 'enable-and-start'  |
+ *
+ * @param {object} opts
+ * @param {boolean} opts.firstInstall   - True when the unit/plist file did not
+ *   exist before this postinstall run (i.e. `writeIfChanged` wrote a new file).
+ * @param {string}  opts.isEnabledState - Output of `systemctl --user is-enabled
+ *   <unit>` (or equivalent), e.g. 'enabled', 'disabled', 'masked',
+ *   'not-found', 'static', 'indirect', ''. On macOS use 'not-found' for a
+ *   missing plist and 'enabled' for a loaded agent.
+ * @param {boolean} opts.autoStartConfig - Value of `daemon.autoStart` from the
+ *   global config (via `readGlobalAutoStart()`). Default: true.
+ * @param {boolean} opts.envDisable     - Whether `CLEO_DAEMON_DISABLE=1` is set.
+ *
+ * @returns {'enable-and-start' | 'restart-if-changed' | 'leave-disabled' | 'skip'}
+ *
+ * @task T11984
+ */
+export function decideDaemonAction({ firstInstall, isEnabledState, autoStartConfig, envDisable }) {
+  // Highest priority: env override or persistent config opt-out.
+  if (envDisable || autoStartConfig === false) {
+    return 'skip';
+  }
+
+  // First install (unit file did not previously exist): safe to enable+start.
+  if (firstInstall) {
+    return 'enable-and-start';
+  }
+
+  // Upgrade path: inspect the current enabled state.
+  const state = (isEnabledState ?? '').trim().toLowerCase();
+
+  if (state === 'disabled' || state === 'masked') {
+    // Operator explicitly disabled the unit — honour that decision.
+    return 'leave-disabled';
+  }
+
+  if (state === 'enabled') {
+    // Already enabled; only restart if the unit content changed (handled by caller).
+    return 'restart-if-changed';
+  }
+
+  // Unknown / 'not-found' / 'static' / 'indirect' / empty — treat as first-like install.
+  return 'enable-and-start';
+}
+
+// ---------------------------------------------------------------------------
+// Linux — cleo.slice unit (T11993 · Epic T11992)
+// ---------------------------------------------------------------------------
+
+/**
+ * Name of the systemd user slice unit (without .slice extension).
+ *
+ * The slice acts as a shared cgroup container for all cleo child scopes:
+ *   cleo.slice
+ *     ├── cleo-daemon.service    (managed by the daemon service unit)
+ *     └── cleo-<class>-<n>.scope (transient scopes from spawn-wrapper)
+ *
+ * IMPORTANT — `Delegate=` is FORBIDDEN on slices (only on services/scopes).
+ * Do NOT add a Delegate= directive here.
+ */
+const CLEO_SLICE_UNIT_NAME = 'cleo.slice';
+
+/**
+ * Absolute path to the cleo.slice unit file.
+ *
+ * Always co-located with the cleo-daemon.service unit under
+ * XDG_CONFIG_HOME/systemd/user/ (default: ~/.config/systemd/user/).
+ *
+ * @returns {string} Absolute path to the cleo.slice file.
+ */
+function getSystemdSliceFile() {
+  const paths = getPlatformPaths();
+  const configParent = join(paths.config, '..');
+  return join(configParent, 'systemd', 'user', CLEO_SLICE_UNIT_NAME);
+}
+
+/**
+ * Generate the cleo.slice unit file content.
+ *
+ * ## Staged P1 budget (data-safety decision — T11993 Amendment 1)
+ *
+ * P1 ships MemoryHigh DISABLED and MemoryMax=85% of the host MemTotal.
+ * A reclaim-stalled scope holding a SQLite WAL write-txn for > 30 s
+ * (busy_timeout) cascades SQLITE_BUSY across every slice member.
+ * MemoryHigh within 5 % of MemoryMax causes exactly this stall.
+ *
+ * P1 safe defaults:
+ *   MemoryMax  = 85% of MemTotal (hard cap, benign cgroup kill)
+ *   MemoryHigh = (omitted — disabled)
+ *
+ * P2 target (after T11994 stall-escalator lands):
+ *   MemoryMax  = 85% of MemTotal
+ *   MemoryHigh = 60% of MemTotal
+ *
+ * Both values are live-tunable via `systemctl --user set-property cleo.slice`
+ * without restarting any cleo process.
+ *
+ * NOTE: With MemorySwapMax=0 on child scopes, MemoryHigh over anonymous
+ * heaps ≈ MemoryMax (reclaim has only page-cache to chew).  Admission (P2)
+ * is the primary control; throttling is not load-bearing in P1.
+ *
+ * @returns {string} Systemd slice unit content.
+ */
+function buildSliceUnit() {
+  // Read MemTotal from /proc/meminfo (Linux only — this function is only
+  // called on Linux so the readFileSync path is always reachable).
+  let memTotalKb = 0;
+  try {
+    const raw = readFileSync('/proc/meminfo', 'utf8');
+    const m = raw.match(/^MemTotal:\s+(\d+)\s+kB/m);
+    if (m && m[1]) memTotalKb = parseInt(m[1], 10);
+  } catch {
+    // ignore — fallback below
+  }
+  // Fallback to a conservative 32 GiB (= 33554432 kB) when /proc is absent.
+  if (!memTotalKb || memTotalKb <= 0) memTotalKb = 32 * 1024 * 1024;
+
+  // P1: MemoryMax = 85% of MemTotal, rounded to nearest MiB.
+  const memMaxMib = Math.round((memTotalKb * 0.85) / 1024);
+  // P2 target (document in comment; not emitted in P1):
+  // const memHighMib = Math.round((memTotalKb * 0.60) / 1024);
+
+  return `# cleo.slice — CLEO child-process cgroup slice (T11993 · Epic T11992)
+#
+# This file was generated by cleo's postinstall / doctor flow.
+# Re-running 'cleo doctor' rewrites it only when content changes.
+#
+# All cleo child processes (gateway, studio, agents, tests) are placed
+# under this slice via `systemd-run --user --slice=cleo.slice`.
+#
+# IMPORTANT: Delegate= is forbidden on slices (only valid on services/scopes).
+#
+# Staged budget — see T11993 for the rationale:
+#   P1 (current): MemoryMax=${memMaxMib}M (hard cap), MemoryHigh disabled
+#   P2 target:    MemoryMax=${memMaxMib}M + MemoryHigh=${Math.round(memTotalKb * 0.60 / 1024)}M (60/85 shape)
+#                 (requires T11994 stall-escalator to be safe)
+#
+# Live-tune without restart:
+#   systemctl --user set-property cleo.slice MemoryMax=<value>
+#   systemctl --user set-property cleo.slice MemoryHigh=<value>
+[Unit]
+Description=CLEO child-process slice (agents, gateway, studio, tools)
+Documentation=https://github.com/kryptobaseddev/cleocode
+
+[Slice]
+# P1: hard cap only — MemoryHigh disabled until T11994 stall-escalator lands.
+MemoryMax=${memMaxMib}M
+# P2 (uncomment after T11994 ships):
+# MemoryHigh=${Math.round(memTotalKb * 0.60 / 1024)}M
+`;
+}
+
+/**
+ * Install the cleo.slice user unit idempotently.
+ *
+ * Writes the slice file only when content has changed (SHA-256 comparison),
+ * then calls `systemctl --user daemon-reload` to make systemd aware of it.
+ *
+ * SAFETY: does NOT touch or restart `cleo-daemon.service` — the operator's
+ * enabled/disabled state (T11984 decision table) is sacred.
+ *
+ * @task T11993
+ */
+function installSliceUnit() {
+  const sliceFile = getSystemdSliceFile();
+  const unit = buildSliceUnit();
+  const written = writeIfChanged(sliceFile, unit);
+
+  if (written) {
+    console.log(`CLEO: Wrote systemd slice unit → ${sliceFile}`);
+    const reload = runBin('systemctl', ['--user', 'daemon-reload']);
+    if (!reload.ok) {
+      console.log(`CLEO: systemctl daemon-reload skipped (${reload.output || 'no output'})`);
+    }
+  } else {
+    console.log('CLEO: cleo.slice already up-to-date — skipping write.');
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Linux — systemd user unit
 // ---------------------------------------------------------------------------
@@ -375,8 +634,20 @@ function buildSystemdUnit(cleoExec, scope) {
   //     OOM-killed. systemd now stops restarting after 5 failures in 60 s.
   //   - NODE_OPTIONS=--max-old-space-size: a runaway daemon tick throws a
   //     recoverable single-process JS heap OOM instead of growing unbounded.
-  //   - MemoryMax: best-effort soft cgroup ceiling (enforced only when the user
-  //     manager has memory-cgroup delegation; harmless otherwise).
+  //   - MemoryMax=2G: best-effort soft cgroup ceiling (enforced only when the
+  //     user manager has memory-cgroup delegation; harmless otherwise).
+  //
+  // Drop-in overrides (T11984 / DHQ-D):
+  //   Operators may tighten MemoryMax — or any other [Service] directive —
+  //   by placing a drop-in file at:
+  //     ~/.config/systemd/user/cleo-daemon.service.d/10-memory-cap.conf
+  //   Example content:
+  //     [Service]
+  //     MemoryHigh=768M
+  //     MemoryMax=1G
+  //   A drop-in's directives override the unit's values; re-running postinstall
+  //   rewrites the BASE unit file but does NOT touch or remove any drop-ins.
+  //   Run `systemctl --user daemon-reload` after adding/changing a drop-in.
   return `[Unit]
 Description=${description}
 Documentation=https://github.com/kryptobaseddev/cleocode
@@ -403,12 +674,23 @@ WantedBy=default.target
 /**
  * Install and optionally activate the systemd user unit.
  *
+ * Respects operator state (T11984): if the unit already exists and is
+ * currently disabled or masked, the postinstall hook does NOT re-enable it.
+ * The operator's explicit `systemctl --user disable cleo-daemon` survives
+ * upgrades. See `decideDaemonAction` for the full decision table.
+ *
  * @param {string} cleoExec - Absolute path to the `cleo` binary.
  * @param {{ scopeSagaId?: string; scopeEpicId?: string }} [scope] - Optional scope filter (T11497 AC3).
  */
 function installSystemd(cleoExec, scope) {
+  // Install the cleo.slice unit first so child scopes can reference it.
+  // The slice write is idempotent and does NOT touch the daemon service.
+  installSliceUnit();
+
   const unitFile = getSystemdUnitFile();
   const unit = buildSystemdUnit(cleoExec, scope);
+  // firstInstall = true when the file did NOT exist before this write.
+  const fileExistedBefore = existsSync(unitFile);
   const written = writeIfChanged(unitFile, unit);
 
   if (written) {
@@ -422,14 +704,54 @@ function installSystemd(cleoExec, scope) {
     console.log('CLEO: systemd unit already up-to-date — skipping write.');
   }
 
-  if (process.env[DAEMON_DISABLE_ENV] === '1') {
+  // Determine the operator's current enabled state (needed for upgrade path).
+  const isEnabledResult = runBin('systemctl', ['--user', 'is-enabled', SYSTEMD_UNIT_NAME]);
+  const isEnabledState = isEnabledResult.output.trim();
+
+  const action = decideDaemonAction({
+    firstInstall: !fileExistedBefore,
+    isEnabledState,
+    autoStartConfig: readGlobalAutoStart(),
+    envDisable: process.env[DAEMON_DISABLE_ENV] === '1',
+  });
+
+  if (action === 'skip') {
+    const reason = process.env[DAEMON_DISABLE_ENV] === '1'
+      ? `${DAEMON_DISABLE_ENV}=1 (CI/container path)`
+      : 'daemon.autoStart=false in global config';
     console.log(
-      `CLEO: ${DAEMON_DISABLE_ENV}=1 — unit written but activation skipped (CI/container path).`,
+      `CLEO: Unit written but activation skipped (${reason}).`,
     );
+    console.log("CLEO: To enable later: run 'cleo daemon enable' or 'systemctl --user enable --now cleo-daemon'");
     return;
   }
 
-  // Enable + start the service.
+  if (action === 'leave-disabled') {
+    console.log(
+      `CLEO: cleo-daemon left ${isEnabledState} (operator state respected — skipping re-enable).`,
+    );
+    console.log("CLEO: To re-enable: run 'cleo daemon enable' or 'systemctl --user enable --now cleo-daemon'");
+    return;
+  }
+
+  if (action === 'restart-if-changed') {
+    if (written) {
+      // Unit content changed on an already-enabled service — restart to pick up changes.
+      const restart = runBin('systemctl', ['--user', 'restart', SYSTEMD_UNIT_NAME]);
+      if (restart.ok) {
+        console.log('CLEO: systemd user service restarted (unit updated).');
+      } else {
+        console.log(
+          `CLEO: systemctl restart skipped (${restart.output || 'systemctl unavailable'}).`,
+        );
+      }
+    } else {
+      console.log('CLEO: systemd unit unchanged and already enabled — no restart needed.');
+    }
+    return;
+  }
+
+  // action === 'enable-and-start': first install or unknown prior state.
   const enable = runBin('systemctl', ['--user', 'enable', '--now', SYSTEMD_UNIT_NAME]);
   if (enable.ok) {
     console.log('CLEO: systemd user service enabled and started.');
@@ -540,15 +862,39 @@ function buildLaunchdPlist(cleoExec, scope) {
 `;
 }
 
+/**
+ * Check whether the launchd agent is currently loaded (macOS).
+ *
+ * Uses `launchctl list <label>` — exit 0 with output = loaded; non-zero or
+ * empty = not loaded (disabled / never loaded).
+ *
+ * @returns {'enabled' | 'disabled' | 'not-found'} Launchd agent state.
+ */
+function getLaunchdEnabledState() {
+  const result = runBin('launchctl', ['list', LAUNCHD_PLIST_LABEL]);
+  if (result.ok && result.output.trim()) {
+    return 'enabled';
+  }
+  // Non-zero means 'not in the service manager' — treat same as 'disabled'.
+  return 'disabled';
+}
+
 /**
  * Install and optionally load the launchd plist.
  *
+ * Respects operator state (T11984): if the plist already exists and the agent
+ * is NOT currently loaded, the postinstall hook does NOT reload it. The
+ * operator's explicit `launchctl bootout` survives upgrades. See
+ * `decideDaemonAction` for the full decision table.
+ *
  * @param {string} cleoExec - Absolute path to the `cleo` binary.
  * @param {{ scopeSagaId?: string; scopeEpicId?: string }} [scope] - Optional scope filter (T11497 AC3).
  */
 function installLaunchd(cleoExec, scope) {
   const plistFile = getLaunchdPlistFile();
   const plist = buildLaunchdPlist(cleoExec, scope);
+  // firstInstall = true when the file did NOT exist before this write.
+  const fileExistedBefore = existsSync(plistFile);
   const written = writeIfChanged(plistFile, plist);
 
   if (written) {
@@ -557,14 +903,55 @@ function installLaunchd(cleoExec, scope) {
     console.log('CLEO: launchd plist already up-to-date — skipping write.');
   }
 
-  if (process.env[DAEMON_DISABLE_ENV] === '1') {
+  // Determine the operator's current loaded state (needed for upgrade path).
+  const isEnabledState = fileExistedBefore ? getLaunchdEnabledState() : 'not-found';
+
+  const action = decideDaemonAction({
+    firstInstall: !fileExistedBefore,
+    isEnabledState,
+    autoStartConfig: readGlobalAutoStart(),
+    envDisable: process.env[DAEMON_DISABLE_ENV] === '1',
+  });
+
+  if (action === 'skip') {
+    const reason = process.env[DAEMON_DISABLE_ENV] === '1'
+      ? `${DAEMON_DISABLE_ENV}=1 (CI/container path)`
+      : 'daemon.autoStart=false in global config';
+    console.log(
+      `CLEO: Plist written but activation skipped (${reason}).`,
+    );
+    console.log(`CLEO: To enable later: launchctl load "${plistFile}"`);
+    return;
+  }
+
+  if (action === 'leave-disabled') {
     console.log(
-      `CLEO: ${DAEMON_DISABLE_ENV}=1 — plist written but activation skipped (CI/container path).`,
+      'CLEO: cleo-daemon launchd agent left unloaded (operator state respected — skipping re-load).',
     );
+    console.log(`CLEO: To re-enable: launchctl load "${plistFile}"`);
+    return;
+  }
+
+  if (action === 'restart-if-changed') {
+    const uid = process.getuid ? String(process.getuid()) : '';
+    if (written && uid) {
+      // Plist content changed on an already-loaded agent — reload to pick up changes.
+      runBin('launchctl', ['bootout', `gui/${uid}`, plistFile]);
+      const reload = runBin('launchctl', ['bootstrap', `gui/${uid}`, plistFile]);
+      if (reload.ok) {
+        console.log(`CLEO: launchd agent reloaded (plist updated, gui/${uid}).`);
+      } else {
+        console.log(
+          `CLEO: launchctl reload skipped (${reload.output || 'launchctl unavailable'}).`,
+        );
+      }
+    } else {
+      console.log('CLEO: launchd plist unchanged and already loaded — no reload needed.');
+    }
     return;
   }
 
-  // Try bootstrap (macOS 10.13+) first; fall back to legacy launchctl load.
+  // action === 'enable-and-start': first install or unknown prior state.
   const uid = process.getuid ? String(process.getuid()) : '';
   if (uid) {
     const bootstrap = runBin('launchctl', [