agent-dag 1.24.0 → 1.26.0

package/src/server/cswap-auto.mjs

@@ -0,0 +1,237 @@
+// Auto-switch controls: read and write claude-swap's autoswitch settings, run
+// a tick on a schedule, and preview what a tick would do without doing it.
+//
+// The engine is claude-swap's own — `cswap auto --once` evaluates one tick and
+// exits, honouring the cooldown, quarantine and poll-budget state it keeps in
+// its own files. Running that on an interval gets the same behaviour as the
+// long-lived `cswap auto` loop while leaving all the decisions with the tool
+// that owns them: nothing here decides when to switch, only when to ask.
+//
+// A tick can move the user's live Claude account, so it is off unless turned
+// on, the setting survives restarts, and the UI can always ask what a tick
+// WOULD do (--dry-run) before committing to letting it happen.
+import { execFile } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const STATE_DIR  = join(homedir(), ".agents-deck");
+const STATE_PATH = join(STATE_DIR, "cswap-auto.json");
+
+const TICK_TIMEOUT_MS = 120_000;   // a tick can refresh a token and switch
+const MIN_INTERVAL_S  = 15;        // claude-swap's own floor
+
+// Only these may be written, and only with a value of the right shape. The
+// value reaches an exec argument, and `cswap config set` will happily store
+// whatever it is handed.
+const SETTINGS = {
+  "autoswitch.threshold":       { type: "number", min: 50, max: 99.9 },
+  "autoswitch.intervalSeconds": { type: "number", min: 15, max: 3600 },
+  "autoswitch.cooldownSeconds": { type: "number", min: 0,  max: 86400 },
+  "autoswitch.hysteresisPct":   { type: "number", min: 0,  max: 50 },
+  "autoswitch.strategy":        { type: "enum",   values: ["best", "consume-first"] },
+  "autoswitch.model":           { type: "model" },
+};
+
+function run(cmd, args, timeout = 20_000) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout, shell: false, windowsHide: true, maxBuffer: 4 << 20 },
+      (err, stdout, stderr) => resolve({
+        ok: !err,
+        code: err?.code ?? 0,
+        stdout: String(stdout ?? ""),
+        stderr: String(stderr ?? ""),
+      }));
+  });
+}
+
+// ── settings ───────────────────────────────────────────────────────────────
+
+/** Parse `cswap config` — "key   value   (default)" per line. */
+export async function readCswapConfig() {
+  const r = await run("cswap", ["config"]);
+  if (!r.ok) return null;
+  const out = {};
+  for (const line of r.stdout.split("\n")) {
+    const m = line.match(/^(\S+)\s+(.*?)\s*(\(default\))?\s*$/);
+    if (!m || !m[1].includes(".")) continue;
+    const raw = m[2].trim();
+    out[m[1]] = {
+      value:     raw === "(none)" ? null : raw,
+      isDefault: Boolean(m[3]),
+    };
+  }
+  return out;
+}
+
+/** Validate against SETTINGS, then hand to `cswap config set`. */
+export async function setCswapConfig(key, value) {
+  const spec = SETTINGS[key];
+  if (!spec) return { ok: false, reason: "unknown_setting" };
+
+  let str;
+  if (spec.type === "number") {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < spec.min || n > spec.max) return { ok: false, reason: "out_of_range" };
+    str = String(n);
+  } else if (spec.type === "enum") {
+    if (!spec.values.includes(value)) return { ok: false, reason: "bad_value" };
+    str = value;
+  } else {
+    // Model names: a comma-separated list of plain words, or "all".
+    str = String(value ?? "").trim();
+    if (str && !/^[A-Za-z0-9 ,._-]{1,120}$/.test(str)) return { ok: false, reason: "bad_value" };
+  }
+
+  const r = await run("cswap", ["config", "set", key, str]);
+  return r.ok ? { ok: true } : { ok: false, reason: "set_failed", detail: (r.stderr || r.stdout).trim().slice(0, 300) };
+}
+
+// ── ticks ──────────────────────────────────────────────────────────────────
+
+/** Last meaningful event from a `cswap auto --once --json` run. */
+function summarise(stdout) {
+  const events = stdout.split("\n")
+    .map(l => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(e => e && typeof e === "object");
+
+  const poll   = events.find(e => e.event === "poll") ?? null;
+  const action = [...events].reverse().find(e => e.event !== "poll" && e.event !== "sleep") ?? null;
+
+  return {
+    event:     action?.event ?? "no-switch",
+    reason:    action?.reason ?? null,
+    detail:    action?.detail ?? null,
+    from:      action?.from ?? null,
+    to:        action?.to ?? null,
+    active:    poll?.active ?? null,
+    threshold: poll?.threshold ?? null,
+    headroom:  poll?.headroomPct ?? null,
+    windows:   poll?.windowsPct ?? null,
+  };
+}
+
+/**
+ * Evaluate a tick without acting. Safe to call from a UI button: --dry-run
+ * never switches and never writes claude-swap's state.
+ */
+export async function previewAutoSwitch() {
+  const r = await run("cswap", ["auto", "--once", "--dry-run", "--json"], TICK_TIMEOUT_MS);
+  if (!r.ok && !r.stdout) {
+    return { ok: false, reason: r.code === "ENOENT" ? "no_cswap" : "tick_failed",
+             detail: (r.stderr || "").trim().slice(0, 300) };
+  }
+  return { ok: true, dryRun: true, ...summarise(r.stdout) };
+}
+
+/** Evaluate a tick for real. May switch the active account. */
+async function runAutoTick() {
+  const r = await run("cswap", ["auto", "--once", "--json"], TICK_TIMEOUT_MS);
+  if (!r.ok && !r.stdout) {
+    return { ok: false, reason: "tick_failed", detail: (r.stderr || "").trim().slice(0, 300) };
+  }
+  return { ok: true, ...summarise(r.stdout) };
+}
+
+// ── external engine detection ──────────────────────────────────────────────
+
+/**
+ * True when the user is already running `cswap auto` themselves.
+ *
+ * Two engines would not corrupt anything — claude-swap serializes decisions
+ * under its state lock — but they would double the tick rate against a request
+ * budget that is already the scarce resource here, and the user would have two
+ * things switching their account with no single place showing why. So the deck
+ * reports it and stays out of the way.
+ */
+export async function externalAutoRunning() {
+  if (process.platform === "win32") return false;   // no cheap equivalent; assume not
+  // `ps`, not `pgrep -a`: BSD pgrep ignores -a and prints bare PIDs, so a
+  // command-line match against its output silently never fires.
+  const r = await run("ps", ["-Ao", "args="], 5_000);
+  if (!r.stdout.trim()) return false;
+  return r.stdout.split("\n").some(line =>
+    /(^|\/)cswap\s+auto(\s|$)/.test(line.trim()) &&
+    !/--once/.test(line)   // our own ticks are --once, and so are cron users'
+  );
+}
+
+// ── deck-managed loop ──────────────────────────────────────────────────────
+
+let _timer   = null;
+let _lastTick = null;
+let _enabled  = false;
+
+async function loadState() {
+  try { return JSON.parse(await readFile(STATE_PATH, "utf8")); } catch { return {}; }
+}
+async function saveState(state) {
+  try {
+    await mkdir(STATE_DIR, { recursive: true });
+    await writeFile(STATE_PATH, JSON.stringify(state, null, 2));
+  } catch { /* best-effort */ }
+}
+
+async function tickInterval() {
+  const cfg = await readCswapConfig();
+  const raw = Number(cfg?.["autoswitch.intervalSeconds"]?.value);
+  return Math.max(MIN_INTERVAL_S, Number.isFinite(raw) ? raw : 60) * 1000;
+}
+
+async function tick() {
+  // Re-check each time: the user can start their own loop at any point, and
+  // the deck should fall silent rather than compete with it.
+  if (await externalAutoRunning()) {
+    _lastTick = { at: Date.now(), event: "skipped", reason: "external-engine" };
+    return;
+  }
+  const result = await runAutoTick();
+  _lastTick = { at: Date.now(), ...result };
+}
+
+async function startLoop() {
+  if (_timer) return;
+  const ms = await tickInterval();
+  _timer = setInterval(() => { tick().catch(() => {}); }, ms);
+  _timer.unref?.();
+  tick().catch(() => {});   // don't make the user wait a full interval for the first one
+}
+
+function stopLoop() {
+  if (_timer) { clearInterval(_timer); _timer = null; }
+}
+
+/** Turn the deck-managed loop on or off, persisting the choice. */
+export async function setAutoEnabled(enabled) {
+  _enabled = Boolean(enabled);
+  await saveState({ ...(await loadState()), enabled: _enabled });
+  if (_enabled) await startLoop(); else stopLoop();
+  return { ok: true, enabled: _enabled };
+}
+
+/** Restore the persisted setting at server boot. */
+export async function initCswapAuto() {
+  const state = await loadState();
+  if (state.enabled) { _enabled = true; await startLoop(); }
+}
+
+export async function autoStatus() {
+  const [config, external] = await Promise.all([readCswapConfig(), externalAutoRunning()]);
+  return {
+    ok:        config != null,
+    enabled:   _enabled,
+    external,                       // user is running their own `cswap auto`
+    lastTick:  _lastTick,
+    settings:  config ?? {},
+  };
+}
+
+// ── per-account rotation flag ──────────────────────────────────────────────
+
+/** Hold an account out of auto-rotation, or return it. */
+export async function setAccountEnabled(accountNum, enabled) {
+  const num = Number(accountNum);
+  if (!Number.isInteger(num) || num < 1 || num > 999) return { ok: false, reason: "bad_account" };
+  const r = await run("cswap", [enabled ? "enable" : "disable", String(num)]);
+  return r.ok ? { ok: true } : { ok: false, reason: "command_failed", detail: (r.stderr || r.stdout).trim().slice(0, 300) };
+}

package/src/server/cswap-install.mjs

@@ -0,0 +1,160 @@
+// Ensures `cswap` (claude-swap) is available, because the accounts panel is
+// built entirely on the store it maintains.
+//
+// Unlike the ccusage install, this one lands in the user's GLOBAL tool path
+// rather than a private prefix under ~/.agents-deck, and claude-swap handles
+// Claude credentials. That makes it something the user should see happen: the
+// caller prints what this returns, and AGENTS_DECK_NO_INSTALL=1 turns it off
+// entirely. It is always best-effort — the deck's core function does not
+// depend on it, so a failure is reported and then ignored.
+import { execFile, spawn } from "node:child_process";
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const INSTALL_TIMEOUT_MS = 180_000; // uv resolves + builds a Python env
+
+// Same throttle the ccusage installer uses: check once a day, tracked by a
+// marker file's mtime so the interval survives restarts.
+const UPDATE_CHECK_MS = 24 * 3600_000;
+const MARKER = join(homedir(), ".agents-deck", ".cswap-update-check");
+
+function run(cmd, args, timeout = 10_000) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout, shell: false, windowsHide: true }, (err, stdout, stderr) => {
+      resolve({ ok: !err, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
+    });
+  });
+}
+
+/** Installed version string, or null when cswap isn't on PATH. */
+export async function cswapVersion() {
+  const r = await run("cswap", ["--version"]);
+  if (!r.ok) return null;
+  // "claude-swap 0.25.0" → "0.25.0"
+  const m = (r.stdout || r.stderr).trim().match(/(\d+\.\d+\.\d+\S*)/);
+  return m ? m[1] : "installed";
+}
+
+/**
+ * Install claude-swap with whichever Python tool installer is present.
+ *
+ * `uv` first because it is what claude-swap documents and it is dramatically
+ * faster; `pipx` as the established alternative. Deliberately NOT falling back
+ * to bare `pip install --user`: that drops the package into the user's default
+ * Python environment where it can collide with their own dependencies, which
+ * is not a thing to do to someone without asking.
+ */
+async function installCswap() {
+  for (const [cmd, args] of [
+    ["uv",   ["tool", "install", "claude-swap"]],
+    ["pipx", ["install", "claude-swap"]],
+  ]) {
+    const probe = await run(cmd, ["--version"], 5_000);
+    if (!probe.ok) continue;
+    const r = await run(cmd, args, INSTALL_TIMEOUT_MS);
+    if (r.ok) return { ok: true, via: cmd };
+    return { ok: false, reason: "install_failed", via: cmd, detail: (r.stderr || r.stdout).trim().slice(0, 300) };
+  }
+  return { ok: false, reason: "no_installer" };
+}
+
+function updateCheckDue() {
+  try { return Date.now() - statSync(MARKER).mtimeMs > UPDATE_CHECK_MS; }
+  catch { return true; }   // no marker yet
+}
+function touchMarker() {
+  try {
+    mkdirSync(join(homedir(), ".agents-deck"), { recursive: true });
+    writeFileSync(MARKER, String(Date.now()));
+  } catch { /* ignore */ }
+}
+
+/** Newest claude-swap on PyPI, or null if the check fails. */
+async function latestOnPypi() {
+  try {
+    const res = await fetch("https://pypi.org/pypi/claude-swap/json", {
+      signal: AbortSignal.timeout(6_000),
+    });
+    if (!res.ok) return null;
+    const v = (await res.json())?.info?.version;
+    return typeof v === "string" ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Numeric-segment version compare; returns true when `a` is older than `b`. */
+function isOlder(a, b) {
+  const seg = (v) => v.split(/[.\-+]/).map(n => parseInt(n, 10)).map(n => Number.isNaN(n) ? 0 : n);
+  const x = seg(a), y = seg(b);
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] ?? 0) - (y[i] ?? 0);
+    if (d !== 0) return d < 0;
+  }
+  return false;
+}
+
+/**
+ * Upgrade claude-swap in the background when a newer release exists.
+ *
+ * Detached and unawaited: an upgrade resolves a Python environment and can
+ * take tens of seconds, which is not a thing to put in front of the server
+ * starting. The running copy keeps working; the new one is there next launch.
+ */
+function upgradeInBackground(via) {
+  const args = via === "uv" ? ["tool", "upgrade", "claude-swap"] : ["upgrade", "claude-swap"];
+  try {
+    const child = spawn(via, args, { stdio: "ignore", shell: false, windowsHide: true, detached: false });
+    child.on("error", () => {});
+    child.unref?.();
+  } catch { /* best-effort */ }
+}
+
+/** Whichever Python tool installer is available, or null. */
+async function findInstaller() {
+  for (const cmd of ["uv", "pipx"]) {
+    if ((await run(cmd, ["--version"], 5_000)).ok) return cmd;
+  }
+  return null;
+}
+
+/**
+ * Make sure cswap exists and is reasonably current, installing it if missing.
+ *
+ * Returns a small status the CLI prints verbatim:
+ *   { state: "present" | "installed" | "upgrading" | "skipped" | "unavailable", ... }
+ */
+export async function ensureCswap() {
+  if (process.env.AGENTS_DECK_NO_INSTALL === "1") {
+    const version = await cswapVersion();
+    return version ? { state: "present", version } : { state: "skipped" };
+  }
+
+  const existing = await cswapVersion();
+  if (existing) {
+    // Installed — the only question left is whether it's stale. One PyPI
+    // request a day, and the upgrade itself never blocks startup.
+    if (!updateCheckDue()) return { state: "present", version: existing };
+    touchMarker();
+    const latest = await latestOnPypi();
+    if (latest && existing !== "installed" && isOlder(existing, latest)) {
+      const via = await findInstaller();
+      if (via) {
+        upgradeInBackground(via);
+        return { state: "upgrading", version: existing, latest, via };
+      }
+    }
+    return { state: "present", version: existing };
+  }
+
+  const result = await installCswap();
+  if (!result.ok) return { state: "unavailable", ...result };
+
+  // Freshly installed tools land in ~/.local/bin, which may not be on the PATH
+  // of the shell that launched us — so confirm rather than assume.
+  const version = await cswapVersion();
+  return version
+    ? { state: "installed", via: result.via, version }
+    : { state: "unavailable", reason: "not_on_path", via: result.via };
+}

package/src/server/index.mjs

@@ -938,6 +938,20 @@ async function serveStatic(req, res, url) {
   }
 }
 
+/** Collect a request body as a string, capped so a bad client can't fill memory. */
+function readBody(req, limit = 64_000) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.setEncoding("utf8");
+    req.on("data", c => {
+      body += c;
+      if (body.length > limit) { req.destroy(); reject(new Error("body too large")); }
+    });
+    req.on("end", () => resolve(body));
+    req.on("error", reject);
+  });
+}
+
 function handleEventIngest(req, res) {
   let body = "";
   req.setEncoding("utf8");
@@ -1035,6 +1049,90 @@ async function handleCcusage(req, res) {
   send(res, 200, data);
 }
 
+async function handleClaudeAccounts(req, res) {
+  const { fetchClaudeAccounts } = await import(
+    pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href
+  );
+  const url = new URL(req.url, "http://localhost");
+  const force = url.searchParams.get("refresh") === "1";
+  send(res, 200, await fetchClaudeAccounts({ force }));
+}
+
+async function handleClaudeAccountSwitch(req, res) {
+  const { switchClaudeAccount, invalidateClaudeAccountsCache } = await import(
+    pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href
+  );
+  const body = await readBody(req).catch(() => null);
+  let parsed = null;
+  try { parsed = JSON.parse(body ?? ""); } catch { /* handled below */ }
+  if (!parsed || typeof parsed !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
+
+  const result = await switchClaudeAccount(parsed.account);
+  // The active account just moved; the next poll should see it immediately
+  // rather than serving the pre-switch roster for another few seconds.
+  invalidateClaudeAccountsCache();
+  send(res, result.ok ? 200 : 400, result);
+}
+
+function cswapAutoModule() {
+  return import(pathToFileURL(join(PKG_ROOT, "src/server/cswap-auto.mjs")).href);
+}
+
+async function handleCswapAuto(req, res) {
+  const { autoStatus } = await cswapAutoModule();
+  send(res, 200, await autoStatus());
+}
+
+/**
+ * One POST for every auto-switch control, keyed by `action`. Each one can move
+ * the user's live Claude account or change when it moves, so nothing here is
+ * reachable by GET.
+ */
+async function handleCswapAutoAction(req, res) {
+  const mod = await cswapAutoModule();
+  const body = await readBody(req).catch(() => null);
+  let parsed = null;
+  try { parsed = JSON.parse(body ?? ""); } catch { /* handled below */ }
+  if (!parsed || typeof parsed !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
+
+  let result;
+  switch (parsed.action) {
+    case "enable":
+      result = await mod.setAutoEnabled(parsed.enabled === true);
+      break;
+    case "preview":
+      result = await mod.previewAutoSwitch();
+      break;
+    case "setting":
+      result = await mod.setCswapConfig(String(parsed.key ?? ""), parsed.value);
+      break;
+    case "account":
+      result = await mod.setAccountEnabled(parsed.account, parsed.enabled === true);
+      break;
+    default:
+      return send(res, 400, { ok: false, reason: "unknown_action" });
+  }
+  send(res, result.ok ? 200 : 400, result);
+}
+
+async function handleSoundHook(req, res) {
+  const { soundHookStatus } = await import(
+    pathToFileURL(join(PKG_ROOT, "src/server/sound-hook.mjs")).href
+  );
+  send(res, 200, await soundHookStatus());
+}
+
+async function handleSoundHookSet(req, res) {
+  const { setSoundHook } = await import(
+    pathToFileURL(join(PKG_ROOT, "src/server/sound-hook.mjs")).href
+  );
+  const body = await readBody(req).catch(() => null);
+  let parsed = null;
+  try { parsed = JSON.parse(body ?? ""); } catch { /* handled below */ }
+  if (!parsed || typeof parsed !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
+  send(res, 200, await setSoundHook(parsed.enabled === true));
+}
+
 function handleHealth(_req, res) {
   send(res, 200, {
     ok: true,
@@ -1115,6 +1213,12 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "GET"  && url.pathname === "/api/codex-usage")  return guard(handleCodexUsage(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/codex-quota") return guard(handleCodexQuota(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/ccusage")     return guard(handleCcusage(req, res), res);
+    if (req.method === "GET"  && url.pathname === "/api/claude-accounts") return guard(handleClaudeAccounts(req, res), res);
+    if (req.method === "POST" && url.pathname === "/api/claude-accounts/switch") return guard(handleClaudeAccountSwitch(req, res), res);
+    if (req.method === "GET"  && url.pathname === "/api/sound-hook") return guard(handleSoundHook(req, res), res);
+    if (req.method === "POST" && url.pathname === "/api/sound-hook") return guard(handleSoundHookSet(req, res), res);
+    if (req.method === "GET"  && url.pathname === "/api/cswap-auto")  return guard(handleCswapAuto(req, res), res);
+    if (req.method === "POST" && url.pathname === "/api/cswap-auto")  return guard(handleCswapAutoAction(req, res), res);
 
     if (req.method === "GET" && url.pathname === "/api/events") {
       const since = Number(url.searchParams.get("since") ?? 0);
@@ -1142,6 +1246,9 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
       await tryListen(server, candidate, host);
       // Codex has no working hooks on Windows — tail its rollout files instead.
       if (codex) startCodexWatcher(workspace);
+      // Auto-switch resumes only if the user previously turned it on; the
+      // module reads its own persisted flag and does nothing otherwise.
+      cswapAutoModule().then(m => m.initCswapAuto()).catch(() => {});
       return server;
     } catch (err) {
       if (err && err.code === "EADDRINUSE") continue;

package/src/server/sound-hook.mjs

@@ -0,0 +1,115 @@
+// Toggle for the "play a sound when the turn finishes" Stop hook.
+//
+// Hand-written versions of this hook are almost always one OS-specific
+// command — `afplay …` on macOS, a PowerShell one-liner on Windows — ending in
+// `|| true`. Each is a silent no-op on every other machine, so a settings.json
+// synced across devices ends up with several of them stacked, none of which
+// work everywhere. This installs a single entry pointing at notify.js, which
+// picks its own player at run time.
+//
+// Only ever touches its own entry, tagged `__agent-dag-sound`. Hooks the user
+// wrote themselves are left exactly as found — including the platform-specific
+// ones this replaces, which are reported rather than deleted.
+import { readFile, writeFile, copyFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT      = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const CLAUDE_DIR    = process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+const SETTINGS_PATH = join(CLAUDE_DIR, "settings.json");
+const INSTALL_DIR   = join(CLAUDE_DIR, "agent-dag");
+const NOTIFY_PATH   = join(INSTALL_DIR, "notify.js");
+
+const MARK = "__agent-dag-sound";
+const EVENT = "Stop";
+
+// Commands that look like a hand-rolled sound hook. Used only to tell the user
+// what is already there — never to modify or remove it.
+const SOUND_HINTS = [/\bafplay\b/i, /Media\.SoundPlayer/i, /\bpaplay\b/i, /\baplay\b/i, /canberra-gtk-play/i];
+
+async function readSettings() {
+  try {
+    const parsed = JSON.parse(await readFile(SETTINGS_PATH, "utf8"));
+    return (parsed && typeof parsed === "object") ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write settings.json back atomically — this file holds every hook the user
+ * has, and a torn write costs them all of them.
+ */
+async function writeSettings(settings) {
+  const tmp = `${SETTINGS_PATH}.agent-dag-${process.pid}.tmp`;
+  await writeFile(tmp, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  const { rename, unlink } = await import("node:fs/promises");
+  try { await rename(tmp, SETTINGS_PATH); }
+  catch (err) { await unlink(tmp).catch(() => {}); throw err; }
+}
+
+const isOurs = (g) => g?.[MARK] === true;
+
+/** Hand-written sound hooks on the Stop event, and whether they run here. */
+function foreignSoundHooks(settings) {
+  const group = settings?.hooks?.[EVENT];
+  if (!Array.isArray(group)) return [];
+  const found = [];
+  for (const entry of group) {
+    if (isOurs(entry)) continue;
+    for (const h of entry.hooks ?? []) {
+      const cmd = typeof h?.command === "string" ? h.command : "";
+      if (!SOUND_HINTS.some(re => re.test(cmd))) continue;
+      // A PowerShell hook on a Mac (or afplay on Windows) still runs — it just
+      // fails, usually swallowed by a trailing `|| true`. Worth naming.
+      const platform = /Media\.SoundPlayer|powershell/i.test(cmd) ? "win32"
+                     : /\bafplay\b/i.test(cmd)                    ? "darwin"
+                     : "linux";
+      found.push({ command: cmd.slice(0, 120), platform, worksHere: platform === process.platform });
+    }
+  }
+  return found;
+}
+
+export async function soundHookStatus() {
+  const settings = await readSettings();
+  const group = settings?.hooks?.[EVENT];
+  return {
+    ok: true,
+    enabled: Array.isArray(group) && group.some(isOurs),
+    platform: process.platform,
+    foreign: foreignSoundHooks(settings),
+  };
+}
+
+export async function setSoundHook(enabled) {
+  const settings = await readSettings();
+  settings.hooks ??= {};
+  const group = Array.isArray(settings.hooks[EVENT]) ? settings.hooks[EVENT] : [];
+  const others = group.filter(g => !isOurs(g));
+
+  if (enabled) {
+    if (!existsSync(INSTALL_DIR)) await mkdir(INSTALL_DIR, { recursive: true });
+    await copyFile(join(PKG_ROOT, "hook", "notify.js"), NOTIFY_PATH);
+    others.push({
+      [MARK]: true,
+      hooks: [{
+        type: "command",
+        // Absolute node path, matching how the event hooks are installed: the
+        // shell a hook runs in does not necessarily have the user's PATH.
+        command: `"${process.execPath}" "${NOTIFY_PATH}"`,
+        timeout: 5,
+      }],
+    });
+    settings.hooks[EVENT] = others;
+  } else if (others.length) {
+    settings.hooks[EVENT] = others;
+  } else {
+    delete settings.hooks[EVENT];   // don't leave an empty array behind
+  }
+
+  await writeSettings(settings);
+  return { ok: true, enabled };
+}