roger-roger 0.1.0

package/skills/roger-roger/scripts/slackcli.mjs

@@ -0,0 +1,144 @@
+// Finding and installing the Slack CLI. Installation mirrors Slack's official install scripts
+// (same download URLs and locations) but runs from Node, so it needs no PowerShell 7 on Windows.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+const METADATA_URL = "https://docs.slack.dev/tools/metadata.json";
+const DOWNLOADS = "https://downloads.slack-edge.com/slack-cli";
+
+/** Run a command and collect its output. Never rejects; `code` is null if it couldn't start. */
+export function capture(cmd, args, { input, env, cwd, timeout = 120_000 } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      // Detached: on Windows the Slack CLI can hang indefinitely when it shares the caller's console
+      // (seen from agent shells); without a console it runs normally. Output is still piped back.
+      child = spawn(cmd, args, {
+        env: env ?? process.env,
+        cwd,
+        timeout,
+        detached: process.platform === "win32",
+        windowsHide: true,
+        stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+      });
+    } catch (e) {
+      return resolve({ code: null, stdout: "", stderr: e.message });
+    }
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (e) => resolve({ code: null, stdout, stderr: stderr || e.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+    if (input !== undefined) child.stdin.end(input);
+  });
+}
+
+/** Where the official installers put the binary, per platform. */
+function installDir() {
+  if (process.platform === "win32") return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "slack-cli");
+  return path.join(os.homedir(), ".slack");
+}
+
+function candidates() {
+  const bin = path.join(installDir(), "bin");
+  const exe = process.platform === "win32" ? ".exe" : "";
+  const known = [path.join(bin, `slackcli${exe}`), path.join(bin, `slack${exe}`)];
+  if (process.platform === "win32") known.push(path.join(os.homedir(), ".slack-cli", "bin", "slackcli.exe"), path.join(os.homedir(), ".slack-cli", "bin", "slack.exe"));
+  return [...known.filter((p) => fs.existsSync(p)), ...pathLookups()];
+}
+
+/** `slackcli` / `slack` on PATH, skipping the Windows Store alias of the Slack *desktop* app. */
+function pathLookups() {
+  const exts = process.platform === "win32" ? [".exe", ".cmd", ""] : [""];
+  const found = [];
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    if (!dir || /WindowsApps/i.test(dir)) continue;
+    for (const name of ["slackcli", "slack"]) {
+      for (const ext of exts) {
+        const p = path.join(dir, name + ext);
+        if (fs.existsSync(p) && fs.statSync(p).isFile()) found.push(p);
+      }
+    }
+  }
+  return found;
+}
+
+/** The first working Slack CLI: `{ command, version }`, or null. */
+export async function findCli() {
+  for (const command of [...new Set(candidates())]) {
+    const r = await capture(command, ["--version"], { timeout: 20_000 });
+    const m = /Using \S+ v(\d+\.\d+\.\d+)/.exec(r.stdout + r.stderr);
+    if (r.code === 0 && m) return { command, version: m[1] };
+  }
+  return null;
+}
+
+async function download(url, file) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(300_000) });
+  if (!res.ok) throw new Error(`download failed (${res.status}): ${url}`);
+  fs.writeFileSync(file, Buffer.from(await res.arrayBuffer()));
+}
+
+function archiveUrl(version) {
+  const arch = process.arch === "arm64" ? "arm64" : "amd64";
+  if (process.platform === "win32") return `${DOWNLOADS}/slack_cli_${version}_windows_64-bit.zip`;
+  if (process.platform === "darwin") return `${DOWNLOADS}/slack_cli_${version}_macOS_${arch}.tar.gz`;
+  return `${DOWNLOADS}/slack_cli_${version}_linux_${arch}.tar.gz`;
+}
+
+/**
+ * Install the latest Slack CLI for this user. On Windows the binary is named `slackcli.exe`
+ * so it never collides with the Slack desktop app's `slack` alias. Returns `{ command, version }`.
+ */
+export async function installCli() {
+  const meta = await (await fetch(METADATA_URL, { signal: AbortSignal.timeout(30_000) })).json();
+  const version = meta?.["slack-cli"]?.releases?.[0]?.version;
+  if (!version) throw new Error("could not find the latest Slack CLI version");
+
+  const dir = installDir();
+  const bin = path.join(dir, "bin");
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (process.platform === "win32") {
+    const zip = path.join(dir, "slack_cli.zip");
+    await download(archiveUrl(version), zip);
+    const unpack = await capture("powershell.exe", [
+      "-NoProfile", "-NonInteractive", "-Command",
+      "Expand-Archive -LiteralPath $env:AG_ZIP -DestinationPath $env:AG_DIR -Force; " +
+        "Move-Item -LiteralPath (Join-Path $env:AG_DIR 'bin\\slack.exe') -Destination (Join-Path $env:AG_DIR 'bin\\slackcli.exe') -Force; " +
+        "$p = [Environment]::GetEnvironmentVariable('Path', 'User'); $b = Join-Path $env:AG_DIR 'bin'; " +
+        "if (-not ((';' + $p + ';').ToLower().Contains(';' + $b.ToLower() + ';'))) { [Environment]::SetEnvironmentVariable('Path', $p.TrimEnd(';') + ';' + $b, 'User') }",
+    ], { env: { ...process.env, AG_ZIP: zip, AG_DIR: dir } });
+    fs.rmSync(zip, { force: true });
+    if (unpack.code !== 0) throw new Error(`could not unpack the Slack CLI: ${unpack.stderr.trim()}`);
+  } else {
+    const tgz = path.join(dir, "slack-cli.tar.gz");
+    await download(archiveUrl(version), tgz);
+    const unpack = await capture("tar", ["-xf", tgz, "-C", dir]);
+    fs.rmSync(tgz, { force: true });
+    if (unpack.code !== 0) throw new Error(`could not unpack the Slack CLI: ${unpack.stderr.trim()}`);
+    fs.chmodSync(path.join(bin, "slack"), 0o755);
+    if (process.platform === "darwin") {
+      // Something fetched over the network can carry a quarantine flag, and macOS then refuses to
+      // run it with a dialog nobody sees from here. Clearing it is best-effort.
+      await capture("xattr", ["-d", "com.apple.quarantine", path.join(bin, "slack")]).catch(() => {});
+    }
+    // Like the official script: link into ~/.local/bin, unless some other `slack` is already there.
+    const localBin = path.join(os.homedir(), ".local", "bin");
+    const link = path.join(localBin, "slack");
+    try {
+      fs.mkdirSync(localBin, { recursive: true });
+      if (!fs.existsSync(link)) fs.symlinkSync(path.join(bin, "slack"), link);
+    } catch {
+      // The absolute path still works for this skill; PATH is a convenience for the user.
+    }
+  }
+
+  const cli = await findCli();
+  if (!cli) throw new Error("the Slack CLI was installed but does not run");
+  return cli;
+}

package/skills/roger-roger/scripts/speaker.mjs

@@ -0,0 +1,224 @@
+// One voice at a time. Every agent runs its own `roger-roger` process, so nothing inside a
+// single process can stop two announcements overlapping — the speakers are shared state
+// between processes. A lock file under ROGER_ROGER_HOME serialises playback: a process waits
+// for its turn, and a holder that died or wedged is stepped over rather than waited on
+// forever. Failing to lock never silences an announcement; it only risks an overlap.
+
+import fs from "node:fs";
+import path from "node:path";
+import { rogerRogerHome, pidAlive } from "./lib.mjs";
+
+export const STALE_MS = 15_000; // a holder that stops refreshing has gone
+export const HEARTBEAT_MS = 5_000;
+export const POLL_MS = 120;
+export const MAX_WAIT_MS = 180_000; // past this the queue is broken rather than left silent
+export const GAP_MS = 200; // breathing room so two announcements don't run together
+
+export { pidAlive };
+
+export function speakerLockPath(env = process.env) {
+  return path.join(rogerRogerHome(env), "speaker.lock");
+}
+
+/** Is this lock still somebody's? Pure, so the rules can be tested without processes. */
+export function lockActive(lock, { now = Date.now(), alive = pidAlive } = {}) {
+  if (!lock || typeof lock.pid !== "number") return false;
+  if (!alive(lock.pid)) return false;
+  return now - (Number(lock.heartbeat) || 0) < STALE_MS;
+}
+
+function readLock(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readRaw(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True while another process holds the speaker, judged from the lock's text as read (`raw`), so
+ * the caller knows exactly which claim it judged. An unreadable lock is judged by its mtime: a
+ * lock is created empty and written a moment later, and that moment is not an abandoned lock.
+ */
+function heldByOther(file, raw) {
+  if (raw === null) return false; // gone: free
+  let lock = null;
+  try {
+    lock = JSON.parse(raw);
+  } catch {}
+  if (lock) return lock.pid !== process.pid && lockActive(lock);
+  try {
+    return Date.now() - fs.statSync(file).mtimeMs < STALE_MS;
+  } catch {
+    return false; // gone between the read and the stat: free
+  }
+}
+
+/** Who holds the speaker right now, or null. For `status` and for tests. */
+export function currentSpeaker(file = speakerLockPath()) {
+  const lock = readLock(file);
+  return lock && lockActive(lock) ? lock : null;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+let holding = false;
+let timer = null;
+let cleanupFile = null;
+
+function write(file) {
+  fs.writeFileSync(file, JSON.stringify({ pid: process.pid, heartbeat: Date.now() }));
+}
+
+function startHeartbeat(file) {
+  timer = setInterval(() => {
+    // If another process took the lock, stop refreshing rather than clobbering its claim.
+    const lock = readLock(file);
+    if (lock && lock.pid !== process.pid) return stopHeartbeat();
+    try {
+      write(file);
+    } catch {
+      // A lock we can no longer refresh just goes stale; playback carries on.
+    }
+  }, HEARTBEAT_MS);
+  timer.unref?.();
+}
+
+function stopHeartbeat() {
+  clearInterval(timer);
+  timer = null;
+}
+
+function drop(file) {
+  if (readLock(file)?.pid === process.pid) fs.rmSync(file, { force: true });
+}
+
+function registerCleanup(file) {
+  if (cleanupFile) return;
+  cleanupFile = file;
+  process.on("exit", () => {
+    if (holding) drop(cleanupFile);
+  });
+}
+
+const disabled = (env = process.env) => env.ROGER_ROGER_NO_SPEAKER_LOCK === "1";
+
+let asideCounter = 0;
+
+/**
+ * Clear the stale claim we judged (`seen`), and only that one. Two waiters can both judge the same
+ * lock stale; if both simply deleted it, the slower one would delete the lock the faster one had
+ * just created, and both would speak at once. A rename is atomic, so the lock is moved aside first
+ * and only then checked: if what was moved is not what we judged — a newer claim, or a heartbeat
+ * that proved the holder alive — it is put back with 'wx', which never overwrites a lock someone
+ * created in between. True when the way is clear to try creating the lock again.
+ */
+function takeOver(file, seen) {
+  if (seen === null) return true; // nothing there to clear
+  const aside = `${file}.${process.pid}.${Date.now()}.${asideCounter++}.stale`;
+  try {
+    fs.renameSync(file, aside);
+  } catch (e) {
+    if (e.code === "ENOENT") return true; // somebody else cleared it; race them for the new one
+    if (["EPERM", "EACCES", "EBUSY"].includes(e.code)) return false; // Windows: open elsewhere, try next poll
+    throw e;
+  }
+  const moved = readRaw(aside);
+  if (moved !== seen) {
+    try {
+      fs.writeFileSync(file, moved ?? "", { flag: "wx" });
+    } catch {
+      // A newer lock is already there; the claim we moved has lost the race regardless.
+    }
+  }
+  fs.rmSync(aside, { force: true });
+  return moved === seen;
+}
+
+/**
+ * Take the speaker, waiting for whoever has it. Returns a handle for `releaseSpeaker`:
+ * `held` says whether we actually got the lock, `waitedMs` how long the queue took, and
+ * `tookOver` that a stale holder was stepped over.
+ */
+export async function acquireSpeaker({ file = speakerLockPath(), wait = MAX_WAIT_MS, env = process.env } = {}) {
+  if (disabled(env)) return { held: false, waitedMs: 0, reason: "disabled" };
+  const start = Date.now();
+  let tookOver = false;
+  let queued = false; // a lock taken on the first try was never a wait
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    for (;;) {
+      try {
+        fs.writeFileSync(file, JSON.stringify({ pid: process.pid, heartbeat: Date.now() }), { flag: "wx" });
+        holding = true;
+        startHeartbeat(file);
+        registerCleanup(file);
+        return { held: true, waitedMs: queued ? Date.now() - start : 0, ...(tookOver ? { tookOver } : {}) };
+      } catch (e) {
+        if (e.code !== "EEXIST") throw e;
+        queued = true;
+        const raw = readRaw(file);
+        if (!heldByOther(file, raw) || Date.now() - start >= wait) {
+          // Free, abandoned, or we have queued long enough to stop believing the holder.
+          if (takeOver(file, raw)) {
+            tookOver = true;
+            continue;
+          }
+        }
+        await sleep(POLL_MS);
+      }
+    }
+  } catch (e) {
+    // No usable lock (read-only home, odd filesystem). Better a possible overlap than silence.
+    return { held: false, waitedMs: Date.now() - start, reason: e.message };
+  }
+}
+
+/** Give the speaker back, after a short gap so the next announcement is distinct from ours. */
+export async function releaseSpeaker(handle, { file = speakerLockPath(), gap = GAP_MS } = {}) {
+  if (!handle?.held) return;
+  if (gap) await sleep(gap);
+  holding = false;
+  stopHeartbeat();
+  try {
+    drop(file);
+  } catch {
+    // The next process steps over a lock nobody refreshes.
+  }
+}
+
+// Inside one process the lock file is not enough: the daemon serves several agents at once, and a
+// second request would find the lock already ours. Callers queue here first, then for the machine.
+let chain = Promise.resolve();
+
+/**
+ * Run `fn` with the speaker to ourselves; the handle tells it how long the queue took. Calls are
+ * served in the order they arrive. Don't nest one inside another: the inner call would wait for the
+ * outer one to finish.
+ */
+export function withSpeaker(fn, opts = {}) {
+  const queuedAt = Date.now();
+  const run = chain.then(() => exclusive(fn, opts, queuedAt), () => exclusive(fn, opts, queuedAt));
+  chain = run.then(() => {}, () => {});
+  return run;
+}
+
+async function exclusive(fn, opts, queuedAt) {
+  const handle = await acquireSpeaker(opts);
+  // Waiting behind another announcement in this process counts as queueing just as much as waiting
+  // for another machine-wide holder, so the caller hears about either.
+  const waited = Math.max(handle.waitedMs ?? 0, Date.now() - queuedAt);
+  try {
+    return await fn({ ...handle, waitedMs: waited });
+  } finally {
+    await releaseSpeaker(handle, opts);
+  }
+}

package/skills/roger-roger/scripts/speechkey.mjs

@@ -0,0 +1,106 @@
+// Where the speech API key comes from: an environment variable, and the user gets to say which.
+//
+// The daemon is long-lived and inherited its environment from whichever agent happened to start it,
+// so a variable the user set afterwards — in Windows' own settings, the usual way — is invisible to
+// it. On Windows the user's and the machine's saved variables are read directly as well, so setting
+// a key there works without restarting anything. Only names ever leave this file, never values.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Tried in this order when nothing else says which (the provider normally does). */
+export const DEFAULT_KEY_VARS = ["GEMINI_API_KEY", "GOOGLE_API_KEY"];
+
+// Keys pasted into `install` are kept here, one JSON object of NAME → value, readable by the user
+// only. It is the third place a key is looked for, after this process's environment and (on
+// Windows) the saved variables, so a key set the ordinary way always wins over one pasted earlier.
+// The home is worked out here rather than imported: lib.mjs imports this file's dependants.
+const keyFilePath = (env = process.env) => path.join(env.ROGER_ROGER_HOME || path.join(os.homedir(), ".roger-roger"), "keys.json");
+
+function savedKeys(env = process.env) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(keyFilePath(env), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Keep a key for `name`, or forget it with an empty value. Returns where it was written. */
+export function saveKey(name, value, env = process.env) {
+  const file = keyFilePath(env);
+  const keys = savedKeys(env);
+  if (value && String(value).trim()) keys[name.toUpperCase()] = String(value).trim();
+  else delete keys[name.toUpperCase()];
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(keys, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600); // A no-op on Windows, where the user profile is already private.
+  } catch {}
+  return file;
+}
+
+/** Whether a pasted key is on file for `name` (never the key itself). */
+export const hasSavedKey = (name, env = process.env) => Boolean(savedKeys(env)[String(name).toUpperCase()]);
+
+/** `reg query` output → { NAME: value }. Values that point at other variables are expanded by hand. */
+function registryVars(key) {
+  if (process.platform !== "win32") return {};
+  try {
+    const out = execFileSync("reg.exe", ["query", key], { encoding: "utf8", windowsHide: true, timeout: 5_000 });
+    const vars = {};
+    for (const line of out.split(/\r?\n/)) {
+      const m = /^\s{4}(\S+)\s+REG_(?:EXPAND_)?SZ\s+(.*)$/.exec(line);
+      if (m) vars[m[1].toUpperCase()] = m[2].replace(/%([^%]+)%/g, (all, name) => process.env[name] ?? all);
+    }
+    return vars;
+  } catch {
+    return {};
+  }
+}
+
+let saved = null;
+let savedAt = 0;
+/**
+ * The variables Windows keeps for new processes. Read at most every half minute: it spawns `reg`,
+ * and the tray's snapshot asks on every write.
+ */
+function savedVars() {
+  if (!saved || Date.now() - savedAt > 30_000) {
+    saved = {
+      ...registryVars("HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment"),
+      ...registryVars("HKCU\\Environment"),
+    };
+    savedAt = Date.now();
+  }
+  return saved;
+}
+
+/** This process's variable first, then Windows' saved one, then a key pasted into `install`. Empty when none has it. */
+export function envValue(name, env = process.env) {
+  if (!name) return "";
+  const live = env[name] ?? env[name.toUpperCase()];
+  if (live && live.trim()) return live.trim();
+  if (env !== process.env) return ""; // a caller with its own env (a test) means exactly that env
+  return (savedVars()[name.toUpperCase()] ?? savedKeys(env)[name.toUpperCase()] ?? "").trim();
+}
+
+/**
+ * The key to use, and which variable it came from. `name` is the user's choice; empty means the
+ * provider's usual names in turn. A chosen variable that is empty is an answer, not a reason to look
+ * elsewhere: the user said where the key is.
+ */
+export function speechKey(name = "", defaults = DEFAULT_KEY_VARS, env = process.env) {
+  const names = name ? [name] : defaults;
+  for (const n of names) {
+    const value = envValue(n, env);
+    if (value) return { name: n, value };
+  }
+  return { name: name || defaults[0], value: "" };
+}
+
+/** What the missing key is called, for an error message that says what to set. */
+export const missingKeyMessage = (name = "", defaults = DEFAULT_KEY_VARS) =>
+  name ? `the environment variable ${name} is empty or not set` : `no API key: set ${defaults.join(" or ")}, or name another variable in setup`;

package/skills/roger-roger/scripts/tray.mjs

@@ -0,0 +1,128 @@
+// What a tray icon shows, as a plain file the daemon keeps up to date.
+//
+// The tray itself is native on each platform and has no business speaking the daemon's protocol, so
+// it doesn't: it watches one small file and draws whatever is in it. Anything it lets you press is
+// an ordinary `roger-roger` command, the same one you could have typed.
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  DUCK_MODES, METHODS, ON_EXPIRE, SPEECH_MODES, WHEN_MODES, duckFactor,
+  rogerRogerHome, inQuietHours, listSounds, snoozeUntil,
+} from "./lib.mjs";
+import * as decisions from "./decisions.mjs";
+import * as progressStore from "./progress.mjs";
+import * as sessions from "./sessions.mjs";
+import { PROVIDERS, catalog, keyFor, providerOf } from "./tts.mjs";
+
+export const snapshotPath = (env = process.env) => path.join(rogerRogerHome(env), "tray.json");
+
+/** One line per agent, short enough to read at a glance and nothing more. */
+function agentLine(session, pending, now) {
+  const waiting = pending.find((d) => d.sessionId === session.id);
+  return {
+    id: session.id,
+    nickname: session.nickname,
+    swatch: session.swatch,
+    colour: session.colour,
+    project: session.project,
+    // The same line Slack puts under a message, so the panel and the DM agree on who this is.
+    agent: session.agent ?? null,
+    model: session.model ?? null,
+    name: session.name ?? null,
+    host: session.host ?? null,
+    state: session.state,
+    quietForMs: Math.max(0, now - Date.parse(session.lastSeen ?? 0)),
+    queued: session.queue?.length ?? 0,
+    owes: decisions.undeliveredFor(session.id).length,
+    ...(waiting ? { waitingOn: { id: waiting.id, question: waiting.question, expiresAt: waiting.expiresAt } } : {}),
+  };
+}
+
+/** Everything a panel needs, and nothing it doesn't. */
+export function snapshot({ config = null, daemon = null, now = Date.now() } = {}) {
+  const pending = decisions.list().filter((d) => d.status === "pending");
+  const live = sessions.live(now);
+  return {
+    updatedAt: new Date(now).toISOString(),
+    daemon: daemon ? { pid: daemon.pid, slackConnected: Boolean(daemon.slackConnected) } : null,
+    muted: {
+      snoozeUntil: snoozeUntil(config, new Date(now)),
+      quietHours: config?.quietHours ?? null,
+      quietNow: Boolean(config?.quietHours && inQuietHours(config.quietHours, new Date(now))),
+    },
+    agents: live.map((s) => agentLine(s, pending, now)),
+    questions: pending.map((d) => ({
+      id: d.id,
+      question: d.question,
+      nickname: d.nickname ?? null,
+      swatch: d.swatch ?? null,
+      choices: d.choices ?? [],
+      expiresAt: d.expiresAt,
+    })),
+    working: progressStore.active(now).map((p) => ({ key: p.key, headline: p.headline, nickname: p.nickname ?? null })),
+    // Everything `setup` can change, so the panel can offer it without asking anyone. Tokens live
+    // in slack.json and the environment and are deliberately not here.
+    settings: config
+      ? {
+          methods: config.methods ?? [],
+          sound: config.sound ?? "",
+          voice: config.voice ?? "",
+          speech: config.speech ?? "auto",
+          when: config.when ?? "auto",
+          remind: (config.remind ?? []).join(","),
+          onExpire: config.onExpire ?? "recommended",
+          quietHours: config.quietHours ? { from: config.quietHours.from, to: config.quietHours.to } : null,
+          quietMute: config.quietHours?.mute ?? ["speech", "sound"],
+          sessionLabel: config.sessionLabel !== false,
+          sayWho: config.sayWho !== false,
+          localFallback: config.localFallback !== false,
+          tray: config.tray ?? "auto",
+          model: config.model ?? "",
+          duck: duckFactor(config) < 1 || config.duck === "on",
+          duckLevel: Math.round(duckFactor({ ...config, duck: "on" }) * 100),
+          speechVolume: Number.isFinite(config.speechVolume) ? config.speechVolume : 100,
+          speechProvider: providerOf(config).id,
+          // The variable's name and whether it holds anything. The key itself never leaves the daemon.
+          speechKeyVar: config.speechKeyVar ?? "",
+          speechKeyFound: Boolean(keyFor(config).value),
+          speechKeyUsed: keyFor(config).name,
+          notes: config.notes ?? "",
+          slackTarget: config.slack?.target ?? "",
+          slackMention: config.slack?.mention ?? "",
+        }
+      : null,
+    options: {
+      methods: METHODS,
+      sounds: listSounds(),
+      // The chosen provider's voices and models, as last fetched; `fetchedAt` is null until they have been.
+      speechProviders: Object.values(PROVIDERS).map((p) => ({ id: p.id, label: p.label, keyVars: p.keyVars })),
+      speechCatalog: catalog(providerOf(config).id),
+      speech: SPEECH_MODES,
+      duck: DUCK_MODES,
+      when: WHEN_MODES,
+      onExpire: ON_EXPIRE,
+    },
+  };
+}
+
+/** Write via a temp file and rename, so a tray watching it never reads half a snapshot. */
+export function write(data, env = process.env) {
+  const file = snapshotPath(env);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", "utf8");
+    fs.renameSync(tmp, file);
+  } catch {
+    // A tray that can't be updated is not a reason to take the daemon down.
+  }
+}
+
+export function read(env = process.env) {
+  try {
+    return JSON.parse(fs.readFileSync(snapshotPath(env), "utf8"));
+  } catch {
+    return null;
+  }
+}