@chorus-aidlc/chorus 0.16.3 → 0.17.0

package/cli/daemon-service.mjs

@@ -35,6 +35,9 @@ import { fileURLToPath } from "node:url";
 /** The systemd --user unit name (also the launchd label stem). */
 export const SERVICE_NAME = "chorus-daemon";
 
+/** The macOS launchd LaunchAgent label. */
+export const LAUNCHD_LABEL = "com.chorus.daemon";
+
 /** Default IO bundle — overridable per-call for tests (no real disk/process). */
 function defaultIO() {
   return {
@@ -232,25 +235,39 @@ function systemdQuoteArg(token) {
 
 /**
  * Detect whether a supervisor already manages the chorus daemon on this host.
- * Linux only (systemd --user); everything else reports `{ kind: "none" }`.
- *   - kind: "systemd" with installed (unit file present, `is-enabled` not
- *     "not-found") and active (`is-active` == "active").
- *   - kind: "none" otherwise (or when systemctl is unavailable).
+ *   - Linux → kind: "systemd" (unit file present and/or `is-active` == "active").
+ *   - macOS → kind: "launchd" (LaunchAgent plist present and/or `launchctl list
+ *     <label>` reports it loaded).
+ *   - kind: "none" otherwise (or when the service manager is unavailable).
  * Used by the lifecycle subcommands to decide whether to delegate.
  * @param {object} [io]
- * @returns {{ kind: "systemd", installed: boolean, active: boolean, unitPath: string } | { kind: "none" }}
+ * @returns {{ kind: "systemd", installed: boolean, active: boolean, unitPath: string }
+ *   | { kind: "launchd", installed: boolean, active: boolean, label: string, plistPath: string }
+ *   | { kind: "none" }}
  */
 export function detectSupervisor(io = defaultIO()) {
-  if (io.platform !== "linux") return { kind: "none" };
-  const unitPath = systemdUnitPath(io);
-  const installed = safeExists(unitPath, io);
-  // `is-active` is authoritative for "running under systemd right now". Query it
-  // even when the unit file is absent: a transient/unit-less path still returns
-  // non-active, and we never want to throw here.
-  const activeRes = systemctlUser(["is-active", `${SERVICE_NAME}.service`], io);
-  const active = (activeRes.stdout ?? "").trim() === "active";
-  if (!installed && !active) return { kind: "none" };
-  return { kind: "systemd", installed, active, unitPath };
+  if (io.platform === "linux") {
+    const unitPath = systemdUnitPath(io);
+    const installed = safeExists(unitPath, io);
+    // `is-active` is authoritative for "running under systemd right now". Query it
+    // even when the unit file is absent: a transient/unit-less path still returns
+    // non-active, and we never want to throw here.
+    const activeRes = systemctlUser(["is-active", `${SERVICE_NAME}.service`], io);
+    const active = (activeRes.stdout ?? "").trim() === "active";
+    if (!installed && !active) return { kind: "none" };
+    return { kind: "systemd", installed, active, unitPath };
+  }
+  if (io.platform === "darwin") {
+    const plistPath = launchdPlistPath(io);
+    const installed = safeExists(plistPath, io);
+    // `launchctl list <label>` exits 0 when the agent is loaded (prints its dict),
+    // non-zero otherwise. This is authoritative for "loaded right now".
+    const listRes = launchctl(["list", LAUNCHD_LABEL], io);
+    const active = listRes.status === 0;
+    if (!installed && !active) return { kind: "none" };
+    return { kind: "launchd", installed, active, label: LAUNCHD_LABEL, plistPath };
+  }
+  return { kind: "none" };
 }
 
 function safeExists(path, io) {
@@ -281,6 +298,44 @@ export function journalctlUser(args, io = defaultIO()) {
   }
 }
 
+/** Run `launchctl <args>`, capturing output. Never throws. macOS only. */
+export function launchctl(args, io = defaultIO()) {
+  try {
+    const r = io.spawnSync("launchctl", args, { encoding: "utf8" });
+    // spawnSync sets .error (and status null) when the binary is missing (ENOENT);
+    // surface that as a null status + the error message rather than throwing.
+    if (r?.error) {
+      return { status: null, stdout: r?.stdout ?? "", stderr: String(r.error.message ?? r.error) };
+    }
+    return { status: r?.status ?? null, stdout: r?.stdout ?? "", stderr: r?.stderr ?? "" };
+  } catch (err) {
+    return { status: null, stdout: "", stderr: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Classify whether THIS host supports installing a real boot-autostart daemon
+ * service, and via which supervisor. The single source of truth both
+ * `chorus daemon install` and the `chorus agents add` daemon-setup step consult so they
+ * cannot disagree about what "supported" means (add-chorus-init-daemon-setup).
+ *   - "systemd"     — Linux where `systemctl --user` is usable.
+ *   - "launchd"     — macOS (launchctl is always present).
+ *   - "unsupported" — Linux without a usable systemctl, Windows, or anything else.
+ * Pure-ish: only probes `systemctl --user --version` on Linux (injected IO).
+ * @param {object} [io]
+ * @returns {"systemd" | "launchd" | "unsupported"}
+ */
+export function autostartCapability(io = defaultIO()) {
+  if (io.platform === "darwin") return "launchd";
+  if (io.platform === "linux") {
+    // `systemctl --user` must be reachable — a container/minimal host may lack it,
+    // in which case there is no real boot service we can install.
+    const probe = systemctlUser(["--version"], io);
+    return probe.status === 0 ? "systemd" : "unsupported";
+  }
+  return "unsupported";
+}
+
 /**
  * Install the systemd --user unit (Linux) or return the template to print
  * (macOS/Windows). On Linux: write the unit, `daemon-reload`, `enable --now`.
@@ -331,19 +386,39 @@ export function installService(spec, io = defaultIO()) {
     }
   }
   if (io.platform === "darwin") {
+    // Real launchd install (add-chorus-init-daemon-setup): write the LaunchAgent
+    // plist and `launchctl load -w` it so it starts now and at every login —
+    // no longer a printed-template-only posture.
     const plistPath = launchdPlistPath(io);
     const unitText = renderLaunchdPlist({ ...spec, home, logPath: join(home, ".chorus", "daemon.log") });
-    return {
-      platform: "darwin",
-      installed: false,
-      unitPath: plistPath,
-      unitText,
-      steps: [
-        `Save the plist below to ${plistPath}`,
-        `launchctl load -w ${plistPath}`,
-        `Check: launchctl list | grep com.chorus.daemon`,
-      ],
-    };
+    const steps = [];
+    try {
+      io.mkdirSync(dirname(plistPath), { recursive: true });
+      // Back up an existing plist before overwrite (backup-before-overwrite
+      // convention, mirrors the init plugin-install step); best-effort.
+      if (safeExists(plistPath, io) && typeof io.readFileSync === "function") {
+        try {
+          io.writeFileSync(`${plistPath}.chorus-bak`, io.readFileSync(plistPath));
+          steps.push(`backed up existing plist → ${plistPath}.chorus-bak`);
+        } catch {
+          // a failed backup must not block the (idempotent) re-install
+        }
+      }
+      // Unload any currently-loaded copy first so a re-install applies the new
+      // plist rather than leaving the old agent running (parallels the systemd
+      // restart). Best-effort — a not-loaded agent returns non-zero here.
+      launchctl(["unload", plistPath], io);
+      io.writeFileSync(plistPath, unitText, { mode: 0o644 });
+      steps.push(`wrote ${plistPath}`);
+      const load = launchctl(["load", "-w", plistPath], io);
+      if (load.status !== 0) {
+        return { platform: "darwin", installed: false, unitPath: plistPath, unitText, steps, error: `launchctl load -w failed: ${load.stderr.trim() || `exit ${load.status}`}` };
+      }
+      steps.push(`launchctl load -w ${plistPath}`);
+      return { platform: "darwin", installed: true, unitPath: plistPath, unitText, steps };
+    } catch (err) {
+      return { platform: "darwin", installed: false, unitPath: plistPath, unitText, steps, error: err instanceof Error ? err.message : String(err) };
+    }
   }
   // Windows / other: no first-class service model without native deps. Print the
   // foreground command an operator can wrap in their supervisor of choice.
@@ -398,18 +473,30 @@ export function uninstallService(io = defaultIO()) {
     return { platform: "linux", removed: existed || disable.status === 0, unitPath, steps };
   }
   if (io.platform === "darwin") {
+    // Real launchd uninstall (add-chorus-init-daemon-setup): unload the agent and
+    // remove the plist. Idempotent: tolerate an already-absent plist / not-loaded
+    // agent.
     const plistPath = launchdPlistPath(io);
-    return {
-      platform: "darwin",
-      removed: false,
-      unitPath: plistPath,
-      steps: [`launchctl unload -w ${plistPath}`, `rm ${plistPath}`],
-    };
+    const steps = [];
+    const existed = safeExists(plistPath, io);
+    // unload -w stops the agent and clears its "enabled" override; a not-loaded
+    // agent returns non-zero, which we tolerate.
+    const unload = launchctl(["unload", "-w", plistPath], io);
+    if (unload.status === 0) steps.push(`launchctl unload -w ${plistPath}`);
+    try {
+      if (existed) {
+        io.unlinkSync(plistPath);
+        steps.push(`removed ${plistPath}`);
+      }
+    } catch (err) {
+      return { platform: "darwin", removed: false, unitPath: plistPath, steps, error: err instanceof Error ? err.message : String(err) };
+    }
+    return { platform: "darwin", removed: existed, unitPath: plistPath, steps };
   }
   return {
     platform: "other",
     removed: false,
-    steps: ["Automatic service uninstall is only supported on Linux (systemd). Remove the daemon from your supervisor manually."],
+    steps: ["Automatic service uninstall is only supported on Linux (systemd) and macOS (launchd). Remove the daemon from your supervisor manually."],
   };
 }
 

package/cli/daemon.mjs

@@ -31,6 +31,7 @@ import {
   yoloWarningLine,
 } from "./daemon-permission-mode.mjs";
 import { resolveAgentType, backendClientType } from "./daemon-agent.mjs";
+import { isWakeableAgentType } from "./init/agent-type-map.mjs";
 import { formatBanner, agentNotFoundWarningLine } from "./daemon-banner.mjs";
 import { ChorusClient, validateAndFetchIdentity } from "./chorus-client.mjs";
 import { SseListener } from "./sse-listener.mjs";
@@ -41,6 +42,8 @@ import { Waker } from "./waker.mjs";
 import { LineageResolver } from "./lineage.mjs";
 import { resolveClaudePath } from "./claude-spawner.mjs";
 import { resolveCodexPath } from "./codex-spawner.mjs";
+import { resolveDshPath } from "./dsh-spawner.mjs";
+import { prepareManagedDshConfig } from "./dsh-managed-config.mjs";
 import { resolveKiroPath } from "./kiro-spawner.mjs";
 import { selectSpawner } from "./spawner-select.mjs";
 import {
@@ -73,6 +76,7 @@ import {
   uninstallService,
   systemctlUser,
   journalctlUser,
+  launchctl,
   resolveServicePaths,
   SERVICE_NAME,
 } from "./daemon-service.mjs";
@@ -152,7 +156,13 @@ export function buildDaemon(creds, deps = {}) {
   // (construction byte-identical to before); codex → CodexSpawner. `creds` are
   // passed through so the Codex backend can export the daemon key into the woken
   // process env (the Claude backend ignores creds — it gets its key via --mcp-config).
-  const spawner = deps.spawner ?? selectSpawner(agentType, { logger, permissionMode, creds });
+  const spawner = deps.spawner ?? selectSpawner(agentType, {
+    logger,
+    permissionMode,
+    creds,
+    bundleVersion: deps.bundleVersion,
+    prepareManagedConfigFn: deps.prepareManagedDshConfig,
+  });
   const maxConcurrency = deps.maxConcurrency ?? 4;
 
   // ===== Multi-path: the SET of cwds this daemon serves (T3 — FR-5) =====
@@ -625,6 +635,27 @@ export function buildMultiAgentDaemon(agentConfigs, deps = {}) {
 
   const agents = agentConfigs
     .map((cfg, i) => {
+      // Offline agents are proxy-only: their key is parked in daemon.json solely so
+      // `chorus mcp` can act under that identity (it reads the file directly, not via
+      // this runtime). The daemon-multi-agent spec says the daemon SHALL NOT construct
+      // a spawner, dispatch wakes, OR register it as a wakeable connection. Building a
+      // runtime here would open an SSE stream that self-reports a connection — so we
+      // SKIP the offline agent entirely (no runtime, no connection, no self-report),
+      // which is what closes the T4-review registration gap. Returning null (kept in
+      // step with a build failure) preserves the original index `i` for the per-agent
+      // injected-dep alignment below (map keeps the index; the filter drops the null).
+      // Skip = not woken: an offline backend (can't be woken) OR a wakeable backend
+      // the operator opted out of (`daemonWake: false`). Both get the same proxy-only
+      // treatment (no runtime/SSE/connection); the key stays in daemon.json for
+      // `chorus mcp`. `daemonWake` absent/true ⇒ woken (back-compat with entries that
+      // predate the field).
+      if (cfg.agentType === "offline" || cfg.daemonWake === false) {
+        const why = cfg.agentType === "offline" ? "offline backend" : "daemon waking disabled (daemonWake:false)";
+        logger.info?.(
+          `[Chorus] agent ${cfg.label}: ${why} — proxy-only key, no wakeable connection registered`,
+        );
+        return null;
+      }
       // Per-agent deps: cfg fields drive the per-agent runtime; injectable fakes are
       // indexed per agent. `cwd` (singular) is cleared so a caller's single value can
       // never leak across agents — each agent's `cwds` is authoritative.
@@ -647,7 +678,13 @@ export function buildMultiAgentDaemon(agentConfigs, deps = {}) {
           : deps.makeSseListener,
       };
       try {
-        return { cfg, daemon: build({ url: cfg.url, apiKey: cfg.apiKey }, agentDeps) };
+        return {
+          cfg,
+          daemon: build(
+            { url: cfg.url, apiKey: cfg.apiKey, agentUuid: cfg.agentUuid, agentName: cfg.agentName },
+            agentDeps,
+          ),
+        };
       } catch (err) {
         logger.error?.(
           `[Chorus] agent ${cfg.label}: failed to build runtime — skipping ` +
@@ -659,6 +696,33 @@ export function buildMultiAgentDaemon(agentConfigs, deps = {}) {
     .filter(Boolean);
 
   if (agents.length === 0) {
+    // Distinguish "all offline" (nothing wakeable to serve — not an error) from
+    // "every wakeable runtime threw" (a real build failure). An all-offline config
+    // is a legitimate proxy-only setup: return an idle no-op daemon so the process
+    // stays up (its offline keys remain available to `chorus mcp`) rather than
+    // crashing with a misleading "all runtimes failed" error.
+    const anyWakeable = agentConfigs.some(
+      (cfg) => isWakeableAgentType(cfg.agentType) && cfg.daemonWake !== false,
+    );
+    if (!anyWakeable) {
+      logger.warn?.(
+        "[Chorus] all configured agents are offline — no daemon-wakeable backend to serve. " +
+          "Offline keys remain in daemon.json for `chorus mcp`; the daemon has nothing to wake.",
+      );
+      return {
+        agents: [],
+        connections: [],
+        // No wakeable connection was registered, so there are no back-compat aliases.
+        waker: undefined,
+        router: undefined,
+        sseListener: undefined,
+        // Never settles: an idle daemon simply waits (it registered no connection, so
+        // it can never be "all-conflicted"). runDaemon keeps it alive on waitForever.
+        allConflict: new Promise(() => {}),
+        async start() {},
+        async stop() {},
+      };
+    }
     throw new Error("buildMultiAgentDaemon: all agent runtimes failed to build");
   }
 
@@ -742,6 +806,7 @@ export async function runDaemon(flags = {}, deps = {}) {
   // banner shows the right binary instead of always probing for `claude`.
   const findClaude = deps.resolveClaudePath ?? resolveClaudePath;
   const findCodex = deps.resolveCodexPath ?? resolveCodexPath;
+  const findDsh = deps.resolveDshPath ?? resolveDshPath;
   const findKiro = deps.resolveKiroPath ?? resolveKiroPath;
   const verbose = flags.verbose === true || env.CHORUS_VERBOSE === "1";
 
@@ -774,6 +839,7 @@ export async function runDaemon(flags = {}, deps = {}) {
     uninstallService,
     systemctlUser,
     journalctlUser,
+    launchctl,
     resolveServicePaths: () => resolveServicePaths(env),
   };
   // The preflight dep bundle — built from the same seams runDaemon resolved, so
@@ -786,6 +852,9 @@ export async function runDaemon(flags = {}, deps = {}) {
     writeConfig: deps.writeConfig,
     readJson: deps.readJson,
     loginPath: deps.loginPath,
+    prepareManagedDshConfig: deps.prepareManagedDshConfig,
+    bundleVersion: version,
+    resolveDshPath: findDsh,
   };
 
   const action = flags.action ?? "run";
@@ -848,6 +917,11 @@ export async function runDaemon(flags = {}, deps = {}) {
     for (const cfg of agentConfigs) {
       try {
         const id = await validate({ url: cfg.url, apiKey: cfg.apiKey });
+        // The validated identity is authoritative for the CHORUS_AGENT_PROFILE the
+        // spawner exports — fill from it when daemon.json omitted the field
+        // (resolveAgentConfigs already normalized these to a trimmed string | undefined).
+        cfg.agentUuid = cfg.agentUuid ?? id.uuid;
+        cfg.agentName = cfg.agentName ?? id.name;
         okConfigs.push(cfg);
         log(
           `[Chorus] agent ${cfg.label}: ${id.name} (${id.uuid}) — ${cfg.agentType}, ` +
@@ -884,6 +958,8 @@ export async function runDaemon(flags = {}, deps = {}) {
       mcpClient: deps.mcpClient,
       lineage: deps.lineage,
       build: deps.build,
+      bundleVersion: version,
+      prepareManagedDshConfig: deps.prepareManagedDshConfig,
     });
 
     const shutdownMulti = () => {
@@ -924,11 +1000,16 @@ export async function runDaemon(flags = {}, deps = {}) {
   // Detect the SELECTED backend's executable (non-fatal): the daemon still
   // subscribes when it's missing; a wake surfaces the error visibly when one
   // arrives. The resolved path (or absence) is shown in the banner below. Each
-  // backend probes its own binary — codex → resolveCodexPath, kiro →
-  // resolveKiroPath, otherwise resolveClaudePath — so a `--agent kiro` run probes
-  // (and the banner reports) `kiro-cli`, not `claude`.
+  // backend probes its own binary, including dsh-jsonrpc-agent for dsh, so the
+  // startup banner and warning report the selected runtime rather than Claude.
   const cliPath =
-    agentType === "codex" ? findCodex() : agentType === "kiro" ? findKiro() : findClaude();
+    agentType === "codex"
+      ? findCodex()
+      : agentType === "kiro"
+        ? findKiro()
+        : agentType === "dsh"
+          ? findDsh()
+          : findClaude();
 
   // The daemon.json the layered config readers (credentials, sigint timeout, cwds)
   // consult. Surfacing its absolute path + presence in the banner makes it obvious
@@ -979,7 +1060,11 @@ export async function runDaemon(flags = {}, deps = {}) {
   }
   log(`[Chorus] browse roots: ${browseRoots.join(", ")} (discovery only; no connections created)`);
 
-  const daemon = build(creds, {
+  const daemon = build(
+    // Export this agent's identity as CHORUS_AGENT_PROFILE in the woken session
+    // (the validated identity is authoritative; creds may already carry it).
+    { ...creds, agentUuid: creds.agentUuid ?? identity.uuid, agentName: creds.agentName ?? identity.name },
+    {
     logger: { info: log, warn: errLog, error: errLog },
     permissionMode,
     agentType,
@@ -987,6 +1072,8 @@ export async function runDaemon(flags = {}, deps = {}) {
     sigintTimeoutMs,
     cwds,
     browseRoots,
+    bundleVersion: version,
+    prepareManagedDshConfig: deps.prepareManagedDshConfig,
   });
 
   // Graceful shutdown on signals.
@@ -1097,11 +1184,13 @@ export async function preflight(ctx) {
 /**
  * Dispatch a daemon lifecycle subcommand. Two families:
  *   - install / uninstall — manage the boot-autostart supervisor service
- *     (systemd --user on Linux; a printed template on macOS/Windows).
+ *     (systemd --user on Linux; launchd LaunchAgent on macOS; a printed template
+ *     on Windows/other).
  *   - status / stop / restart / logs — when a supervisor unit is installed and
- *     active, DELEGATE to it (systemctl / journalctl) so a supervised daemon is
- *     never misreported as "not running"; otherwise operate on the
- *     pidfile/logfile-managed `-d` background daemon exactly as before.
+ *     active, DELEGATE to it (systemctl / journalctl on Linux, launchctl on
+ *     macOS) so a supervised daemon is never misreported as "not running";
+ *     otherwise operate on the pidfile/logfile-managed `-d` background daemon
+ *     exactly as before.
  * Each reports clearly (no silent failure). `restart` performs
  * stop-then-detached-start on the pidfile path.
  * @returns {Promise<number>} exit code
@@ -1171,7 +1260,7 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
     // CHORUS_AGENT env / a prior stored choice; probes the selected CLI and warns
     // (non-fatal) when it is missing. An unknown --agent was already rejected by
     // resolveAgentType above, so this phase never fails.
-    await installCfg.resolveInstallAgent(flags, env, {
+    const installAgent = await installCfg.resolveInstallAgent(flags, env, {
       isTTY,
       skip,
       writeConfig: pfDeps?.writeConfig ?? updateDaemonConfig,
@@ -1181,6 +1270,26 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
       log,
       errLog,
     });
+    if (
+      installAgent.agent === "dsh" &&
+      !String(env.CHORUS_DSH_CONFIG ?? "").trim() &&
+      !String(env.DSH_CORDIS_CONFIG ?? "").trim()
+    ) {
+      try {
+        await (pfDeps?.prepareManagedDshConfig ?? prepareManagedDshConfig)({
+          env,
+          bundleVersion: pfDeps?.bundleVersion,
+          dshPath: installAgent.cliPath ?? pfDeps?.resolveDshPath?.(),
+          creds: credResult.creds,
+        });
+      } catch (error) {
+        errLog(
+          `[Chorus] install aborted — dsh managed composition preparation failed: ` +
+            `${error instanceof Error ? error.message : String(error)}`,
+        );
+        return 1;
+      }
+    }
 
     const spec = {
       ...svc.resolveServicePaths(),
@@ -1198,21 +1307,26 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
       for (const s of r.steps) log(`[Chorus]   ${s}`);
       log(`[Chorus] it will now start automatically at login. Manage it with:`);
       log(`[Chorus]   chorus daemon status | stop | restart | logs`);
-      // A --user service only survives logout with lingering enabled; and a
-      // separately-started `chorus daemon -d` would hold the same paths and make
-      // this service exit-and-retry. Surface both so neither is a silent gotcha.
-      log(`[Chorus] to keep it running after you log out: loginctl enable-linger "$USER"`);
-      log(`[Chorus] if you previously ran 'chorus daemon -d', stop it first ('chorus daemon stop') so it doesn't hold the same paths.`);
+      if (r.platform === "linux") {
+        // A --user service only survives logout with lingering enabled; and a
+        // separately-started `chorus daemon -d` would hold the same paths and make
+        // this service exit-and-retry. Surface both so neither is a silent gotcha.
+        log(`[Chorus] to keep it running after you log out: loginctl enable-linger "$USER"`);
+        log(`[Chorus] if you previously ran 'chorus daemon -d', stop it first ('chorus daemon stop') so it doesn't hold the same paths.`);
+      } else if (r.platform === "darwin") {
+        log(`[Chorus] if you previously ran 'chorus daemon -d', stop it first ('chorus daemon stop') so it doesn't hold the same paths.`);
+      }
       return 0;
     }
-    if (r.platform === "linux") {
-      // Linux install actually failed (write / systemctl error) — surface it.
+    if (r.platform === "linux" || r.platform === "darwin") {
+      // A real install (systemd/launchd) actually failed — surface it, never a
+      // silent success or a misleading "not supported" message.
       errLog(`[Chorus] service install failed: ${r.error}`);
       for (const s of r.steps) errLog(`[Chorus]   (did: ${s})`);
       return 1;
     }
-    // macOS / Windows: not auto-installed by design — print the template + steps.
-    log(`[Chorus] automatic install is Linux-only. To run the daemon as a service on this platform:`);
+    // Windows / other: no first-class auto-install — print the template + steps.
+    log(`[Chorus] automatic install is not supported on this platform. To run the daemon as a service:`);
     for (const s of r.steps) log(`[Chorus]   ${s}`);
     log("");
     log(r.unitText);
@@ -1220,7 +1334,7 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
   }
   if (action === "uninstall") {
     const r = svc.uninstallService();
-    if (r.platform === "linux") {
+    if (r.platform === "linux" || r.platform === "darwin") {
       if (r.error) {
         errLog(`[Chorus] service uninstall failed: ${r.error}`);
         return 1;
@@ -1233,22 +1347,32 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
       }
       return 0;
     }
-    log(`[Chorus] automatic uninstall is Linux-only. To remove the service on this platform:`);
+    log(`[Chorus] automatic uninstall is not supported on this platform. To remove the service:`);
     for (const s of r.steps) log(`[Chorus]   ${s}`);
     return 0;
   }
 
   // For the control verbs, prefer a live supervisor unit over the pidfile.
+  // A supervisor is systemd (Linux) or launchd (macOS); both delegate the verbs
+  // to their service manager so a supervised daemon is never misreported as "not
+  // running" via the pidfile.
   const sup = svc.detectSupervisor();
-  const supervised = sup.kind === "systemd" && sup.installed;
+  const systemd = sup.kind === "systemd" && sup.installed;
+  const launchd = sup.kind === "launchd" && sup.installed;
 
   if (action === "status") {
-    if (supervised) {
+    if (systemd) {
       log(`[Chorus] daemon is managed by systemd (${SERVICE_NAME}.service) — ${sup.active ? "active" : "installed but NOT active"}.`);
       const r = svc.systemctlUser(["status", "--no-pager", `${SERVICE_NAME}.service`]);
       if (r.stdout) log(r.stdout.trimEnd());
       return sup.active ? 0 : 1;
     }
+    if (launchd) {
+      log(`[Chorus] daemon is managed by launchd (${sup.label}) — ${sup.active ? "loaded" : "installed but NOT loaded"}.`);
+      const r = svc.launchctl(["list", sup.label]);
+      if (r.stdout) log(r.stdout.trimEnd());
+      return sup.active ? 0 : 1;
+    }
     const s = lifecycle.isRunning();
     if (s.running) log(`[Chorus] daemon is running (pid ${s.pid}).`);
     else if (s.stale) log(`[Chorus] daemon is NOT running (stale pidfile for pid ${s.pid}).`);
@@ -1256,7 +1380,7 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
     return 0;
   }
   if (action === "logs") {
-    if (supervised) {
+    if (systemd) {
       const r = svc.journalctlUser(["-u", `${SERVICE_NAME}.service`, "--no-pager", "-n", "200"]);
       if (r.status !== 0 && !r.stdout) {
         errLog(`[Chorus] could not read the service journal: ${r.stderr.trim() || `exit ${r.status}`}`);
@@ -1265,6 +1389,8 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
       log(r.stdout.trimEnd());
       return 0;
     }
+    // launchd (and the pidfile path) both log to ~/.chorus/daemon.log — the plist
+    // routes stdout/stderr there — so the pidfile logfile reader serves both.
     const r = lifecycle.readLog();
     if (!r.ok) {
       errLog(`[Chorus] ${r.message}`);
@@ -1274,7 +1400,7 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
     return 0;
   }
   if (action === "stop") {
-    if (supervised) {
+    if (systemd) {
       const r = svc.systemctlUser(["stop", `${SERVICE_NAME}.service`]);
       if (r.status === 0) {
         log(`[Chorus] stopped the daemon service (systemctl --user stop ${SERVICE_NAME}.service).`);
@@ -1284,6 +1410,16 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
       errLog(`[Chorus] failed to stop the service: ${r.stderr.trim() || `exit ${r.status}`}`);
       return 1;
     }
+    if (launchd) {
+      const r = svc.launchctl(["unload", sup.plistPath]);
+      if (r.status === 0) {
+        log(`[Chorus] stopped the daemon service (launchctl unload ${sup.plistPath}).`);
+        log(`[Chorus] note: it will load again at next login. To disable: chorus daemon uninstall`);
+        return 0;
+      }
+      errLog(`[Chorus] failed to stop the service: ${r.stderr.trim() || `exit ${r.status}`}`);
+      return 1;
+    }
     // --force: unconditional pidfile cleanup for stuck states the identity
     // probe cannot resolve. Threaded from the parsed client flags.
     const r = lifecycle.stopDaemon({ force: pfDeps?.flags?.force === true });
@@ -1295,7 +1431,7 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
     return ok ? 0 : 1;
   }
   if (action === "restart") {
-    if (supervised) {
+    if (systemd) {
       const r = svc.systemctlUser(["restart", `${SERVICE_NAME}.service`]);
       if (r.status === 0) {
         log(`[Chorus] restarted the daemon service (systemctl --user restart ${SERVICE_NAME}.service).`);
@@ -1304,6 +1440,17 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, se
       errLog(`[Chorus] failed to restart the service: ${r.stderr.trim() || `exit ${r.status}`}`);
       return 1;
     }
+    if (launchd) {
+      // launchd has no atomic restart — unload then load the same plist.
+      svc.launchctl(["unload", sup.plistPath]);
+      const r = svc.launchctl(["load", sup.plistPath]);
+      if (r.status === 0) {
+        log(`[Chorus] restarted the daemon service (launchctl unload+load ${sup.plistPath}).`);
+        return 0;
+      }
+      errLog(`[Chorus] failed to restart the service: ${r.stderr.trim() || `exit ${r.status}`}`);
+      return 1;
+    }
     const r = lifecycle.stopDaemon();
     log(`[Chorus] ${r.message}`);
     // Start a fresh detached instance regardless of whether one was running.