@chorus-aidlc/chorus 0.16.4 → 0.17.1

package/cli/credentials.mjs

@@ -18,15 +18,19 @@
 
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
 /** Absolute path to the login file written by `chorus login`. */
 export function loginFilePath() {
+  const override = process.env.CHORUS_DAEMON_CONFIG_PATH?.trim();
+  if (override) return resolve(override);
   return join(homedir(), ".chorus", "daemon.json");
 }
 
 /** Absolute path to the Claude Code user settings file (plugin fallback source). */
 export function claudeSettingsPath() {
+  const override = process.env.CHORUS_CLAUDE_SETTINGS_PATH?.trim();
+  if (override) return resolve(override);
   return join(homedir(), ".claude", "settings.json");
 }
 
@@ -159,13 +163,26 @@ export function resolveCredentials(flags = {}, deps = {}) {
     if (url && apiKey) return { url, apiKey, source: "env" };
   }
 
-  // 3. Login file (~/.chorus/daemon.json)
+  // 3. Login file (~/.chorus/daemon.json): the flat top-level url/apiKey, else the
+  //    first agents[] entry. The flat top-level agent config is DEPRECATED — `chorus
+  //    init` now writes credentials only into agents[] — so fall back to agents[0]
+  //    so this single-credential resolver (install/daemon-setup gate, legacy flat
+  //    daemon) still resolves from an agents[]-only daemon.json.
   tried.push(`login file (${loginPath}, run \`chorus login\`)`);
   {
     const file = readJson(loginPath);
     if (file) {
-      const url = nonEmpty(file.url);
-      const apiKey = nonEmpty(file.apiKey);
+      let url = nonEmpty(file.url);
+      let apiKey = nonEmpty(file.apiKey);
+      if (!(url && apiKey) && Array.isArray(file.agents)) {
+        const a0 = file.agents.find(
+          (a) => a && typeof a === "object" && nonEmpty(a.url) && nonEmpty(a.apiKey),
+        );
+        if (a0) {
+          url = nonEmpty(a0.url);
+          apiKey = nonEmpty(a0.apiKey);
+        }
+      }
       if (url && apiKey) return { url, apiKey, source: "login-file" };
     }
   }
@@ -194,3 +211,172 @@ export function resolveCredentials(flags = {}, deps = {}) {
       "  • login:   chorus login   (persists to ~/.chorus/daemon.json)\n"
   );
 }
+
+/**
+ * @typedef {Object} McpCredentials
+ * @property {string} url
+ * @property {string} apiKey
+ * @property {string} label  Diagnostic label for the acting identity ("flag" /
+ *   "env" / a `~/.chorus/daemon.json` agent name/label / the flat-resolution source).
+ */
+
+/**
+ * Resolve the url + `cho_` API key AND the acting agent identity for the
+ * `chorus mcp` command group. Unlike `resolveCredentials`, this understands the
+ * multi-agent `agents[]` model and refuses to guess which agent to act as.
+ *
+ * PROFILE identity (AWS-CLI style): a caller can name WHICH agent to act as by
+ * `--agent <name|uuid>` (explicit flag) or the `CHORUS_AGENT_PROFILE` env var,
+ * and this resolves that agent's key from `~/.chorus/daemon.json` — the secret
+ * never has to be threaded through the caller's environment. A profile matches
+ * an `agents[]` entry by its `agentUuid`, `agentName`, or the back-compat
+ * `label`/`name` aliases (exact). Ambiguous (matches >1 entry) → hard error.
+ *
+ * Precedence (owner decision: PREFER profile, fall back to url+key mode when no
+ * profile resolves — the key stays written in daemon.json, url+key is the
+ * fallback so the CLI-absent curl path still works):
+ *   1. Explicit `--agent <name|uuid>` flag → deliberate profile selection from
+ *      `agents[]`, PREFERRED over an explicit url+key pair (no match → hard error
+ *      listing agents). With NO `agents[]` it rides along an explicit `--url/--api-key`
+ *      pair (else the env pair) as the label, else it is a usage error.
+ *   2. Explicit `--url` + `--api-key` flags (no `--agent`) → used directly
+ *      (identity is explicit); a `CHORUS_AGENT_PROFILE` name rides along as the label.
+ *   3. `CHORUS_AGENT_PROFILE` env → ambient profile selection from `agents[]`.
+ *      A match wins over the url+key env pair; NO match falls through (the
+ *      profile "doesn't exist" → url-mode fallback), an ambiguous match throws.
+ *   4. `CHORUS_URL` + `CHORUS_API_KEY` env pair → used directly (url-mode
+ *      fallback / legacy plugin-hook path); a profile name rides as the label.
+ *   5. Exactly one agent in `agents[]` + nothing specified → that agent.
+ *   6. More than one agent + nothing specified → hard error (never pick
+ *      silently), listing the available agents.
+ *   7. No `agents[]` → flat resolution via `resolveCredentials`.
+ *
+ * Each selected agent's `url`/`apiKey` merges over the top-level per-field
+ * defaults (`resolveCredentialDefaults`), so an agent that omits a field
+ * inherits it.
+ *
+ * This never imports `cli/daemon-config.mjs` (which imports THIS module) — it
+ * reads `agents[]` directly to stay cycle-free; only url/apiKey/label matter for
+ * MCP, so per-agent agentType/permissionMode validation is intentionally skipped.
+ *
+ * @param {{ url?: string, apiKey?: string, agent?: string }} flags
+ * @param {ResolveDeps} [deps]
+ * @returns {McpCredentials}
+ * @throws {Error} on ambiguity, a missing `--agent` label, or nothing resolvable.
+ */
+export function resolveMcpCredentials(flags = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const flagAgent = nonEmpty(flags.agent);
+  const envProfile = nonEmpty(env.CHORUS_AGENT_PROFILE);
+  // The profile name a caller asked for, whatever its source — used as the
+  // diagnostic label when creds ultimately come from explicit flags / the env pair.
+  const wanted = flagAgent ?? envProfile;
+
+  const envPair = () => {
+    const url = nonEmpty(env.CHORUS_URL);
+    const apiKey = nonEmpty(env.CHORUS_API_KEY);
+    return url && apiKey ? { url, apiKey } : null;
+  };
+  const flagPair = () => {
+    const url = nonEmpty(flags.url);
+    const apiKey = nonEmpty(flags.apiKey);
+    return url && apiKey ? { url, apiKey } : null;
+  };
+
+  // Read agents[] once and pre-resolve every entry (label, its match keys, and
+  // its effective url/apiKey merged over the top-level per-field defaults).
+  const file = readJson(loginPath);
+  const agentEntries =
+    file && Array.isArray(file.agents)
+      ? file.agents.filter((a) => a && typeof a === "object")
+      : [];
+  const hasAgents = agentEntries.length > 0;
+  const defaults = hasAgents ? resolveCredentialDefaults(flags, deps) : { url: undefined, apiKey: undefined };
+  const labelOf = (entry, i) =>
+    nonEmpty(entry.agentName) ?? nonEmpty(entry.label) ?? nonEmpty(entry.name) ?? `agents[${i}]`;
+  const resolved = agentEntries.map((entry, i) => ({
+    label: labelOf(entry, i),
+    // A profile may name an entry by its uuid, its display name, or the
+    // back-compat label/name aliases.
+    keys: [entry.agentUuid, entry.agentName, entry.label, entry.name]
+      .map((k) => nonEmpty(k))
+      .filter((k) => k !== undefined),
+    url: nonEmpty(entry.url) ?? defaults.url,
+    apiKey: nonEmpty(entry.apiKey) ?? defaults.apiKey,
+  }));
+  const labels = resolved.map((a) => a.label).join(", ");
+  const pick = (a) => {
+    if (!a.url || !a.apiKey) {
+      throw new Error(
+        `Agent "${a.label}" in ${loginPath} is missing a url or apiKey (and no top-level default supplies it).`,
+      );
+    }
+    return { url: a.url, apiKey: a.apiKey, label: a.label };
+  };
+  const matchesFor = (name) => resolved.filter((a) => a.keys.includes(name));
+  const selectOrThrow = (name, source) => {
+    const matches = matchesFor(name);
+    if (matches.length === 1) return pick(matches[0]);
+    if (matches.length > 1) {
+      throw new Error(
+        `${source} "${name}" is ambiguous in ${loginPath} — it matches ${matches.length} agents ` +
+          `(${matches.map((m) => m.label).join(", ")}). Use the agent UUID to disambiguate.`,
+      );
+    }
+    return null; // no match
+  };
+
+  // 1. Explicit --agent flag: a deliberate profile selection — PREFERRED over an
+  //    explicit url+key flag pair (owner: "prefer profile"). With NO agents[] to
+  //    match, it rides an explicit flag pair (else the env pair), using the name
+  //    as the diagnostic label; with neither it is a usage error.
+  if (flagAgent) {
+    if (hasAgents) {
+      const hit = selectOrThrow(flagAgent, "--agent");
+      if (hit) return hit;
+      throw new Error(`--agent "${flagAgent}" not found in ${loginPath} agents[]. Available: ${labels}.`);
+    }
+    const pair = flagPair() ?? envPair();
+    if (pair) return { url: pair.url, apiKey: pair.apiKey, label: flagAgent };
+    throw new Error(
+      `--agent "${flagAgent}" was given but ${loginPath} declares no agents[]. ` +
+        `Remove --agent, or configure an agents[] list.`,
+    );
+  }
+
+  // 2. Explicit url+key flag pair (no --agent) — identity is explicit.
+  {
+    const pair = flagPair();
+    if (pair) return { url: pair.url, apiKey: pair.apiKey, label: wanted ?? "flag" };
+  }
+
+  // 3. CHORUS_AGENT_PROFILE env: ambient profile selection. A match wins over the
+  //    url+key env pair; a no-match falls through to url-mode (profile "doesn't
+  //    exist"); an ambiguous match throws.
+  if (envProfile && hasAgents) {
+    const hit = selectOrThrow(envProfile, "CHORUS_AGENT_PROFILE");
+    if (hit) return hit;
+    // no match → fall through to the url-mode fallback below
+  }
+
+  // 4. Env pair (url-mode fallback). Carry the profile name as the label if set.
+  {
+    const pair = envPair();
+    if (pair) return { url: pair.url, apiKey: pair.apiKey, label: wanted ?? "env" };
+  }
+
+  // 5/6. agents[] with nothing specified: auto-single, else hard error.
+  if (hasAgents) {
+    if (resolved.length === 1) return pick(resolved[0]);
+    throw new Error(
+      `Multiple agents are configured in ${loginPath} (${labels}). ` +
+        `Specify which one to act as with --agent <name|uuid> or CHORUS_AGENT_PROFILE.`,
+    );
+  }
+
+  // 7. No agents[] → flat resolution (throws the detailed "could not resolve" error).
+  const flat = resolveCredentials(flags, deps);
+  return { url: flat.url, apiKey: flat.apiKey, label: flat.source };
+}

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."],
   };
 }