roger-roger 0.1.14 → 0.2.0

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

@@ -0,0 +1,241 @@
+// `roger-roger doctor`: everything that can quietly stop a notification from arriving, checked in
+// one go, each with the one thing to do about it. `status` says what is set; this says what is wrong.
+//
+// It reads, and never changes anything. The checks that need the network (are the Slack tokens still
+// good, does the bot have every scope) are skipped with --offline.
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+import { SKILL_DIR, VERSION, configPath, loadConfig, olderThan, pidAlive, rogerRogerHome, readSlackCredentials, slackAppToken, slackToken } from "./lib.mjs";
+import { keyFor, providerOf } from "./tts.mjs";
+import { apiBase } from "./slack.mjs";
+import { MANIFEST_PATH, appUrl, currentApp } from "./slackapp.mjs";
+import { trayInstalled, trayProcesses } from "./handlers.mjs";
+import { presence } from "./presence.mjs";
+import { handlerCommand } from "./desktop.mjs";
+import { skillFootprint } from "./install.mjs";
+
+const real = (p) => {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+};
+const same = (a, b) => {
+  const [x, y] = [real(a), real(b)];
+  return process.platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+};
+
+/** `{ name, level: "ok"|"warn"|"fail"|"info", detail, fix? }` */
+const check = (name, level, detail, fix) => ({ name, level, detail, ...(fix ? { fix } : {}) });
+
+/**
+ * Every copy of the package that a `roger-roger` on the PATH leads to, by real path, so one copy
+ * reached through two links (nvm's `Program Files\nodejs`, say) counts once.
+ */
+export function copiesOnPath(env = process.env) {
+  const seen = new Map();
+  for (const dir of String(env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean)) {
+    for (const pkg of [path.join(dir, "node_modules", "roger-roger"), path.join(dir, "..", "lib", "node_modules", "roger-roger")]) {
+      try {
+        const version = JSON.parse(fs.readFileSync(path.join(pkg, "package.json"), "utf8")).version ?? "";
+        const key = real(pkg).toLowerCase();
+        if (!seen.has(key)) seen.set(key, { dir: real(pkg), version });
+      } catch {}
+    }
+  }
+  return [...seen.values()];
+}
+
+/** The bot's scopes, from the header Slack puts on every Web API answer. */
+async function botScopes(token) {
+  const res = await fetch(`${apiBase()}/auth.test`, { method: "POST", headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(15_000) });
+  const body = await res.json();
+  return { ok: Boolean(body.ok), error: body.error, team: body.team, scopes: (res.headers.get("x-oauth-scopes") ?? "").split(",").map((s) => s.trim()).filter(Boolean) };
+}
+
+async function appTokenWorks(token) {
+  const res = await fetch(`${apiBase()}/apps.connections.open`, { method: "POST", headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(15_000) });
+  const body = await res.json();
+  return { ok: Boolean(body.ok), error: body.error };
+}
+
+function hasCommand(name) {
+  try {
+    execFileSync(process.platform === "win32" ? "where" : "which", [name], { stdio: "ignore", windowsHide: true, timeout: 5_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run every check. `daemon` is what the running daemon said about itself (or null), `agents` the
+ * hook installers keyed by agent, `script` this copy's CLI.
+ */
+export async function runDoctor({ daemon = null, agents = {}, script = "", offline = false, env = process.env } = {}) {
+  const checks = [];
+
+  // ---- settings
+  let config = null;
+  try {
+    config = loadConfig();
+    checks.push(config
+      ? check("settings", "ok", configPath())
+      : check("settings", "fail", "not set up yet", "run `npx roger-roger@latest install` in a terminal"));
+  } catch (e) {
+    checks.push(check("settings", "fail", `${configPath()} can't be read: ${e.message}`, "fix the file by hand, or run `roger-roger install` to write it again"));
+  }
+  const methods = config?.methods ?? [];
+
+  // ---- this copy, the others, and the daemon
+  const copies = copiesOnPath(env);
+  const here = path.join(SKILL_DIR, "..", "..");
+  checks.push(check("this copy", "info", `${VERSION || "unversioned"} at ${real(SKILL_DIR)}`));
+  if (copies.length > 1) {
+    checks.push(check("copies on the PATH", "warn", copies.map((c) => `${c.version} at ${c.dir}`).join("; "), "keep one: `npm uninstall -g roger-roger` with the Node that installed each extra"));
+  }
+  const newest = copies.reduce((best, c) => (!best || olderThan(best.version, c.version) ? c : best), null);
+  if (newest && VERSION && olderThan(VERSION, newest.version) && !same(here, newest.dir)) {
+    checks.push(check("copy in use", "warn", `this is ${VERSION}, but ${newest.version} is installed at ${newest.dir}`, "run the `roger-roger` command rather than this copy, or update this one"));
+  }
+  if (!daemon) {
+    checks.push(check("daemon", "info", "not running; the next command starts it"));
+  } else {
+    const where = daemon.script ? path.dirname(daemon.script) : null;
+    const detail = `pid ${daemon.pid}${daemon.version ? `, ${daemon.version}` : ""}${where ? ` from ${real(where)}` : ""}`;
+    if (!daemon.version) checks.push(check("daemon", "warn", `${detail}, from a copy too old to say its version`, "`roger-roger daemon stop`; the next command starts a current one"));
+    else if (VERSION && olderThan(daemon.version, VERSION)) checks.push(check("daemon", "warn", `${detail}, older than this copy (${VERSION})`, "it hands over by itself at the next command; `roger-roger daemon stop` makes it now"));
+    else checks.push(check("daemon", "ok", detail));
+    if (methods.includes("slack") && daemon.slackConnected === false && slackAppToken()) {
+      checks.push(check("slack connection", "warn", "the daemon isn't connected to Slack, so buttons and messages won't arrive", "see ~/.roger-roger/daemon.log for why"));
+    }
+  }
+
+  // ---- Slack
+  if (methods.includes("slack")) {
+    if (!config.slack?.target) checks.push(check("slack target", "fail", "Slack is on, but nowhere to post", "`roger-roger setup --slack-target U…` (your member ID) or a channel"));
+    const token = slackToken();
+    if (!token) {
+      checks.push(check("slack bot token", "fail", "missing", "run `roger-roger install` to connect Slack"));
+    } else if (!offline) {
+      try {
+        const bot = await botScopes(token);
+        if (!bot.ok) {
+          checks.push(check("slack bot token", "fail", `Slack refused it (${bot.error})`, "`roger-roger slack-setup create` installs the app again and saves fresh tokens"));
+        } else {
+          checks.push(check("slack bot token", "ok", `works, in ${bot.team}`));
+          const wanted = JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8")).oauth_config?.scopes?.bot ?? [];
+          const missing = bot.scopes.length ? wanted.filter((s) => !bot.scopes.includes(s)) : [];
+          if (missing.length) checks.push(check("slack scopes", "warn", `the app lacks ${missing.join(", ")}`, "`roger-roger slack-setup create` updates the same app with the current manifest"));
+        }
+      } catch (e) {
+        checks.push(check("slack bot token", "warn", `could not reach Slack: ${e.message}`));
+      }
+      const appToken = slackAppToken();
+      if (!appToken) {
+        checks.push(check("slack app token", "warn", "missing, so questions with buttons won't work", "`roger-roger slack-setup create`"));
+      } else {
+        const r = await appTokenWorks(appToken).catch((e) => ({ ok: false, error: e.message }));
+        checks.push(r.ok ? check("slack app token", "ok", "works") : check("slack app token", "fail", `Slack refused it (${r.error})`, "`roger-roger slack-setup create`"));
+      }
+    }
+    const app = currentApp();
+    if (app?.appId) {
+      checks.push(check("slack app", "info", `this machine uses ${app.appId} (${appUrl(app.appId)}). Any other roger-roger app on https://api.slack.com/apps is left over from an earlier install and can be deleted there`));
+    } else if (readSlackCredentials()?.source === "slack-cli") {
+      checks.push(check("slack app", "warn", "the tokens are here, but not which app they belong to, so `slack-setup create` would make a second app", "find the app whose tokens these are on https://api.slack.com/apps; delete any others"));
+    }
+  }
+
+  // ---- speech and sound
+  if (methods.includes("speech")) {
+    const key = keyFor(config);
+    checks.push(key.value
+      ? check("speech key", "ok", `${providerOf(config).label} key in ${key.name}`)
+      : check("speech key", "warn", `no ${providerOf(config).label} key (${key.name}); the computer's own voice speaks instead`, "paste one into `roger-roger install`, or set the variable"));
+  }
+  if (methods.includes("sound") || methods.includes("speech")) {
+    if (process.platform === "darwin") {
+      if (!hasCommand("afplay")) checks.push(check("audio player", "fail", "afplay is missing"));
+    } else if (process.platform !== "win32") {
+      const players = ["paplay", "pw-play", "aplay", "ffplay"].filter(hasCommand);
+      checks.push(players.length ? check("audio player", "ok", players[0]) : check("audio player", "fail", "none of paplay, pw-play, aplay, ffplay", "install pulseaudio-utils or alsa-utils"));
+    }
+  }
+
+  // ---- desktop notifications
+  if (methods.includes("desktop")) {
+    if (process.platform === "win32") {
+      const r = spawnSync("reg.exe", ["query", "HKCU\\Software\\Classes\\roger-roger\\shell\\open\\command", "/ve"], { encoding: "utf8", windowsHide: true, timeout: 5_000 });
+      const handler = r.status === 0 ? r.stdout : "";
+      if (!handler) checks.push(check("desktop", "info", "not registered with Windows yet; the first notification does it"));
+      else if (!handler.includes(handlerCommand())) checks.push(check("desktop", "info", "the Go to pane button runs another copy of the skill; the next notification from this one points it here"));
+      else checks.push(check("desktop", "ok", "Windows notifications, with Go to pane"));
+    } else if (process.platform === "darwin") {
+      checks.push(hasCommand("terminal-notifier")
+        ? check("desktop", "ok", "macOS notifications, with Go to pane (terminal-notifier)")
+        : check("desktop", "warn", "notifications show, but clicking one can't go to the agent's pane", "`brew install terminal-notifier`"));
+    } else {
+      checks.push(check("desktop", "warn", "desktop notifications work on Windows and macOS only", "`roger-roger setup --methods` without desktop"));
+    }
+  }
+
+  // ---- where the user is
+  if (config && config.presence !== "off") {
+    const where = await presence({ awayAfterMs: (config.awayAfter ?? 180) * 1000 });
+    checks.push(where.state === "unknown"
+      ? check("presence", "info", "this machine doesn't say whether you are at it, so every configured method is used")
+      : check("presence", "ok", `${where.state}${where.idleSeconds !== null ? `, idle ${where.idleSeconds}s` : ""}; at the desk you get ${(config.presentMethods ?? []).join(", ") || "nothing"}`));
+  }
+
+  // ---- hooks and skill links pointing elsewhere
+  for (const [name, agent] of Object.entries(agents)) {
+    let s;
+    try {
+      s = agent.status({ script });
+    } catch {
+      continue;
+    }
+    if (!s.installed && !s.partial) continue;
+    if (s.scriptExists === false) checks.push(check(`${name} hooks`, "fail", `they run ${s.script}, which is gone`, `\`roger-roger hooks install ${name}\``));
+    else if (s.partial) checks.push(check(`${name} hooks`, "warn", "only some are installed", `\`roger-roger hooks install ${name}\``));
+    else if (s.note) checks.push(check(`${name} hooks`, "warn", s.note, `\`roger-roger hooks install ${name}\``));
+    else checks.push(check(`${name} hooks`, "ok", "installed"));
+  }
+  for (const link of skillFootprint()) {
+    try {
+      if (!fs.existsSync(path.join(link.link, "SKILL.md"))) checks.push(check(`${link.label} skill`, "fail", `${link.link} leads nowhere`, "`roger-roger install` links it again"));
+    } catch {}
+  }
+
+  // ---- the tray
+  if (trayInstalled() && config?.tray !== "off") {
+    // Any copy's tray counts. The process list only finds this copy's, so its pid file is asked too.
+    const running = await trayProcesses().catch(() => []);
+    try {
+      const raw = fs.readFileSync(path.join(rogerRogerHome(), "tray.pid"), "utf8").trim();
+      const pid = Number(raw.startsWith("{") ? JSON.parse(raw).pid : raw);
+      if (pidAlive(pid) && !running.includes(pid)) running.push(pid);
+    } catch {}
+    checks.push(running.length
+      ? check("tray", "ok", `running (pid ${running.join(", ")})`)
+      : check("tray", "warn", "installed but not running (quit from its menu, it stays away until the daemon next starts)", "`roger-roger tray start`"));
+  }
+
+  const worst = checks.some((c) => c.level === "fail") ? "fail" : checks.some((c) => c.level === "warn") ? "warn" : "ok";
+  return { ok: worst !== "fail", worst, checks };
+}
+
+/** The checks as lines for a person, with the fix under each one that needs it. */
+export function formatDoctor({ checks }, style = { green: (s) => s, yellow: (s) => s, red: (s) => s, dim: (s) => s, bold: (s) => s }) {
+  const mark = { ok: style.green("✔"), warn: style.yellow("!"), fail: style.red("✖"), info: style.dim("·") };
+  const lines = [];
+  for (const c of checks) {
+    lines.push(`${mark[c.level]} ${style.bold(c.name)}  ${c.detail}`);
+    if (c.fix) lines.push(`    ${style.dim("→")} ${c.fix}`);
+  }
+  return lines.join("\n") + "\n";
+}

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

@@ -16,7 +16,7 @@ import {
   announceAs, applySetup, applyQuietHours, rogerRogerHome, machineEnv, pidAlive, decisionBlocks, formatElapsed, listArg, listSounds, saveConfig,
   messageBlocks, parseChoices, parseDuration, parseFields, parseRecommend, parseRecommendMany,
   parseRemind, previewList, progressBlocks, sessionLabel, slackAppToken, slackText, slackToken,
-  soundAnnouncement, speechText, splitList, stripTags, summaryBlocks, voiceSample,
+  soundAnnouncement, speechText, splitList, stripTags, summaryBlocks, voiceSample, withGotoButton,
 } from "./lib.mjs";
 import {
   deliverSpeech, mapPool, playAlert, playWav, playWavBuffer, prepareSpeech, soundFile,
@@ -30,7 +30,9 @@ import * as sessions from "./sessions.mjs";
 import * as inbox from "./inbox.mjs";
 import * as decisions from "./decisions.mjs";
 import * as activity from "./activity.mjs";
-import { labelPane } from "./herdr.mjs";
+import { focusPane, labelPane } from "./herdr.mjs";
+import { methodsForPresence, presence } from "./presence.mjs";
+import { notificationText, showDesktop } from "./desktop.mjs";
 import { answeredNotice, isQuestion, matchRequest, permissionNotice, rememberRequest } from "./hooks.mjs";
 
 export const EXIT_NOT_CONFIGURED = 3;
@@ -96,6 +98,21 @@ function methodsFor(args, config) {
   return applyQuietHours(wanted, config);
 }
 
+/**
+ * Where the user is, and what that leaves of `methods`. `--only` is the agent saying exactly how,
+ * so it is left alone; so is everything when presence is off. `keep` are methods this call can't do
+ * without, such as Slack for a reply in a Slack thread.
+ */
+export async function withPresence(args, config, methods, keep = []) {
+  if (config.presence === "off" || splitList(args.only).length) return { methods, presence: null };
+  const where = await presence({ awayAfterMs: (config.awayAfter ?? DEFAULTS.awayAfter) * 1000 });
+  const { methods: left, skipped } = methodsForPresence(methods, where.state, {
+    presentMethods: config.presentMethods ?? DEFAULTS.presentMethods,
+    keep,
+  });
+  return { methods: left, presence: { ...where, ...(skipped.length ? { skipped } : {}) } };
+}
+
 function attachments(args) {
   const files = listArg(args.attach);
   for (const f of files) {
@@ -112,6 +129,31 @@ function draftOf(args) {
   return draft.trim() ? draft : "";
 }
 
+/**
+ * The sound and the voice. The daemon plays them after it has answered, so the agent isn't held for
+ * the synthesis and the whole announcement; it gets `{ playing: true }` per method instead. Without
+ * a daemon the command has to stay for them, because ending the process would cut them off.
+ */
+async function announce(ctx, opts) {
+  const audible = opts.methods.filter((m) => m === "sound" || m === "speech");
+  if (!audible.length) return {};
+  if (!ctx.later) return playAlert(opts);
+  ctx.later("announcement", playAlert(opts));
+  return Object.fromEntries(audible.map((m) => [m, { ok: true, playing: true }]));
+}
+
+/**
+ * The native notification, when `desktop` is among the methods. It carries a Go to pane button when
+ * the agent sits in a Herdr pane. A failure is reported, never thrown: the other methods still count.
+ */
+function desktopJob(ctx, methods, { kind, message, project }) {
+  if (!methods.includes("desktop")) return null;
+  const session = ctx.session;
+  const text = notificationText({ kind, message, nickname: session?.nickname ?? null, project });
+  return showDesktop({ ...text, goto: session?.herdr?.tab ? session.nickname : null, tag: session?.nickname ?? null })
+    .catch((e) => ({ ok: false, error: e.message }));
+}
+
 /** Note what the agent is doing, so the picker can say "waiting on you" next to its name. */
 function setState(ctx, state) {
   if (ctx.session) sessions.touch(ctx.session.id, { state });
@@ -128,7 +170,11 @@ export async function notify(ctx, args) {
   const fields = parseFields(listArg(args.field));
   const replyTo = typeof args["reply-to"] === "string" ? args["reply-to"].trim() : "";
   const files = attachments(args);
-  const { methods, muted } = methodsFor(args, config);
+  const quiet = methodsFor(args, config);
+  const muted = quiet.muted;
+  // A reply to something said in Slack, buttons and files only make sense in Slack, wherever the user is.
+  const needsSlack = Boolean(replyTo || args.actions !== undefined || files.length);
+  const { methods, presence: where } = await withPresence(args, config, quiet.methods, needsSlack ? ["slack"] : []);
   const followUp = followUpActions(args, config, methods);
   const text = spoken(ctx, config, args, message);
   const results = {};
@@ -147,6 +193,7 @@ export async function notify(ctx, args) {
     const elapsed = args.summary && ctx.session ? formatElapsed(Date.now() - Date.parse(ctx.session.firstSeen)) : "";
     blocks = summaryBlocks({ headline, fields, elapsed, decisions: answered, label });
   }
+  if (ctx.session?.herdr?.tab) blocks = withGotoButton(blocks, ctx.session.id);
 
   // Slack posts while the speech is synthesized; the sound waits for the speech.
   if (methods.includes("sound") || methods.includes("speech")) warmUpAudio();
@@ -180,9 +227,12 @@ export async function notify(ctx, args) {
       })().catch((e) => (results.slack = { ok: Boolean(results.slack?.ok), error: e.message }))
     : null;
 
-  Object.assign(results, await playAlert({ methods, config, text, prepared, who: ctx.session?.nickname }));
+  const desktop = desktopJob(ctx, methods, { kind, message, project: args.project });
+  Object.assign(results, await announce(ctx, { methods, config, text, prepared, who: ctx.session?.nickname }));
   await slackJob;
-  const succeeded = Object.values(results).some((r) => r.ok);
+  if (desktop) results.desktop = await desktop;
+  // Nothing left to do because the user is at the desk and wants nothing there is a success too.
+  const succeeded = Object.values(results).some((r) => r.ok) || (!methods.length && Boolean(where?.skipped?.length));
   if (succeeded) activity.record({ from: "agent", kind, agent: activity.agentOf(ctx.session), text: message });
   const body = {
     ok: succeeded,
@@ -190,6 +240,7 @@ export async function notify(ctx, args) {
     results,
     ...(followUpId ? { id: followUpId, status: "pending", next: `wait ${followUpId}` } : {}),
     ...(muted.length ? { mutedByQuietHours: muted } : {}),
+    ...(where ? { presence: where } : {}),
     ...(files.length && !methods.includes("slack") ? { note: "--attach needs slack" } : {}),
   };
   // Park in the same breath as replying. Doing it as a second command leaves a few seconds where
@@ -741,6 +792,18 @@ export function renameSession(ctx, args) {
   return ok({ ok: true, session: sessions.decorate(renamed) });
 }
 
+/** `goto sage`: bring that agent's Herdr tab to the front. The tray's and Slack's "Go to pane" run this. */
+export async function gotoSession(ctx, args) {
+  const who = (args._ ?? [])[0];
+  const target = who ? sessions.byNickname(who) ?? sessions.get(who) : ctx.session;
+  if (!target) fail(who ? `no session called "${who}"` : "say which agent, e.g. `goto sage`");
+  try {
+    return ok({ ok: true, nickname: target.nickname, ...(await focusPane(target)) });
+  } catch (e) {
+    fail(e.message);
+  }
+}
+
 export function endSession(ctx, args) {
   const who = (args._ ?? [])[0];
   const target = who ? sessions.byNickname(who) ?? sessions.get(who) : ctx.session;
@@ -779,7 +842,7 @@ export async function ask(ctx, args) {
   if (!slackToken()) fail("asking needs Slack: SLACK_API_BOT_TOKEN is not set");
   if (!config.slack.target) fail("asking needs Slack: run setup with --slack-target");
   if (!slackAppToken()) {
-    fail("asking needs Slack buttons: set ROGER_ROGER_SLACK_APP_TOKEN (or SLACK_APP_TOKEN) to an app-level xapp- token with Socket Mode and Interactivity on (see SKILL.md, Requirements)");
+    fail("asking needs Slack buttons: set ROGER_ROGER_SLACK_APP_TOKEN (or SLACK_APP_TOKEN) to an app-level xapp- token with Socket Mode and Interactivity on (see reference.md, Requirements)");
   }
   if (typeof WebSocket !== "function") fail("asking needs Node 22 or newer (built-in WebSocket)");
 
@@ -852,7 +915,9 @@ export async function ask(ctx, args) {
   setState(ctx, "waiting");
   activity.record({ from: "agent", kind: "question", agent: activity.agentOf(ctx.session), text: question, detail: choices.join(" / ") });
 
-  const audio = await playAlert({ methods: audible, config, text, prepared, who: ctx.session?.nickname });
+  const desktop = desktopJob(ctx, methods, { kind: "question", message: `${stripTags(question)} (${choices.join(" / ")})`, project: args.project });
+  const audio = await announce(ctx, { methods: audible, config, text, prepared, who: ctx.session?.nickname });
+  if (desktop) audio.desktop = await desktop;
   const extra = { audio, ...(attached ? { attached } : {}), ...(muted.length ? { mutedByQuietHours: muted } : {}) };
   if (args.wait !== undefined) return waitFor(ctx, id, parseDuration(args.wait, Infinity), extra);
   // Waiting costs the agent nothing: run it in the background and carry on. It always comes back,
@@ -1162,6 +1227,7 @@ export const HANDLERS = {
   sessions: listSessions,
   rename: renameSession,
   end: endSession,
+  goto: gotoSession,
   play,
   say,
   "preview-sounds": previewSounds,

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

@@ -11,12 +11,13 @@ export const TAGLINE = "Bring yourself back to the conversation: your agents rea
 export const COMMANDS = [
   // ---- setting up
   { section: "Setting up", name: "install", usage: "[--yes]", summary: "Set everything up in the terminal: the command on your PATH, the skill for every agent and a standing instruction to use it, Herdr, Slack, the sound and the voice, hooks, tray. Run it again to change anything. --yes asks nothing and only links the skill.", flags: [["--yes", "no questions: link the skill for every agent on the machine and register with Herdr, then print what was done. Nothing is written to CLAUDE.md or AGENTS.md"]] },
-  { section: "Setting up", name: "uninstall", usage: "[--yes]", summary: "Take it out again: the standing instruction, hooks, links, Herdr, the daemon and the tray, settings and tokens, the global command.", flags: [["--yes", "no questions: remove everything except the Slack CLI, then print what was done"], ["--slack-cli", "with --yes, remove the Slack CLI and its login as well"]] },
+  { section: "Setting up", name: "uninstall", usage: "[--yes]", summary: "Take it out again: the standing instruction, hooks, links, Herdr, the daemon and the tray, settings and tokens, the global command.", flags: [["--yes", "no questions: remove everything except the Slack CLI, then print what was done"], ["--slack-cli", "with --yes, remove the Slack CLI and its login as well"], ["--slack-app", "with --yes, delete the roger-roger app from the Slack workspace as well"]] },
   { section: "Setting up", name: "status", usage: "", summary: "Settings, whether the tokens are there, the daemon, who is running, and every valid option value." },
+  { section: "Setting up", name: "doctor", usage: "[--offline] [--json]", summary: "Everything that could stop a notification arriving, each with what to do about it: tokens and scopes, the daemon and which copy it runs, hooks, the tray, the speech key.", flags: [["--offline", "skip the checks that ask Slack"], ["--json", "the report as JSON even in a terminal"]] },
   {
     section: "Setting up", name: "setup", usage: "[flags]", summary: "Change any setting; the rest are kept.",
     flags: [
-      ["--methods slack,sound,speech", "how to be reached, any combination"],
+      ["--methods slack,sound,speech,desktop", "how to be reached, any combination; desktop is a native notification (Windows, macOS)"],
       ["--slack-target U0123|C0123|#name", "your member ID for DMs, or a channel"],
       ["--slack-mention U0123", "who to mention in channel posts"],
       ["--sound NAME", "chime, ding, marimba, bubble, alert"],
@@ -34,6 +35,9 @@ export const COMMANDS = [
       ["--remind 15m|off", "remind about an unanswered question after this long"],
       ["--on-expire recommended|nothing", "what an unanswered question settles as"],
       ["--quiet-hours 22:00-08:00|off, --quiet-mute speech,sound", "when, and what, to keep quiet"],
+      ["--presence on|off", "at the desk, use only --present-methods; away or locked, everything"],
+      ["--present-methods sound,speech,desktop|none", "what reaches you while you are at the computer"],
+      ["--away-after 3m", "no keyboard or mouse for this long counts as away"],
       ["--permission-pings on|off", "also ping for ordinary permission prompts in the terminal"],
       ["--terminal-wait 20s", "how long a terminal question waits before the ping (OpenCode, Codex)"],
       ["--tray auto|off", "start the tray with the daemon once it is installed"],
@@ -65,6 +69,7 @@ export const COMMANDS = [
   { section: "Reaching the user", name: "progress", usage: "--message TEXT [--key NAME] [--done]", summary: "One Slack message, edited in place as the work moves on, with Pause, Stop and Note buttons." },
   { section: "Reaching the user", name: "control", usage: "[--key NAME] [--wait DURATION]", summary: "Read Pause, Stop and new messages without posting. --wait blocks while paused." },
   { section: "Reaching the user", name: "listen", usage: "[--wait 25m]", summary: "Park until the user says something. Run it in the background as the last thing you do." },
+  { section: "Reaching the user", name: "desktop", usage: "test [--goto NAME]", summary: "Show one native notification now, to see that this machine shows them. --goto adds the Go to pane button for that agent." },
   { section: "Reaching the user", name: "snooze", usage: "[1h|off]", summary: "Sound and speech off for a while; Slack keeps working." },
   { section: "Reaching the user", name: "hush", usage: "", summary: "Stop the voice or sound playing right now. Only this announcement: the next plays as usual, and the Slack message stays. The tray's Stop button does the same." },
 
@@ -95,6 +100,7 @@ export const COMMANDS = [
 
   // ---- sessions
   { section: "Sessions", name: "sessions", usage: "[--all] | rename NAME NEWNAME", summary: "Who is running and what each is called. Rename gives one a different colour name." },
+  { section: "Sessions", name: "goto", usage: "NAME", summary: "Bring that agent's Herdr tab to the front. The tray and Slack messages from a Herdr pane offer the same as a button." },
   { section: "Sessions", name: "end", usage: "[NAME]", summary: "This session is finished; stop routing messages to it." },
   { section: "Sessions", name: "inbox", usage: "", summary: "Messages the user sent this session, and anything left for the next agent." },
 

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

@@ -216,3 +216,15 @@ export async function labelPane(session, { log = () => {}, touch = () => {}, run
     inFlight.delete(session.id);
   }
 }
+
+/**
+ * Bring a session's pane to the front in Herdr: its workspace, then its tab. Herdr focuses panes
+ * only by direction, so the tab is as close as it goes; an agent normally has a tab to itself.
+ */
+export async function focusPane(session, { run = runHerdr } = {}) {
+  if (!session?.herdr?.tab) throw new Error(`${session?.nickname ?? "that agent"} isn't running in a Herdr pane`);
+  const opts = { bin: session.herdr.bin, socket: session.herdr.socket };
+  if (session.herdr.workspace) await run(["workspace", "focus", session.herdr.workspace], opts);
+  await run(["tab", "focus", session.herdr.tab], opts);
+  return { focused: true, tab: session.herdr.tab, ...(session.herdr.workspace ? { workspace: session.herdr.workspace } : {}) };
+}

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

@@ -0,0 +1,105 @@
+// The roger-roger app's Home tab in Slack: who is running, what is waiting on you, what is in
+// progress, and the few buttons worth having from a phone (snooze, stop the voice, go to an agent's
+// pane). The tray shows the same at the desk; this is the one that travels.
+//
+// Slack keeps a published Home view until the next publish, so it is redrawn whenever something
+// moves (at most every few seconds) for anyone who has opened it, and for the configured DM user.
+
+import { GOTO_PREFIX, stripTags } from "./lib.mjs";
+import { permalink, slackCall } from "./slack.mjs";
+import { slackToken } from "./lib.mjs";
+
+export const HOME_PREFIX = "roger-roger_home";
+
+/** `roger-roger_home:snooze:1h` → { action: "snooze", value: "1h" }, or null. */
+export function parseHomeActionId(value) {
+  const m = new RegExp(`^${HOME_PREFIX}:(snooze|hush)(?::(.+))?$`).exec(String(value));
+  return m ? { action: m[1], value: m[2] ?? null } : null;
+}
+
+const button = (text, actionId, style) => ({ type: "button", action_id: actionId, text: { type: "plain_text", text, emoji: true }, ...(style ? { style } : {}) });
+const section = (text) => ({ type: "section", text: { type: "mrkdwn", text } });
+const context = (text) => ({ type: "context", elements: [{ type: "mrkdwn", text }] });
+
+function ago(ms) {
+  const m = Math.round(ms / 60_000);
+  if (m < 1) return "just now";
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  return `${h}h ${m % 60}m ago`;
+}
+
+/**
+ * The Home view for a tray snapshot (tray.mjs). `links` maps a question's id to its message's
+ * permalink, when there is one.
+ */
+export function homeView(snap, { links = {}, now = Date.now() } = {}) {
+  const blocks = [{ type: "header", text: { type: "plain_text", text: "roger-roger", emoji: true } }];
+
+  // What is muted, and the buttons that change it.
+  const muted = snap.muted ?? {};
+  const status = [];
+  if (!snap.daemon) status.push(":warning: The daemon on the computer isn't running, so this may be out of date.");
+  if (muted.snoozeUntil) status.push(`:zzz: Snoozed until ${new Date(muted.snoozeUntil).toTimeString().slice(0, 5)}: no sound or voice, Slack still on.`);
+  else if (muted.quietNow) status.push(":crescent_moon: Quiet hours.");
+  if (snap.speaking) status.push(`:loud_sound: ${snap.speaking.who ? `*${snap.speaking.who}* is speaking.` : "Something is playing."}`);
+  if (status.length) blocks.push(section(status.join("\n")));
+  const controls = muted.snoozeUntil
+    ? [button("Stop snoozing", `${HOME_PREFIX}:snooze:off`)]
+    : [button("Snooze 15m", `${HOME_PREFIX}:snooze:15m`), button("Snooze 1h", `${HOME_PREFIX}:snooze:1h`)];
+  if (snap.speaking) controls.push(button(":octagonal_sign: Stop the voice", `${HOME_PREFIX}:hush`, "danger"));
+  blocks.push({ type: "actions", block_id: `${HOME_PREFIX}_controls`, elements: controls });
+
+  // Waiting on you comes first: it is the reason to open this.
+  const questions = snap.questions ?? [];
+  if (questions.length) {
+    blocks.push({ type: "divider" }, section("*Waiting on you*"));
+    for (const q of questions) {
+      const who = q.nickname ? `${q.swatch ? `${q.swatch} ` : ""}*${q.nickname}*` : "An agent";
+      const link = links[q.id] ? ` · <${links[q.id]}|answer it>` : "";
+      const left = q.expiresAt ? ` · settles in ${Math.max(0, Math.round((Date.parse(q.expiresAt) - now) / 60_000))}m` : "";
+      blocks.push(section(`${who}: ${stripTags(q.question)}${link}`), context(`${(q.choices ?? []).join(" / ")}${left}`));
+    }
+  }
+
+  const agents = snap.agents ?? [];
+  blocks.push({ type: "divider" }, section(agents.length ? "*Running*" : "_Nothing is running._"));
+  for (const a of agents) {
+    const what = [a.project, a.name].filter(Boolean).join(" · ");
+    const row = section(`${a.swatch ? `${a.swatch} ` : ""}*${a.nickname}*  ${a.state ?? ""}${what ? `\n${what}` : ""}`);
+    if (a.inHerdr) row.accessory = button(":desktop_computer: Go to pane", `${GOTO_PREFIX}:${a.id}`);
+    blocks.push(row, context(`quiet ${ago(a.quietForMs ?? 0)}${a.queued ? ` · ${a.queued} unread` : ""}${a.owes ? ` · ${a.owes} answer(s) to collect` : ""}`));
+  }
+
+  const working = snap.working ?? [];
+  if (working.length) {
+    blocks.push({ type: "divider" }, section("*In progress*"));
+    for (const w of working) blocks.push(section(`${w.nickname ? `*${w.nickname}*: ` : ""}${stripTags(w.headline)}`));
+  }
+
+  blocks.push(context(`Updated ${new Date(snap.updatedAt ?? now).toTimeString().slice(0, 5)}`));
+  // Slack's limit for a Home view.
+  return { type: "home", blocks: blocks.slice(0, 100) };
+}
+
+const linkCache = new Map();
+
+/** Permalinks for the open questions, asked once per question. */
+async function linksFor(decisions) {
+  const links = {};
+  for (const d of decisions) {
+    if (!d.channel || !d.ts) continue;
+    if (!linkCache.has(d.id)) linkCache.set(d.id, await permalink(d.channel, d.ts).catch(() => null));
+    if (linkCache.get(d.id)) links[d.id] = linkCache.get(d.id);
+  }
+  return links;
+}
+
+/** Draw the Home tab for one user. `pending` are the open decisions, for their links. */
+export async function publishHome(userId, snap, pending = []) {
+  const token = slackToken();
+  if (!token || !userId) return { ok: false, error: "no token or user" };
+  const view = homeView(snap, { links: await linksFor(pending) });
+  const r = await slackCall("views.publish", token, { user_id: userId, view });
+  return r.ok ? { ok: true } : { ok: false, error: r.error };
+}