@juspay/shooter 1.21.0 → 1.23.0

package/src/lib/modules/server/terminal/terminal-emulator.ts

@@ -0,0 +1,102 @@
+/**
+ * Server-side authoritative terminal emulator (Phase 1).
+ *
+ * Wraps a DOM-free @xterm/headless Terminal + @xterm/addon-serialize. Every
+ * PTY output chunk is fed in via write(); snapshot() returns a VT-escape string
+ * that reconstructs the CURRENT screen — including the alternate buffer (TUIs
+ * like vim/htop) and modes — when written into a fresh terminal. This is what
+ * a new or reconnecting client receives instead of a raw scrollback replay,
+ * fixing late-join corruption (G2) and the scrollback/live duplication race (G3).
+ *
+ * Caveats handled here (see the keystone spike): @xterm/addon-serialize does
+ * NOT serialize cursor visibility (DECTCEM ?25l), so we track it from the byte
+ * stream and re-emit it; cursor position restores functionally but not
+ * byte-exactly (do not assert byte-equality). Pinned to @xterm/headless@6.0.0
+ * and @xterm/addon-serialize@0.14.0 (serialize() reaches into _core internals).
+ *
+ * Interop note: both packages export via CJS in a way tsx/Node cannot resolve
+ * as named ESM imports, so the runtime values come through createRequire() while
+ * the types are imported separately.
+ */
+
+import type { TerminalSnapshot } from '$lib/types';
+import type { SerializeAddon as SerializeAddonInstance } from '@xterm/addon-serialize';
+import type { Terminal as HeadlessTerminal } from '@xterm/headless';
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { Terminal } = require('@xterm/headless') as {
+  Terminal: new (options?: object) => HeadlessTerminal;
+};
+const { SerializeAddon } = require('@xterm/addon-serialize') as {
+  SerializeAddon: new () => SerializeAddonInstance;
+};
+
+/** Scrollback lines retained in the emulator and included in snapshots. */
+const SNAPSHOT_SCROLLBACK_LINES = 1000;
+
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+
+export class TerminalEmulator {
+  private cursorHidden = false;
+  private readonly serializer: SerializeAddonInstance;
+  private readonly term: HeadlessTerminal;
+
+  constructor(cols: number, rows: number) {
+    this.term = new Terminal({
+      allowProposedApi: true,
+      cols: cols > 0 ? cols : 80,
+      rows: rows > 0 ? rows : 24,
+      scrollback: SNAPSHOT_SCROLLBACK_LINES,
+    });
+    this.serializer = new SerializeAddon();
+    // @xterm/addon-serialize types its addon against @xterm/xterm's Terminal,
+    // but we run it on @xterm/headless's Terminal. Runtime-compatible; the cast
+    // bridges the two structurally-different Terminal types at loadAddon only.
+    this.term.loadAddon(this.serializer as unknown as Parameters<HeadlessTerminal['loadAddon']>[0]);
+  }
+
+  dispose(): void {
+    try {
+      this.serializer.dispose();
+      this.term.dispose();
+    } catch {
+      // Already disposed — ignore.
+    }
+  }
+
+  resize(cols: number, rows: number): void {
+    if (cols > 0 && rows > 0) {
+      this.term.resize(cols, rows);
+    }
+  }
+
+  /**
+   * Capture the current screen as a VT-escape string. Serialization runs inside
+   * a write() callback so all previously-written bytes are parsed first.
+   */
+  snapshot(): Promise<TerminalSnapshot> {
+    return new Promise<TerminalSnapshot>((resolve) => {
+      this.term.write('', () => {
+        let data = this.serializer.serialize({ scrollback: SNAPSHOT_SCROLLBACK_LINES });
+        // SerializeAddon omits cursor visibility — re-emit when hidden.
+        if (this.cursorHidden) {
+          data += HIDE_CURSOR;
+        }
+        resolve({ cols: this.term.cols, data, rows: this.term.rows });
+      });
+    });
+  }
+
+  write(data: string): void {
+    // Track cursor visibility (DECTCEM) from the stream; last toggle wins.
+    const hideIdx = data.lastIndexOf(HIDE_CURSOR);
+    const showIdx = data.lastIndexOf(SHOW_CURSOR);
+    if (hideIdx !== -1 || showIdx !== -1) {
+      this.cursorHidden = hideIdx > showIdx;
+    }
+    this.term.write(data);
+  }
+}

package/src/lib/modules/server/terminal/terminal-store.ts

@@ -13,9 +13,11 @@ import Database from 'better-sqlite3';
 import * as fs from 'fs';
 import * as path from 'path';
 
+import { shooterDataDir } from '../utils/shooter-home.js';
+
 // ── Constants ────────────────────────────────────────────────────────
 
-const DB_DIR = path.join(process.env.HOME || '', '.shooter');
+const DB_DIR = shooterDataDir();
 const DB_PATH = path.join(DB_DIR, 'shooter.db');
 
 // ── Snake/Camel Conversion ───────────────────────────────────────────

package/src/lib/modules/server/utils/shooter-home.ts

@@ -0,0 +1,16 @@
+import { homedir } from 'os';
+import { join } from 'path';
+
+/**
+ * The Shooter data directory — the SQLite DB and engine/permission state live here.
+ *
+ * Honors `SHOOTER_HOME` so an isolated instance (a test server, or a second server run alongside
+ * the user's daemon) keeps its DB/state separate from the default `~/.shooter` instead of sharing
+ * it (which would let one server's `reconnectAll()` adopt the other's live terminals). This matches
+ * the CLI (`bin/shooter.cjs`) and the env loader (`env.ts`), which already treat `SHOOTER_HOME` as
+ * the data dir. When unset, falls back to `~/.shooter`.
+ */
+export function shooterDataDir(): string {
+  const override = process.env.SHOOTER_HOME?.trim();
+  return override && override.length > 0 ? override : join(homedir(), '.shooter');
+}

package/src/lib/modules/server/ws/presence-store.ts

@@ -0,0 +1,50 @@
+// Viewer-presence store: "is someone actually watching" (foreground) vs "away".
+//
+// Why this exists: the phone-resident autonomous loop holds a PERSISTENT /ws/events
+// connection to run. So raw WebSocket-connection count no longer means "the user is
+// watching" — it's always > 0. The autopilot push decision must instead key on whether a
+// viewer is FOREGROUNDED (heartbeat within TTL), reported via POST /api/presence.
+//
+// globalThis singleton so the SvelteKit route (which writes it) and the server.ts engine
+// (which reads it) share one instance across the dual module graph — same pattern as the
+// ws ticket store and the event-listener registry.
+
+const PRESENCE_TTL_MS = 45_000;
+const KEY = '__shooter_presence';
+
+// eslint-disable-next-line no-restricted-syntax -- internal singleton shape, never exported
+interface PresenceRecord {
+  everReported: boolean;
+  lastForegroundAt: number;
+}
+
+/** True once any client has ever reported presence (used for backward-compatible fallback). */
+export function hasEverReported(): boolean {
+  return store().everReported;
+}
+
+/** True when a viewer reported `foreground` within the TTL window. */
+export function isViewerPresent(
+  now: number = Date.now(),
+  ttlMs: number = PRESENCE_TTL_MS
+): boolean {
+  return now - store().lastForegroundAt < ttlMs;
+}
+
+/**
+ * Record a presence heartbeat. `foreground` marks the viewer as actively watching (now);
+ * `background` marks them away immediately (so push resumes without waiting out the TTL).
+ */
+export function reportPresence(state: 'background' | 'foreground', now: number = Date.now()): void {
+  const s = store();
+  s.everReported = true;
+  s.lastForegroundAt = state === 'foreground' ? now : 0;
+}
+
+function store(): PresenceRecord {
+  const g = globalThis as Record<string, unknown>;
+  if (!g[KEY]) {
+    g[KEY] = { everReported: false, lastForegroundAt: 0 };
+  }
+  return g[KEY] as PresenceRecord;
+}

package/src/lib/modules/server/ws/server.ts

@@ -56,8 +56,24 @@ export function setupWebSocketHandlers(
 ): void {
   const host = request.headers.host ?? 'localhost';
   let pathname: string;
+  let snapshotCapable = false;
+  let lastSeq = 0;
   try {
-    pathname = new URL(request.url || '/', `http://${host}`).pathname;
+    const url = new URL(request.url || '/', `http://${host}`);
+    pathname = url.pathname;
+    // Capability negotiation: clients that understand the {snapshot} frame
+    // advertise ?caps=snapshot. Others fall back to raw scrollback replay.
+    snapshotCapable = url.searchParams.get('caps') === 'snapshot';
+    // Reconnect resume (Phase 2): a returning client passes the highest output
+    // seq it already applied so the server can replay just the gap (or snapshot
+    // if the gap aged out of the ring). Absent / non-numeric ⇒ fresh join.
+    const rawLastSeq = url.searchParams.get('lastSeq');
+    if (rawLastSeq !== null) {
+      const parsed = Number(rawLastSeq);
+      if (Number.isFinite(parsed) && parsed > 0) {
+        lastSeq = Math.floor(parsed);
+      }
+    }
   } catch {
     socket.destroy();
     return;
@@ -103,7 +119,7 @@ export function setupWebSocketHandlers(
 
     if (terminalMatch) {
       const terminalId = terminalMatch[1];
-      handleTerminalConnection(ws, terminalId, scope);
+      handleTerminalConnection(ws, terminalId, scope, snapshotCapable, lastSeq);
     } else if (superSessionMatch) {
       const superSessionId = superSessionMatch[1];
       handleSuperSessionConnection(ws, superSessionId);

package/src/lib/modules/server/ws/terminal-handler.ts

@@ -32,7 +32,9 @@ let _ptyManager: null | PtyManagerLike = null;
 export function handleTerminalConnection(
   ws: WebSocket,
   terminalId: string,
-  scope?: TicketScope
+  scope?: TicketScope,
+  snapshotCapable = false,
+  lastSeq = 0
 ): void {
   // ── 1. Look up the terminal ──────────────────────────────────────
   if (!_ptyManager) {
@@ -48,11 +50,14 @@ export function handleTerminalConnection(
     return;
   }
 
-  // ── 2. Attach via pty-manager (registers client + sends scrollback) ──
-  // The pty-manager's attach() adds ws to terminal.clients AND
-  // terminal.outputBuffers, then replays scrollback. Its broadcastOutput()
-  // loop delivers all PTY output — no per-client onData listener needed.
-  _ptyManager.attach(terminalId, ws);
+  // ── 2. Attach via pty-manager (registers client + sends initial state) ──
+  // Snapshot-capable clients (?caps=snapshot) get a serialized current-screen
+  // snapshot; others get the legacy raw scrollback replay. A reconnecting
+  // client also passes lastSeq (>0) so attach() can replay only the missing
+  // frames from the ring instead of re-snapshotting. attach() adds the ws to
+  // terminal.clients + outputBuffers; broadcastOutput() then delivers all live
+  // PTY output — no per-client onData listener needed.
+  _ptyManager.attach(terminalId, ws, { lastSeq, snapshot: snapshotCapable });
 
   // If the terminal already exited, tell the client immediately.
   if (terminal.status === 'exited') {

package/src/lib/types/autopilot.ts

@@ -15,6 +15,16 @@ export interface AutopilotState {
 /** Per-session autopilot lifecycle state. */
 export type AutopilotStatus = 'error' | 'idle' | 'running';
 
+/** Verdict from guardCommand() — whether a concrete command is safe to write to the PTY. */
+export interface CommandVerdict {
+  /** The trimmed command (echoed back for convenience). */
+  command: string;
+  /** Human-readable reason for the verdict. */
+  reason: string;
+  /** True when the command passed all guards and may be injected. */
+  safe: boolean;
+}
+
 /** Result from mergeNextStepConsensus(). */
 export interface ConsensusResult {
   /** Number of agent lists passed in. */
@@ -25,6 +35,61 @@ export interface ConsensusResult {
   steps: NextStep[];
 }
 
+/** A record of one autonomous-loop decision, surfaced in the dashboard panel. */
+export interface DriverAction {
+  /** ms timestamp of the action. */
+  at: number;
+  /** The command injected, or a short reason it was skipped / failed. */
+  detail: string;
+  /** What happened. */
+  kind: DriverActionKind;
+  /** The terminal acted on. */
+  terminalId: string;
+}
+
+/** Outcome of one driver evaluation. */
+export type DriverActionKind = 'error' | 'injected' | 'skipped';
+
+/** Decision from decideInjection() — the gate deciding whether to auto-act. */
+export interface GateDecision {
+  /** True when all safety gates pass and the loop should produce + inject a command. */
+  act: boolean;
+  /** Human-readable reason (always set, for logging + the phone UI). */
+  reason: string;
+  /** The consensus step being acted on (present when act is true). */
+  step?: NextStep;
+}
+
+/** Tunable thresholds for the auto-inject safety gate. */
+export interface InjectionPolicy {
+  /** Suppress injection within this many ms of observed human / output activity. */
+  humanGraceMs: number;
+  /** Minimum confidence of the top consensus step required to inject. */
+  injectConfidence: number;
+  /** Stop auto-injecting a terminal after this many consecutive actions without progress. */
+  maxAutoActions: number;
+  /** Minimum gap in ms between injections into the same terminal. */
+  minIntervalMs: number;
+}
+
+/** Per-terminal snapshot the driver passes to decideInjection(). */
+export interface InjectionState {
+  /** Consecutive auto-injections without a human touch or successful tool completion. */
+  autoActionCount: number;
+  /** True only for terminals Shooter created (POST /api/terminals); external sessions are read-only. */
+  isManaged: boolean;
+  /** Normalized text of the last consensus step acted on (dedup guard). */
+  lastActedStep: null | string;
+  /** ms timestamp of the last observed human input / terminal output activity. */
+  lastActivityAt: number;
+  /** The most recent WireShooterEvent type seen for this terminal. */
+  lastEventType: string;
+  /** ms timestamp of the last command injection into this terminal. */
+  lastInjectedAt: number;
+  /** The terminal id. */
+  terminalId: string;
+}
+
 /** Options for mergeNextStepConsensus(). */
 export interface MergeOptions {
   /** Max steps taken from each agent list (default 3). */

package/src/lib/types/generated/WsProtocol.ts

@@ -238,20 +238,29 @@ export type TerminalOutputMessage = {
    * @memberof TerminalOutputMessage
    */
   data: string;
+  /**
+   * @description Monotonic per-terminal sequence number (starts at 1, increments by 1 for every broadcast output frame). Clients track lastSeq to enable gap detection and reconnect resume (Phase 2).
+
+   * @type { number }
+   * @memberof TerminalOutputMessage
+  */
+  seq: number;
 };
 
 export function decodeTerminalOutputMessage(rawInput: unknown): TerminalOutputMessage | null {
   if (isJSON(rawInput)) {
     const decodedType = decodeString(rawInput['type']);
     const decodedData = decodeString(rawInput['data']);
+    const decodedSeq = decodeNumber(rawInput['seq']);
 
-    if (decodedType === null || decodedData === null) {
+    if (decodedType === null || decodedData === null || decodedSeq === null) {
       return null;
     }
 
     return {
       type: decodedType,
       data: decodedData,
+      seq: decodedSeq,
     };
   }
   return null;

package/src/lib/types/server.ts

@@ -10,6 +10,7 @@ import type WebSocket from 'ws';
 
 import type { CodexStreamParser } from '../modules/server/sessions/codex-parser';
 import type { HolderClient } from '../modules/server/terminal/holder-client';
+import type { TerminalEmulator } from '../modules/server/terminal/terminal-emulator';
 import type { ConversationMessage } from './sessions';
 
 // ── holder-client types ─────────────────────────────────────────────
@@ -87,6 +88,8 @@ export interface PtyManagedTerminal {
   createdAt: Date;
   currentCwd: null | string;
   cwd: string;
+  /** Server-side headless emulator for snapshot-on-join (null when disabled). */
+  emulator: null | TerminalEmulator;
   exitCode: null | number;
   exitedAt: Date | null;
   holderPid: number;
@@ -100,6 +103,10 @@ export interface PtyManagedTerminal {
   pty: HolderClient;
   rows: number;
   scrollback: string;
+  /** Monotonic counter; equals the last assigned seq for this terminal. */
+  seqCounter: number;
+  /** Bounded replay ring of recent output chunks (max SEQ_RING_MAX_ENTRIES). */
+  seqRing: SeqRingEntry[];
   sessionFile: null | string;
   socketPath: string;
   status: 'exited' | 'running';
@@ -113,7 +120,14 @@ export interface PtyOutputBuffer {
   size: number;
 }
 
-// ── generic-session-watcher types ───────────────────────────────────
+/**
+ * One entry in the per-terminal sequence ring (in-memory store type;
+ * structurally identical to the generated wire SeqRingEntry).
+ */
+export interface SeqRingEntry {
+  data: string;
+  seq: number;
+}
 
 export interface SessionWatchedFile {
   callbacks: Set<OnNewEntries>;
@@ -121,3 +135,15 @@ export interface SessionWatchedFile {
   offset: number;
   watcher: FSWatcher;
 }
+
+// ── generic-session-watcher types ───────────────────────────────────
+
+/**
+ * A serialized snapshot of a terminal's current screen (VT escape string)
+ * produced by the server-side headless emulator, plus its dimensions.
+ */
+export interface TerminalSnapshot {
+  cols: number;
+  data: string;
+  rows: number;
+}

package/src/lib/types/terminal-client.ts

@@ -108,6 +108,8 @@ export interface ShortcutsHelpProps {
 export interface TerminalInstance {
   dispose: () => void;
   fitAddon: FitAddon | null;
+  /** Highest output `seq` seen from the server (for Phase 2 reconnect resume). */
+  getLastSeq: () => number;
   sendInput: (data: string) => void;
   term: Terminal;
 }
@@ -147,5 +149,6 @@ export interface WsTerminalInboundMessage {
   data?: string;
   path?: string;
   rows?: number;
+  seq?: number;
   type: string;
 }

package/src/lib/types/ws.ts

@@ -73,7 +73,7 @@ export interface TerminalManagedTerminal {
 }
 
 export interface TerminalPtyManagerLike {
-  attach: (id: string, ws: WebSocket) => boolean;
+  attach: (id: string, ws: WebSocket, opts?: { lastSeq?: number; snapshot?: boolean }) => boolean;
   detach: (id: string, ws: WebSocket) => boolean;
   getTerminal: (id: string) => TerminalManagedTerminal | undefined;
 }
@@ -146,8 +146,9 @@ export type WireTerminalServerMessage =
   | { bytes: number; type: 'output-dropped' }
   | { chunk: number; data: string; total: number; type: 'scrollback' }
   | { code: null | number; signal: null | string; type: 'exit' }
+  | { cols: number; data: string; rows: number; seq: number; type: 'snapshot' }
   | { cols: number; rows: number; type: 'resize' }
-  | { data: string; type: 'output' }
+  | { data: string; seq: number; type: 'output' }
   | { message: string; type: 'error' };
 
 // ── notification-sessions type alias ────────────────────────────────

package/src/routes/api/autopilot/goal/+server.ts

@@ -0,0 +1,72 @@
+// Set/read the per-terminal autopilot GOAL that anchors the engine's context every cycle.
+//
+// POST { terminalId, goal } pins the goal; GET ?terminalId=… reads it back. Like
+// /api/autopilot, this reaches the engine via globalThis.__shooter_autopilot rather than
+// importing it (importing would start a second event subscriber). Goals live in-memory in the
+// engine (no file fallback): if the engine is not running there is nothing to set, so we 503.
+
+import { validateAuth } from '$lib/modules/server/auth';
+import { json } from '@sveltejs/kit';
+
+import type { RequestHandler } from './$types';
+
+function control():
+  | undefined
+  | {
+      getGoal?: (terminalId: string) => string | undefined;
+      setGoal?: (terminalId: string, goal: string) => void;
+    } {
+  return (globalThis as Record<string, unknown>).__shooter_autopilot as
+    | undefined
+    | {
+        getGoal?: (terminalId: string) => string | undefined;
+        setGoal?: (terminalId: string, goal: string) => void;
+      };
+}
+
+export const GET: RequestHandler = ({ request, url }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  const terminalId = url.searchParams.get('terminalId') ?? '';
+  if (!terminalId) {
+    return json({ error: 'terminalId query param is required' }, { status: 400 });
+  }
+  const ctrl = control();
+  if (!ctrl?.getGoal) {
+    return json({ error: 'autopilot engine not running', running: false }, { status: 503 });
+  }
+  return json({ goal: ctrl.getGoal(terminalId) ?? null, running: true });
+};
+
+export const POST: RequestHandler = async ({ request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  let body: { goal?: unknown; terminalId?: unknown };
+  try {
+    body = (await request.json()) as { goal?: unknown; terminalId?: unknown };
+  } catch {
+    return json({ error: 'Invalid JSON body' }, { status: 400 });
+  }
+  if (typeof body.terminalId !== 'string' || body.terminalId.length === 0) {
+    return json({ error: 'terminalId must be a non-empty string' }, { status: 400 });
+  }
+  if (typeof body.goal !== 'string') {
+    return json({ error: 'goal must be a string' }, { status: 400 });
+  }
+  if (body.goal.length > 500) {
+    // The goal is prepended to EVERY engine LLM context, so an unbounded string would permanently
+    // bloat (and could dominate) the prompt. Cap it like the summaries route caps its fields.
+    return json({ error: 'goal must be 500 characters or fewer' }, { status: 400 });
+  }
+
+  const ctrl = control();
+  if (!ctrl?.setGoal) {
+    return json({ error: 'autopilot engine not running', running: false }, { status: 503 });
+  }
+  ctrl.setGoal(body.terminalId, body.goal);
+  return json({ goal: body.goal.trim() || null, running: true, terminalId: body.terminalId });
+};

package/src/routes/api/neurolink-proxy/+server.ts

@@ -112,10 +112,16 @@ export const POST: RequestHandler = async ({ request }) => {
   // For Bearer-token providers, only inject the header when the key is non-empty
   // to avoid sending a malformed `Authorization: Bearer ` to the upstream.
   if (provider === 'anthropic') {
-    forwardHeaders['x-api-key'] = apiKeyEnv.anthropic;
+    // Only inject the key header when non-empty — sending `x-api-key: ` (empty) is a malformed
+    // header that the upstream rejects with a confusing error instead of a clean 401.
+    if (apiKeyEnv.anthropic) {
+      forwardHeaders['x-api-key'] = apiKeyEnv.anthropic;
+    }
     forwardHeaders['anthropic-version'] = forwardHeaders['anthropic-version'] ?? '2023-06-01';
   } else if (provider === 'google-ai') {
-    forwardHeaders['x-goog-api-key'] = apiKeyEnv['google-ai'];
+    if (apiKeyEnv['google-ai']) {
+      forwardHeaders['x-goog-api-key'] = apiKeyEnv['google-ai'];
+    }
   } else if (provider === 'openai') {
     if (apiKeyEnv.openai) {
       forwardHeaders.Authorization = `Bearer ${apiKeyEnv.openai}`;

package/src/routes/api/notify/+server.ts

@@ -173,13 +173,8 @@ function intelligentNotificationFilter(
     };
   }
 
-  // Always allow Stop hook completion notifications
-  if (source === 'stop-hook') {
-    return {
-      reason: 'Stop hook completion notification - session finished',
-      send: true,
-    };
-  }
+  // (Removed a dead `source === 'stop-hook'` branch: the notifier emits
+  // 'shooter-completion-detector', never 'stop-hook', and the default below already allows it.)
 
   // Filter out only very specific spam patterns to be less restrictive
   const spamPatterns = [
@@ -263,18 +258,28 @@ function isDuplicateNotification(
     }
   }
 
-  // Do NOT record here -- caller must call recordNotification() after
-  // successful delivery to avoid cache poisoning on send failure.
+  // RESERVE the slot atomically (check-and-set): a second concurrent request with the same key now
+  // sees it as a duplicate before either has delivered, closing the TOCTOU window that let two
+  // identical pushes through. The delivery path RELEASES the slot (releaseNotification) if the send
+  // fails, so a legitimate retry is not blocked — this replaces the old record-only-on-success
+  // scheme while still avoiding cache poisoning on failure.
+  notificationCache.set(key, now);
   return false;
 }
 
-/** Record a notification key in the dedup cache after successful delivery. */
-function recordNotification(title: string, message: string, data?: NotificationData): void {
+function notificationKey(title: string, message: string, data?: NotificationData): string {
   const dataRecord = data as (NotificationData & { dedupKey?: string }) | undefined;
-  const key = dataRecord?.dedupKey
-    ? dataRecord.dedupKey
-    : `${title}|${message}|${data?.category || 'unknown'}`;
-  notificationCache.set(key, Date.now());
+  return dataRecord?.dedupKey ?? `${title}|${message}|${data?.category || 'unknown'}`;
+}
+
+/** Refresh a reserved dedup key after successful delivery (keeps the window measured from send). */
+function recordNotification(title: string, message: string, data?: NotificationData): void {
+  notificationCache.set(notificationKey(title, message, data), Date.now());
+}
+
+/** Release a reserved dedup key when delivery failed, so a legitimate retry is not blocked. */
+function releaseNotification(title: string, message: string, data?: NotificationData): void {
+  notificationCache.delete(notificationKey(title, message, data));
 }
 
 // TODO(refactor): extract body parsing, filtering, and platform routing into
@@ -501,6 +506,7 @@ export const POST: RequestHandler = async ({ request }) => {
         });
       } else {
         console.error(`[notify] FCM delivery failed: ${fcmResult.error}`);
+        releaseNotification(title, message, data); // free the reserved dedup slot for a retry
 
         addNotification(
           buildNotificationRecord(
@@ -581,6 +587,7 @@ export const POST: RequestHandler = async ({ request }) => {
       } catch (notificationError) {
         const notifErrMsg = toErrorMessage(notificationError);
         console.error(`[notify] APNs delivery failed: ${notifErrMsg}`);
+        releaseNotification(title, message, data); // free the reserved dedup slot for a retry
 
         addNotification(
           buildNotificationRecord(canonicalRequestId, title, message, 'failed', data, notifErrMsg)

package/src/routes/api/presence/+server.ts

@@ -0,0 +1,39 @@
+// Viewer-presence endpoint. The dashboard / phone posts a heartbeat so the autopilot
+// engine can push only when the user is AWAY (not foregrounded) — see presence-store.ts.
+// Distinct from raw WebSocket connection count, which the autonomous loop keeps open.
+
+import { validateAuth } from '$lib/modules/server/auth';
+import {
+  hasEverReported,
+  isViewerPresent,
+  reportPresence,
+} from '$lib/modules/server/ws/presence-store';
+import { json } from '@sveltejs/kit';
+
+import type { RequestHandler } from './$types';
+
+export const GET: RequestHandler = ({ request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  return json({ everReported: hasEverReported(), present: isViewerPresent() });
+};
+
+export const POST: RequestHandler = async ({ request }) => {
+  const authError = validateAuth(request);
+  if (authError) {
+    return authError;
+  }
+  let body: { state?: unknown };
+  try {
+    body = (await request.json()) as { state?: unknown };
+  } catch {
+    return json({ error: 'Invalid JSON body' }, { status: 400 });
+  }
+  if (body.state !== 'foreground' && body.state !== 'background') {
+    return json({ error: "state must be 'foreground' or 'background'" }, { status: 400 });
+  }
+  reportPresence(body.state);
+  return json({ everReported: hasEverReported(), present: isViewerPresent(), state: body.state });
+};