relay-companion 0.1.52 → 0.1.56

package/bin/relay.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import os from "node:os";
+import fsSync from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
@@ -392,6 +393,50 @@ async function cmdPill(flags = {}) {
   console.log(`Relay pill is visible. Reopen it from ${statusAreaReopenText()} after hiding it.`);
 }
 
+// Diagnose (and optionally heal) swallowed notifications: relays that are
+// unread on disk but marked presented with no pending-attention entry can
+// never notify again. --requeue-unseen strands them back into the queue;
+// --restart-pill makes the running pill reload the healed prefs.
+async function cmdDoctor(flags = {}) {
+  const home = process.env.RELAY_HOME || process.env.RELAY_COMPANION_HOME || path.join(os.homedir(), ".relay-companion");
+  const statePath = path.join(home, "state.json");
+  const prefsPath = path.join(home, "overlay-prefs.json");
+  const readJson = (p) => {
+    try {
+      return JSON.parse(fsSync.readFileSync(p, "utf8")) || {};
+    } catch {
+      return {};
+    }
+  };
+  const state = readJson(statePath);
+  const prefs = readJson(prefsPath);
+  const presented = new Set(Array.isArray(prefs.presentedRelayIds) ? prefs.presentedRelayIds.map(String) : []);
+  const pending = new Set(Object.keys(prefs.pendingAttention && typeof prefs.pendingAttention === "object" ? prefs.pendingAttention : {}));
+  const unread = Object.entries(state.packets || {})
+    .filter(([, row]) => row && row.direction === "inbound" && row.state !== "read")
+    .map(([id]) => id);
+  const swallowed = unread.filter((id) => presented.has(id) && !pending.has(id));
+  console.log(`relay doctor @ ${new Date().toISOString()}`);
+  console.log(`  staged unread: ${unread.length}`);
+  console.log(`  confirmed-seen ledger: ${presented.size}`);
+  console.log(`  pending attention queue: ${pending.size}`);
+  console.log(`  SWALLOWED (unread, marked seen, not queued): ${swallowed.length}`);
+  for (const id of swallowed.slice(0, 20)) console.log(`    - ${id}`);
+  if (swallowed.length > 20) console.log(`    … and ${swallowed.length - 20} more`);
+  if (flags["requeue-unseen"] && swallowed.length) {
+    prefs.presentedRelayIds = [...presented].filter((id) => !swallowed.includes(id));
+    fsSync.writeFileSync(prefsPath, `${JSON.stringify(prefs, null, 2)}\n`);
+    console.log(`Requeued ${swallowed.length} relay(s): removed from the confirmed-seen ledger.`);
+    if (flags["restart-pill"] && process.platform === "darwin") {
+      const uid = typeof process.getuid === "function" ? process.getuid() : 501;
+      spawnSync("launchctl", ["kickstart", "-k", `gui/${uid}/work.relay.companion.pill`], { stdio: "ignore" });
+      console.log("Pill restarted; the queue will replay them sequentially when you are present.");
+    } else {
+      console.log("Restart the pill to pick this up: launchctl kickstart -k gui/$UID/work.relay.companion.pill");
+    }
+  }
+}
+
 async function main() {
   const [command, ...rest] = process.argv.slice(2);
   const { flags, positional } = parseFlags(rest);
@@ -433,6 +478,8 @@ async function main() {
     case "update":
     case "self-update":
       return runUpdateOnce({ mode: modeFromFlags(flags) }).then(() => {});
+    case "doctor":
+      return cmdDoctor(flags);
     default:
       console.log(
         [

package/overlay/attention-queue.cjs

@@ -0,0 +1,164 @@
+// Durable per-relay attention queue: the single source of truth for "which
+// relays still owe the user a visible notification".
+//
+// Invariants (from the 2026-08 notification reliability audit):
+//  - A relay enters the queue when it is staged unread and has never been
+//    CONFIRMED seen. It leaves only via confirmSeen() (renderer-confirmed
+//    visible dwell / explicit interaction) or drop() (the user acted on that
+//    relay elsewhere: opened, deleted, read on another surface).
+//  - "presented" (the legacy ledger) now means confirmed-seen, never
+//    fired-and-forgotten. Sending IPC to the renderer proves nothing.
+//  - The queue is plain serializable state persisted in overlay prefs, so a
+//    crash, renderer reload, or process restart replays it instead of
+//    dropping it. beginShow() is an in-flight marker, not an exit.
+//  - Presentation is sequential: one card at a time, oldest first, so a
+//    backlog plays one after another instead of a single folded stack.
+//
+// Pure logic + explicit state in/out: no Electron, no fs, unit-testable.
+
+"use strict";
+
+const SHOW_RETRY_LIMIT = 2; // failed dwells before a card turns sticky
+
+function normalizeEntry(raw, id) {
+  if (!raw || typeof raw !== "object") return null;
+  const entryId = String(raw.id || id || "").trim();
+  if (!entryId) return null;
+  return {
+    id: entryId,
+    enqueuedAt: Number.isFinite(raw.enqueuedAt) ? raw.enqueuedAt : Date.now(),
+    attempts: Number.isFinite(raw.attempts) ? raw.attempts : 0,
+    showing: raw.showing === true,
+    sticky: raw.sticky === true,
+  };
+}
+
+// prefs.pendingAttention -> Map(id -> entry). Tolerates legacy shapes.
+function loadQueue(prefs) {
+  const queue = new Map();
+  const raw = prefs && typeof prefs === "object" ? prefs.pendingAttention : null;
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    for (const [id, entry] of Object.entries(raw)) {
+      const normalized = normalizeEntry(entry, id);
+      if (normalized) queue.set(normalized.id, normalized);
+    }
+  } else if (Array.isArray(raw)) {
+    for (const entry of raw) {
+      const normalized = normalizeEntry(entry);
+      if (normalized) queue.set(normalized.id, normalized);
+    }
+  }
+  // A crash mid-show leaves showing=true with no renderer to confirm it.
+  // Recover by demoting to pending; the attempt already counted.
+  for (const entry of queue.values()) entry.showing = false;
+  return queue;
+}
+
+function saveQueue(queue, prefs) {
+  const out = {};
+  for (const [id, entry] of queue.entries()) {
+    out[id] = {
+      id,
+      enqueuedAt: entry.enqueuedAt,
+      attempts: entry.attempts,
+      showing: entry.showing === true,
+      sticky: entry.sticky === true,
+    };
+  }
+  prefs.pendingAttention = out;
+  return prefs;
+}
+
+// Enqueue ids that are unread, not confirmed-seen, and not already queued.
+// Returns the ids actually added (for logging).
+function enqueueUnseen(queue, ids, { presentedIds, now = Date.now() } = {}) {
+  const presented = presentedIds instanceof Set ? presentedIds : new Set(presentedIds || []);
+  const added = [];
+  for (const rawId of ids || []) {
+    const id = String(rawId || "").trim();
+    if (!id || queue.has(id) || presented.has(id)) continue;
+    queue.set(id, { id, enqueuedAt: now, attempts: 0, showing: false, sticky: false });
+    added.push(id);
+  }
+  return added;
+}
+
+// Oldest pending entry that is not mid-show. Sticky entries still surface —
+// they just render latched instead of timer-folded.
+function nextToShow(queue) {
+  let best = null;
+  for (const entry of queue.values()) {
+    if (entry.showing) return null; // a card is on stage; strict one-at-a-time
+    if (!best || entry.enqueuedAt < best.enqueuedAt) best = entry;
+  }
+  return best;
+}
+
+function beginShow(queue, id) {
+  const entry = queue.get(String(id || ""));
+  if (!entry) return null;
+  entry.showing = true;
+  entry.attempts += 1;
+  return entry;
+}
+
+// The renderer confirmed a real, user-present dwell (or an interaction).
+// Returns true when the id was pending.
+function confirmSeen(queue, id) {
+  return queue.delete(String(id || ""));
+}
+
+// The show did not count (user away, screen dark, renderer died). The entry
+// stays queued; after SHOW_RETRY_LIMIT failed dwells it turns sticky so the
+// next presentation latches open until interacted with instead of folding.
+function abortShow(queue, id) {
+  const entry = queue.get(String(id || ""));
+  if (!entry) return null;
+  entry.showing = false;
+  if (entry.attempts >= SHOW_RETRY_LIMIT) entry.sticky = true;
+  return entry;
+}
+
+// The user acted on the relay through another path (opened it, deleted it,
+// read it on the web/another device, mark-all-read). That is "seen".
+function drop(queue, id) {
+  return queue.delete(String(id || ""));
+}
+
+// Remove entries whose relay is no longer unread (read elsewhere, deleted,
+// tombstoned). unreadIds is the currently-staged unread set.
+function reconcileWithUnread(queue, unreadIds) {
+  const unread = unreadIds instanceof Set ? unreadIds : new Set(unreadIds || []);
+  const dropped = [];
+  for (const id of [...queue.keys()]) {
+    if (!unread.has(id)) {
+      queue.delete(id);
+      dropped.push(id);
+    }
+  }
+  return dropped;
+}
+
+function pendingCount(queue) {
+  return queue.size;
+}
+
+function hasShowing(queue) {
+  for (const entry of queue.values()) if (entry.showing) return true;
+  return false;
+}
+
+module.exports = {
+  SHOW_RETRY_LIMIT,
+  loadQueue,
+  saveQueue,
+  enqueueUnseen,
+  nextToShow,
+  beginShow,
+  confirmSeen,
+  abortShow,
+  drop,
+  reconcileWithUnread,
+  pendingCount,
+  hasShowing,
+};