roger-roger 0.1.0

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

@@ -0,0 +1,1151 @@
+// What every command actually does. The daemon serves these; the CLI calls them directly when no
+// daemon can be reached, so there is one implementation either way.
+//
+// A handler takes (ctx, args) and returns { data, code }. `ctx` carries the loaded config, the agent
+// session that is calling, a log, and a bus that wakes `wait` the moment something changes.
+// Anything that needs the caller's working directory — attachments, the project name — is resolved
+// by the CLI before it gets here, because the daemon runs somewhere else entirely.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+  DEFAULT_DRAFT_CHOICE, DEFAULTS, KINDS, METHODS, MAX_DRAFT, ON_EXPIRE,
+  announceAs, applySetup, applyQuietHours, rogerRogerHome, machineEnv, pidAlive, decisionBlocks, formatElapsed, listArg, listSounds, saveConfig,
+  messageBlocks, parseChoices, parseDuration, parseFields, parseRecommend, parseRecommendMany,
+  parseRemind, previewList, progressBlocks, sessionLabel, slackAppToken, slackText, slackToken,
+  soundAnnouncement, speechText, splitList, stripTags, summaryBlocks, voiceSample,
+} from "./lib.mjs";
+import {
+  deliverSpeech, mapPool, playAlert, playWav, playWavBuffer, prepareSpeech, soundFile,
+  speakLocally, speechAudio, warmUpAudio, withOthersQuieter,
+} from "./audio.mjs";
+import { withSpeaker } from "./speaker.mjs";
+import { catalog, findVoice, keyFor, missingKey, providerOf, refreshCatalog, testSample } from "./tts.mjs";
+import { addReaction, postMessage, removeReaction, updateMessage, uploadFiles } from "./slack.mjs";
+import * as progressStore from "./progress.mjs";
+import * as sessions from "./sessions.mjs";
+import * as inbox from "./inbox.mjs";
+import * as decisions from "./decisions.mjs";
+import { labelPane } from "./herdr.mjs";
+import { answeredNotice, isQuestion, matchRequest, permissionNotice, rememberRequest } from "./hooks.mjs";
+
+export const EXIT_NOT_CONFIGURED = 3;
+export const EXIT_STILL_PENDING = 4;
+export const EXIT_CLOSED = 5;
+export const EXIT_MESSAGE = 6;
+// A question an agent is waiting on settles itself in well under an hour: the recommended option is
+// applied at 45 minutes, with a nudge at 15. Follow-up buttons on a summary card block nobody, so
+// they stay open far longer.
+const DEFAULT_ASK_EXPIRY = 45 * 60;
+// Short on purpose: waking inside the agent's prompt cache costs about a tenth of waking outside it.
+const DEFAULT_LISTEN = 25 * 60;
+const DEFAULT_ACTIONS_EXPIRY = 4 * 3600;
+
+const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+const ok = (data, code = 0) => ({ data, code });
+
+function fail(message, code = 1) {
+  throw Object.assign(new Error(message), { code });
+}
+
+function requireConfig(ctx) {
+  if (!ctx.config) fail("not configured", EXIT_NOT_CONFIGURED);
+  return ctx.config;
+}
+
+const sayArg = (args) => (typeof args.say === "string" ? args.say : undefined);
+
+/** What is actually said out loud, with this agent's name on the front unless that is turned off. */
+function spoken(ctx, config, args, message) {
+  const text = speechText({ mode: config.speech, message, say: sayArg(args) });
+  return announceAs(text, config.sayWho === false ? null : ctx.session?.nickname);
+}
+
+/** The user's message has now been answered, which is what the tick means. */
+async function markAnswered(channel, ts) {
+  if (!ts) return;
+  await addReaction(channel, ts, "white_check_mark").catch(() => {});
+  await removeReaction(channel, ts, "eyes").catch(() => {});
+}
+
+/** "🌿 sage · machine · agent · model · session" under Slack messages. */
+function labelFor(ctx, args, config) {
+  if (config.sessionLabel === false) return "";
+  const str = (v) => (typeof v === "string" ? v : undefined);
+  return sessionLabel({
+    hostname: ctx.session?.host || os.hostname(),
+    agent: str(args.agent) || ctx.session?.agent,
+    model: str(args["agent-model"]),
+    session: str(args.session),
+    nickname: ctx.session?.nickname,
+  });
+}
+
+/** The session's colour, which Slack draws as a bar down the left of its messages. */
+const colourOf = (ctx) => ctx.session?.colour;
+
+/** Methods for this call: `--only` or the configured ones, minus whatever quiet hours mute. */
+function methodsFor(args, config) {
+  const only = splitList(args.only);
+  const wanted = only.length ? only.filter((m) => METHODS.includes(m)) : config.methods;
+  return applyQuietHours(wanted, config);
+}
+
+function attachments(args) {
+  const files = listArg(args.attach);
+  for (const f of files) {
+    if (!fs.existsSync(f) || !fs.statSync(f).isFile()) fail(`--attach: no such file: ${f}`);
+  }
+  return files;
+}
+
+function draftOf(args) {
+  const draft = typeof args.draft === "string" ? args.draft.replace(/\r\n/g, "\n") : "";
+  if (draft.length > MAX_DRAFT) {
+    fail(`the draft is ${draft.length} characters; Slack can only edit ${MAX_DRAFT}. Shorten it, or --attach the full text and ask about it instead`);
+  }
+  return draft.trim() ? draft : "";
+}
+
+/** Note what the agent is doing, so the picker can say "waiting on you" next to its name. */
+function setState(ctx, state) {
+  if (ctx.session) sessions.touch(ctx.session.id, { state });
+}
+
+// ---------------------------------------------------------------- notify
+
+export async function notify(ctx, args) {
+  const config = requireConfig(ctx);
+  const kind = args.kind ?? "info";
+  if (!KINDS.includes(kind)) fail(`--kind must be one of: ${KINDS.join(", ")}`);
+  const message = typeof args.message === "string" ? args.message : (args._ ?? []).join(" ");
+  if (!message) fail("--message is required");
+  const fields = parseFields(listArg(args.field));
+  const replyTo = typeof args["reply-to"] === "string" ? args["reply-to"].trim() : "";
+  const files = attachments(args);
+  const { methods, muted } = methodsFor(args, config);
+  const followUp = followUpActions(args, config, methods);
+  const text = spoken(ctx, config, args, message);
+  const results = {};
+  setState(ctx, kind === "done" ? "done" : "working");
+
+  const headline = slackText({ kind, message, project: args.project, mention: config.slack.mention });
+  const label = labelFor(ctx, args, config);
+  const colour = colourOf(ctx);
+  let blocks = messageBlocks({ headline, label });
+  if (args.summary || fields.length) {
+    // The end-of-task card: facts, time taken, and the questions answered in this session.
+    const name = typeof args.session === "string" ? args.session.trim().toLowerCase() : "";
+    const answered = args.summary && name
+      ? decisions.list().filter((d) => d.status !== "pending" && d.session?.trim().toLowerCase() === name).reverse()
+      : [];
+    const elapsed = args.summary && ctx.session ? formatElapsed(Date.now() - Date.parse(ctx.session.firstSeen)) : "";
+    blocks = summaryBlocks({ headline, fields, elapsed, decisions: answered, label });
+  }
+
+  // Slack posts while the speech is synthesized; the sound waits for the speech.
+  if (methods.includes("sound") || methods.includes("speech")) warmUpAudio();
+  const prepared = methods.includes("speech") ? prepareSpeech(text, config) : null;
+  let followUpId = null;
+  const slackJob = methods.includes("slack")
+    ? (async () => {
+        const id = followUp ? decisions.newId() : null;
+        const now = Date.now();
+        const expiresAt = followUp ? new Date(now + followUp.expiresIn * 1000).toISOString() : null;
+        const payload = followUp
+          ? { text: stripTags(headline), blocks: decisionBlocks({ id, baseBlocks: blocks, choices: followUp.choices, recommended: followUp.recommended, allowOther: followUp.allowOther, expiresAt, onExpire: followUp.onExpire }), color: colour }
+          : { text: stripTags(headline), blocks, color: colour };
+        // Answering something the user said in a thread belongs in that thread, not the channel.
+        const { channel, ts } = await postMessage(config, { ...payload, ...(replyTo ? { thread_ts: replyTo } : {}) });
+        await markAnswered(channel, replyTo);
+        sessions.bindThread(ts, ctx.session?.id);
+        results.slack = { ok: true, channel, ts };
+        if (followUp) {
+          decisions.create({
+            id, status: "pending", question: stripTags(message), details: "", headline, baseBlocks: blocks,
+            choices: followUp.choices, recommended: followUp.recommended, multi: false, label, allowOther: followUp.allowOther,
+            onExpire: followUp.onExpire, reminders: [], remindersSent: 0, channel, ts, colour,
+            sessionId: ctx.session?.id ?? null,
+            ...(typeof args.session === "string" ? { session: args.session.trim() } : {}),
+            createdAt: new Date(now).toISOString(), expiresAt,
+          });
+          followUpId = id;
+        }
+        if (files.length) results.slack.attached = await uploadFiles(channel, files);
+      })().catch((e) => (results.slack = { ok: Boolean(results.slack?.ok), error: e.message }))
+    : null;
+
+  Object.assign(results, await playAlert({ methods, config, text, prepared }));
+  await slackJob;
+  const succeeded = Object.values(results).some((r) => r.ok);
+  const body = {
+    ok: succeeded,
+    kind,
+    results,
+    ...(followUpId ? { id: followUpId, status: "pending", next: `wait ${followUpId}` } : {}),
+    ...(muted.length ? { mutedByQuietHours: muted } : {}),
+    ...(files.length && !methods.includes("slack") ? { note: "--attach needs slack" } : {}),
+  };
+  // Park in the same breath as replying. Doing it as a second command leaves a few seconds where
+  // the agent looks idle, and a message sent in that gap goes to the picker instead of here.
+  if (succeeded && args["then-listen"] !== undefined) {
+    const parked = await listen(ctx, { wait: args["then-listen"] });
+    return ok({ ...body, ...parked.data }, parked.code);
+  }
+  return ok(body, succeeded ? 0 : 1);
+}
+
+// ---------------------------------------------------------------- permission prompts
+
+/**
+ * The agent is waiting on the user in the terminal — a question, a plan, or leave to act — the one
+ * moment the model can't tell anyone, because it can't run anything. The agents' hooks call this
+ * (see hooks.mjs), in steps: `request` notes what is being asked the moment it is, `prompt` pings
+ * once it has gone unanswered with nobody at the keyboard, and `answered` closes the ping once the
+ * user has dealt with it in the terminal. Nothing here ever fails loudly — it runs inside a hook,
+ * and there is nobody to read an error.
+ */
+export async function permission(ctx, args) {
+  const id = ctx.session?.id;
+  if (!id) return ok({ ok: false, skipped: "no session" });
+  const now = Date.now();
+
+  if (args.event === "request") {
+    const tool = typeof args.tool === "string" ? args.tool : "";
+    const input = args.input && typeof args.input === "object" ? args.input : {};
+    // An id when the agent gives one (OpenCode, Codex), so later steps can name this exact request.
+    const request = { tool, input, at: new Date(now).toISOString(), ...(typeof args.id === "string" && args.id ? { id: args.id } : {}) };
+    // The agent's hooks run side by side, so a quick answer (or a tool that failed at once) can
+    // arrive before the question it answers. It left a marker; the question is then already closed.
+    const early = request.id ? (ctx.session.permissions ?? []).find((r) => r.id === request.id && r.answeredAt) : null;
+    if (early) {
+      sessions.touch(id, { permissions: (ctx.session.permissions ?? []).map((r) => (r === early ? { ...early, tool, input } : r)) });
+      return ok({ ok: false, skipped: "answered before it was noted", about: tool });
+    }
+    sessions.touch(id, { permissions: rememberRequest(ctx.session.permissions, request, now) });
+    return ok({ ok: true, noted: tool });
+  }
+  if (args.event === "answered") return questionAnswered(ctx, args);
+  // The turn was cut short (Codex): whatever it was still asking won't be answered now.
+  if (args.event === "interrupted") {
+    const open = (ctx.session.permissions ?? []).filter((r) => r.id && !r.answeredAt);
+    const closed = [];
+    for (const r of open) {
+      const fresh = { ...ctx, session: { ...ctx.session, permissions: sessions.get(id)?.permissions ?? [] } };
+      closed.push((await questionAnswered(fresh, { id: r.id, tool: r.tool, outcome: "dismissed" })).data);
+    }
+    return ok({ ok: true, closed: closed.some((c) => c.closed), about: open.length ? `${open.length} open` : "nothing open" });
+  }
+  if (args.event !== "prompt") fail(`permission: unknown event "${args.event}"`, 2);
+
+  const config = ctx.config;
+  if (!config) return ok({ ok: false, skipped: "not configured" });
+  // "Only when I ask for one" covers this too: nobody asked.
+  if (config.when === "on-request") return ok({ ok: false, skipped: "when is on-request" });
+
+  const notice = typeof args.notice === "string" ? args.notice : "";
+  const requests = ctx.session.permissions ?? [];
+  // A ping for a known request (the agent's own id) is about exactly that one; if it has been dealt
+  // with in the meantime, that is the whole point of having waited.
+  let request;
+  if (typeof args.id === "string" && args.id) {
+    request = requests.find((r) => r.id === args.id);
+    if (!request) return ok({ ok: false, skipped: "no such request" });
+    if (request.answeredAt) return ok({ ok: false, skipped: "already answered", about: request.tool });
+    if (request.pingedAt) return ok({ ok: false, skipped: "already pinged", about: request.tool });
+  } else {
+    request = matchRequest(requests, notice, now);
+  }
+  // A question always pings. Leave to run something only when the user turned that on: most of
+  // those come while they're at the keyboard, approving as the agent goes.
+  if (!isQuestion(request?.tool) && config.permissionPings !== true) {
+    return ok({ ok: false, skipped: "permission pings are off", about: request?.tool ?? null });
+  }
+  // With nothing noted to tie it to, a second notice for the same prompt is told apart by time.
+  if (!request && ctx.session.permissionPingAt && now - Date.parse(ctx.session.permissionPingAt) < 60_000) {
+    return ok({ ok: false, skipped: "already pinged" });
+  }
+  const { kind, message, say } = permissionNotice({ request, notice, cwd: args.cwd || ctx.session.cwd });
+  const sent = await notify(ctx, {
+    kind,
+    message,
+    say,
+    project: args.cwd ? path.basename(args.cwd) : ctx.session.project,
+    ...(ctx.session.name ? { session: ctx.session.name } : {}),
+    ...(ctx.session.model ? { "agent-model": ctx.session.model } : {}),
+  });
+  const pingedAt = new Date().toISOString();
+  const slack = sent.data.results?.slack;
+  // Where the message went, so answering in the terminal can close it.
+  const posted = slack?.ts ? { channel: slack.channel, ts: slack.ts, project: args.cwd ? path.basename(args.cwd) : ctx.session.project } : {};
+  sessions.touch(id, {
+    state: "waiting",
+    permissionPingAt: pingedAt,
+    permissions: requests.map((r) => (r === request ? { ...r, pingedAt, ...posted } : r)),
+  });
+  return ok({ ...sent.data, about: request?.tool ?? null }, 0);
+}
+
+/**
+ * The user dealt with it in the terminal. The Slack message about it would otherwise sit there
+ * asking, so it is rewritten to say what they chose — and one answered before any ping went out is
+ * marked, so a late notice for it doesn't ping after all.
+ */
+async function questionAnswered(ctx, args) {
+  const id = ctx.session.id;
+  const requests = ctx.session.permissions ?? [];
+  // By id when the agent gives one; otherwise the newest open request for this tool, since
+  // questions are answered one at a time, in order.
+  const request = typeof args.id === "string" && args.id
+    ? requests.find((r) => r.id === args.id && !r.answeredAt)
+    : [...requests].reverse().find((r) => r.tool === args.tool && !r.answeredAt);
+  if (!request) {
+    // Arrived ahead of the question it answers: leave a marker for it (see `request` above).
+    if (typeof args.id === "string" && args.id && !requests.some((r) => r.id === args.id)) {
+      const at = new Date().toISOString();
+      sessions.touch(id, { permissions: rememberRequest(requests, { id: args.id, tool: args.tool ?? "", input: {}, at, answeredAt: at, pingedAt: at }) });
+      return ok({ ok: true, closed: false, about: args.tool ?? null, early: true });
+    }
+    return ok({ ok: false, skipped: "no question on record" });
+  }
+  const answeredAt = new Date().toISOString();
+  sessions.touch(id, {
+    state: "working",
+    permissions: requests.map((r) => (r === request ? { ...r, answeredAt, pingedAt: r.pingedAt ?? answeredAt } : r)),
+  });
+  if (!request.ts) return ok({ ok: true, closed: false, about: request.tool });
+  const config = ctx.config;
+  const outcome = ["answered", "dismissed", "allowed", "denied"].includes(args.outcome) ? args.outcome : "answered";
+  const { message } = answeredNotice(request, args.response, outcome);
+  const headline = slackText({ kind: outcome === "dismissed" || outcome === "denied" ? "info" : "done", message, project: request.project });
+  const label = config ? labelFor(ctx, { session: ctx.session.name, "agent-model": ctx.session.model }, config) : "";
+  try {
+    await updateMessage(request.channel, request.ts, { text: stripTags(headline), blocks: messageBlocks({ headline, label }), color: colourOf(ctx) });
+    return ok({ ok: true, closed: true, about: request.tool });
+  } catch (e) {
+    return ok({ ok: false, closed: false, about: request.tool, error: e.message });
+  }
+}
+
+/** `--actions "Open a PR|Run the full suite"`: follow-ups offered as buttons on the message. */
+function followUpActions(args, config, methods) {
+  if (args.actions === undefined) return null;
+  if (!methods.includes("slack")) fail("--actions needs slack");
+  if (!slackAppToken()) fail("--actions needs Slack buttons (an app-level token; see slack-setup)");
+  const choices = parseChoices(typeof args.actions === "string" ? args.actions : undefined, { min: 1 });
+  const onExpire = args["on-expire"] === undefined ? "nothing" : String(args["on-expire"]);
+  if (!ON_EXPIRE.includes(onExpire)) fail(`--on-expire must be one of: ${ON_EXPIRE.join(", ")}`);
+  return {
+    choices,
+    recommended: parseRecommend(args.recommend, choices),
+    allowOther: args.other === undefined || !["false", "no", "0", "off"].includes(String(args.other).toLowerCase()),
+    onExpire,
+    expiresIn: parseDuration(args.expires, DEFAULT_ACTIONS_EXPIRY),
+  };
+}
+
+// ---------------------------------------------------------------- progress
+
+export async function progress(ctx, args) {
+  const config = requireConfig(ctx);
+  const message = typeof args.message === "string" ? args.message : (args._ ?? []).join(" ");
+  if (!message) fail("--message is required");
+  if (!config.methods.includes("slack") || !config.slack.target) {
+    return ok({ ok: false, skipped: true, reason: "progress messages need slack in the configured methods" });
+  }
+  const key = progressStore.progressKey(typeof args.key === "string" ? args.key : args.project);
+  const done = Boolean(args.done);
+  // Buttons pressed and messages sent since the last update: this call counts as the agent's check.
+  await ctx.catchUp();
+  const updatedAt = new Date().toISOString();
+  const headline = slackText({ kind: done ? "done" : "progress", message, project: args.project });
+  const label = labelFor(ctx, args, config);
+  const colour = colourOf(ctx);
+  setState(ctx, done ? "done" : "working");
+
+  let state = progressStore.current(key);
+  const seen = progressStore.acknowledge(state);
+  const control = seen.control;
+  const payload = { text: stripTags(headline), blocks: progressBlocks({ headline, updatedAt, label, key, control, notes: seen.notes, done }), color: colour };
+
+  let action = "updated";
+  if (state) {
+    try {
+      await updateMessage(state.channel, state.ts, payload);
+    } catch (e) {
+      // The message was deleted or can't be edited any more: start a new one.
+      if (!["message_not_found", "cant_update_message", "channel_not_found"].includes(e.code)) throw e;
+      state = null;
+    }
+  }
+  if (!state) {
+    state = await postMessage(config, payload);
+    action = "posted";
+  }
+  sessions.bindThread(state.ts, ctx.session?.id);
+  if (done) {
+    progressStore.finish(key);
+  } else {
+    // Merge with a fresh read, so a click or note that landed during the update isn't lost.
+    const merged = progressStore.mergeAcknowledged(progressStore.current(key), seen);
+    progressStore.save(key, {
+      channel: state.channel, ts: state.ts, updatedAt, headline, label, colour,
+      session: ctx.session?.id ?? null, nickname: ctx.session?.nickname ?? "", ...merged,
+    });
+  }
+  await inbox.markNotesRead(seen.unread);
+  return ok({ ok: true, key, action, done, ...(await report(ctx, control, seen.unread)) });
+}
+
+/** The part of `progress` / `control` output the agent acts on. */
+async function report(ctx, control, unread) {
+  const messages = ctx.session ? await inbox.takeForSession(ctx.session.id) : [];
+  const waiting = await inbox.takeInbox();
+  return {
+    control: control.state,
+    ...(control.by ? { controlBy: control.by } : {}),
+    ...(unread.length ? { notes: unread.map((n) => ({ text: n.text, by: n.by, at: n.at })) } : {}),
+    ...(messages.length ? { messages } : {}),
+    ...(waiting.length ? { inbox: waiting } : {}),
+  };
+}
+
+/** Record that the agent has seen the latest Pause / Stop and notes, and show that in the message. */
+async function acknowledgeProgress(key) {
+  const state = progressStore.current(key);
+  const seen = progressStore.acknowledge(state);
+  if (state && seen.changed) {
+    const merged = progressStore.mergeAcknowledged(progressStore.current(key), seen);
+    const next = { ...state, ...merged };
+    progressStore.save(key, next);
+    try {
+      await updateMessage(state.channel, state.ts, { text: stripTags(state.headline), blocks: progressBlocks({ ...next, key }), color: state.colour });
+    } catch {
+      // The agent still gets its answer; the message just keeps its previous wording.
+    }
+  }
+  return { state, control: seen.control, unread: seen.unread };
+}
+
+export async function control(ctx, args) {
+  const key = progressStore.progressKey(typeof args.key === "string" ? args.key : args.project);
+  const timeout = args.wait === undefined ? 0 : parseDuration(args.wait, Infinity);
+  const deadline = Date.now() + timeout * 1000;
+  const unread = [];
+  while (true) {
+    await ctx.catchUp();
+    const { state, control: c, unread: fresh } = await acknowledgeProgress(key);
+    await inbox.markNotesRead(fresh);
+    unread.push(...fresh);
+    if (c.state === "pause") setState(ctx, "paused");
+    if (c.state !== "pause" || Date.now() >= deadline) {
+      return ok(
+        { key, active: Boolean(state), ...(await report(ctx, c, unread)) },
+        c.state === "pause" && timeout > 0 ? EXIT_STILL_PENDING : 0,
+      );
+    }
+    await ctx.idle(Math.min(1000, Math.max(0, deadline - Date.now())));
+  }
+}
+
+// ---------------------------------------------------------------- messages
+
+/** Messages for this session, plus anything in the shared inbox nobody claimed. */
+export async function messages(ctx) {
+  requireConfig(ctx);
+  if (!slackToken()) fail("Slack isn't set up (see slack-setup)");
+  await ctx.catchUp();
+  const mine = ctx.session ? await inbox.takeForSession(ctx.session.id) : [];
+  const waiting = await inbox.takeInbox();
+  return ok({ ok: true, messages: mine, ...(waiting.length ? { inbox: waiting } : {}) });
+}
+
+/**
+ * Park until the user says something. This is what keeps an agent reachable once its work is done:
+ * run it in the background as the last thing in a turn, and when it returns the agent's own harness
+ * starts a new turn with whatever arrived. Nothing is polled — the daemon wakes it the moment
+ * anything lands — and nothing is spent while it waits, so the only cost is the turn it wakes into.
+ *
+ * It does not park itself again when the time runs out. Re-parking forever is the one version of
+ * this that costs real money, so it is the caller's decision, not a default.
+ */
+/** Progress messages of this session with a button press or a note the agent hasn't dealt with. */
+function steering(sessionId) {
+  if (!sessionId) return [];
+  return progressStore.active()
+    .filter((p) => p.session === sessionId)
+    .filter((p) => (p.control?.state && p.control.state !== "running" && !p.control.ack) || (p.notes ?? []).some((n) => !n.readAt))
+    .map((p) => p.key)
+    .filter(Boolean);
+}
+
+export async function listen(ctx, args) {
+  const seconds = parseDuration(args.wait ?? args.timeout, DEFAULT_LISTEN);
+  const startedAt = Date.now();
+  const deadline = startedAt + seconds * 1000;
+  setState(ctx, "listening");
+  // Whatever this command had to do is done; from here it is only waiting. Saying so lets the
+  // caller pick the waiting back up if the daemon hands over mid-park, without repeating the rest
+  // of the command — which matters for `notify --then-listen`, where the rest was a notification.
+  ctx.emit?.("parked", { until: new Date(deadline).toISOString() });
+  try {
+    while (true) {
+      await ctx.catchUp();
+      const woke = await owedTo(ctx, {});
+      if (woke.messages?.length || woke.answers?.length) {
+        return ok({ ok: true, woke: woke.messages?.length ? "message" : "answer", ...woke });
+      }
+      // Pause, Stop and notes should reach a parked agent too: being reachable and being steerable
+      // are the same thing. `control` does the acknowledging, so this only points at it.
+      const keys = steering(ctx.session?.id);
+      if (keys.length) return ok({ ok: true, woke: "control", keys, next: `control --key ${keys[0]}` });
+      // The agent is doing something again — the user must have reached it another way. Stand down
+      // rather than interrupting it half an hour from now for nothing.
+      if ((ctx.lastActivity?.() ?? 0) > startedAt) {
+        return ok({ ok: false, woke: "resumed" }, EXIT_STILL_PENDING);
+      }
+      if (Date.now() >= deadline) {
+        return ok({ ok: false, woke: "timeout", listenedFor: formatElapsed(seconds * 1000) }, EXIT_STILL_PENDING);
+      }
+      await ctx.idle(Math.min(1000, Math.max(0, deadline - Date.now())));
+    }
+  } finally {
+    setState(ctx, "working");
+  }
+}
+
+// The native window is installed on request rather than vendored here.
+const TRAY_PACKAGES = ["@webviewjs/webview"];
+const TRAY_PACKAGE = TRAY_PACKAGES[0];
+const TRAY_ENTRY = path.resolve(SCRIPTS_DIR, "..", "tray", "main.mjs");
+const TRAY_INSTALL_TIMEOUT_MS = 5 * 60_000;
+
+/** Run a program and hand back its output, without holding up the daemon while it runs. */
+function capture(file, argv, timeout = 15_000) {
+  return new Promise((resolve, reject) => {
+    execFile(file, argv, { encoding: "utf8", windowsHide: true, timeout, maxBuffer: 8 * 1024 * 1024 }, (e, stdout) => (e ? reject(e) : resolve(stdout)));
+  });
+}
+
+/**
+ * Every tray process on this machine, found by looking rather than by trusting a file. A pid file
+ * goes stale the moment something is killed rather than asked to stop, and two trays is worse than
+ * none: each draws its own icon and neither knows about the other.
+ *
+ * Matched on the exact path of this skill's tray script, not on anything that merely mentions a
+ * tray — an agent whose message says "fixed tray/main.mjs" is not a tray, and must not be stopped.
+ * Asynchronous because listing processes on Windows takes seconds, and the daemon serving this
+ * cannot stop answering Slack for that long.
+ */
+export async function trayProcesses() {
+  const mine = [];
+  const target = TRAY_ENTRY.toLowerCase();
+  try {
+    if (process.platform === "win32") {
+      const out = await capture("powershell.exe", [
+        "-NoProfile", "-NonInteractive", "-Command",
+        "Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | ForEach-Object { \"$($_.ProcessId)`t$($_.CommandLine)\" }",
+      ]);
+      for (const line of out.split(/\r?\n/)) {
+        const tab = line.indexOf("\t");
+        if (tab === -1) continue;
+        const pid = Number(line.slice(0, tab).trim());
+        const command = line.slice(tab + 1).replace(/"/g, "").replace(/\//g, "\\").toLowerCase();
+        if (pid && pid !== process.pid && command.includes(target)) mine.push(pid);
+      }
+    } else {
+      const out = await capture("ps", ["-eo", "pid=,args="]);
+      for (const line of out.split("\n")) {
+        const m = /^\s*(\d+)\s+(.*)$/.exec(line);
+        if (!m) continue;
+        const pid = Number(m[1]);
+        // The script is node's first argument; a path that merely appears later is someone's text.
+        const argv = m[2].split(/\s+/);
+        if (pid !== process.pid && argv[1]?.toLowerCase() === target) mine.push(pid);
+      }
+    }
+  } catch {
+    // Without a process list the pid file is all there is; better than refusing to work.
+    try {
+      const raw = fs.readFileSync(path.join(rogerRogerHome(), "tray.pid"), "utf8").trim();
+      const pid = Number(raw.startsWith("{") ? JSON.parse(raw).pid : raw);
+      if (pidAlive(pid)) mine.push(pid);
+    } catch {
+      // Nothing running, or nothing we can see.
+    }
+  }
+  return [...new Set(mine)];
+}
+
+export const trayInstalled = () => fs.existsSync(path.join(rogerRogerHome(), "node_modules", "@webviewjs", "webview", "package.json"));
+
+/**
+ * Start the tray if it isn't running. Started from the user's home directory rather than wherever
+ * the caller happened to be, so no project folder is held open for as long as the tray lives, and
+ * with the machine's environment rather than an agent's, so what it does isn't credited to that agent.
+ */
+export async function startTray() {
+  if (!trayInstalled()) return { running: false, installed: false };
+  const already = await trayProcesses();
+  if (already.length) return { running: true, pids: already, note: "already running" };
+  const child = spawn(process.execPath, [TRAY_ENTRY], {
+    cwd: os.homedir(),
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: { ...machineEnv(), ROGER_ROGER_CALLER: "tray" },
+  });
+  child.unref();
+  return { running: true, starting: true, pid: child.pid };
+}
+
+/**
+ * The tray icon: start it, stop it, or say what it is doing. The native part is not vendored here —
+ * it is installed into ~/.roger-roger on request, so the skill itself stays a dependency-free Node
+ * script and everything works with no tray at all. Once installed, the daemon starts it by itself
+ * (`setup --tray off` stops that).
+ */
+export async function tray(ctx, args) {
+  const what = (args._ ?? [])[0] ?? "status";
+  const home = rogerRogerHome();
+
+  if (what === "status") {
+    const all = await trayProcesses();
+    return ok({
+      ok: true,
+      installed: trayInstalled(),
+      running: all.length > 0,
+      autostart: ctx.config?.tray !== "off",
+      ...(all.length ? { pids: all } : {}),
+      ...(all.length > 1 ? { warning: `${all.length} trays are running; "tray stop" ends all of them` } : {}),
+      package: TRAY_PACKAGE,
+      home,
+    });
+  }
+
+  if (what === "install") {
+    fs.mkdirSync(home, { recursive: true });
+    const manifest = path.join(home, "package.json");
+    if (!fs.existsSync(manifest)) fs.writeFileSync(manifest, JSON.stringify({ name: "roger-roger-local", private: true }, null, 2) + "\n", "utf8");
+    const done = await new Promise((resolve) => {
+      const npm = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["install", "--no-audit", "--no-fund", ...TRAY_PACKAGES], {
+        cwd: home,
+        stdio: "ignore",
+        windowsHide: true,
+        shell: process.platform === "win32",
+      });
+      // A registry that never answers would otherwise leave this waiting for ever.
+      const timer = setTimeout(() => {
+        npm.kill();
+        resolve(false);
+      }, TRAY_INSTALL_TIMEOUT_MS);
+      npm.on("error", () => (clearTimeout(timer), resolve(false)));
+      npm.on("close", (code) => (clearTimeout(timer), resolve(code === 0)));
+    });
+    if (!done) fail(`could not install the tray packages; try it by hand: npm install --prefix "${home}" ${TRAY_PACKAGES.join(" ")}`);
+    return ok({ ok: true, installed: true, packages: TRAY_PACKAGES, home });
+  }
+
+  if (what === "stop") {
+    const all = await trayProcesses();
+    if (!all.length) return ok({ ok: true, running: false, note: "it wasn't running" });
+    const stopped = [];
+    const stubborn = [];
+    for (const pid of all) {
+      try {
+        process.kill(pid);
+        stopped.push(pid);
+      } catch (e) {
+        stubborn.push({ pid, error: e.message });
+      }
+    }
+    fs.rmSync(path.join(home, "tray.pid"), { force: true });
+    return ok({ ok: stubborn.length === 0, stopped, ...(stubborn.length ? { stubborn } : {}) });
+  }
+
+  if (what !== "start") fail("tray takes status, start, stop or install");
+  const started = await startTray();
+  if (started.installed === false) {
+    fail(`the tray needs ${TRAY_PACKAGE}, which isn't installed yet. Run \`tray install\` (about 4 MB, no compiler) and then \`tray start\`.`);
+  }
+  return ok({ ok: true, ...started });
+}
+
+/**
+ * Quiet for a while, on purpose. Quiet hours are a schedule and a meeting is not one, so this is
+ * the ad-hoc version: sound and speech off until it runs out, Slack untouched.
+ */
+export function snooze(ctx, args) {
+  const value = (args._ ?? [])[0] ?? args.for ?? "1h";
+  // Snoozing is not setting up: saving here would write the defaults and call that the user's choice.
+  if (!ctx.config) fail("not configured yet, so there is nothing to snooze: run setup first", EXIT_NOT_CONFIGURED);
+  const config = applySetup(ctx.config, { snooze: value }, listSounds());
+  saveConfig(config);
+  ctx.config = config;
+  return ok({ ok: true, snoozeUntil: config.snoozeUntil, ...(config.snoozeUntil ? {} : { note: "not snoozed" }) });
+}
+
+// ---------------------------------------------------------------- sessions
+
+export function listSessions(ctx, args) {
+  const all = args.all ? sessions.all() : sessions.live();
+  return ok({
+    ok: true,
+    me: ctx.session?.id ?? null,
+    sessions: all.map((s) => ({
+      owes: decisions.undeliveredFor(s.id).map((d) => d.id),
+      nickname: s.nickname,
+      swatch: s.swatch,
+      colour: s.colour,
+      project: s.project,
+      name: s.name,
+      model: s.model,
+      state: s.state,
+      live: s.live,
+      queued: s.queue?.length ?? 0,
+      lastSeen: s.lastSeen,
+      id: s.id,
+      ...(s.id === ctx.session?.id ? { me: true } : {}),
+    })),
+  });
+}
+
+export function renameSession(ctx, args) {
+  const [from, to] = args._ ?? [];
+  const target = from ? sessions.byNickname(from) ?? sessions.get(from) : ctx.session;
+  if (!target) fail(`no session called "${from}"`);
+  const nickname = String(to ?? "").toLowerCase();
+  if (!nickname) fail("give the new name, e.g. `sessions rename sage plum`");
+  const renamed = sessions.rename(target.id, nickname);
+  // A new name goes on the Herdr tab too, if the session sits in one.
+  labelPane(sessions.decorate(renamed), { log: ctx.log, touch: sessions.touch }).catch(() => {});
+  return ok({ ok: true, session: sessions.decorate(renamed) });
+}
+
+export function endSession(ctx, args) {
+  const who = (args._ ?? [])[0];
+  const target = who ? sessions.byNickname(who) ?? sessions.get(who) : ctx.session;
+  if (!target) fail("no such session");
+  sessions.end(target.id);
+  return ok({ ok: true, ended: target.nickname });
+}
+
+// ---------------------------------------------------------------- questions
+
+function decisionReport(d) {
+  return {
+    id: d.id,
+    status: d.status,
+    question: d.question,
+    choices: d.choices,
+    multi: Boolean(d.multi),
+    recommended: d.recommended ?? null,
+    onExpire: d.onExpire ?? "nothing",
+    ...(d.answer ? { answer: d.answer } : {}),
+    ...(d.reason ? { reason: d.reason } : {}),
+    createdAt: d.createdAt,
+    expiresAt: d.expiresAt,
+    ...(d.resolvedAt ? { resolvedAt: d.resolvedAt } : {}),
+  };
+}
+
+function exitFor(d) {
+  if (d.status === "answered") return 0;
+  if (d.status === "pending") return EXIT_STILL_PENDING;
+  return EXIT_CLOSED;
+}
+
+export async function ask(ctx, args) {
+  const config = requireConfig(ctx);
+  if (!slackToken()) fail("asking needs Slack: SLACK_API_BOT_TOKEN is not set");
+  if (!config.slack.target) fail("asking needs Slack: run setup with --slack-target");
+  if (!slackAppToken()) {
+    fail("asking needs Slack buttons: set ROGER_ROGER_SLACK_APP_TOKEN (or SLACK_APP_TOKEN) to an app-level xapp- token with Socket Mode and Interactivity on (see SKILL.md, Requirements)");
+  }
+  if (typeof WebSocket !== "function") fail("asking needs Node 22 or newer (built-in WebSocket)");
+
+  const question = typeof args.question === "string" ? args.question : (args._ ?? []).join(" ");
+  if (!question) fail("--question is required");
+  const draft = draftOf(args);
+  const choices = draft && args.choices === undefined ? [DEFAULT_DRAFT_CHOICE] : parseChoices(args.choices, { min: draft ? 1 : 2 });
+  const multi = Boolean(args.multi) && !["false", "no", "0", "off"].includes(String(args.multi).toLowerCase());
+  if (draft && multi) fail("--draft can't be combined with --multi");
+  const recommended = multi ? parseRecommendMany(args.recommend, choices) : parseRecommend(args.recommend, choices);
+  const label = labelFor(ctx, args, config);
+  const colour = colourOf(ctx);
+  const kind = args.kind ?? "input";
+  if (!KINDS.includes(kind)) fail(`--kind must be one of: ${KINDS.join(", ")}`);
+  const expiresIn = parseDuration(args.expires, DEFAULT_ASK_EXPIRY);
+  const details = typeof args.details === "string" ? args.details : "";
+  const allowOther = args.other === undefined || !["false", "no", "0", "off"].includes(String(args.other).toLowerCase());
+  const onExpire = args["on-expire"] === undefined ? config.onExpire : String(args["on-expire"]);
+  if (!ON_EXPIRE.includes(onExpire)) fail(`--on-expire must be one of: ${ON_EXPIRE.join(", ")}`);
+  const remind = args.remind === undefined ? (config.remind ?? []).map((d) => parseDuration(d)) : parseRemind(args.remind);
+  const files = attachments(args);
+
+  const { methods, muted } = methodsFor(args, config);
+  const audible = methods.filter((m) => m === "sound" || m === "speech");
+  const replyTo = typeof args["reply-to"] === "string" ? args["reply-to"].trim() : "";
+  const text = spoken(ctx, config, args, question);
+  if (audible.length) warmUpAudio();
+  const prepared = audible.includes("speech") ? prepareSpeech(text, config) : null;
+
+  const id = decisions.newId();
+  const headline = slackText({ kind, message: question, project: args.project, mention: config.slack.mention });
+  const fallback = `${stripTags(headline)} (${choices.join(" / ")})`;
+  const now = Date.now();
+  const expiresAt = new Date(now + expiresIn * 1000).toISOString();
+  const { channel, ts } = await postMessage(config, {
+    text: fallback,
+    blocks: decisionBlocks({ id, headline, details, choices, recommended, multi, allowOther, expiresAt, onExpire, label, draft }),
+    color: colour,
+    ...(replyTo ? { thread_ts: replyTo } : {}),
+  });
+  await markAnswered(channel, replyTo);
+  const attached = files.length ? await uploadFiles(channel, files).catch((e) => ({ error: e.message })) : null;
+
+  decisions.create({
+    id,
+    status: "pending",
+    question: stripTags(question),
+    details,
+    ...(draft ? { draft } : {}),
+    ...(typeof args.session === "string" ? { session: args.session.trim() } : {}),
+    sessionId: ctx.session?.id ?? null,
+    nickname: ctx.session?.nickname ?? null,
+    swatch: ctx.session?.swatch ?? null,
+    headline,
+    choices,
+    recommended,
+    multi,
+    label,
+    colour,
+    allowOther,
+    onExpire,
+    reminders: remind.filter((sec) => sec < expiresIn).map((sec) => new Date(now + sec * 1000).toISOString()),
+    remindersSent: 0,
+    channel,
+    ts,
+    createdAt: new Date(now).toISOString(),
+    expiresAt,
+  });
+  sessions.bindThread(ts, ctx.session?.id);
+  setState(ctx, "waiting");
+
+  const audio = await playAlert({ methods: audible, config, text, prepared });
+  const extra = { audio, ...(attached ? { attached } : {}), ...(muted.length ? { mutedByQuietHours: muted } : {}) };
+  if (args.wait !== undefined) return waitFor(ctx, id, parseDuration(args.wait, Infinity), extra);
+  // Waiting costs the agent nothing: run it in the background and carry on. It always comes back,
+  // because the question settles itself at `settlesAt` whatever the user does.
+  return ok({
+    ok: true,
+    id,
+    status: "pending",
+    ...extra,
+    next: `wait ${id}`,
+    settlesAt: expiresAt,
+    hint: onExpire === "recommended" && recommended !== null
+      ? `run \`wait ${id}\` in the background and keep working; it returns when the user answers, or by ${expiresAt} with the recommended option applied`
+      : `run \`wait ${id}\` in the background and keep working; it returns when the user answers, or by ${expiresAt} unanswered`,
+  });
+}
+
+async function waitFor(ctx, id, timeoutSeconds, extra = {}) {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  // Say that someone is here. Settling a question nobody waits on marks the answer undelivered, so
+  // the Slack message can be honest about it.
+  const release = ctx.waiting?.(id) ?? (() => {});
+  try {
+    while (true) {
+      let d = decisions.read(id);
+      if (!d) fail(`no decision with id "${id}"`);
+      if (decisions.isExpired(d)) d = (await decisions.expire(d, ctx.log, { waiting: true })) ?? decisions.read(id);
+      if (d.status !== "pending" || Date.now() >= deadline) {
+        setState(ctx, d.status === "pending" ? "waiting" : "working");
+        // An answer settled before this wait started is still owed to us; take it now.
+        if (d.status === "answered" && d.deliveredAt === null) d = (await decisions.deliver(d.id, ctx.log)) ?? d;
+        return ok({ ok: d.status === "answered", ...decisionReport(d), ...extra }, exitFor(d));
+      }
+      // A message sent to this agent while it waits: hand it over now, and leave the question open.
+      await ctx.catchUp();
+      const mine = ctx.session ? await inbox.takeForSession(ctx.session.id) : [];
+      if (mine.length) {
+        return ok({ ok: false, ...decisionReport(d), messages: mine, ...extra }, EXIT_MESSAGE);
+      }
+      await ctx.idle(Math.min(1000, Math.max(0, deadline - Date.now())));
+    }
+  } finally {
+    release();
+  }
+}
+
+/**
+ * Everything this agent is owed: answers it stopped waiting for, and messages the user sent it.
+ * Attached to every command's reply, so the user is never left wondering whether it arrived — the
+ * agent does not have to happen to run the one command that looks.
+ */
+export async function owedTo(ctx, data) {
+  if (!ctx?.session || !data || typeof data !== "object") return data;
+  const answers = await pendingAnswers(ctx);
+  // A handler that already went looking (wait, inbox, progress, control) keeps what it took.
+  const messages = "messages" in data ? [] : await inbox.takeForSession(ctx.session.id);
+  if (!answers.length && !messages.length) return data;
+  return { ...data, ...(answers.length ? { answers } : {}), ...(messages.length ? { messages } : {}) };
+}
+
+/**
+ * Answers the user gave while this agent was not waiting, handed over by whatever it runs next.
+ * Every command carries them, so an agent that stopped waiting — for any reason, on any agent
+ * product — still finds out what the user said. Delivering one also updates its Slack message.
+ */
+export async function pendingAnswers(ctx) {
+  if (!ctx?.session) return [];
+  const answers = [];
+  for (const owed of decisions.undeliveredFor(ctx.session.id)) {
+    const d = await decisions.deliver(owed.id, ctx.log);
+    if (!d) continue;
+    answers.push({
+      ...decisionReport(d),
+      waited: formatElapsed(Date.parse(d.resolvedAt) - Date.parse(d.createdAt)),
+    });
+  }
+  return answers;
+}
+
+const idArg = (args) => {
+  const id = (args._ ?? [])[0];
+  if (!id) fail("give the decision id");
+  return id;
+};
+
+export function wait(ctx, args) {
+  return waitFor(ctx, idArg(args), parseDuration(args.timeout, Infinity));
+}
+
+export function check(ctx, args) {
+  return waitFor(ctx, idArg(args), 0);
+}
+
+export async function cancel(ctx, args) {
+  const id = idArg(args);
+  const reason = typeof args.reason === "string" ? args.reason : "no longer needed";
+  const settled = await decisions.settle(id, { status: "cancelled", reason });
+  const d = settled ?? decisions.read(id);
+  if (!d) fail(`no decision with id "${id}"`);
+  return ok({
+    ok: Boolean(settled),
+    ...decisionReport(d),
+    ...(settled ? {} : { note: "already closed" }),
+    ...(settled?.slackUpdateError ? { slackUpdateError: settled.slackUpdateError } : {}),
+  });
+}
+
+export function listDecisions(ctx, args) {
+  const all = decisions.list();
+  const shown = args.all ? all : all.filter((d) => d.status === "pending");
+  return ok({ decisions: shown.map(decisionReport) });
+}
+
+// ---------------------------------------------------------------- previews
+
+export async function play(ctx, args) {
+  const name = (args._ ?? [])[0] ?? ctx.config?.sound ?? DEFAULTS.sound;
+  const sounds = listSounds();
+  if (!sounds.includes(name)) fail(`unknown sound "${name}"; available: ${sounds.join(", ")}`);
+  await withSpeaker(() => playWav(soundFile(name)));
+  return ok({ ok: true, played: name });
+}
+
+/** A voice for this call: `--voice` if given (by id or name), else the configured one. */
+function voiceFor(config, wanted) {
+  if (!wanted) return config.voice;
+  const provider = providerOf(config);
+  const found = findVoice(provider.id, wanted);
+  if (!found && catalog(provider.id).voices.length) fail(`--voice: "${wanted}" is not a ${provider.label} voice (see \`voices\`)`);
+  return found ? found.id : String(wanted);
+}
+
+export async function say(ctx, args) {
+  // `say --test "hello"` reads as --test=hello to the parser; the words are the words either way.
+  // (`--gemini` is the older name for `--test`, from when there was only one provider.)
+  const flagText = [args.test, args.gemini].find((v) => typeof v === "string") ?? "";
+  const text = typeof args.text === "string" ? args.text : (args._ ?? []).join(" ") || flagText;
+  if (!text) fail("give the text to say");
+  const config = { ...DEFAULTS, ...(ctx.config ?? {}) };
+  config.voice = voiceFor(config, args.voice);
+  // `--test` checks the provider and its key, so it is never covered for: falling back to the
+  // computer's own voice would sound like success while the thing being tested had failed.
+  if (args.test || args.gemini) {
+    const provider = providerOf(config);
+    const key = keyFor(config);
+    if (!key.value) fail(missingKey(config));
+    let sample;
+    try {
+      sample = await testSample(text, config);
+    } catch (e) {
+      fail(`${provider.label} failed with the key from ${key.name}: ${e.message}`);
+    }
+    await withSpeaker(() => withOthersQuieter(config, () => playWavBuffer(sample.wav)));
+    return ok({ ok: true, engine: provider.id, voice: config.voice, model: config.model, keyVar: key.name, cached: sample.cached });
+  }
+  const prepared = await prepareSpeech(text, config, { local: Boolean(args.local) });
+  const result = await withSpeaker(() => deliverSpeech(prepared, text, config));
+  return ok(result, result.ok ? 0 : 1);
+}
+
+/** Fetch the audio up front; on failure the entry carries the error instead. */
+function prefetch(texts, config) {
+  if (!keyFor(config).value) return texts.map(() => ({ error: missingKey(config) }));
+  return mapPool(texts, 4, (text) => speechAudio(text, config).then((wav) => ({ wav }), (e) => ({ error: e.message })));
+}
+
+/**
+ * The provider's voices and models. `--refresh` asks the provider (with the configured key) and
+ * remembers the answer; without it, the last answer, or what is known without asking. A refresh
+ * that finds the configured voice or model gone moves to one that exists, so speech keeps working
+ * after switching provider or account.
+ */
+export async function voices(ctx, args) {
+  const config = { ...DEFAULTS, ...(ctx.config ?? {}) };
+  const provider = providerOf(config);
+  let error = null;
+  let refreshed = false;
+  if (args.refresh) {
+    try {
+      await refreshCatalog(config);
+      refreshed = true;
+    } catch (e) {
+      error = e.message;
+    }
+  }
+  const found = catalog(provider.id);
+  const changed = {};
+  if (refreshed && ctx.config) {
+    const next = { ...ctx.config };
+    const pick = (list, preferred) => (list.find((x) => x.id === preferred) ?? list[0])?.id;
+    if (found.voices.length && !found.voices.some((v) => v.id === next.voice)) next.voice = pick(found.voices, provider.defaultVoice);
+    if (found.models.length && !found.models.some((m) => m.id === next.model)) next.model = pick(found.models, provider.defaultModel);
+    for (const k of ["voice", "model"]) if (next[k] !== ctx.config[k]) changed[k] = next[k];
+    if (Object.keys(changed).length) {
+      saveConfig(next);
+      ctx.config = next;
+    }
+  }
+  const key = keyFor(config);
+  return ok({
+    ok: !error,
+    provider: provider.id,
+    keyVar: key.name,
+    keyFound: Boolean(key.value),
+    voice: ctx.config?.voice ?? config.voice,
+    model: ctx.config?.model ?? config.model,
+    voices: found.voices,
+    models: found.models,
+    fetchedAt: found.fetchedAt,
+    ...(Object.keys(changed).length ? { changed } : {}),
+    ...(error ? { error } : {}),
+  }, error ? 1 : 0);
+}
+
+export async function previewSounds(ctx, args) {
+  const config = { ...DEFAULTS, ...(ctx.config ?? {}) };
+  config.voice = voiceFor(config, args.voice);
+  const sounds = previewList(args._ ?? [], listSounds(), listSounds());
+  // Synthesize every announcement first so playback runs back to back.
+  const audio = args.local ? sounds.map(() => ({ error: "--local" })) : await prefetch(sounds.map(soundAnnouncement), config);
+
+  // The whole run-through is one turn at the speakers, so another agent can't cut in mid-list.
+  const played = await withSpeaker(async () => {
+    const done = [];
+    for (const [i, name] of sounds.entries()) {
+      const entry = { sound: name };
+      try {
+        if (audio[i].wav) await playWavBuffer(audio[i].wav);
+        else await speakLocally(soundAnnouncement(name));
+      } catch (e) {
+        entry.announceError = e.message;
+      }
+      try {
+        await playWav(soundFile(name));
+        entry.ok = true;
+      } catch (e) {
+        Object.assign(entry, { ok: false, error: e.message });
+      }
+      done.push(entry);
+    }
+    return done;
+  });
+  const succeeded = played.some((p) => p.ok);
+  return ok({ ok: succeeded, order: sounds, played }, succeeded ? 0 : 1);
+}
+
+export async function previewVoices(ctx, args) {
+  const config = { ...DEFAULTS, ...(ctx.config ?? {}) };
+  const provider = providerOf(config);
+  const offered = catalog(provider.id).voices;
+  if (!offered.length) fail(`no ${provider.label} voices known yet: run \`voices --refresh\` first`);
+  const all = offered.map((v) => v.id);
+  const byId = Object.fromEntries(offered.map((v) => [v.id, v]));
+  const shortlist = provider.previewVoices.filter((v) => byId[v]);
+  const voices = args.all ? all : previewList(args._ ?? [], all, shortlist.length ? shortlist : all.slice(0, 6), (n) => findVoice(provider.id, n)?.id ?? n);
+  if (!keyFor(config).value) fail(`${missingKey(config)}, so ${provider.label} voices can't be previewed`);
+  const text = (v) => (typeof args.text === "string" ? args.text : voiceSample(byId[v]?.name ?? v));
+  const audio = await mapPool(voices, 4, (voice) =>
+    speechAudio(text(voice), { ...config, voice }).then((wav) => ({ wav }), (e) => ({ error: e.message })));
+
+  const played = await withSpeaker(async () => {
+    const done = [];
+    for (const [i, voice] of voices.entries()) {
+      const entry = { voice, name: byId[voice]?.name ?? voice, ...(byId[voice]?.description ? { character: byId[voice].description } : {}) };
+      if (audio[i].error) {
+        Object.assign(entry, { ok: false, error: audio[i].error });
+      } else {
+        try {
+          await playWavBuffer(audio[i].wav);
+          entry.ok = true;
+        } catch (e) {
+          Object.assign(entry, { ok: false, error: e.message });
+        }
+      }
+      done.push(entry);
+    }
+    return done;
+  });
+  const succeeded = played.some((p) => p.ok);
+  return ok({ ok: succeeded, order: voices, played }, succeeded ? 0 : 1);
+}
+
+/**
+ * Commands run by the agent's program (its hooks), not by the model. They must not hand over what
+ * the agent is owed — nobody would read it, and the agent would never get it — and they don't mean
+ * the agent is back, so they leave a parked `listen` alone.
+ */
+export const FROM_HOOKS = new Set(["permission"]);
+
+export const HANDLERS = {
+  voices,
+  notify,
+  progress,
+  control,
+  messages,
+  listen,
+  snooze,
+  tray,
+  ask,
+  wait,
+  check,
+  cancel,
+  decisions: listDecisions,
+  sessions: listSessions,
+  rename: renameSession,
+  end: endSession,
+  play,
+  say,
+  "preview-sounds": previewSounds,
+  "preview-voices": previewVoices,
+  permission,
+};