roger-roger 0.1.0

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

@@ -0,0 +1,1133 @@
+// Pure helpers for the roger-roger skill: config, argument parsing, text shaping, WAV,
+// and the Slack message shapes for decisions. Nothing in here touches the network,
+// spawns processes, or plays audio.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { badge, colourOf } from "./names.mjs";
+import { detectAgent } from "./agent.mjs";
+
+export const SKILL_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const SOUNDS_DIR = path.join(SKILL_DIR, "sounds");
+
+export const METHODS = ["slack", "sound", "speech"];
+export const KINDS = ["done", "blocked", "input", "milestone", "error", "info"];
+export const SPEECH_MODES = ["auto", "same", "brief"];
+export const WHEN_MODES = ["auto", "done-and-blocked", "blocked-only", "on-request"];
+
+export const DEFAULT_MODEL = "gemini-3.1-flash-tts-preview";
+
+/** How far other sounds go down while the voice speaks, as a share of their own volume. */
+export const DUCK_LEVELS = { off: 1, quieter: 0.4, "much-quieter": 0.15, silent: 0 };
+export const DUCK_MODES = ["on", "off"];
+
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+
+/**
+ * The share of their own volume other apps keep while the voice speaks: 1 when ducking is off.
+ * The level is `duckLevel` (0–100); a config from before there was a slider says it by name.
+ */
+export function duckFactor(config) {
+  const duck = config?.duck ?? "on";
+  if (duck === "off" || duck === false) return 1;
+  if (Number.isFinite(config?.duckLevel)) return clamp(config.duckLevel, 0, 100) / 100;
+  return DUCK_LEVELS[duck] ?? DUCK_LEVELS.quieter;
+}
+
+/** The voice's volume as a factor: 1 is as the provider made it. */
+export const speechGain = (config) => clamp(Number.isFinite(config?.speechVolume) ? config.speechVolume : 100, 0, 150) / 100;
+
+/**
+ * A 16-bit PCM WAV with every sample scaled by `gain`, clipped rather than wrapped. Anything that
+ * isn't 16-bit PCM is returned as it came: better at the wrong volume than not at all. The data
+ * chunk runs to the end of the buffer, whatever its header says — a streamed WAV says nonsense.
+ */
+export function scaleWav(wav, gain) {
+  if (gain === 1 || !Buffer.isBuffer(wav) || wav.length < 44 || wav.toString("ascii", 0, 4) !== "RIFF") return wav;
+  let offset = 12;
+  let format = null;
+  let bits = null;
+  while (offset + 8 <= wav.length) {
+    const id = wav.toString("ascii", offset, offset + 4);
+    const size = wav.readUInt32LE(offset + 4);
+    if (id === "fmt ") {
+      format = wav.readUInt16LE(offset + 8);
+      bits = wav.readUInt16LE(offset + 22);
+    } else if (id === "data") {
+      if (format !== 1 || bits !== 16) return wav;
+      const out = Buffer.from(wav);
+      for (let i = offset + 8; i + 1 < out.length; i += 2) {
+        out.writeInt16LE(clamp(Math.round(out.readInt16LE(i) * gain), -32768, 32767), i);
+      }
+      return out;
+    }
+    offset += 8 + size + (size % 2);
+  }
+  return wav;
+}
+
+// Gemini TTS prebuilt voices. The API has no list endpoint, so this is the published set.
+export const VOICES = {
+  Zephyr: "Bright", Puck: "Upbeat", Charon: "Informative", Kore: "Firm",
+  Fenrir: "Excitable", Leda: "Youthful", Orus: "Firm", Aoede: "Breezy",
+  Callirrhoe: "Easy-going", Autonoe: "Bright", Enceladus: "Breathy", Iapetus: "Clear",
+  Umbriel: "Easy-going", Algieba: "Smooth", Despina: "Smooth", Erinome: "Clear",
+  Algenib: "Gravelly", Rasalgethi: "Informative", Laomedeia: "Upbeat", Achernar: "Soft",
+  Alnilam: "Firm", Schedar: "Even", Gacrux: "Mature", Pulcherrima: "Forward",
+  Achird: "Friendly", Zubenelgenubi: "Casual", Vindemiatrix: "Gentle", Sadachbia: "Lively",
+  Sadaltager: "Knowledgeable", Sulafat: "Warm",
+};
+
+/** Case-insensitive voice lookup returning the canonical name; throws on an unknown voice. */
+export function matchVoice(name) {
+  const match = Object.keys(VOICES).find((v) => v.toLowerCase() === String(name).toLowerCase());
+  if (!match) throw new Error(`--voice must be one of: ${Object.keys(VOICES).join(", ")}`);
+  return match;
+}
+
+/** A varied shortlist for `preview-voices` when the user doesn't name voices; `--all` plays every one. */
+export const PREVIEW_VOICES = ["Kore", "Puck", "Charon", "Aoede", "Achird", "Sulafat"];
+
+/** What each voice says when previewed. */
+export function voiceSample(name) {
+  return `Hi, I'm ${name}. [short pause] I'll let you know when your work is done.`;
+}
+
+/** Spoken before each sound in `preview-sounds`, so the user can tell them apart. */
+export function soundAnnouncement(name) {
+  return `This is ${name}.`;
+}
+
+/**
+ * Which items a preview covers: the positionals if given (validated against `available`),
+ * otherwise `fallback`. `match` canonicalises a name or throws.
+ */
+export function previewList(requested, available, fallback, match = (n) => n) {
+  if (!requested.length) return fallback;
+  return [...new Set(requested.map((n) => {
+    const canonical = match(n);
+    if (!available.includes(canonical)) throw new Error(`unknown "${n}"; available: ${available.join(", ")}`);
+    return canonical;
+  }))];
+}
+
+export const DEFAULTS = {
+  version: 1,
+  methods: ["sound", "speech"],
+  sound: "chime",
+  voice: "Kore",
+  model: DEFAULT_MODEL,
+  localFallback: true,
+  speech: "auto",
+  when: "auto",
+  slack: { target: "", mention: "" },
+  // Reminders while a question is unanswered, measured from when it was asked.
+  remind: ["15m"],
+  // What an unanswered question settles as: its recommended option, or nothing (expired).
+  onExpire: "recommended",
+  // e.g. { from: "22:00", to: "08:00", mute: ["speech", "sound"] }; null means never quiet.
+  quietHours: null,
+  // Quiet until this moment, set by hand when something comes up. Null means not snoozed.
+  snoozeUntil: null,
+  // Show "machine · agent · session" under Slack messages, to tell several agents apart.
+  sessionLabel: true,
+  // Start a spoken line with the agent's name, so a voice from the next room is identifiable.
+  sayWho: true,
+  // Ping when an agent stops at an ordinary permission prompt (Claude Code hooks). Questions and plans
+  // to approve always ping; a prompt to run a command mostly means someone is at the keyboard anyway.
+  permissionPings: false,
+  // Seconds a question waits in the terminal before the ping goes out, for agents that can't tell
+  // whether anyone is typing (OpenCode, Codex). Claude Code waits until nobody has typed for a bit.
+  terminalWait: 20,
+  // Who makes the voice, and which environment variable holds that provider's key. An empty variable
+  // means the provider's usual one (GEMINI_API_KEY for Gemini, OPENAI_API_KEY for OpenAI, …).
+  speechProvider: "gemini",
+  speechKeyVar: "",
+  // Everything else playing is turned down while the voice speaks: "on" or "off", and to what share
+  // of its own volume (0–100). On by default: a notification you can't hear over a video is missed.
+  duck: "on",
+  duckLevel: 40,
+  // The voice's own volume, 0–150: 100 is as the provider made it.
+  speechVolume: 100,
+  // The tray icon: "auto" starts it with the daemon whenever it is installed, "off" leaves it to `tray start`.
+  tray: "auto",
+  notes: "",
+};
+
+export const ON_EXPIRE = ["recommended", "nothing"];
+
+const KIND_EMOJI = {
+  done: ":white_check_mark:",
+  blocked: ":octagonal_sign:",
+  input: ":raising_hand:",
+  milestone: ":triangular_flag_on_post:",
+  error: ":x:",
+  info: ":speech_balloon:",
+  progress: ":hourglass_flowing_sand:",
+};
+
+/** Is a process still running? EPERM means it exists but belongs to someone else. */
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+
+/** Everything the skill stores lives under one dot-directory: config, decisions, daemon lock. */
+export function rogerRogerHome(env = process.env) {
+  return env.ROGER_ROGER_HOME || path.join(os.homedir(), ".roger-roger");
+}
+
+/**
+ * Where this skill kept its things when it was called "attention". Only the default location is
+ * looked at: someone who pointed ATTENTION_HOME elsewhere knows where their files are.
+ */
+export const legacyHome = () => path.join(os.homedir(), ".attention");
+
+// What belonged to the old daemon's process rather than to the user: locks, sockets, pid files and
+// the tray's drawing of a moment that has passed. Copying them would only confuse the new daemon.
+const LEFT_BEHIND = new Set(["daemon.json", "daemon.sock", "speaker.lock", "tray.pid", "tray.json", "webview"]);
+
+/**
+ * The first run after the rename: copy ~/.attention to ~/.roger-roger, so the config, the Slack
+ * tokens, open questions and the tray's packages come along instead of everything quietly looking
+ * unconfigured. Copied, not moved — the old folder stays as it was, in case anyone goes back.
+ * Returns what happened, or null when there was nothing to do.
+ */
+export function migrateLegacyHome({ env = process.env, from = legacyHome(), hooks = null } = {}) {
+  if (env.ROGER_ROGER_HOME) return null;
+  const home = rogerRogerHome(env);
+  if (fs.existsSync(home) || !fs.existsSync(from)) return null;
+  // Built beside the real one and renamed into place, so a second command starting at the same
+  // moment either sees nothing yet or sees all of it.
+  const staging = `${home}.migrating-${process.pid}`;
+  try {
+    fs.cpSync(from, staging, {
+      recursive: true,
+      filter: (src) => {
+        const rel = path.relative(from, src);
+        if (!rel) return true;
+        const top = rel.split(path.sep)[0];
+        return !LEFT_BEHIND.has(top) && !(rel === top && /\.(log|tmp)$/.test(top));
+      },
+    });
+    // The Slack CLI runs the app's hooks by command line, and those still name the old script.
+    const hooksFile = path.join(staging, "slack-app", ".slack", "hooks.json");
+    if (hooks && fs.existsSync(hooksFile)) fs.writeFileSync(hooksFile, JSON.stringify(hooks, null, 2) + "\n");
+    fs.renameSync(staging, home);
+  } catch (e) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    if (fs.existsSync(home)) return null; // someone else finished first
+    throw e;
+  }
+  return { migrated: true, from, to: home };
+}
+
+export function configPath(env = process.env) {
+  return path.join(rogerRogerHome(env), "config.json");
+}
+
+export function listSounds(dir = SOUNDS_DIR) {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.endsWith(".wav")).map((f) => f.slice(0, -4)).sort();
+  } catch {
+    return [];
+  }
+}
+
+export function loadConfig(file = configPath()) {
+  if (!fs.existsSync(file)) return null;
+  const raw = JSON.parse(fs.readFileSync(file, "utf8").replace(/^/, ""));
+  return { ...DEFAULTS, ...raw, slack: { ...DEFAULTS.slack, ...(raw.slack ?? {}) } };
+}
+
+/**
+ * Written beside the real file and renamed over it. The daemon reads the config every few seconds,
+ * and a read that landed in the middle of a plain rewrite saw half a file and took the daemon down.
+ */
+export function saveConfig(config, file = configPath()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", "utf8");
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * The config, or null when it is missing or unreadable. For the places that must keep going — the
+ * daemon's loop above all — where a typo in a hand-edited file should cost a log line, not the process.
+ */
+export function loadConfigSafely(file = configPath(), log = () => {}) {
+  try {
+    return loadConfig(file);
+  } catch (e) {
+    log(`config is unreadable, carrying on without it: ${e.message}`);
+    return null;
+  }
+}
+
+// What an agent puts in the environment to say which session this is. A process started on behalf
+// of the machine — the daemon, the tray — must not carry them, or everything it does is credited to
+// whichever agent happened to start it.
+const AGENT_ENV = /^(?:CLAUDECODE|CLAUDE_CODE_.*|CLAUDE_PID|CODEX_.*|OPENCODE_.*|AI_AGENT|ROGER_ROGER_SESSION_ID|ROGER_ROGER_AGENT_PID|HERDR_.*|[A-Z][A-Z0-9_]*_(?:SESSION|THREAD|CONVERSATION)_ID|[A-Z][A-Z0-9_]*_SESSION_ATTENDED)$/;
+
+/** The environment for a long-lived process that belongs to nobody in particular. */
+export function machineEnv(env = process.env) {
+  return Object.fromEntries(Object.entries(env).filter(([k]) => !AGENT_ENV.test(k)));
+}
+
+/** Where `slack-setup` keeps the tokens the Slack CLI created for the skill's own app. */
+export function slackCredentialsPath(env = process.env) {
+  return path.join(rogerRogerHome(env), "slack.json");
+}
+
+/** Tokens saved by `slack-setup`, or null. */
+export function readSlackCredentials(file = slackCredentialsPath()) {
+  try {
+    const c = JSON.parse(fs.readFileSync(file, "utf8"));
+    return c && typeof c.botToken === "string" ? c : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The bot token: the one `slack-setup` saved, else the manual environment variables (the documented
+ * name first, then the common alternative). Saved credentials are only consulted for the real
+ * process environment, so a caller passing its own `env` sees exactly that.
+ */
+export function slackToken(env = process.env, stored = env === process.env ? readSlackCredentials() : null) {
+  return stored?.botToken || (env.SLACK_API_BOT_TOKEN || env.SLACK_BOT_TOKEN || "").trim();
+}
+
+/**
+ * Button clicks arrive over Socket Mode, which needs an app-level `xapp-` token: the saved one,
+ * else `ROGER_ROGER_SLACK_APP_TOKEN`, else `SLACK_APP_TOKEN` (for machines where that already holds
+ * something else, the first wins). A value that isn't an `xapp-` token is ignored.
+ */
+export function slackAppToken(env = process.env, stored = env === process.env ? readSlackCredentials() : null) {
+  if (stored?.appToken?.startsWith("xapp-")) return stored.appToken;
+  const t = (env.ROGER_ROGER_SLACK_APP_TOKEN || env.SLACK_APP_TOKEN || "").trim();
+  return t.startsWith("xapp-") ? t : "";
+}
+
+
+/** `--key value`, `--key=value` and bare `--flag` (true). Positionals collect in `_`. */
+export function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      out._.push(a);
+      continue;
+    }
+    const eq = a.indexOf("=");
+    let key;
+    let value;
+    if (eq !== -1) {
+      [key, value] = [a.slice(2, eq), a.slice(eq + 1)];
+    } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+      [key, value] = [a.slice(2), argv[++i]];
+    } else {
+      [key, value] = [a.slice(2), true];
+    }
+    // A repeated flag (e.g. several --attach) collects into an array.
+    out[key] = key in out ? [].concat(out[key], value) : value;
+  }
+  return out;
+}
+
+/** A flag that may be given several times → array of strings. */
+export function listArg(value) {
+  if (value === undefined) return [];
+  return [].concat(value).filter((v) => typeof v === "string" && v.trim());
+}
+
+export function splitList(value) {
+  if (value === undefined || value === true) return [];
+  return String(value).split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+
+function bool(value, name) {
+  if (value === true || value === "true" || value === "yes" || value === "1") return true;
+  if (value === "false" || value === "no" || value === "0") return false;
+  throw new Error(`--${name} must be true or false`);
+}
+
+/** A whole percentage from `0` to `max`, with or without the % sign. */
+function percent(value, name, max) {
+  const n = Number(String(value).trim().replace(/%$/, ""));
+  if (!Number.isFinite(n) || n < 0 || n > max) throw new Error(`--${name} must be a number from 0 to ${max}`);
+  return Math.round(n);
+}
+
+function oneOf(value, allowed, name) {
+  if (!allowed.includes(value)) throw new Error(`--${name} must be one of: ${allowed.join(", ")}`);
+  return value;
+}
+
+/**
+ * What setup needs to know about speech providers. The real table lives in tts.mjs, which talks to
+ * the network; this is the part of it that works offline, and Gemini alone when nothing better is
+ * passed — which is how everything before there was a choice behaved.
+ */
+const GEMINI_ONLY = {
+  ids: ["gemini"],
+  defaults: { gemini: { voice: "Kore", model: DEFAULT_MODEL } },
+  findVoice: (provider, name) => {
+    const match = Object.keys(VOICES).find((v) => v.toLowerCase() === String(name).toLowerCase());
+    return match ? { id: match } : null;
+  },
+  knowsVoices: () => true,
+};
+
+/**
+ * Merge setup flags into an existing (or default) config, validating each one.
+ * Throws with a message naming the offending flag.
+ */
+export function applySetup(base, args, sounds = listSounds(), speech = GEMINI_ONLY) {
+  const c = { ...DEFAULTS, ...(base ?? {}), slack: { ...DEFAULTS.slack, ...(base?.slack ?? {}) } };
+  delete c.names; // once a setting; nicknames are the built-in colours now, so nobody has to choose
+
+  if (args.methods !== undefined) {
+    const methods = splitList(args.methods);
+    if (methods.length === 0) throw new Error("--methods needs at least one of: " + METHODS.join(", "));
+    for (const m of methods) oneOf(m, METHODS, "methods");
+    c.methods = [...new Set(methods)];
+  }
+  if (args.sound !== undefined) {
+    if (sounds.length && !sounds.includes(args.sound)) {
+      throw new Error(`--sound must be one of: ${sounds.join(", ")}`);
+    }
+    c.sound = args.sound;
+  }
+  // A different provider has different voices, models and a different key: start it from its own
+  // defaults, and let anything given in the same breath override them.
+  if (args["speech-provider"] !== undefined) {
+    const provider = oneOf(String(args["speech-provider"]).toLowerCase(), speech.ids, "speech-provider");
+    if (provider !== (c.speechProvider || "gemini")) {
+      c.speechProvider = provider;
+      c.voice = speech.defaults[provider].voice;
+      c.model = speech.defaults[provider].model;
+      c.speechKeyVar = "";
+    }
+  }
+  if (args.voice !== undefined) {
+    const provider = c.speechProvider || "gemini";
+    const found = speech.findVoice(provider, args.voice);
+    // A provider whose voices we haven't fetched yet can't be checked; the name is taken on trust.
+    if (!found && speech.knowsVoices(provider)) throw new Error(`--voice: "${args.voice}" is not a ${provider} voice (see \`voices\`)`);
+    c.voice = found ? found.id : String(args.voice).trim();
+  }
+  if (args.model !== undefined) c.model = String(args.model).trim() || speech.defaults[c.speechProvider || "gemini"].model;
+  if (args["local-fallback"] !== undefined) c.localFallback = bool(args["local-fallback"], "local-fallback");
+  if (args.speech !== undefined) c.speech = oneOf(args.speech, SPEECH_MODES, "speech");
+  if (args.when !== undefined) c.when = oneOf(args.when, WHEN_MODES, "when");
+  if (args["slack-target"] !== undefined) c.slack.target = String(args["slack-target"]).trim();
+  if (args["slack-mention"] !== undefined) c.slack.mention = String(args["slack-mention"]).trim();
+  if (args.notes !== undefined) c.notes = String(args.notes);
+  if (args.snooze !== undefined) {
+    const value = String(args.snooze).trim().toLowerCase();
+    c.snoozeUntil = value === "off" || value === "" ? null : new Date(Date.now() + parseDuration(value) * 1000).toISOString();
+  }
+  if (args["say-who"] !== undefined) {
+    const v = String(args["say-who"]).toLowerCase();
+    c.sayWho = v === "on" ? true : v === "off" ? false : bool(args["say-who"], "say-who");
+  }
+  if (args["terminal-wait"] !== undefined) {
+    const seconds = parseDuration(String(args["terminal-wait"]));
+    if (!Number.isFinite(seconds) || seconds < 0 || seconds > 3600) throw new Error("--terminal-wait must be a duration from 0s to 1h, e.g. 20s or 2m");
+    c.terminalWait = seconds;
+  }
+  if (args["permission-pings"] !== undefined) {
+    const v = String(args["permission-pings"]).toLowerCase();
+    c.permissionPings = v === "on" ? true : v === "off" ? false : bool(args["permission-pings"], "permission-pings");
+  }
+  if (args["session-label"] !== undefined) {
+    const v = String(args["session-label"]).toLowerCase();
+    c.sessionLabel = v === "on" ? true : v === "off" ? false : bool(args["session-label"], "session-label");
+  }
+  if (args["speech-key-var"] !== undefined) {
+    const value = String(args["speech-key-var"]).trim();
+    if (value && value.toLowerCase() !== "auto" && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+      throw new Error("--speech-key-var must be the name of an environment variable, like GEMINI_API_KEY (or auto)");
+    }
+    c.speechKeyVar = value.toLowerCase() === "auto" ? "" : value.toUpperCase();
+  }
+  if (args.duck !== undefined) {
+    const v = String(args.duck).toLowerCase();
+    // The old names still work, and say how far down as well as that it's on.
+    if (v in DUCK_LEVELS && v !== "off") {
+      c.duck = "on";
+      c.duckLevel = Math.round(DUCK_LEVELS[v] * 100);
+    } else {
+      c.duck = oneOf(v === "true" ? "on" : v === "false" ? "off" : v, DUCK_MODES, "duck");
+    }
+  }
+  if (args["duck-level"] !== undefined) c.duckLevel = percent(args["duck-level"], "duck-level", 100);
+  if (args["speech-volume"] !== undefined) c.speechVolume = percent(args["speech-volume"], "speech-volume", 150);
+  if (args.tray !== undefined) {
+    const v = String(args.tray).toLowerCase();
+    c.tray = v === "on" || v === "true" || v === "auto" ? "auto" : v === "off" || v === "false" ? "off" : oneOf(v, ["auto", "off"], "tray");
+  }
+  if (args.remind !== undefined) c.remind = parseRemind(args.remind).map((s) => formatDuration(s));
+  if (args["on-expire"] !== undefined) c.onExpire = oneOf(args["on-expire"], ON_EXPIRE, "on-expire");
+  if (args["quiet-hours"] !== undefined) {
+    const range = parseQuietHours(args["quiet-hours"]);
+    c.quietHours = range && { ...range, mute: c.quietHours?.mute ?? ["speech", "sound"] };
+  }
+  if (args["quiet-mute"] !== undefined) {
+    if (!c.quietHours) throw new Error("--quiet-mute needs quiet hours: pass --quiet-hours 22:00-08:00 too");
+    const mute = splitList(args["quiet-mute"]);
+    for (const m of mute) oneOf(m, METHODS, "quiet-mute");
+    c.quietHours = { ...c.quietHours, mute: [...new Set(mute)] };
+  }
+
+  if (c.methods.includes("slack") && !c.slack.target) {
+    throw new Error("slack is enabled but --slack-target is not set (a member ID like U0123ABCD, or a channel)");
+  }
+  return c;
+}
+
+/** Audio tags like `[whispers]` steer Gemini; everywhere else they are noise. */
+//
+// Only something shaped like one counts: lowercase words standing on their own. `[JIRA-123]`,
+// `arr[0]` and `pages/[id].tsx` are the user's text and go to Slack untouched.
+export function stripTags(text) {
+  return String(text)
+    .replace(/(^|\s)\[[a-z][a-z' -]{0,38}\](?=$|\s|[,.!?;:])/g, "$1")
+    .replace(/\s+([,.!?;:])/g, "$1")
+    .replace(/\s{2,}/g, " ")
+    .trim();
+}
+
+/** Slack refuses a whole message over one section longer than 3000 characters, so cut it first. */
+export function fitSection(text, max = 3000) {
+  const t = String(text ?? "");
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+export function isUserId(target) {
+  return /^[UW][A-Z0-9]{6,}$/.test(target);
+}
+
+export function slackText({ kind = "info", message, project, mention }) {
+  const emoji = KIND_EMOJI[kind] ?? KIND_EMOJI.info;
+  const who = mention ? `<@${mention}> ` : "";
+  const where = project ? `*${project}* · ` : "";
+  return `${emoji} ${who}${where}${stripTags(message)}`;
+}
+
+/** What gets spoken: the agent's `--say` line, unless the user wants the message read verbatim. */
+export function speechText({ mode = "auto", message, say }) {
+  if (mode === "same") return message;
+  return say || message;
+}
+
+// Several agents share one pair of speakers, and a voice from the next room with no name on it is
+// a guessing game. Varied openers so it stays a greeting rather than a recording.
+const OPENERS = [
+  (n) => `${n} here.`,
+  (n) => `This is ${n}.`,
+  (n) => `${n} speaking.`,
+  (n) => `${n} talking.`,
+  (n) => `It's ${n}.`,
+  (n) => `${n} again.`,
+  (n) => `Hello, this is ${n}.`,
+  (n) => `${n}, checking in.`,
+];
+
+/**
+ * Put the speaker's name in front of a spoken line. A leading tone tag stays first, so the tone
+ * still covers the whole thing. Unchanged when there is no name to give.
+ */
+export function announceAs(text, who, pick = Math.random) {
+  const name = String(who ?? "").trim();
+  const line = String(text ?? "");
+  if (!name || !line.trim()) return line;
+  const spoken = name.charAt(0).toUpperCase() + name.slice(1);
+  const opener = OPENERS[Math.min(OPENERS.length - 1, Math.max(0, Math.floor(pick() * OPENERS.length)))](spoken);
+  const tag = /^\s*(\[[^\]]+\]\s*)/.exec(line);
+  return tag ? `${tag[1]}${opener} ${line.slice(tag[0].length)}` : `${opener} ${line}`;
+}
+
+/** Wrap Gemini's headerless 16-bit mono PCM in a 44-byte RIFF header. */
+export function wavFromPcm(pcm, sampleRate = 24000, channels = 1, bits = 16) {
+  const blockAlign = (channels * bits) / 8;
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0);
+  header.writeUInt32LE(36 + pcm.length, 4);
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(channels, 22);
+  header.writeUInt32LE(sampleRate, 24);
+  header.writeUInt32LE(sampleRate * blockAlign, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(bits, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([header, pcm]);
+}
+
+/** `audio/l16; rate=24000; channels=1` → { rate, channels }. */
+export function parsePcmMime(mime = "") {
+  const rate = Number(/rate=(\d+)/i.exec(mime)?.[1]) || 24000;
+  const channels = Number(/channels=(\d+)/i.exec(mime)?.[1]) || 1;
+  return { rate, channels };
+}
+
+// ---------------------------------------------------------------- decisions
+
+export const MAX_CHOICES = 10;
+
+/** `"Ship it|Wait|Roll back"` → trimmed, de-duplicated labels. */
+export function parseChoices(value, { min = 2 } = {}) {
+  if (typeof value !== "string") throw new Error('--choices is required, e.g. --choices "Yes|No"');
+  const choices = [...new Set(value.split("|").map((c) => c.trim()).filter(Boolean))];
+  if (choices.length < min) throw new Error(`--choices needs at least ${min === 1 ? "one option" : "two options separated by |"}`);
+  if (choices.length > MAX_CHOICES) throw new Error(`--choices allows at most ${MAX_CHOICES} options`);
+  return choices;
+}
+
+/** `--recommend` as a choice label (case-insensitive) or 1-based number → index, or null when absent. */
+export function parseRecommend(value, choices) {
+  if (value === undefined) return null;
+  const v = String(value).trim();
+  let index = choices.findIndex((c) => c.toLowerCase() === v.toLowerCase());
+  if (index === -1 && /^\d+$/.test(v) && Number(v) >= 1 && Number(v) <= choices.length) index = Number(v) - 1;
+  if (index === -1) throw new Error(`--recommend must be one of the choices (label or number 1-${choices.length})`);
+  return index;
+}
+
+/** `90`, `90s`, `30m`, `4h`, `2d` → seconds. */
+export function parseDuration(value, fallback) {
+  if (value === undefined || value === true) return fallback;
+  const m = /^(\d+(?:\.\d+)?)\s*([smhd]?)$/i.exec(String(value).trim());
+  if (!m) throw new Error(`invalid duration "${value}" (use e.g. 90s, 30m, 4h)`);
+  const unit = { "": 1, s: 1, m: 60, h: 3600, d: 86400 }[m[2].toLowerCase()];
+  return Math.round(Number(m[1]) * unit);
+}
+
+export function formatDuration(seconds) {
+  if (seconds % 3600 === 0) return `${seconds / 3600}h`;
+  if (seconds % 60 === 0) return `${seconds / 60}m`;
+  return `${seconds}s`;
+}
+
+/** `"10m,30m"` → [600, 1800] (sorted, de-duplicated); `"off"` → []. */
+export function parseRemind(value) {
+  const v = String(value).trim().toLowerCase();
+  if (v === "off" || v === "none" || v === "false") return [];
+  const seconds = splitList(v).map((d) => parseDuration(d));
+  if (seconds.some((s) => s <= 0)) throw new Error("--remind durations must be positive");
+  return [...new Set(seconds)].sort((a, b) => a - b);
+}
+
+/** `"22:00-08:00"` → { from, to }; `"off"` → null. */
+export function parseQuietHours(value) {
+  const v = String(value).trim().toLowerCase();
+  if (v === "off" || v === "none" || v === "false") return null;
+  const m = /^(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})$/.exec(v);
+  if (!m || Number(m[1]) > 23 || Number(m[3]) > 23 || Number(m[2]) > 59 || Number(m[4]) > 59) {
+    throw new Error('--quiet-hours must look like "22:00-08:00" (or "off")');
+  }
+  const pad = (h, mm) => `${h.padStart(2, "0")}:${mm}`;
+  return { from: pad(m[1], m[2]), to: pad(m[3], m[4]) };
+}
+
+/** Whether local time `date` falls inside quiet hours; ranges may wrap past midnight. */
+export function inQuietHours(quiet, date = new Date()) {
+  if (!quiet) return false;
+  const minutes = (hhmm) => Number(hhmm.slice(0, 2)) * 60 + Number(hhmm.slice(3));
+  const now = date.getHours() * 60 + date.getMinutes();
+  const [from, to] = [minutes(quiet.from), minutes(quiet.to)];
+  if (from === to) return false;
+  return from < to ? now >= from && now < to : now >= from || now < to;
+}
+
+/** Drop the methods quiet hours mute right now. Returns the methods left and what was muted. */
+// A snooze mutes the two methods that make noise. Slack keeps working, so nothing is lost —
+// you just don't hear about it until it's over.
+const SNOOZE_MUTES = ["sound", "speech"];
+
+/** When a snooze runs out, or null if there isn't one running. */
+export function snoozeUntil(config, date = new Date()) {
+  const until = config?.snoozeUntil ? Date.parse(config.snoozeUntil) : 0;
+  return until > date.getTime() ? config.snoozeUntil : null;
+}
+
+/**
+ * Methods left after the user's quiet hours and any snooze. `reason` says which of the two did it,
+ * because "it's the middle of the night" and "you asked for an hour's peace" are not the same
+ * message to read the next morning.
+ */
+export function applyQuietHours(methods, config, date = new Date()) {
+  const snoozed = Boolean(snoozeUntil(config, date));
+  const quiet = inQuietHours(config.quietHours, date);
+  if (!snoozed && !quiet) return { methods, muted: [], reason: null };
+  const mute = snoozed ? SNOOZE_MUTES : config.quietHours.mute ?? [];
+  return {
+    methods: methods.filter((m) => !mute.includes(m)),
+    muted: methods.filter((m) => mute.includes(m)),
+    reason: snoozed ? "snooze" : "quiet hours",
+  };
+}
+
+export const OTHER = "other";
+export const EDIT = "edit";
+export const EDIT_CALLBACK = "roger-roger_edit";
+// Slack's limit for a text input, and so for a draft the user can edit.
+export const MAX_DRAFT = 3000;
+export const DEFAULT_DRAFT_CHOICE = "Use as is";
+export const CHECKS = "checks";
+export const SUBMIT = "submit";
+export const OTHER_CALLBACK = "roger-roger_other";
+
+// ---------------------------------------------------------------- routing a message to an agent
+
+export const ROUTE_PREFIX = "roger-roger_route";
+export const NOBODY = "nobody";
+
+export function routeActionId(messageTs, sessionId) {
+  return `${ROUTE_PREFIX}:${messageTs}:${sessionId}`;
+}
+
+export function parseRouteActionId(value) {
+  // `attention_route:` is what the buttons said before the rename; messages already in Slack keep it.
+  const m = /^(?:roger-roger|attention)_route:([0-9.]+):(.+)$/.exec(String(value));
+  return m ? { ts: m[1], sessionId: m[2] } : null;
+}
+
+const quote = (text) => String(text ?? "").split(/\r?\n/).map((line) => `> ${line}`).join("\n");
+
+/**
+ * "Which one is this for?" — posted in the thread of a message that arrived while several agents
+ * were running. One button per live session, in its own colour, plus a way to say none of them.
+ */
+export function pickerBlocks({ text, sessions, messageTs }) {
+  return [
+    { type: "section", text: { type: "mrkdwn", text: `*Which one is this for?*\n${quote(text)}` } },
+    {
+      type: "actions",
+      elements: [
+        ...sessions.slice(0, 9).map((s) => ({
+          type: "button",
+          text: { type: "plain_text", text: `${s.swatch} ${s.nickname}${s.project ? ` · ${s.project}` : ""}`.slice(0, 75), emoji: true },
+          action_id: routeActionId(messageTs, s.id),
+        })),
+        {
+          type: "button",
+          text: { type: "plain_text", text: "📥 Nobody — keep it", emoji: true },
+          action_id: routeActionId(messageTs, NOBODY),
+        },
+      ],
+    },
+  ];
+}
+
+/**
+ * Where a message went when one agent was listening and the rest were idle, with the others a tap
+ * away. Guessing is only fair if correcting the guess is easy.
+ */
+export function sentToBlocks({ text, session, others = [], messageTs }) {
+  const to = `*${badge(session.nickname)}*${session.project ? ` · ${session.project}` : ""}`;
+  const blocks = [{
+    type: "section",
+    text: { type: "mrkdwn", text: `${quote(text)}\n\n:incoming_envelope: Sent to ${to} — the only agent listening.` },
+  }];
+  if (others.length) {
+    blocks.push({ type: "context", elements: [{ type: "mrkdwn", text: "Wrong one? Send it to:" }] });
+    blocks.push({
+      type: "actions",
+      elements: others.slice(0, 9).map((s) => ({
+        type: "button",
+        text: { type: "plain_text", text: `${s.swatch} ${s.nickname}${s.project ? ` · ${s.project}` : ""}`.slice(0, 75), emoji: true },
+        action_id: routeActionId(messageTs, s.id),
+      })),
+    });
+  }
+  return blocks;
+}
+
+/** What the picker turns into once it has been answered. */
+export function pickedBlocks({ text, session }) {
+  const to = session ? `*${badge(session.nickname)}*${session.project ? ` · ${session.project}` : ""}` : "nobody — it's waiting in the inbox";
+  return [{ type: "section", text: { type: "mrkdwn", text: `${quote(text)}\n\n:incoming_envelope: Sent to ${to}` } }];
+}
+
+export function actionId(id, index) {
+  return `roger-roger:${id}:${index}`;
+}
+
+/** `roger-roger:<id>:<index|other|edit|checks|submit>` → { id, index }, or null for an element this skill didn't make. */
+export function parseActionId(value) {
+  // `attention:` is what the buttons said before the rename; questions already in Slack keep it.
+  const m = /^(?:roger-roger|attention):([a-z0-9]+):(\d+|other|edit|checks|submit)$/.exec(String(value));
+  if (!m) return null;
+  return { id: m[1], index: /^\d+$/.test(m[2]) ? Number(m[2]) : m[2] };
+}
+
+/** `--recommend "A|C"` for a multi-select question → sorted indices (labels or 1-based numbers). */
+export function parseRecommendMany(value, choices) {
+  if (value === undefined) return null;
+  const parts = String(value).split("|").map((p) => p.trim()).filter(Boolean);
+  if (!parts.length) throw new Error("--recommend needs at least one choice");
+  return [...new Set(parts.map((p) => parseRecommend(p, choices)))].sort((a, b) => a - b);
+}
+
+/** Ticked checkbox indices from a block_actions payload's `state`, for decision `id`. */
+export function checkedIndices(state, id) {
+  // A question posted before the rename has its checkboxes under the old names.
+  const selected = state?.values?.[`roger-roger:${id}:pick`]?.[actionId(id, CHECKS)]?.selected_options
+    ?? state?.values?.[`attention:${id}:pick`]?.[`attention:${id}:${CHECKS}`]?.selected_options
+    ?? [];
+  return [...new Set(selected.map((o) => Number(o.value)).filter(Number.isInteger))].sort((a, b) => a - b);
+}
+
+// Friendly names for the agent products that announce themselves in AI_AGENT.
+export { detectAgent } from "./agent.mjs";
+
+/**
+ * "machine · agent · model · session" for telling apart messages from several agents.
+ * The model and the session name come from the agent itself (it knows both; the environment
+ * doesn't), so anything not supplied is simply left out. "" when there is nothing to say.
+ */
+export function sessionLabel({ env = process.env, hostname = "", agent, model, session, nickname } = {}) {
+  const clean = (v) => (typeof v === "string" ? v.replace(/\s+/g, " ").trim().slice(0, 60) : "");
+  const who = clean(nickname) ? `*${badge(clean(nickname))}*` : "";
+  return [who, hostname, clean(agent) || detectAgent(env), clean(model), clean(session)].filter(Boolean).join(" · ");
+}
+
+export function labelBlock(label) {
+  return label ? [{ type: "context", elements: [{ type: "mrkdwn", text: `:computer: ${label}` }] }] : [];
+}
+
+function questionBlocks(headline, details, label, draft) {
+  const blocks = [{ type: "section", text: { type: "mrkdwn", text: fitSection(headline) } }];
+  if (details) blocks.push({ type: "section", text: { type: "mrkdwn", text: fitSection(stripTags(details)) } });
+  if (draft) blocks.push(draftBlock(draft));
+  return [...blocks, ...labelBlock(label)];
+}
+
+/** A draft shown verbatim in a code block, cut to fit Slack's 3000-character section limit. */
+function draftBlock(text) {
+  const body = text.length > 2900 ? `${text.slice(0, 2900)}\n…` : text;
+  return { type: "section", text: { type: "mrkdwn", text: `\`\`\`${body.replace(/\`\`\`/g, "ʼʼʼ")}\`\`\`` } };
+}
+
+/** Labels of the given indices, bolded and comma-separated, for Slack. */
+function boldList(choices, indices) {
+  return indices.map((i) => `*${choices[i]}*`).join(", ");
+}
+
+/** Slack renders `<!date^…>` in the reader's own timezone. */
+function slackTime(iso) {
+  const unix = Math.floor(Date.parse(iso) / 1000);
+  return `<!date^${unix}^{time}|${new Date(iso).toISOString().slice(11, 16)} UTC>`;
+}
+
+/**
+ * The open question. Single choice: one button per choice, the recommended one green.
+ * Multi-select: checkboxes (recommended ones pre-ticked) and a Submit button. Either way an
+ * optional "Other…" button for a typed answer, and a note on what happens if nobody answers.
+ */
+export function decisionBlocks({ id, headline, details, choices, recommended = null, multi = false, allowOther = false, expiresAt, onExpire, label, draft, baseBlocks }) {
+  // With a draft, "Edit" replaces "Other…": the typed answer starts from the agent's text.
+  const other = draft
+    ? { type: "button", action_id: actionId(id, EDIT), value: EDIT, text: { type: "plain_text", text: "✏️ Edit", emoji: true } }
+    : { type: "button", action_id: actionId(id, OTHER), value: OTHER, text: { type: "plain_text", text: "Other…", emoji: true } };
+  // `baseBlocks`: an already-built message (e.g. a summary card) that the buttons are added to.
+  const blocks = baseBlocks ? [...baseBlocks] : questionBlocks(headline, details, null, draft);
+  if (baseBlocks) label = "";
+  if (draft) allowOther = true;
+
+  if (multi) {
+    const option = (c, i) => ({ text: { type: "plain_text", text: c.slice(0, 75), emoji: true }, value: String(i) });
+    const options = choices.map(option);
+    const initial = (recommended ?? []).map((i) => options[i]);
+    blocks.push({
+      type: "actions",
+      block_id: `roger-roger:${id}:pick`,
+      elements: [{ type: "checkboxes", action_id: actionId(id, CHECKS), options, ...(initial.length ? { initial_options: initial } : {}) }],
+    });
+    const submit = { type: "button", action_id: actionId(id, SUBMIT), value: SUBMIT, style: "primary", text: { type: "plain_text", text: "Submit", emoji: true } };
+    blocks.push({ type: "actions", block_id: `roger-roger:${id}`, elements: allowOther ? [submit, other] : [submit] });
+  } else {
+    const elements = choices.map((c, i) => ({
+      type: "button",
+      action_id: actionId(id, i),
+      value: String(i),
+      text: { type: "plain_text", text: c.slice(0, 75), emoji: true },
+      ...(i === recommended ? { style: "primary" } : {}),
+    }));
+    if (allowOther) elements.push(other);
+    blocks.push({ type: "actions", block_id: `roger-roger:${id}`, elements });
+  }
+
+  if (expiresAt) {
+    const hasDefault = onExpire === "recommended" && recommended !== null && !(multi && recommended.length === 0);
+    const picked = multi ? boldList(choices, recommended ?? []) : `*${choices[recommended]}*`;
+    const fallback = hasDefault ? `I'll go with ${picked}` : "this closes unanswered";
+    blocks.push({ type: "context", elements: [{ type: "mrkdwn", text: `If there's no answer by ${slackTime(expiresAt)}, ${fallback}.` }] });
+  }
+  return [...blocks, ...labelBlock(label)];
+}
+
+/** The pop-up behind "Other…": one text box; the decision id rides along in private_metadata. */
+export function otherModal({ id, question }) {
+  return {
+    type: "modal",
+    callback_id: OTHER_CALLBACK,
+    private_metadata: id,
+    title: { type: "plain_text", text: "Your answer" },
+    submit: { type: "plain_text", text: "Send" },
+    close: { type: "plain_text", text: "Cancel" },
+    blocks: [
+      { type: "section", text: { type: "mrkdwn", text: stripTags(question).slice(0, 2900) } },
+      {
+        type: "input",
+        block_id: "answer",
+        label: { type: "plain_text", text: "Answer" },
+        element: { type: "plain_text_input", action_id: "text", multiline: true },
+      },
+    ],
+  };
+}
+
+/** The pop-up behind "✏️ Edit": the agent's draft, ready to change; the decision id rides along. */
+export function editModal({ id, question, draft }) {
+  return {
+    type: "modal",
+    callback_id: EDIT_CALLBACK,
+    private_metadata: id,
+    title: { type: "plain_text", text: "Edit and send" },
+    submit: { type: "plain_text", text: "Send" },
+    close: { type: "plain_text", text: "Cancel" },
+    blocks: [
+      { type: "section", text: { type: "mrkdwn", text: stripTags(question).slice(0, 2900) } },
+      {
+        type: "input",
+        block_id: "answer",
+        label: { type: "plain_text", text: "Draft" },
+        element: { type: "plain_text_input", action_id: "text", multiline: true, max_length: MAX_DRAFT, initial_value: draft.slice(0, MAX_DRAFT) },
+      },
+    ],
+  };
+}
+
+/** A reminder about an open question, linking back to it. */
+export function reminderText({ question, permalink, count }) {
+  const link = permalink ? `<${permalink}|${stripTags(question)}>` : `*${stripTags(question)}*`;
+  return `:alarm_clock: ${count > 1 ? "Still" : "Reminder:"} waiting for your answer: ${link}`;
+}
+
+/** A progress message: the latest status plus when it was last updated (and by which session). */
+export function progressBlocks({ headline, updatedAt, label, key, control, notes = [], done = false }) {
+  const context = [`Updated ${slackTime(updatedAt)}`, label ? `:computer: ${label}` : ""].filter(Boolean).join("  ·  ");
+  const blocks = [
+    { type: "section", text: { type: "mrkdwn", text: headline } },
+    { type: "context", elements: [{ type: "mrkdwn", text: context }] },
+  ];
+  // The latest few notes, and whether the agent has picked each one up.
+  for (const n of notes.slice(-3)) {
+    const status = n.readAt ? "_read by the agent_" : "_not read yet_";
+    blocks.push({ type: "context", elements: [{ type: "mrkdwn", text: `:memo: <@${n.by}>: “${n.text.slice(0, 200)}” · ${status}` }] });
+  }
+  if (done || !key) return blocks;
+
+  const state = control?.state ?? "running";
+  const by = control?.by ? ` by <@${control.by}>` : "";
+  // "Requested" until the agent's next check sees it; then the message says what the agent is doing.
+  if (state === "pause") {
+    const text = control.ack ? `:double_vertical_bar: Paused${by}. The agent is holding until you resume.` : `:double_vertical_bar: Pause requested${by}. The agent pauses at its next check.`;
+    blocks.push({ type: "context", elements: [{ type: "mrkdwn", text }] });
+  } else if (state === "stop") {
+    const text = control.ack ? `:black_square_for_stop: Stopped${by}. The agent is wrapping up.` : `:black_square_for_stop: Stop requested${by}. The agent stops at its next check.`;
+    blocks.push({ type: "context", elements: [{ type: "mrkdwn", text }] });
+  }
+  const button = (action, text, style) => ({
+    type: "button",
+    action_id: progressActionId(key, action),
+    value: action,
+    text: { type: "plain_text", text, emoji: true },
+    ...(style ? { style } : {}),
+  });
+  const note = button("note", "📝 Note");
+  const buttons = state === "running"
+    ? [button("pause", "⏸ Pause"), button("stop", "⏹ Stop", "danger"), note]
+    : state === "pause"
+      ? [button("resume", "▶ Resume", "primary"), button("stop", "⏹ Stop", "danger"), note]
+      : [button("resume", "↩ Undo stop"), note];
+  blocks.push({ type: "actions", block_id: `roger-roger-progress:${key}`, elements: buttons });
+  return blocks;
+}
+
+export const NOTE_CALLBACK = "roger-roger_progress_note";
+
+/** The pop-up behind "📝 Note": a message for the running agent; the progress key rides along. */
+export function noteModal({ key, headline }) {
+  return {
+    type: "modal",
+    callback_id: NOTE_CALLBACK,
+    private_metadata: key,
+    title: { type: "plain_text", text: "Note to the agent" },
+    submit: { type: "plain_text", text: "Send" },
+    close: { type: "plain_text", text: "Cancel" },
+    blocks: [
+      { type: "context", elements: [{ type: "mrkdwn", text: stripTags(headline ?? "").slice(0, 2900) || " " }] },
+      {
+        type: "input",
+        block_id: "note",
+        label: { type: "plain_text", text: "It gets this at its next check" },
+        element: { type: "plain_text_input", action_id: "text", multiline: true, max_length: 2000 },
+      },
+    ],
+  };
+}
+
+export function progressActionId(key, action) {
+  return `roger-roger-progress:${key}:${action}`;
+}
+
+/** `roger-roger-progress:<key>:<pause|resume|stop|note>` → { key, action }, or null. */
+export function parseProgressActionId(value) {
+  const m = /^(?:roger-roger|attention)-progress:([a-z0-9._-]+):(pause|resume|stop|note)$/.exec(String(value));
+  return m ? { key: m[1], action: m[2] } : null;
+}
+
+/** 45s, 12m, 1h 12m, 2d 3h. */
+export function formatElapsed(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return m % 60 ? `${h}h ${m % 60}m` : `${h}h`;
+  const d = Math.floor(h / 24);
+  return h % 24 ? `${d}d ${h % 24}h` : `${d}d`;
+}
+
+/** `--field "Tests=31 passed"` (repeatable) → [{ label, value }]. */
+export function parseFields(values) {
+  return listArg(values).map((f) => {
+    const eq = f.indexOf("=");
+    if (eq <= 0) throw new Error(`--field must look like "Label=value", got "${f}"`);
+    return { label: f.slice(0, eq).trim(), value: f.slice(eq + 1).trim() };
+  });
+}
+
+/** One line per settled question: what was asked and what came of it. */
+export function decisionSummaryLine(d) {
+  const q = stripTags(d.question);
+  const question = q.length > 90 ? `${q.slice(0, 89)}…` : q;
+  const a = d.answer ?? {};
+  let outcome;
+  if (d.status === "answered") {
+    if (Array.isArray(a.indices)) outcome = a.indices.length ? a.choices.map((c) => `*${c}*`).join(", ") : "_none of the options_";
+    else if (a.edited) outcome = "_edited the draft_";
+    else if (a.choice === null) outcome = `“${String(a.text).slice(0, 80)}”`;
+    else outcome = `*${a.choice}*`;
+    if (a.auto) outcome += " _(no answer, went with the recommendation)_";
+  } else {
+    outcome = d.status === "expired" ? "_no answer_" : "_closed_";
+  }
+  return `• ${question} → ${outcome}`;
+}
+
+/**
+ * The end-of-task card: the message, key facts side by side, how long it took, and the
+ * decisions the user made along the way.
+ */
+export function summaryBlocks({ headline, fields = [], elapsed, decisions = [], label }) {
+  const blocks = [{ type: "section", text: { type: "mrkdwn", text: headline } }];
+  // Slack allows 10 fields per section; more go into a second one.
+  for (let i = 0; i < fields.length; i += 10) {
+    blocks.push({
+      type: "section",
+      fields: fields.slice(i, i + 10).map((f) => ({ type: "mrkdwn", text: `*${f.label}*\n${f.value}`.slice(0, 2000) })),
+    });
+  }
+  if (decisions.length) {
+    const lines = decisions.slice(-10).map(decisionSummaryLine);
+    const more = decisions.length > 10 ? `\n_…and ${decisions.length - 10} earlier_` : "";
+    blocks.push({ type: "section", text: { type: "mrkdwn", text: `*Your decisions along the way*\n${lines.join("\n")}${more}`.slice(0, 3000) } });
+  }
+  const context = [elapsed ? `:stopwatch: Took ${elapsed}` : "", label ? `:computer: ${label}` : ""].filter(Boolean).join("  ·  ");
+  if (context) blocks.push({ type: "context", elements: [{ type: "mrkdwn", text: context }] });
+  return blocks;
+}
+
+/** A plain notification: the message, plus the session label when there is one. */
+export function messageBlocks({ headline, label }) {
+  return [{ type: "section", text: { type: "mrkdwn", text: fitSection(headline) } }, ...labelBlock(label)];
+}
+
+/**
+ * Whether the agent has actually been given the answer. An agent that stopped waiting gets it at its
+ * next check-in, which can be a while, so the message says which of the two is true rather than
+ * leaving the user to assume it landed.
+ */
+export function deliveryNote(decision) {
+  if (decision.status !== "answered" || !decision.sessionId) return "";
+  const who = decision.nickname ? `${decision.swatch ? `${decision.swatch} ` : ""}*${decision.nickname}*` : "the agent";
+  if (decision.deliveredAt) return `:inbox_tray: Delivered to ${who}.`;
+  return `:hourglass_flowing_sand: Saved for ${who} — it isn't waiting right now, so it gets this at its next check-in.`;
+}
+
+/** The same message once settled: the question stays, the choices give way to the outcome. */
+export function resolvedBlocks(decision, outcome) {
+  const { headline, details, label, draft, answer, baseBlocks } = decision;
+  const delivery = deliveryNote(decision);
+  const notes = [
+    { type: "context", elements: [{ type: "mrkdwn", text: outcome }] },
+    ...(delivery ? [{ type: "context", elements: [{ type: "mrkdwn", text: delivery }] }] : []),
+  ];
+  if (baseBlocks) return [...baseBlocks, ...notes];
+  // A draft stays visible once settled: the user's edited version if they changed it.
+  const finalDraft = draft ? (answer?.edited ? answer.text : draft) : "";
+  return [
+    { type: "section", text: { type: "mrkdwn", text: fitSection(headline) } },
+    ...(details ? [{ type: "section", text: { type: "mrkdwn", text: fitSection(stripTags(details)) } }] : []),
+    ...(finalDraft ? [draftBlock(finalDraft)] : []),
+    ...notes,
+    ...labelBlock(label),
+  ];
+}
+
+export function outcomeText(decision) {
+  const a = decision.answer ?? {};
+  const by = a.by ? ` by <@${a.by}>` : "";
+  const choices = decision.choices ?? [];
+  switch (decision.status) {
+    case "answered":
+      if (Array.isArray(a.indices)) {
+        const picked = a.indices.length ? boldList(choices, a.indices) : "*none of the options*";
+        return a.auto
+          ? `:hourglass: No answer in time, so I went with ${picked} (recommended).`
+          : `:white_check_mark: ${picked} (chosen${by})`;
+      }
+      if (a.auto) return `:hourglass: No answer in time, so I went with *${a.choice}* (recommended).`;
+      if (a.edited) return `:pencil2: Edited${by} and sent (the version above).`;
+      if (a.choice === null) {
+        const also = a.files?.length ? ` (with ${a.files.length === 1 ? "a file" : `${a.files.length} files`})` : "";
+        return a.text
+          ? `:speech_balloon: Answered${by}: “${a.text}”${also}`
+          : `:paperclip: Answered${by} with ${a.files?.length === 1 ? "a file" : "files"}.`;
+      }
+      return `:white_check_mark: *${a.choice}* (chosen${by})`;
+    case "expired":
+      return ":hourglass: Expired without an answer.";
+    case "cancelled":
+      return `:no_entry_sign: Closed: ${decision.reason || "no longer needed"}.`;
+    default:
+      return "";
+  }
+}