@chorus-aidlc/chorus 0.16.4 → 0.17.0

package/cli/daemon-agent.mjs

@@ -17,8 +17,18 @@ import { readFileSync } from "node:fs";
 import { loginFilePath } from "./credentials.mjs";
 
 /** The agent backends the daemon recognizes. Existing spawners cover claude-code,
- * codex, and kiro; dsh registration is the base contract for its bridge. */
-export const KNOWN_AGENTS = ["claude-code", "codex", "kiro", "dsh"];
+ * codex, and kiro; dsh registration is the base contract for its bridge.
+ *
+ * `offline` is a NON-wakeable classification, not a real backend: an agent whose
+ * key is parked in daemon.json purely so `chorus mcp` can proxy through it, while
+ * the daemon builds NO spawner and dispatches NO wake for it. It is accepted here
+ * (and by-name in agent-backend-prompt via this list) so an agents[] entry may set
+ * `agentType: "offline"` and pass resolveAgentConfigs' KNOWN_AGENTS validation. The
+ * fail-closed no-wake handling lives in spawner-select.mjs (selectSpawner returns
+ * an OfflineSpawner that refuses to spawn) — an offline value MUST NOT fall through
+ * to the claude-code default and wake it. `chorus agents add` maps every non-wakeable
+ * selected agent (opencode/openclaw/pi/dsh) to this classification. */
+export const KNOWN_AGENTS = ["claude-code", "codex", "kiro", "dsh", "offline"];
 
 /** The default agent backend when neither --agent nor CHORUS_AGENT is set. */
 export const DEFAULT_AGENT = "claude-code";
@@ -35,6 +45,11 @@ export function backendCli(agentType) {
   if (agentType === "codex") return { name: "codex", envVar: "CHORUS_CODEX_PATH" };
   if (agentType === "kiro") return { name: "kiro-cli", envVar: "CHORUS_KIRO_PATH" };
   if (agentType === "dsh") return { name: "dsh-jsonrpc-agent", envVar: "CHORUS_DSH_PATH" };
+  // `offline` has no CLI to resolve — it is never woken (see backendClientType).
+  // The daemon does not probe a binary for it; this explicit descriptor keeps the
+  // return sensible if some banner path ever reads it (CHORUS_AGENT selects the
+  // backend), instead of mislabeling it as `claude`.
+  if (agentType === "offline") return { name: "offline", envVar: "CHORUS_AGENT" };
   return { name: "claude", envVar: "CHORUS_CLAUDE_PATH" };
 }
 
@@ -50,6 +65,15 @@ export function backendClientType(agentType) {
   if (agentType === "codex") return "codex";
   if (agentType === "kiro") return "kiro";
   if (agentType === "dsh") return "dsh";
+  // `offline` is a non-wakeable classification — the daemon SHALL NOT register it
+  // as a wakeable connection (daemon-multi-agent spec). It must therefore NOT
+  // fall through to the `claude_code` default (which would make an offline agent
+  // present as a wakeable claude_code connection). Return the distinct `offline`
+  // string: the runtime fan-out skips registering it at all, and this value is
+  // intentionally OUTSIDE the server's DAEMON_CLIENT_TYPES allowlist, so any
+  // future path that DID try to register it fails closed (server rejects) rather
+  // than silently registering it as claude_code.
+  if (agentType === "offline") return "offline";
   return "claude_code";
 }
 

package/cli/daemon-config.mjs

@@ -306,13 +306,19 @@ function positiveInt(value) {
  * @typedef {Object} AgentConfig  One fully-resolved agent runtime config.
  * @property {string} url                       Chorus server URL for this agent.
  * @property {string} apiKey                    This agent's `cho_` API key.
- * @property {string} agentType                 Backend: claude-code | codex | kiro | dsh.
+ * @property {string} agentType                 Backend: claude-code | codex | kiro | dsh | offline.
+ * @property {boolean} [daemonWake]             Wake opt-in for a wakeable backend; only
+ *                                              `false` disables (absent/true ⇒ woken).
  * @property {Array<string|undefined>} cwds     Served paths (`undefined` ⇒ process cwd).
  * @property {"yolo"|"chorus"} permissionMode   Woken-agent permission posture.
  * @property {number} maxConcurrency            This agent's wake-queue cap.
  * @property {number} sigintTimeoutMs           Interrupt escalation window (ms).
  * @property {string[]} browseRoots             Directory-discovery allowlist.
  * @property {string} label                     Diagnostic label ("agent" or "agents[i]").
+ * @property {string} [agentUuid]               This agent's Chorus UUID — exported to a
+ *                                              woken session as CHORUS_AGENT_PROFILE so its
+ *                                              hooks/skills resolve the key from daemon.json.
+ * @property {string} [agentName]               This agent's Chorus display name (profile alias).
  */
 
 /**
@@ -365,6 +371,8 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
         sigintTimeoutMs: resolveSigintTimeoutMs(flags, deps),
         browseRoots: resolveBrowseRoots(flags, deps),
         label: "agent",
+        agentUuid: nonEmptyStr(file?.agentUuid),
+        agentName: nonEmptyStr(file?.agentName),
       },
     ];
   }
@@ -433,6 +441,23 @@ export function resolveAgentConfigs(flags = {}, deps = {}) {
     const browseRoots =
       entry.browseRoots !== undefined ? cleanCwdList(entry.browseRoots, home) : defaultBrowseRoots;
 
-    return { url, apiKey, agentType, cwds, permissionMode, maxConcurrency, sigintTimeoutMs, browseRoots, label };
+    // daemonWake: per-agent opt-in for daemon waking (pass-through boolean). Only
+    // `=== false` disables waking; absent (undefined) or true ⇒ woken, so agent
+    // entries written before this field existed keep being woken. Orthogonal to
+    // agentType (offline is never woken regardless).
+    return {
+      url,
+      apiKey,
+      agentType,
+      cwds,
+      permissionMode,
+      maxConcurrency,
+      sigintTimeoutMs,
+      browseRoots,
+      daemonWake: entry.daemonWake,
+      label,
+      agentUuid: nonEmptyStr(entry.agentUuid),
+      agentName: nonEmptyStr(entry.agentName),
+    };
   });
 }

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";
@@ -75,6 +76,7 @@ import {
   uninstallService,
   systemctlUser,
   journalctlUser,
+  launchctl,
   resolveServicePaths,
   SERVICE_NAME,
 } from "./daemon-service.mjs";
@@ -633,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.
@@ -655,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 ` +
@@ -667,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");
   }
 
@@ -783,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
@@ -860,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}, ` +
@@ -998,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,
@@ -1118,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
@@ -1239,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);
@@ -1261,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;
@@ -1274,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}).`);
@@ -1297,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}`}`);
@@ -1306,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}`);
@@ -1315,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).`);
@@ -1325,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 });
@@ -1336,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).`);
@@ -1345,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.

package/cli/dsh-spawner.mjs

@@ -187,6 +187,13 @@ export class DshSpawner {
     };
     if (this.creds?.url) childEnv.CHORUS_URL = this.creds.url;
     if (this.creds?.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
+    // Identity profile — the dsh doc-mirror wrapper passes this to `chorus mcp
+    // --agent` (resolving the key from ~/.chorus/daemon.json). dsh scrubs
+    // credential-shaped env from tool subprocesses; the profile is not a secret,
+    // and the wrapper also reads it from $DSH_HOME/.env, so url/apiKey remain the
+    // reliable fallback when it doesn't survive.
+    if (this.creds?.agentUuid || this.creds?.agentName)
+      childEnv.CHORUS_AGENT_PROFILE = this.creds.agentUuid || this.creds.agentName;
 
     const { command, argv } = resolveDshSpawnCommand(dshPath, this.platform, childEnv);
     let child;