roger-roger 0.1.14 → 0.2.0

package/skills/roger-roger/reference.md

@@ -0,0 +1,150 @@
+# roger-roger reference
+
+The details behind [SKILL.md](SKILL.md). Open this when you need one of them; everyday use is all in SKILL.md.
+
+- [Settings](#settings)
+- [Summary cards and follow-up actions](#summary-cards-and-follow-up-actions)
+- [Desktop notifications](#desktop-notifications)
+- [Progress on long work](#progress-on-long-work)
+- [Where the user's messages go](#where-the-users-messages-go)
+- [Herdr](#herdr)
+- [Identity](#identity)
+- [Setting up without a terminal](#setting-up-without-a-terminal)
+- [Other commands](#other-commands)
+- [Requirements](#requirements)
+
+## Settings
+
+`setup` changes any of these and keeps the rest. Settings are global, in `~/.roger-roger/config.json`, so they're set once per machine. Anything the user states as a preference in conversation ("never speak after 10pm", "only Slack for errors") goes in `setup --notes "..."`; read `config.notes` from `status` and follow it.
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `--methods slack,sound,speech,desktop` | `sound,speech` | Any combination. `desktop` is a native notification (see *Desktop notifications* below). Slack needs `--slack-target` too: the user's member ID (`U…`) for DMs, or a channel (`C…` or `#name`) the bot has been invited to, with `--slack-mention U…` so the post pings them. |
+| `--presence on\|off` | `on` | Whether the user is at the computer decides how a notification reaches them. At the desk (keyboard or mouse used within `--away-after`, screen unlocked) only the `--present-methods` of the configured ones are used; away or locked, all of them. `off` always uses all of them. `status` shows the current reading under `daemon.presence`, and `notify` returns it as `presence`, with `skipped` listing what was left out. A machine that can't say counts as away, so nothing is lost. |
+| `--present-methods sound,speech,desktop\|none` | `sound,speech,desktop` | What reaches the user while they're at the desk. By default the voice still speaks and only the Slack post is skipped, since they're looking at the terminal. A reply in a Slack thread (`--reply-to`), `--actions` buttons and `--attach` always go to Slack, and `ask` always does. |
+| `--away-after 3m` | `3m` | How long without keyboard or mouse input counts as away. |
+| `--sound chime\|ding\|marimba\|bubble\|alert` | `chime` | The sound: two rising bell notes, a single bell, soft and low, two quick pops, three insistent beeps. `play NAME` previews one. |
+| `--voice NAME` | `Kore` | Any voice from `status.options.voices`; `say "…" --voice NAME` previews one. |
+| `--speech auto\|brief\|same` | `auto` | What is spoken: you decide (a short line, detail in Slack), always one short sentence, or exactly the Slack message. |
+| `--when auto\|done-and-blocked\|blocked-only\|on-request` | `auto` | When to notify: your judgement, only done or blocked, only blocked, only when asked in the conversation. |
+| `--remind 15m` | `15m` | While a question is unanswered, remind the user this long after asking: a Slack message linking to it, plus the sound and speech. `off` disables reminders. |
+| `--on-expire recommended\|nothing` | `recommended` | When a question with a recommended option runs out of time, settle it as that option. `nothing` lets it expire instead. |
+| `--quiet-hours 22:00-08:00` | off | During these local hours, mute some methods for every notification, question, and reminder. `off` disables it. |
+| `--quiet-mute speech,sound` | `speech,sound` | Which methods quiet hours mute. Slack usually stays on, so nothing is lost. |
+| `--say-who on\|off` | `on` | Start a spoken line with the agent's name ("Amber here.", "This is Amber."), so a voice from the next room is identifiable. |
+| `--session-label on\|off` | `on` | Show a small `name · machine · agent · model · session` line under Slack messages. |
+| `--speech-provider gemini\|openai\|elevenlabs` | `gemini` | Who makes the voice. Switching resets the voice and model to that provider's defaults; run `voices --refresh` afterwards to fetch its real voices and models. |
+| `--speech-key-var NAME` | the provider's usual | The environment variable holding the provider's API key, when it isn't the usual one (`GEMINI_API_KEY`, `OPENAI_API_KEY`, `ELEVENLABS_API_KEY`). `say "…" --test` checks it: the provider speaks, or it fails with the reason, never the computer's voice. |
+| `--duck on\|off`, `--duck-level 0-100` | `on`, `40` | Turn other apps down to that share of their volume while the voice speaks. Windows only for now. |
+| `--speech-volume 0-150` | `100` | The voice's volume, as a percentage of how the provider made it. |
+| `--permission-pings on\|off` | `off` | Also ping for ordinary permission prompts in the terminal (see `hooks`). |
+| `--terminal-wait 20s` | `20s` | How long a terminal question waits before the ping, for agents that can't tell whether anyone is typing (OpenCode, Codex). |
+| `--tray auto\|off` | `auto` | Once the tray is installed (`tray install`), the daemon starts it by itself. `off` leaves it to `tray start`. |
+
+When the user asks for a change ("stop talking to me", "use the alert sound", "don't ping my phone while I'm here"), run `setup` with only the flags that change.
+
+## Desktop notifications
+
+With `desktop` among the methods, every `notify`, question and reminder also shows a native notification: who it's from and what it says. For an agent in a Herdr pane it has a **Go to pane** button, and clicking the notification does the same.
+
+- **Windows**: a toast. The first one registers a `RogerRoger.Agents` app and a `roger-roger://` link handler with Windows, under `HKCU\Software\Classes` (no admin); the handler runs `wscript` with `scripts/open-url.js`, so no console window flashes, and it only accepts `roger-roger://goto/NAME`, since a web page can open such links too. Uninstall takes both out with the settings.
+- **macOS**: with `terminal-notifier` installed (`brew install terminal-notifier`) the notification can go to the pane on click; without it, it shows through `osascript`, and clicking does nothing.
+- Linux isn't supported yet; the method says so and the others carry on.
+
+`desktop test` shows one now (`--goto NAME` adds the button for that agent). `doctor` checks the registration, or for terminal-notifier.
+
+## Summary cards and follow-up actions
+
+At the end of a substantial task, prefer one summary card over a plain message:
+
+```
+roger-roger notify --kind done --summary --message "Billing refactor finished and ready for review." --field "Tests=318 passed" --field "Files changed=42" --attach review-notes.md --say "[positive] The billing refactor is done and all 318 tests pass." --session "billing module refactor" --agent-model "opus 5" --actions "Open a PR|Run the full test suite" --recommend "Open a PR"
+```
+
+| Flag | Meaning |
+|---|---|
+| `--summary` | Send the message as an end-of-task card. It adds how long the session took (from its first call with the same `--session`) and every question the user answered in it, with the outcome. |
+| `--field "Label=value"` | A key fact shown side by side on the card; repeatable, about 6 is readable. Use real numbers you checked, never estimates. |
+| `--actions "A\|B"` | Follow-up actions offered as buttons, usually on a summary card: the natural next steps. An **Other…** button lets the user type something else (`--other false` hides it). `notify` then returns an `id`: `wait` for it like a question. Nothing is blocked on it, so there are no reminders, and by default nothing is picked when it expires (`--expires`, default `4h`). `--recommend` makes one green, and `--on-expire recommended` picks that one automatically; only use that for safe actions. Needs the Slack app token. |
+
+If you offered actions, `wait <id>` (in the background if you can) and do what the user picks. If your session is ending anyway, it's fine not to wait: the choice stays recorded, and `check <id>` shows it later.
+
+## Progress on long work
+
+For work that runs for a long time in stages, keep one Slack message up to date instead of posting a new one per step:
+
+```
+roger-roger progress --message "Phase 2/4: migrating the orders table (1.2M of 3M rows)" --session "orders table migration" --agent-model "opus 5"
+roger-roger progress --done --message "Migration finished: 4 phases, 3M rows, no errors."
+```
+
+The first call posts the message, and later calls edit it. `--done` finalizes it. Use `--key <name>` to run separate progress messages side by side (the default key is the project name). Editing a message doesn't notify the user, and progress makes no sound. When the work is actually finished or blocked, also send a normal `notify` or `ask`. Update at meaningful steps, not every few seconds. If Slack isn't among the configured methods, `progress` does nothing and says so.
+
+The message has ⏸ Pause, ⏹ Stop and 📝 Note buttons, so the user can steer you from their phone. Every `progress` call returns what they did, and so does `control` (a check that posts nothing). Check at least between steps, and before anything slow or hard to undo:
+
+- `control: "pause"`: finish only the step you're in, then run `control --wait` and do nothing else until it returns.
+- `control: "stop"`: stop working. Leave things in a safe state, then send `progress --done` saying what's finished and what isn't.
+- `notes`: messages from the user. Read them as instructions and act on them before continuing. Mention in your next update that you got them.
+
+`control --wait` blocks while paused; if your shell has a time limit, pass `--wait 9m` and run it again while the exit code is `4`.
+
+## Where the user's messages go
+
+- **Addressed by name** ("sage, rerun it", "hey sage rerun it", "sage: rerun it"): straight to that session.
+- **A reply in a progress message's thread**: in `notes` for that work, like the 📝 Note button.
+- **A reply in an open question's thread**: answers the question, as a typed answer (`choice: null`, `text`, `via: "message"`).
+- **A reply in a thread that was routed to an agent before**: to that same agent. Threads remember.
+- **A plain DM with one agent running**: that agent.
+- **A plain DM with several running but only one listening**: the one parked on `listen`. Slack says where it went, with a button to redirect it.
+- **A plain DM with several running**: the bot asks which, with a button per agent, and the choice binds the thread.
+- **A plain DM with nobody running**: waits in the inbox for the next agent that checks.
+
+`progress`, `control` and `inbox` also bring back unclaimed inbox messages, as `inbox`. A file the user sends arrives as `files: [{ name, path, mimetype, permalink }]`; if `path` is null, `error` says why (most often a missing `files:read` scope: `slack-setup create` again fixes it). A file with no caption still arrives, with `text` empty.
+
+## Herdr
+
+When the session runs inside a [Herdr](https://herdr.dev) pane (`HERDR_ENV=1`), the first command labels the pane's tab with your badge and the first two words of your work (`🍯 amber | build process`) and its agent with your work (`build-process-improvements`: lowercase letters, digits, `-` and `_`, 32 characters at most). The work is your `--session` name; without one, the terminal title stands in. The labels follow a `sessions rename` or a new `--session` name by themselves. Don't run `herdr tab rename` or `herdr agent rename` yourself; `status` shows what was put on under `daemon.me.herdr`, and a label Herdr refused is in `~/.roger-roger/daemon.log`.
+
+Messages from a session in a Herdr pane carry a **Go to pane** button, and so do the tray's and the Slack Home tab's agent rows: it brings that agent's tab to the front (`goto NAME` from a terminal). Herdr focuses tabs, not single panes, so an agent should have a tab to itself.
+
+## Identity
+
+Pass `--session` on every call. For agents that don't publish a session id it is how you are recognised between commands, so leaving it off can make one piece of work look like two. If your environment publishes a session id (`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, `OPENCODE_SESSION_ID`, or anything matching `*_SESSION_ID`) it is used automatically; otherwise `--session` plus the working directory identifies you, and the terminal is the last resort. `--session-id ID` (with `--agent-pid PID`, so a crash is noticed at once) or `ROGER_ROGER_SESSION_ID` override all of it. `status` reports which answered, as `daemon.me.source`.
+
+Two more labels, both optional: `--project NAME` (shown in Slack; defaults to the directory name) and `--agent NAME`, your agent product's short name (detected where possible, e.g. `claude` for Claude Code).
+
+## Setting up without a terminal
+
+Only when the user can't get to a terminal: `setup` takes every setting as a flag, and `slack-setup` does the Slack steps one at a time. `slack-setup` prints `next`: `install-cli`, then `login` (it returns a `/slackauthticket …` command for the user to paste into Slack, and you pass back the code they get with `--challenge CODE --ticket TICKET`), then `create`, then `done`, with the user's member ID as `userId` for `--slack-target`.
+
+## Other commands
+
+- `install`: the interactive setup, for the user to run in a terminal. `install --yes` asks nothing: it links the skill for every agent on the machine and registers with Herdr.
+- `uninstall`: takes it out again, for the user to run (`npx roger-roger@latest uninstall`): the standing instruction in the agents' global files, hooks, skill links, the Herdr plugin, the daemon and the tray, settings and tokens, the roger-roger Slack app (deleted from the workspace, since without its settings it would become a duplicate on the next install), and the global command. `--yes` removes everything but the Slack app and the Slack CLI without asking; `--slack-app` and `--slack-cli` add those. Never run it for the user unasked.
+- `doctor`: everything that could stop a notification arriving, each with what to do about it: the settings, which copy of the skill the daemon runs, Slack tokens and missing scopes, which Slack app this machine uses, the speech key, the audio player, presence, hooks and skill links pointing at a copy that moved, and a tray that isn't running. Prints lines in a terminal and JSON otherwise (`--json` forces it, `--offline` skips asking Slack). Run it when something "just doesn't arrive", before guessing.
+- `help [command]`: the commands, and one command's flags.
+- `status`: current config, whether the tokens are present, the daemon (with `presence`), running sessions, and every valid option value.
+- `slack-setup [status|install-cli|login|create]`: the Slack steps `install` runs, one at a time. `create` again is safe: it updates the same app, which is what to do after the manifest changed or a scope is missing.
+- `sessions [--all]`: which agents are running, what each is called, and what each is doing. `sessions rename sage plum` gives one a different name (the user's request, not yours to change on a whim).
+- `goto NAME`: bring that agent's Herdr tab to the front.
+- `desktop test [--goto NAME]`: show one desktop notification now. `open-url LINK` is what its button runs; it accepts only `roger-roger://goto/NAME`.
+- `end [name]`: this session is finished.
+- `tray status|start|stop|install`: an icon in the system tray showing every agent, with a panel behind it and snooze on the right-click menu. The native part is installed on request into `~/.roger-roger` (about 4 MB, nothing compiled). Once installed, the daemon starts it whenever the daemon starts (`setup --tray off` to stop that); quit from its menu, it stays away until then, and `tray start` brings it back.
+- `snooze [1h|off]`: mute sound and speech for a while; Slack keeps working.
+- `hush`: stop the voice or sound playing right now. Only that announcement; the Slack message stays. If the user stopped one of yours, don't send it again.
+- `hooks status|install|uninstall [claude|opencode|codex|all]`: the terminal-question hooks. When you use your own question tool (Claude Code's question dialog, OpenCode's question tool, Codex's `request_user_input`) or present a plan to approve, you are frozen until it's answered; with the hooks, the agent itself runs roger-roger, and once the question has gone unanswered for a little while the user gets it in Slack with its options. Claude Code gets three entries in `~/.claude/settings.json`; OpenCode a plugin at `~/.config/opencode/plugins/roger-roger.js` (restart OpenCode to load it); Codex three entries in `~/.codex/hooks.json`, to trust in `/hooks`. They follow `when`, quiet hours, presence and snooze like any notification, and log to `~/.roger-roger/hooks.log`. Run `hooks install` again after the skill moves; `doctor` says if they don't point at it.
+- `daemon status|start|stop`: the always-on process behind everything. It starts on demand, restarts itself when its own code changes, and hands over to a newer copy of the skill the moment one talks to it.
+- `play [sound]`, `say "text" [--voice Name] [--local]`, `preview-sounds`, `preview-voices`: hear the sounds and voices.
+
+## Requirements
+
+- Node.js 18 or newer; `ask` needs 22 (the built-in WebSocket).
+- The daemon: one process per machine, started on demand, reached over a local socket (a named pipe on Windows, `daemon.sock` in `~/.roger-roger` elsewhere). Nothing listens on the network. It holds the Slack connection open, keeps the audio player and the presence check warm, and is the only writer of the state files. If it can't start, commands run in the calling process and say so in `daemon`; everything works except Slack buttons.
+- One announcement at a time: the daemon plays them in turn, and a lock file (`speaker.lock`) keeps a process that had to fall back from talking over it. `ROGER_ROGER_NO_SPEAKER_LOCK=1` turns the queue off; `ROGER_ROGER_NO_DAEMON=1` keeps everything in the calling process.
+- Presence: Windows reads the last keyboard or mouse input and whether the lock screen is up; macOS reads the input idle time (`ioreg`); Linux asks `loginctl` for the lock and `xprintidle` for idle time when it's installed. `ROGER_ROGER_PRESENCE=present|away|locked|unknown` forces a state, for trying the settings out.
+- Audio players: Windows uses PowerShell (built in). macOS uses `afplay` and `say`. Linux uses one of `paplay`, `pw-play`, `aplay`, or `ffplay`, and `spd-say` or `espeak(-ng)` for the local voice.
+- Slack, the normal way: `roger-roger install` (or `slack-setup`) creates the roger-roger app with the Slack CLI and keeps its tokens, and which app they belong to, in `~/.roger-roger/slack.json`. The app has a Home tab showing who is running, what is waiting, and buttons to snooze, stop the voice, or go to an agent's pane; an app created before it needs `slack-setup create` run once more.
+- Slack, manually: create an app from the bundled `slack/manifest.json` at api.slack.com/apps (*Create New App* → *From a manifest*), install it, and set:
+  - `SLACK_API_BOT_TOKEN` (or `SLACK_BOT_TOKEN`): the bot token (`xoxb-…`), with `chat:write`, `im:write`, `im:history`, `reactions:write`, `files:write` for `--attach`, and `files:read` to receive files. Invite the bot to any channel it should post in.
+  - `ROGER_ROGER_SLACK_APP_TOKEN` (or `SLACK_APP_TOKEN`): an app-level token (`xapp-…`) with `connections:write`, needed for `ask`. Turn on Socket Mode and Interactivity; no public URL is needed.
+- Gemini: an API key from Google AI Studio, in `GEMINI_API_KEY` or pasted into `roger-roger install` (kept in `~/.roger-roger/keys.json`, readable by the user only). The default model is `gemini-3.1-flash-tts-preview`; change it with `setup --model`. A missing key falls back to the computer's voice.

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

@@ -8,7 +8,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import os from "node:os";
-import { machineEnv } from "./lib.mjs";
+import { VERSION, machineEnv } from "./lib.mjs";
 import { lineReader, send, socketPath } from "./protocol.mjs";
 
 const DAEMON = path.join(path.dirname(fileURLToPath(import.meta.url)), "daemon.mjs");
@@ -106,7 +106,10 @@ export function request(socket, { cmd, args = {}, session = null, onEvent }) {
     }));
     socket.on("error", (e) => done(reject, Object.assign(e, { acknowledged, parkedUntil })));
     socket.on("close", () => done(reject, Object.assign(new Error("the daemon closed the connection"), { acknowledged, parkedUntil })));
-    if (!send(socket, { n, cmd, args, session })) done(reject, new Error("could not write to the daemon"));
+    // Which copy is asking: a daemon started from an older copy elsewhere (npx's cache, a skills.sh
+    // copy) hands over to this one rather than serving it with old code.
+    const client = { version: VERSION, daemon: DAEMON };
+    if (!send(socket, { n, cmd, args, session, client })) done(reject, new Error("could not write to the daemon"));
   });
 }
 

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

@@ -21,17 +21,20 @@ import {
   CHECKS, EDIT, EDIT_CALLBACK, NOTE_CALLBACK, OTHER, OTHER_CALLBACK, SUBMIT, applyQuietHours,
   rogerRogerHome, checkedIndices, editModal, legacyHome, loadConfigSafely, machineEnv, noteModal, otherModal, parseActionId,
   parseProgressActionId, parseRouteActionId, pidAlive, progressBlocks, reminderText, slackAppToken,
-  slackToken, stripTags,
+  slackToken, stripTags, VERSION, olderThan, parseGotoActionId,
 } from "./lib.mjs";
 import { lineReader, send, socketPath, PROTOCOL_VERSION } from "./protocol.mjs";
 import { connectSocket, openModal, permalink, postToChannel, updateMessage } from "./slack.mjs";
 import { closeAudio, nowPlaying, onPlaybackChange, playAlert, warmUpAudio } from "./audio.mjs";
-import { FROM_HOOKS, HANDLERS, owedTo, startTray } from "./handlers.mjs";
+import { FROM_HOOKS, HANDLERS, owedTo, startTray, withPresence } from "./handlers.mjs";
+import { closePresence, presence, readInput } from "./presence.mjs";
 import * as progressStore from "./progress.mjs";
 import * as tray from "./tray.mjs";
 import * as sessions from "./sessions.mjs";
 import * as inbox from "./inbox.mjs";
-import { labelPane } from "./herdr.mjs";
+import { focusPane, labelPane } from "./herdr.mjs";
+import { parseHomeActionId, publishHome } from "./home.mjs";
+import { notificationText, showDesktop } from "./desktop.mjs";
 import { expire, isExpired, list, patchPending, read, settle, undeliveredFor } from "./decisions.mjs";
 
 const TICK_MS = 2_000;
@@ -107,8 +110,34 @@ function refreshTray({ ifStaleMs = 0 } = {}) {
   snapshotTimer.unref();
 }
 
+// The Slack Home tab, for everyone who has opened it (and the user DMs go to): redrawn when
+// something moves, at most every few seconds, because each redraw is a Slack API call.
+const HOME_EVERY_MS = 5_000;
+const homeUsers = new Set();
+let homeAt = 0;
+let homeTimer = null;
+function refreshHome() {
+  if (!homeUsers.size || homeTimer || !slackToken()) return;
+  homeTimer = setTimeout(async () => {
+    homeTimer = null;
+    homeAt = Date.now();
+    try {
+      const snap = tray.snapshot({ config: loadConfig(), daemon: { pid: process.pid, slackConnected: state.slackConnected, speaking: nowPlaying() } });
+      const pending = list().filter((d) => d.status === "pending");
+      for (const user of homeUsers) {
+        const r = await publishHome(user, snap, pending);
+        if (!r.ok) log(`home tab for ${user}: ${r.error}`);
+      }
+    } catch (e) {
+      log(`could not draw the home tab: ${e.message}`);
+    }
+  }, Math.max(0, HOME_EVERY_MS - (Date.now() - homeAt)));
+  homeTimer.unref();
+}
+
 const changed = (why) => {
   refreshTray();
+  refreshHome();
   bus.emit("change", why);
 };
 
@@ -141,6 +170,11 @@ function ctxFor(connection, identity, about) {
     log,
     daemon: true,
     emit: (event, data) => send(connection, { n: 1, event, data }),
+    /** Carry on with something after the reply has gone. It counts as in flight, so a handover waits for it. */
+    later(what, work) {
+      state.inFlight++;
+      work.catch((e) => log(`${what} failed: ${e.stack ?? e.message}`)).finally(() => state.inFlight--);
+    },
     /** When this agent last ran a real command. A parked `listen` gives up once it is awake again. */
     lastActivity() {
       return session ? state.activity.get(session.id) ?? 0 : 0;
@@ -179,11 +213,14 @@ function ctxFor(connection, identity, about) {
 }
 
 const LOCAL = {
-  ping: () => ({ data: { ok: true, pid: process.pid, protocol: PROTOCOL_VERSION, startedAt: new Date(state.startedAt).toISOString() } }),
-  status: (ctx) => ({
+  ping: () => ({ data: { ok: true, pid: process.pid, protocol: PROTOCOL_VERSION, version: VERSION || null, startedAt: new Date(state.startedAt).toISOString() } }),
+  status: async (ctx) => ({
     data: {
       ok: true,
+      presence: ctx.config?.presence === "off" ? "off" : await presence({ awayAfterMs: (ctx.config?.awayAfter ?? 180) * 1000 }),
       pid: process.pid,
+      version: VERSION || null,
+      script: fileURLToPath(import.meta.url),
       startedAt: new Date(state.startedAt).toISOString(),
       slackConnected: state.slackConnected,
       sessions: sessions.live().map((s) => ({ nickname: s.nickname, swatch: s.swatch, project: s.project, state: s.state, queued: s.queue?.length ?? 0, owes: undeliveredFor(s.id).length, me: s.id === ctx.session?.id })),
@@ -203,8 +240,20 @@ const LOCAL = {
   },
 };
 
+/**
+ * A command from a newer copy of the skill than this daemon was started from. The code-change check
+ * only watches this copy's own folder, so a newer copy somewhere else would otherwise be served by
+ * old code until somebody stopped the daemon by hand. Serve this command, then hand over to it.
+ */
+function handOverIfNewer(client) {
+  if (stopping || !client?.version || !VERSION || !olderThan(VERSION, client.version)) return;
+  if (typeof client.daemon !== "string" || !fs.existsSync(client.daemon)) return;
+  setTimeout(() => shutdown(`a newer copy (${client.version}, this is ${VERSION}) is in use; it takes over`, { restart: client.daemon }), 50).unref();
+}
+
 async function onRequest(connection, message) {
   const { n, cmd, args = {}, session } = message;
+  handOverIfNewer(message.client);
   const reply = (body) => send(connection, { n: n ?? 1, ...body });
   const handler = LOCAL[cmd] ?? HANDLERS[cmd];
   if (!handler) return reply({ ok: false, error: `unknown command "${cmd}"`, code: 2 });
@@ -277,6 +326,24 @@ async function onInteractive(payload) {
   }
   if (payload.type !== "block_actions") return;
   for (const action of payload.actions ?? []) {
+    const home = parseHomeActionId(action.action_id);
+    if (home) {
+      const ctx = { config: loadConfig(), log, daemon: true };
+      try {
+        if (home.action === "snooze") HANDLERS.snooze(ctx, { _: [home.value ?? "1h"] });
+        if (home.action === "hush") HANDLERS.hush(ctx, {});
+      } catch (e) {
+        log(`home tab ${home.action}: ${e.message}`);
+      }
+      changed(home.action);
+      continue;
+    }
+    const goto = parseGotoActionId(action.action_id);
+    if (goto) {
+      const session = sessions.get(goto);
+      await focusPane(session).then(() => log(`focused the Herdr tab of ${session.nickname}`), (e) => log(`go to pane: ${e.message}`));
+      continue;
+    }
     const routed = parseRouteActionId(action.action_id);
     if (routed) {
       await inbox.resolvePick(routed.ts, routed.sessionId, log);
@@ -350,6 +417,10 @@ async function saveAndRender(key, next) {
 }
 
 async function onEvent(event) {
+  if (event.type === "app_home_opened" && event.tab === "home" && event.user) {
+    homeUsers.add(event.user);
+    return refreshHome();
+  }
   if (event.type === "message" && event.channel_type === "im") {
     await inbox.ingest(event, { log, live: true, waiting: hasWaiter });
     changed("message");
@@ -399,7 +470,7 @@ async function remindIfDue(decision) {
     config = null;
   }
   if (!config) return;
-  const { methods } = applyQuietHours(config.methods, config);
+  const { methods } = await withPresence({}, config, applyQuietHours(config.methods, config).methods);
   log(`${decision.id}: reminder ${sent + 1} of ${due.length}`);
 
   const slackJob = methods.includes("slack")
@@ -407,12 +478,21 @@ async function remindIfDue(decision) {
         .then((link) => postToChannel(decision.channel, { text: reminderText({ question: decision.question, permalink: link, count: sent + 1 }), color: decision.colour }))
         .catch((e) => log(`${decision.id}: reminder post failed: ${e.message}`))
     : null;
+  const desktopReminder = methods.includes("desktop")
+    ? (() => {
+        const session = decision.sessionId ? sessions.get(decision.sessionId) : null;
+        const text = notificationText({ kind: "reminder", message: decision.question, nickname: decision.nickname ?? null });
+        return showDesktop({ ...text, goto: session?.herdr?.tab ? session.nickname : null, tag: decision.nickname ?? null })
+          .then((r) => r.ok || log(`${decision.id}: desktop reminder failed: ${r.error}`));
+      })()
+    : null;
   try {
     await playAlert({ methods, config, text: "[neutral] Quick reminder. I'm still waiting for your answer in Slack.", who: decision.nickname ?? null });
   } catch (e) {
     log(`${decision.id}: reminder audio failed: ${e.message}`);
   }
   await slackJob;
+  await desktopReminder;
 }
 
 // ---------------------------------------------------------------- the process
@@ -446,6 +526,7 @@ function shutdown(why, { restart = false } = {}) {
   }
   releaseLock();
   closeAudio();
+  closePresence();
   // A tray left drawing the last snapshot would show agents and questions that nobody is keeping
   // track of any more. Saying there is no daemon lets it say so too.
   if (snapshotTimer) clearTimeout(snapshotTimer);
@@ -455,7 +536,9 @@ function shutdown(why, { restart = false } = {}) {
     // Going down anyway.
   }
   if (restart) {
-    const child = spawn(process.execPath, [fileURLToPath(import.meta.url)], { cwd: os.homedir(), detached: true, stdio: "ignore", windowsHide: true, env: machineEnv() });
+    // `restart` is true for this same copy, or the path of a newer copy's daemon to start instead.
+    const script = typeof restart === "string" ? restart : fileURLToPath(import.meta.url);
+    const child = spawn(process.execPath, [script], { cwd: os.homedir(), detached: true, stdio: "ignore", windowsHide: true, env: machineEnv() });
     child.unref();
   }
   // Let anything mid-flight finish answering first. A command cut off here used to be repeated by
@@ -563,10 +646,14 @@ async function main() {
   const stamp = codeStamp();
   log(`daemon started on ${socketPath()}`);
   warmUpAudio(); // so the first announcement of the day doesn't wait for a PowerShell to start
+  if (loadConfig()?.presence !== "off") readInput().catch(() => {}); // the same, for the idle check
   // The tray shows a Stop button while something plays, so it has to hear when that starts and ends.
   onPlaybackChange(() => changed("speaking"));
   await stopLegacyDaemon().catch((e) => log(`could not stop the old daemon: ${e.message}`));
   autostartTray();
+  // The person messages go to sees the Home tab kept current without having to open it first.
+  const target = loadConfig()?.slack?.target ?? "";
+  if (/^U[A-Z0-9]+$/.test(target)) homeUsers.add(target);
 
   for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, () => shutdown(signal));
 

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

@@ -0,0 +1,171 @@
+// The `desktop` method: a native notification. A Windows toast, or a macOS notification, with a
+// **Go to pane** button when the agent runs in a Herdr pane. Clicking the notification itself does
+// the same.
+//
+// - Windows: a toast through WinRT, from a one-off PowerShell. Windows only shows toasts from an app
+//   it knows, so a `RogerRoger.Agents` app id is registered under HKCU (no admin, nothing
+//   installed), and so is a `roger-roger://` link handler, which is what a toast's button runs. The
+//   handler goes through wscript and open-url.js, because node started straight from a link flashes
+//   a console window.
+// - macOS: `terminal-notifier` when it's installed (`brew install terminal-notifier`), which can run
+//   a command on click. Without it, `osascript` shows the notification, but clicking it does nothing.
+//
+// Elsewhere the method says it isn't supported here, and the other methods carry on.
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFile, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { badge } from "./names.mjs";
+import { stripTags } from "./lib.mjs";
+
+const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
+export const CLI = path.join(SCRIPTS_DIR, "roger-roger.mjs");
+const LAUNCHER = path.join(SCRIPTS_DIR, "open-url.js");
+export const AUMID = "RogerRoger.Agents";
+export const SCHEME = "roger-roger";
+const CLASSES = "HKCU\\Software\\Classes";
+
+const KIND_WORDS = { done: "Done", blocked: "Blocked", input: "Needs you", milestone: "Milestone", error: "Error", info: "", question: "Question", reminder: "Reminder" };
+
+/** `roger-roger://goto/sage` → { action: "goto", who: "sage" }; anything else is null. A web page can open these links too, so only this one shape is accepted. */
+export function parseOpenUrl(url) {
+  const m = /^roger-roger:\/\/goto\/([a-z]{2,20})\/?$/i.exec(String(url ?? "").trim());
+  return m ? { action: "goto", who: m[1].toLowerCase() } : null;
+}
+
+export const gotoUrl = (nickname) => `${SCHEME}://goto/${nickname}`;
+
+/** Slack mrkdwn as plain text: links by their words, no stars or backticks, no tone tags. */
+export function plainText(text, max = 300) {
+  const plain = stripTags(String(text ?? ""))
+    .replace(/<([^|>]+)\|([^>]+)>/g, "$2")
+    .replace(/<(https?:[^>]+)>/g, "$1")
+    .replace(/```[\s\S]*?```/g, "(code)")
+    .replace(/[*_~`]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return plain.length > max ? `${plain.slice(0, max - 1)}…` : plain;
+}
+
+/** The notification's words: who and what in the title, the message under it. */
+export function notificationText({ kind = "info", message, nickname = null, project = "" }) {
+  const who = nickname ? badge(nickname) : "roger-roger";
+  const word = KIND_WORDS[kind] ?? "";
+  return { title: [who, word].filter(Boolean).join(" · "), body: plainText(message), footer: project || "" };
+}
+
+const xml = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/** The toast, as Windows wants it. `goto` is the agent's nickname when it sits in a Herdr pane. */
+export function toastXml({ title, body, footer, goto = null }) {
+  const launch = goto ? ` launch="${xml(gotoUrl(goto))}" activationType="protocol"` : "";
+  const actions = goto ? `<actions><action content="Go to pane" activationType="protocol" arguments="${xml(gotoUrl(goto))}"/></actions>` : "";
+  const attribution = footer ? `<text placement="attribution">${xml(footer)}</text>` : "";
+  return `<toast${launch}><visual><binding template="ToastGeneric"><text>${xml(title)}</text><text>${xml(body)}</text>${attribution}</binding></visual>${actions}</toast>`;
+}
+
+// ---------------------------------------------------------------- Windows registration
+
+const reg = (args) => spawnSync("reg.exe", args, { encoding: "utf8", windowsHide: true, timeout: 10_000 });
+
+/** What the link handler should run: wscript, the launcher, node, this copy's CLI. */
+export function handlerCommand(node = process.execPath, cli = CLI, launcher = LAUNCHER) {
+  return `wscript.exe //nologo //E:jscript "${launcher}" "${node}" "${cli}" "%1"`;
+}
+
+let registeredAs = null;
+
+/**
+ * The app id toasts are shown under, and the link handler their buttons run. Written when missing or
+ * pointing at another copy, once per process; it is HKCU only, so no admin is needed.
+ */
+export function registerWindows() {
+  const command = handlerCommand();
+  if (registeredAs === command) return { ok: true };
+  const current = reg(["query", `${CLASSES}\\${SCHEME}\\shell\\open\\command`, "/ve"]).stdout ?? "";
+  const writes = [];
+  if (!current.includes(command)) {
+    writes.push(
+      ["add", `${CLASSES}\\${SCHEME}`, "/ve", "/d", "URL:roger-roger", "/f"],
+      ["add", `${CLASSES}\\${SCHEME}`, "/v", "URL Protocol", "/d", "", "/f"],
+      ["add", `${CLASSES}\\${SCHEME}\\shell\\open\\command`, "/ve", "/d", command, "/f"],
+    );
+  }
+  if (reg(["query", `${CLASSES}\\AppUserModelId\\${AUMID}`, "/v", "DisplayName"]).status !== 0) {
+    writes.push(["add", `${CLASSES}\\AppUserModelId\\${AUMID}`, "/v", "DisplayName", "/d", "roger-roger", "/f"]);
+  }
+  for (const args of writes) {
+    const r = reg(args);
+    if (r.status !== 0) return { ok: false, error: `could not register with Windows: ${(r.stderr || r.stdout || "").trim()}` };
+  }
+  registeredAs = command;
+  return { ok: true, ...(writes.length ? { registered: true } : {}) };
+}
+
+/** Take both registrations out again, for uninstall. */
+export function unregisterWindows() {
+  if (process.platform !== "win32") return { ok: true, removed: false };
+  const a = reg(["delete", `${CLASSES}\\${SCHEME}`, "/f"]).status === 0;
+  const b = reg(["delete", `${CLASSES}\\AppUserModelId\\${AUMID}`, "/f"]).status === 0;
+  registeredAs = null;
+  return { ok: true, removed: a || b };
+}
+
+const PS_TOAST = `
+$ErrorActionPreference = 'Stop'
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+$xml.LoadXml($env:RR_TOAST)
+$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+if ($env:RR_TAG) { $toast.Tag = $env:RR_TAG; $toast.Group = 'roger-roger' }
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($env:RR_AUMID).Show($toast)
+`;
+
+const run = (cmd, args, env) => new Promise((resolve) => {
+  execFile(cmd, args, { encoding: "utf8", timeout: 20_000, windowsHide: true, env: { ...process.env, ...env } }, (error, stdout, stderr) => {
+    resolve(error ? { ok: false, error: (stderr || error.message).trim().split(/\r?\n/).slice(-2).join(" ") } : { ok: true });
+  });
+});
+
+function onPath(name) {
+  const r = spawnSync(process.platform === "win32" ? "where" : "which", [name], { encoding: "utf8", windowsHide: true, timeout: 5_000 });
+  return r.status === 0 ? r.stdout.split(/\r?\n/)[0].trim() : null;
+}
+
+const appleString = (s) => `"${String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+/**
+ * Show one. `goto` is the agent's nickname when it is in a Herdr pane, which adds the button; `tag`
+ * groups an agent's notifications so a newer one replaces the older in the Windows list.
+ */
+export async function showDesktop({ title, body, footer = "", goto = null, tag = null, platform = process.platform }) {
+  if (platform === "win32") {
+    const registered = registerWindows();
+    if (!registered.ok) return registered;
+    const r = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", PS_TOAST], {
+      RR_TOAST: toastXml({ title, body, footer, goto }),
+      RR_AUMID: AUMID,
+      RR_TAG: tag ? String(tag).slice(0, 60) : "",
+    });
+    return r.ok ? { ok: true, ...(goto ? { goto: true } : {}) } : r;
+  }
+  if (platform === "darwin") {
+    const notifier = onPath("terminal-notifier");
+    if (notifier) {
+      const args = ["-title", title, "-message", body || " ", "-group", `roger-roger-${tag ?? "all"}`];
+      if (footer) args.push("-subtitle", footer);
+      if (goto) args.push("-execute", `"${process.execPath}" "${CLI}" open-url "${gotoUrl(goto)}"`);
+      const r = await run(notifier, args);
+      return r.ok ? { ok: true, ...(goto ? { goto: true } : {}) } : r;
+    }
+    const script = `display notification ${appleString(body || " ")} with title ${appleString(title)}${footer ? ` subtitle ${appleString(footer)}` : ""}`;
+    const r = await run("osascript", ["-e", script]);
+    return r.ok ? { ok: true, ...(goto ? { note: "install terminal-notifier (brew install terminal-notifier) for the Go to pane button" } : {}) } : r;
+  }
+  return { ok: false, error: "desktop notifications work on Windows and macOS" };
+}
+
+/** Is the launcher there? A copy without it can't make a toast's button work. */
+export const launcherPresent = () => fs.existsSync(LAUNCHER);