agent-dag 1.25.0 → 1.27.0

package/src/server/cswap-auto.mjs

@@ -0,0 +1,238 @@
+// 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 { run } from "./exec.mjs";
+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" },
+};
+
+// ── 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"], { timeout: 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"], { timeout: 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() {
+  // A line is the user's loop if it runs `cswap auto` without --once. Our own
+  // ticks are --once, and so is a cron user's.
+  const isLoop = (line) => /(^|[\\/])cswap(\.exe|\.cmd|\.bat)?\s+auto(\s|$)/i.test(line.trim())
+                        && !/--once/i.test(line);
+
+  if (process.platform === "win32") {
+    // No `ps` on Windows, and `tasklist` reports the image name only — every
+    // Python tool shows up as python.exe, which cannot tell cswap from
+    // anything else. CIM is the one place the full command line is available.
+    const r = await run("powershell.exe", [
+      "-NoProfile", "-NonInteractive", "-Command",
+      "Get-CimInstance Win32_Process | Select-Object -ExpandProperty CommandLine",
+    ], { timeout: 8_000 });
+    if (!r.ok) return false;   // no PowerShell, or the query was refused
+    return r.stdout.split("\n").some(isLoop);
+  }
+
+  // `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="], { timeout: 5_000 });
+  if (!r.stdout.trim()) return false;
+  return r.stdout.split("\n").some(isLoop);
+}
+
+// ── 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

@@ -7,7 +7,7 @@
 // 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 { run, runDetached } from "./exec.mjs";
 import { mkdirSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -19,14 +19,6 @@ const INSTALL_TIMEOUT_MS = 180_000; // uv resolves + builds a Python env
 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"]);
@@ -50,9 +42,9 @@ async function installCswap() {
     ["uv",   ["tool", "install", "claude-swap"]],
     ["pipx", ["install", "claude-swap"]],
   ]) {
-    const probe = await run(cmd, ["--version"], 5_000);
+    const probe = await run(cmd, ["--version"], { timeout: 5_000 });
     if (!probe.ok) continue;
-    const r = await run(cmd, args, INSTALL_TIMEOUT_MS);
+    const r = await run(cmd, args, { timeout: 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) };
   }
@@ -104,17 +96,13 @@ function isOlder(a, b) {
  */
 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 */ }
+  runDetached(via, args);
 }
 
 /** 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;
+    if ((await run(cmd, ["--version"], { timeout: 5_000 })).ok) return cmd;
   }
   return null;
 }

package/src/server/exec.mjs

@@ -0,0 +1,79 @@
+// Running an external command the same way on Linux, macOS and Windows.
+//
+// On POSIX, `spawn("cswap", …)` finds cswap on PATH. On Windows it does not:
+// the thing on PATH is `cswap.exe` or a `cswap.cmd` shim, and Node only
+// applies PATHEXT when it goes through a shell. So the naive call fails with
+// ENOENT on Windows even though the tool is installed and on PATH — which
+// looks exactly like "not installed" and is why this is worth a module.
+//
+// The alternative, `shell: true`, would work but concatenates arguments into a
+// command line instead of passing them as a vector: an argument containing a
+// quote or an ampersand stops being an argument. Resolving the extension
+// ourselves keeps the argument vector intact.
+import { execFile, spawn } from "node:child_process";
+
+// Extensions Windows will execute, most specific first. `.com` is omitted —
+// nothing ships one, and every extra candidate costs a failed spawn.
+const WIN_EXTS = [".exe", ".cmd", ".bat", ""];
+
+// Which spelling worked, per command name. A failed spawn is cheap but not
+// free, and these run on a poll.
+const resolved = new Map();
+
+function candidates(cmd) {
+  if (process.platform !== "win32") return [cmd];
+  // An explicit extension is respected as given.
+  if (/\.[a-z]+$/i.test(cmd)) return [cmd];
+  const known = resolved.get(cmd);
+  return known ? [known] : WIN_EXTS.map(ext => cmd + ext);
+}
+
+const isMissing = (err) => err && (err.code === "ENOENT" || err.code === "EACCES");
+
+/**
+ * Run a command and collect its output. Never rejects — failures come back as
+ * `{ ok: false }`, because every caller here is a poll or a UI action where a
+ * missing tool is an expected state rather than an exception.
+ */
+export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20 } = {}) {
+  const tries = candidates(cmd);
+  return new Promise((resolve) => {
+    const attempt = (i) => {
+      execFile(tries[i], args, { timeout, shell: false, windowsHide: true, maxBuffer },
+        (err, stdout, stderr) => {
+          if (err && isMissing(err) && i + 1 < tries.length) return attempt(i + 1);
+          if (!err) resolved.set(cmd, tries[i]);
+          resolve({
+            ok: !err,
+            code: err?.code ?? 0,
+            killed: Boolean(err?.killed),
+            stdout: String(stdout ?? ""),
+            stderr: String(stderr ?? ""),
+          });
+        });
+    };
+    attempt(0);
+  });
+}
+
+/**
+ * Start a command and don't wait for it. Same resolution, no output captured.
+ * Used where the result lands somewhere else — a file the next poll reads, or
+ * a sound the user hears.
+ */
+export function runDetached(cmd, args) {
+  const tries = candidates(cmd);
+  const attempt = (i) => {
+    try {
+      const child = spawn(tries[i], args, { stdio: "ignore", shell: false, windowsHide: true });
+      child.on("error", (err) => {
+        if (isMissing(err) && i + 1 < tries.length) attempt(i + 1);
+      });
+      child.on("spawn", () => resolved.set(cmd, tries[i]));
+      child.unref?.();
+    } catch {
+      if (i + 1 < tries.length) attempt(i + 1);
+    }
+  };
+  attempt(0);
+}

package/src/server/index.mjs

@@ -1074,6 +1074,66 @@ async function handleClaudeAccountSwitch(req, res) {
   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, restoreParkedSoundHooks } = 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" });
+  if (parsed.action === "restore") return send(res, 200, await restoreParkedSoundHooks());
+  send(res, 200, await setSoundHook(parsed.enabled === true));
+}
+
 function handleHealth(_req, res) {
   send(res, 200, {
     ok: true,
@@ -1156,6 +1216,10 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     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);
@@ -1183,6 +1247,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/quota.mjs

@@ -264,7 +264,12 @@ async function _execOnce(shellCmd) {
   try {
     const { stdout, stderr } = await execAsync(shellCmd, {
       timeout: 15_000,
-      env: { ...process.env, NO_COLOR: "1", TERM: "dumb" },
+      // Marks this Claude Code run as the deck's own. `claude --print /usage`
+      // is a full invocation, so it fires the hooks we installed, and every
+      // quota poll was drawing itself onto the canvas as a fresh session with
+      // no prompt and no tools. Hooks inherit the environment, so hook.js
+      // sees this and stays quiet.
+      env: { ...process.env, NO_COLOR: "1", TERM: "dumb", AGENTS_DECK_INTERNAL: "1" },
       maxBuffer: 1024 * 1024,
     });
     const combined = stdout + "\n" + stderr;

package/src/server/sound-hook.mjs

@@ -0,0 +1,175 @@
+// 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";
+// Where a user's own sound hooks are kept while the toggle is off, so turning
+// the feature off actually produces silence and nothing is destroyed.
+const PARKED_PATH = join(homedir(), ".agents-deck", "parked-sound-hooks.json");
+
+// 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;
+}
+
+async function readParked() {
+  try {
+    const parsed = JSON.parse(await readFile(PARKED_PATH, "utf8"));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch { return []; }
+}
+
+async function writeParked(entries) {
+  try {
+    if (!existsSync(dirname(PARKED_PATH))) await mkdir(dirname(PARKED_PATH), { recursive: true });
+    await writeFile(PARKED_PATH, JSON.stringify(entries, null, 2) + "\n", "utf8");
+  } catch { /* best-effort */ }
+}
+
+/**
+ * True when this Stop entry plays a sound, on any platform.
+ *
+ * Deliberately not limited to the current one. settings.json is commonly
+ * synced between machines — this user's own file carries Windows paths
+ * alongside macOS ones — so parking only the hook that fires here leaves the
+ * other in place, and the switch looks broken again on the other machine.
+ */
+function isSoundHook(entry) {
+  if (isOurs(entry)) return false;
+  return (entry.hooks ?? []).some(h =>
+    SOUND_HINTS.some(re => re.test(typeof h?.command === "string" ? h.command : "")));
+}
+
+export async function soundHookStatus() {
+  const settings = await readSettings();
+  const group = settings?.hooks?.[EVENT];
+  const parked = await readParked();
+  return {
+    ok: true,
+    enabled: Array.isArray(group) && group.some(isOurs),
+    platform: process.platform,
+    foreign: foreignSoundHooks(settings),
+    parked: parked.length,
+  };
+}
+
+/**
+ * Put back the hooks the toggle set aside.
+ *
+ * Nothing is deleted, only moved, so a user who preferred their own command
+ * can have it back exactly as it was.
+ */
+export async function restoreParkedSoundHooks() {
+  const parked = await readParked();
+  if (parked.length === 0) return { ok: true, restored: 0 };
+  const settings = await readSettings();
+  settings.hooks ??= {};
+  const group = Array.isArray(settings.hooks[EVENT]) ? settings.hooks[EVENT] : [];
+  settings.hooks[EVENT] = [...parked, ...group];
+  await writeSettings(settings);
+  await writeParked([]);
+  return { ok: true, restored: parked.length };
+}
+
+export async function setSoundHook(enabled) {
+  const settings = await readSettings();
+  settings.hooks ??= {};
+  const group = Array.isArray(settings.hooks[EVENT]) ? settings.hooks[EVENT] : [];
+
+  // Set aside any of the user's own hooks that play a sound on this machine.
+  // Without this the toggle is a lie in both directions: off still plays their
+  // afplay/PowerShell hook, and on plays twice. They are moved, not deleted —
+  // restoreParkedSoundHooks puts them back untouched.
+  const parking = group.filter(isSoundHook);
+  if (parking.length > 0) {
+    await writeParked([...(await readParked()), ...parking]);
+  }
+  const others = group.filter(g => !isOurs(g) && !isSoundHook(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 };
+}