@cplieger/web-terminal-ui 8.6.0-dev.4 → 8.6.0-dev.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "8.6.0-dev.4",
+  "version": "8.6.0-dev.6",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "MPL-2.0",
@@ -44,7 +44,7 @@
     "verify": "bash scripts/verify.sh"
   },
   "peerDependencies": {
-    "@cplieger/web-terminal-engine": "^6.0.0 || ^6.2.0-dev || ^6.4.0-dev"
+    "@cplieger/web-terminal-engine": "^6.4.0-dev.4"
   },
   "overrides": {
     "qs": "^6.15.2"
@@ -64,7 +64,7 @@
     "html-validate": "11.16.2",
     "knip": "6.41.0",
     "playwright": "1.64.0",
-    "prettier": "3.9.9",
+    "prettier": "3.9.10",
     "stylelint": "17.16.0",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",

package/src/features/tabs/index.ts

@@ -28,8 +28,6 @@ import {
 } from "./route.js";
 import type { CueStatus, PaneLayout, SessionInfo, StatusRecord, Tab } from "./model.js";
 import {
-  CUE_SEEN_KEY,
-  MAX_PERSISTED_CUE_SEEN,
   MAX_PINNED_NAME,
   PROGRESS_ABSENT,
   SWIPE_HINT_KEY,
@@ -43,15 +41,14 @@ import {
   hasPinnedName,
   isCueStatus,
   isEndedStatus,
-  isUnseenCue,
+  isUnread,
   normalizeActivity,
   normalizeActivityCount,
   normalizeProgress,
+  normalizeSeq,
   orderedInsertIndex,
-  parseCueSeen,
   renderedProgress,
   sanitizePinnedName,
-  serializeCueSeen,
   statusPhrase,
   summarizeCues,
   tabAccessibleName,
@@ -196,29 +193,6 @@ const CATCHUP_SETTLE_MS = 250;
  *  multiple frames; ordinary streaming must never arm the cue. */
 const CATCHUP_MIN_BACKLOG = 400;
 
-/** The acknowledged background-tab cues, or an empty map when storage throws or
- *  holds nothing trustworthy: the dot simply lights again. */
-function readCueSeen(win: Pick<Window, "localStorage">): Map<string, CueStatus> {
-  try {
-    return parseCueSeen(win.localStorage.getItem(CUE_SEEN_KEY));
-  } catch {
-    return new Map<string, CueStatus>();
-  }
-}
-
-/** writeCueSeen persists acknowledgements, best-effort: a full quota must not
- *  break the dismissal the user just performed on screen. */
-function writeCueSeen(
-  win: Pick<Window, "localStorage">,
-  seen: ReadonlyMap<string, CueStatus>,
-): void {
-  try {
-    win.localStorage.setItem(CUE_SEEN_KEY, serializeCueSeen(seen));
-  } catch {
-    /* storage unavailable or full — the dismissal still holds for this page */
-  }
-}
-
 /** A wait the feature's teardown ends early: the timer goes with the feature. */
 function retryWait(win: Window, ms: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve) => {
@@ -234,6 +208,10 @@ function retryWait(win: Window, ms: number, signal: AbortSignal): Promise<void>
   });
 }
 
+/** Where a status record came from: the stream, or a list requested when the
+ *  stream epoch read `listedAt`. */
+type RecordSource = { readonly stream: true } | { readonly listedAt: number };
+
 /** How long a run of refusals has waited and when it last told the user. */
 interface RefusalWait {
   readonly startedAt: number;
@@ -460,8 +438,8 @@ type SplitOpening =
  *  `/api/sessions`, `?session=<id>` on the WebSocket, ideally the status SSE).
  *  It registers as the terminal's `paneLayoutOwner`, so it decides which session
  *  the first connect attaches to; two owners fail at `kernel-init`. The strip's
- *  order and the pane layout are SERVER state every viewer shares; the dismissed
- *  cues are per-viewer in `localStorage`. Teardown removes the chrome and leaves
+ *  order and the pane layout are SERVER state every viewer shares; which cues
+ *  each session's readers have seen is server state too. Teardown removes the chrome and leaves
  *  the sessions running; closing a tab is what kills a process. */
 export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
   const apiBase = opts.apiBase ?? DEFAULT_API_BASE;
@@ -676,59 +654,92 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       const swSwitchDot = pick(swSwitch, ".wt-switcher-switch-dot");
       const swNew = makeNewButton("wt-switcher-new wt-btn wt-switcher-new-btn");
       swBar.append(swKb, ...(swSplit === null ? [] : [swSplit]), swSwitch, swNew);
-      // Latest-wins cue for the switch button's dot, cleared when the list opens or
-      // the raising tab is visited or closed; "" is no pending cue.
+      // Latest-wins cue for the switch button's dot, cleared when the list opens,
+      // the raising tab is visited or closed, or its occurrence (switchNotifySeq)
+      // is read on any window or device; "" is no pending cue.
       let switchNotify: "" | CueStatus = "";
       // The session that raised the pending cue, so arriving on that tab (a
       // swipe or any switch) acknowledges it without opening the list.
       let switchNotifyId: string | null = null;
-      // Cues this viewer has already SEEN, per session (see CUE_SEEN_KEY).
-      // Loaded here so a reload starts from what the user already dismissed:
-      // input/done stay LATCHED server-side, and the status stream re-pushes the
-      // latch in the snapshot it sends on every open, so without this a
-      // dismissed dot came back on the next load — and on every SSE reconnect,
-      // which on a phone is just returning to a backgrounded page.
-      const cueSeen = readCueSeen(win);
-      // markCueSeen records that this viewer has seen `id` holding `status`:
-      // either because that tab is the one on screen, or because the tray listing
-      // every tab's dot was opened. A non-cue status is not an acknowledgeable
-      // event, so it is ignored rather than stored.
-      function markCueSeen(id: string, status: string): void {
-        if (!isCueStatus(status) || cueSeen.get(id) === status) {
+      let switchNotifySeq = 0;
+      // Counts status-stream records; applyStatus compares a list's reading of it
+      // with each tab's streamAt to skip a list older than the stream.
+      let streamEpoch = 0;
+      let warnedSeen = false;
+      // The out-of-page surfaces render the SAME unread-cue set the switch dot
+      // shows, fed only through paintAttention below.
+      const attention = ctx.shell.attention({ icons: opts.attentionIcons === true });
+      // markCueSeen acknowledges t's current occurrence for every reader: the tab
+      // is on screen, or the tray listing every tab's dot was opened. Every read
+      // re-asserts the badge, which may still show a write the platform dropped,
+      // and closes the session's banner. The surfaces clear before the round trip,
+      // so a cue landing on the watched tab never paints a count. The automatic
+      // path (retry false) skips an occurrence whose ack already failed, so a
+      // failing server sees one PUT per occurrence rather than one per record.
+      function markCueSeen(t: Tab, how: { readonly retry: boolean }): void {
+        attention.resync();
+        ctx.shell.notifications.retract(t.id);
+        t.bannerSeq = 0;
+        if (!isCueStatus(statusOf(t)) || t.statusSeq <= Math.max(t.seenSeq, t.ackSeq)) {
           return;
         }
-        cueSeen.set(id, status);
-        // Evict the oldest entries so the live map obeys the same cap the parser
-        // does. dropTab prunes a session closed while this page was open, but one
-        // that vanished while the page was CLOSED leaves an entry nothing else
-        // collects; unbounded, that would eventually push the map past the cap and
-        // make the parser discard whatever it read last — dropping fresh
-        // acknowledgements to keep dead ones.
-        while (cueSeen.size > MAX_PERSISTED_CUE_SEEN) {
-          const oldest = cueSeen.keys().next().value;
-          if (oldest === undefined) {
-            break;
-          }
-          cueSeen.delete(oldest);
+        if (!how.retry && t.failedSeq === t.statusSeq) {
+          return;
         }
-        writeCueSeen(win, cueSeen);
-        // An acknowledgement can change the unseen count without touching the tab
-        // list, so syncChrome's sweep is not enough on its own: opening the tray
-        // and arriving on a tab both land here and neither adds or removes a chip.
+        const seq = t.statusSeq;
+        t.ackSeq = seq;
+        closeReadSurfaces(t);
         paintAttention();
+        api.markSeen(t.id, seq).then(
+          () => {
+            if (tornDown() || !tabList.includes(t)) {
+              return;
+            }
+            // seq came from the server, so a 204 means its floor is at least seq.
+            t.seenSeq = Math.max(t.seenSeq, seq);
+            if (t.ackSeq <= t.seenSeq) {
+              t.ackSeq = 0;
+            }
+            if (t.failedSeq <= seq) {
+              t.failedSeq = 0;
+            }
+          },
+          (err: unknown) => {
+            if (tornDown() || !tabList.includes(t)) {
+              return;
+            }
+            if (err instanceof SessionAPIError && err.status === 404) {
+              return; // the session is gone; its removal drops the tab
+            }
+            // A later ack owns ackSeq, and seenSeq is never written here: a
+            // broadcast may already carry this ack though its response was lost.
+            if (t.ackSeq === seq) {
+              t.ackSeq = 0;
+            }
+            t.failedSeq = Math.max(t.failedSeq, seq);
+            if (!warnedSeen) {
+              warnedSeen = true;
+              console.warn("web-terminal-ui: marking a session read failed", err);
+            }
+            paintAttention();
+          },
+        );
       }
-      // forgetCueSeen drops an acknowledgement, so the session's NEXT input/done
-      // is a fresh cue: called when its status moves off the acknowledged value
-      // (a new working phase, an exit) and when the session goes away. Every
-      // caller ends in syncChrome, which repaints the out-of-page surfaces.
-      function forgetCueSeen(id: string): void {
-        if (cueSeen.delete(id)) {
-          writeCueSeen(win, cueSeen);
+      // A surface this page raised for an occurrence closes once the page's read
+      // floor reaches that occurrence, keyed on the number rather than the fold: a
+      // done held by background activity folds to "" yet may own a banner, and a
+      // late ack of an older occurrence must not close one raised for a newer.
+      function closeReadSurfaces(t: Tab): void {
+        const floor = Math.max(t.seenSeq, t.ackSeq);
+        if (t.bannerSeq !== 0 && floor >= t.bannerSeq) {
+          ctx.shell.notifications.retract(t.id); // only this page can close its own banners
+          t.bannerSeq = 0;
+        }
+        if (switchNotifyId === t.id && floor >= switchNotifySeq) {
+          clearSwitchNotify();
         }
+        attention.resync();
       }
-      // The out-of-page surfaces render the SAME unseen-cue set the switch dot
-      // shows, fed only through paintAttention below.
-      const attention = ctx.shell.attention({ icons: opts.attentionIcons === true });
       // visibilityState, not document.hasFocus(), which is false for a
       // visible-but-unfocused window where the terminal IS on screen.
       function pageVisible(): boolean {
@@ -738,29 +749,46 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // The DEFERRED half of the shown-tab acknowledgement: a cue that latched on
       // a hidden page raised the out-of-page surfaces and is acknowledged when the
       // user can see the terminal. The SHOWN tabs only: blanking a background
-      // tab's cue the viewer never saw loses the thing they came back for.
+      // tab's cue the viewer never saw loses the thing they came back for. Also
+      // the retry point for a failed ack.
       function onPageVisible(): void {
         if (!pageVisible()) {
           return;
         }
         for (const t of tabList) {
           if (isShown(t.id)) {
-            markCueSeen(t.id, statusOf(t));
+            markCueSeen(t, { retry: true });
           }
         }
       }
       doc.addEventListener("visibilitychange", onPageVisible);
+      // A desktop window can regain focus while it stays visible, which fires no
+      // visibilitychange.
+      win.addEventListener("focus", onPageVisible);
       ctx.defer(() => {
         doc.removeEventListener("visibilitychange", onPageVisible);
+        win.removeEventListener("focus", onPageVisible);
       });
 
+      /** The cue fold's view of a tab (isUnread), shared by the count and the raise. */
+      function fold(t: Tab): {
+        status: string;
+        statusSeq: number;
+        seenSeq: number;
+        ackSeq: number;
+      } {
+        return {
+          status: cueStatusOf(t),
+          statusSeq: t.statusSeq,
+          seenSeq: t.seenSeq,
+          ackSeq: t.ackSeq,
+        };
+      }
+
       // A FOLD over the tab list rather than incremental bookkeeping: no state of
       // its own can go stale, and the shell no-ops when nothing changed.
       function paintAttention(): void {
-        const { count, worst } = summarizeCues(
-          tabList.map((t) => ({ id: t.id, status: cueStatusOf(t) })),
-          cueSeen,
-        );
+        const { count, worst } = summarizeCues(tabList.map(fold));
         attention.report({ count, icon: worst === "" ? null : cueIconName(worst) });
       }
       function paintSwitchDot(): void {
@@ -778,11 +806,12 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       function clearSwitchNotify(): void {
         switchNotify = "";
         switchNotifyId = null;
+        switchNotifySeq = 0;
         paintSwitchDot();
       }
       // The pending cue is resolved when its session is reached (a switch, a swipe
       // arriving on it) and moot when the session ceases to exist (a close, a
-      // reap); opening the list alone does not clear it.
+      // reap).
       function acknowledgeSwitchNotify(id: string): void {
         if (switchNotifyId === id) {
           clearSwitchNotify();
@@ -1537,9 +1566,9 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // The tray lists EVERY tab with its own status dot, so every latched tab
         // is acknowledged here, not just the cue's latest subject — several tabs
         // can be latched at once while the dot only ever showed the newest, and an
-        // unacknowledged sibling would re-raise it on the next load.
+        // unread sibling would stay unread on every device.
         for (const t of tabList) {
-          markCueSeen(t.id, t.dot.dataset["status"] ?? "");
+          markCueSeen(t, { retry: true });
         }
         clearSwitchNotify();
         renderSwitcherList();
@@ -1618,6 +1647,13 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           aria,
           view: null,
           reports: reportsOf(info.reportsActivity),
+          // The boot list adopts without applyStatus, so these carry its numbers.
+          statusSeq: normalizeSeq(info.statusSeq) ?? 0,
+          seenSeq: normalizeSeq(info.seenSeq) ?? 0,
+          ackSeq: 0,
+          failedSeq: 0,
+          bannerSeq: 0,
+          streamAt: 0,
         };
         paintProgress(progressEl, renderedProgress(info.status, tab.progress));
         paintActivityMark(activityEl, tab.activity, tab.activityCount);
@@ -1835,7 +1871,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // The terminal is now on screen, so a reload must not notify about a state
         // the user just looked at.
         acknowledgeSwitchNotify(next.id);
-        markCueSeen(next.id, next.dot.dataset["status"] ?? "");
+        markCueSeen(next, { retry: true });
         const moveSelection = how.keepSelection !== true || selectedId() === null;
         // The view goes in WITH the bind, which makes the swap atomic: the pane's
         // follow flag is one per renderer, so a bind without it gated the first
@@ -2725,11 +2761,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // the server reaping it cannot re-adopt the just-closed tab.
         tombstones.add(id);
         // A pending switch-button cue whose subject just closed is moot: clear
-        // it rather than leaving a dot no tab visit can ever resolve. Its stored
-        // acknowledgement goes too — the session is gone, so the entry would only
-        // sit in storage forever.
+        // it rather than leaving a dot no tab visit can ever resolve.
         acknowledgeSwitchNotify(id);
-        forgetCueSeen(id);
         ctx.shell.notifications.forget(id);
         tab.aria.remove();
         // Remove immediately (no exit animation): a lingering element made the
@@ -2833,7 +2866,6 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           // re-adopt a just-closed tab.
           tombstones.add(t.id);
           acknowledgeSwitchNotify(t.id);
-          forgetCueSeen(t.id);
           ctx.shell.notifications.forget(t.id);
           t.aria.remove();
           abortReorderFor(t.el); // a live drag holds this node
@@ -3269,13 +3301,28 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
 
       // Takes the record whole: its title fields are interchangeable strings that
       // as positional parameters would be swappable. `reports` travels separately
-      // because it is normalised (reportsOf) first.
-      function applyStatus(rec: StatusRecord, reports: boolean): void {
+      // because it is normalised (reportsOf) first. `source` says whether the
+      // record came off the stream or from a list requested at stream epoch
+      // `listedAt`.
+      function applyStatus(rec: StatusRecord, reports: boolean, source: RecordSource): void {
         const t = tabList.find((tab) => tab.id === rec.id);
         if (!t) {
           return;
         }
-        t.reports = reports;
+        if ("stream" in source) {
+          t.streamAt = streamEpoch;
+        }
+        // The stream-owned tuple is skipped from a list older than the stream's
+        // last record for the tab, or carrying an older occurrence: anything such a
+        // list could add arrives on the stream anyway, and applying it can hide a
+        // cue no later frame restores.
+        const seq = normalizeSeq(rec.statusSeq);
+        const stale =
+          ("listedAt" in source && t.streamAt > source.listedAt) ||
+          (seq !== null && seq < t.statusSeq);
+        if (!stale) {
+          applyStreamTuple(t, rec, reports, seq);
+        }
         // The server's shared position. Only an explicitly PRESENT value updates
         // the tab, for the same reason as progressValue below: an engine that
         // keeps no order sends no field, and reading that absence as "position 0"
@@ -3293,50 +3340,30 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
             scheduleAddress("replace");
           }
         }
-        paintStatusDot(t.dot, rec.status, reports);
-        // Only a PRESENT percentage updates the tab: the polling fallback lists
-        // SessionInfo, which carries none, and reading absence as cleared would
-        // blank a live bar every tick. A clear arrives as an explicit -1.
-        if (rec.progressValue !== undefined) {
-          t.progress = normalizeProgress(rec.progressValue);
-        }
-        paintProgress(t.progressEl, shownProgress(t));
-        // The host's secondary activity, read with the same PRESENT-only guard and
-        // for the same reason: the polling fallback lists SessionInfo, and a
-        // pre-release server carries neither field at all, so reading absence as
-        // "no background task" would blank a live mark on every tick. An empty
-        // string IS the withdrawal, and it arrives explicitly.
-        if (rec.activity !== undefined) {
-          t.activity = normalizeActivity(rec.activity);
+        // The seen floor only rises, so a lower value is an older record.
+        const seen = normalizeSeq(rec.seenSeq);
+        if (seen !== null && seen > t.seenSeq) {
+          t.seenSeq = seen;
+          closeReadSurfaces(t);
         }
-        if (rec.activityCount !== undefined) {
-          t.activityCount = normalizeActivityCount(rec.activityCount);
-        }
-        paintActivityMark(t.activityEl, t.activity, t.activityCount);
         // A program that speaks OSC 9 may also post a notification: arm the
         // permission request for the next user gesture.
         if (reports) {
           ctx.shell.notifications.arm();
         }
-        // The switch button's latest-wins dot. Cue statuses are LATCHED server-side
-        // and re-delivered on every snapshot, so cueSeen is what makes a dismissal
-        // stick. The acknowledgement reads the RAW status (a non-cue must reach the
-        // forget below); the raise and the forget read the FOLDED one.
-        const raw = statusOf(t);
-        const cue = cueStatusOf(t);
-        if (isShown(rec.id) && pageVisible() && isCueStatus(raw)) {
+        // The switch button's latest-wins dot. The acknowledgement reads the RAW
+        // status; the raise reads the FOLDED one, so a done held by background
+        // activity raises nothing.
+        const folded = fold(t);
+        if (isShown(rec.id) && pageVisible() && isCueStatus(statusOf(t))) {
           // BOTH halves: keyed on the shown tabs alone, this swallowed the cue of
           // the one session the user left running on a hidden page, the case the
           // out-of-page surfaces exist for.
-          markCueSeen(rec.id, raw);
-        } else if (cue === "") {
-          // NO INFORMATION: forgetting here would re-raise the cue from scratch
-          // the moment the background task ended.
-        } else if (!isCueStatus(cue)) {
-          forgetCueSeen(rec.id);
-        } else if (isUnseenCue(cue, rec.id, cueSeen)) {
-          switchNotify = cue;
+          markCueSeen(t, { retry: false });
+        } else if (isUnread(folded)) {
+          switchNotify = folded.status;
           switchNotifyId = rec.id;
+          switchNotifySeq = t.statusSeq;
           paintSwitchDot();
         }
         // A BLANK title (a status sweep, or the process clearing its OSC 0/2
@@ -3355,6 +3382,40 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         }
       }
 
+      // The fields only the stream decides: the status and its dot, its
+      // occurrence number, the reveal gate, the percentage and the activity pair.
+      function applyStreamTuple(
+        t: Tab,
+        rec: StatusRecord,
+        reports: boolean,
+        seq: number | null,
+      ): void {
+        t.reports = reports;
+        if (seq !== null) {
+          t.statusSeq = seq;
+        }
+        paintStatusDot(t.dot, rec.status, reports);
+        // Only a PRESENT percentage updates the tab: the polling fallback lists
+        // SessionInfo, which carries none, and reading absence as cleared would
+        // blank a live bar every tick. A clear arrives as an explicit -1.
+        if (rec.progressValue !== undefined) {
+          t.progress = normalizeProgress(rec.progressValue);
+        }
+        paintProgress(t.progressEl, shownProgress(t));
+        // The host's secondary activity, read with the same PRESENT-only guard and
+        // for the same reason: the polling fallback lists SessionInfo, and a
+        // pre-release server carries neither field at all, so reading absence as
+        // "no background task" would blank a live mark on every tick. An empty
+        // string IS the withdrawal, and it arrives explicitly.
+        if (rec.activity !== undefined) {
+          t.activity = normalizeActivity(rec.activity);
+        }
+        if (rec.activityCount !== undefined) {
+          t.activityCount = normalizeActivityCount(rec.activityCount);
+        }
+        paintActivityMark(t.activityEl, t.activity, t.activityCount);
+      }
+
       // One list reconcile for both status sources: adopt every session the
       // server lists, then drop tabs it no longer lists. The SSE path runs it on
       // every (re)open because a RESTARTED manager's snapshot carries no
@@ -3413,6 +3474,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // requested: a tab adopted while the GET was in flight is invisible to
         // it, and dropping it here cascaded into a duplicate replacement session.
         const epochAtList = tabEpoch;
+        const listedAt = streamEpoch;
         let list: SessionInfo[];
         try {
           list = await api.list();
@@ -3435,7 +3497,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         }
         for (const info of list) {
           adoptSession(info); // add sessions created elsewhere (no local tab)
-          applyStatus(info, reportsOf(info.reportsActivity));
+          applyStatus(info, reportsOf(info.reportsActivity), { listedAt });
         }
         // Already gone server-side, so no DELETE; tabs born after the snapshot
         // wait for the next reconcile.
@@ -3472,13 +3534,14 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
                 applyingRecord = false;
               }
             }
+            const listedAt = streamEpoch;
             const settled = await settleOrToast();
             if (tornDown()) {
               return;
             }
             for (const info of settled.sessions) {
               adoptSession(info);
-              applyStatus(info, reportsOf(info.reportsActivity));
+              applyStatus(info, reportsOf(info.reportsActivity), { listedAt });
             }
             // Read now, so an address the user navigated to during the wait wins.
             const route =
@@ -3714,14 +3777,15 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
             void dropTab(s.id, { remote: false }); // already gone server-side; no DELETE
             return;
           }
+          streamEpoch++;
           adoptSession(s);
-          applyStatus(s, reportsOf(s.reportsActivity));
+          applyStatus(s, reportsOf(s.reportsActivity), { stream: true });
           ensureActive();
           syncChrome();
           // A notification is an EVENT delivered once, so it is handled here and
           // not in applyStatus, which also runs on re-delivered STATE. After
           // syncChrome, so its title is the label the user would see.
-          ctx.shell.notifications.deliver(s, {
+          const posted = ctx.shell.notifications.deliver(s, {
             sessionIsActive: isShown(s.id),
             label: tabList.find((t) => t.id === s.id)?.display ?? s.title,
             // switchTo no-ops on an id that is gone, which is the case that
@@ -3730,6 +3794,11 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
               switchTo(s.id);
             },
           });
+          const shownFor = posted ? tabList.find((t) => t.id === s.id) : undefined;
+          if (shownFor) {
+            // The event's own number: a skipped tuple leaves the tab's newer.
+            shownFor.bannerSeq = normalizeSeq(s.statusSeq) ?? shownFor.statusSeq;
+          }
         });
         ctx.defer(offStatus);
         // The first open joins the boot's reconcile. A reopen queues a fresh one
@@ -3738,11 +3807,14 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         let streamOpens = 0;
         const offStreamOpen = monitor.onStreamOpen?.(() => {
           streamOpens++;
-          if (streamOpens === 1) {
-            void reconcileOnce();
-          } else {
-            void withPlacementHold(() => inReconcileSlot(reconcileNow));
-          }
+          const settled =
+            streamOpens === 1
+              ? reconcileOnce()
+              : withPlacementHold(() => inReconcileSlot(reconcileNow));
+          void settled.then(() => {
+            attention.resync();
+            onPageVisible(); // re-acks the shown tabs, now reconciled
+          });
         });
         if (offStreamOpen) {
           ctx.defer(offStreamOpen);

package/src/features/tabs/model.ts

@@ -183,7 +183,7 @@ export const SWIPE_HINT_KEY = "wt-swipe-hint-seen";
  *  a notification. `working` and `warning` are ongoing and informational, so a
  *  dot for them would nag with nothing to act on; `failed` is a parked result the
  *  program does not revisit, so it belongs. Declared once so the raise test, the
- *  acknowledgement store and every attention sink cannot disagree. */
+ *  acknowledgement and every attention sink cannot disagree. */
 export type CueStatus = "input" | "done" | "crashed" | "failed";
 
 /** Severity order, most severe first, AND the complete set isCueStatus tests
@@ -226,10 +226,8 @@ export function cueIconName(status: CueStatus): "input" | "done" | "alert" {
 const SETTLED_CUES: ReadonlySet<string> = new Set<CueStatus>(["done"]);
 
 /** The status the CUE surfaces see: the session's own, unless a settled turn's
- *  background task is still running, in which case "". "" and NOT "idle": "" means
- *  NO INFORMATION, so the seen map is left alone, where "idle" is a real non-cue
- *  state that would forget the acknowledgement and re-raise the cue when the task
- *  ends. The status DOT keeps rendering the real state. */
+ *  background task is still running, in which case "" (no cue). The status DOT
+ *  keeps rendering the real state. */
 export function foldedCueStatus(status: string, activity: string): string {
   if (!SETTLED_CUES.has(status) || normalizeActivity(activity) === "") {
     return status;
@@ -237,25 +235,29 @@ export function foldedCueStatus(status: string, activity: string): string {
   return "";
 }
 
-/** Whether a session's CURRENT status is a cue this viewer has not acknowledged;
- *  the one predicate behind the raise and the attention count. A latch arriving
- *  on a shown tab is acknowledged at arrival, so no caller needs a special case. */
-export function isUnseenCue(
-  status: string,
-  id: string,
-  seen: ReadonlyMap<string, CueStatus>,
-): status is CueStatus {
-  return isCueStatus(status) && seen.get(id) !== status;
-}
-
 /** What the cue fold reads per tab; structural, so a caller passes its own tab
- *  objects. */
+ *  objects. `status` is the FOLDED status (foldedCueStatus). */
 interface CueCandidate {
-  readonly id: string;
   readonly status: string;
+  /** the server's number for that status's occurrence */
+  readonly statusSeq: number;
+  /** the server-confirmed seen floor */
+  readonly seenSeq: number;
+  /** this page's optimistic read floor, 0 when none */
+  readonly ackSeq: number;
 }
 
-/** The unseen cues over the tab list: a COUNT for the title and the badge, one
+/** Whether a session's CURRENT status is a cue no reader has acknowledged; the
+ *  one predicate behind the raise and the attention count. The floor is the
+ *  higher of what the server confirmed and what this page has already sent, so
+ *  a read paints at once and a lagging record cannot relight it. */
+export function isUnread<T extends CueCandidate>(
+  tab: T,
+): tab is T & { readonly status: CueStatus } {
+  return isCueStatus(tab.status) && tab.statusSeq > Math.max(tab.seenSeq, tab.ackSeq);
+}
+
+/** The unread cues over the tab list: a COUNT for the title and the badge, one
  *  WORST for the icon. A count is set-valued and needs no rule for choosing among
  *  sessions; severity is a total order, so the icon's choice is not arbitrary.
  *  Neither names a session, the standing constraint on a page-wide surface. */
@@ -264,16 +266,12 @@ interface CueSummary {
   readonly worst: CueStatus | "";
 }
 
-/** Fold the tab list and this viewer's acknowledgements into the one summary
- *  every attention surface renders. */
-export function summarizeCues(
-  tabs: readonly CueCandidate[],
-  seen: ReadonlyMap<string, CueStatus>,
-): CueSummary {
+/** Fold the tab list into the one summary every attention surface renders. */
+export function summarizeCues(tabs: readonly CueCandidate[]): CueSummary {
   let count = 0;
   let worst: CueStatus | "" = "";
   for (const tab of tabs) {
-    if (!isUnseenCue(tab.status, tab.id, seen)) {
+    if (!isUnread(tab)) {
       continue;
     }
     count += 1;
@@ -282,52 +280,10 @@ export function summarizeCues(
   return { count, worst };
 }
 
-/** localStorage key for the cues this viewer has SEEN: session id -> the
- *  acknowledged status. Remembered because `input` and `done` are latched on the
- *  server and re-delivered in every snapshot, so a dismissed dot came back on
- *  every reload; client-side because "seen" is the VIEWER's, not the session's;
- *  per session because several background tabs can hold a latch at once. */
-export const CUE_SEEN_KEY = "wt-cue-seen";
-
-/** Bound on the acknowledgement map, so a corrupted or hostile stored value
- *  cannot make the restore path do unbounded work. */
-export const MAX_PERSISTED_CUE_SEEN = 200;
-
-/** Read stored acknowledgements into a clean map, dropping anything untrusted: a
- *  lost acknowledgement only re-lights a dot the user can dismiss again. */
-export function parseCueSeen(raw: string | null): Map<string, CueStatus> {
-  const out = new Map<string, CueStatus>();
-  if (raw === null) {
-    return out;
-  }
-  let data: unknown;
-  try {
-    data = JSON.parse(raw);
-  } catch {
-    return out;
-  }
-  // Arrays and null are typeof "object" too, and neither is a cue map.
-  if (typeof data !== "object" || data === null || Array.isArray(data)) {
-    return out;
-  }
-  for (const [id, status] of Object.entries(data)) {
-    if (id === "" || typeof status !== "string" || !isCueStatus(status)) {
-      continue;
-    }
-    out.set(id, status);
-    if (out.size >= MAX_PERSISTED_CUE_SEEN) {
-      break;
-    }
-  }
-  return out;
-}
-
-/** serializeCueSeen encodes acknowledgements for storage. The caller keeps the
- *  live map within the cap (see markCueSeen), so this does not truncate: a silent
- *  truncation here would drop whichever entries the parser happened to read last,
- *  which is the opposite of what an eviction should discard. */
-export function serializeCueSeen(seen: ReadonlyMap<string, CueStatus>): string {
-  return JSON.stringify(Object.fromEntries(seen));
+/** A status-occurrence number off the wire: a non-negative safe integer, or null
+ *  for anything else, which leaves the tab's value unchanged. */
+export function normalizeSeq(raw: unknown): number | null {
+  return typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 0 ? raw : null;
 }
 
 /** TabOrderKey is what the strip's order is decided by: the server's shared
@@ -457,6 +413,25 @@ export interface Tab {
    *  tab menu's "use the automatic name" action. Undefined or empty means the tab
    *  has no user-set name. */
   pinnedTitle?: string | undefined;
+  /** The server's number for the status this tab holds (0: none yet). */
+  statusSeq: number;
+  /** The server-confirmed seen floor. Only rises: a record carrying a lower one
+   *  is older, never a retraction. */
+  seenSeq: number;
+  /** This page's optimistic read floor: the occurrence its latest ack sent, 0
+   *  when none. A 204 clears it once seenSeq covers it, and a non-404 failure
+   *  only while it still holds the failed number; a 404 keeps it until the
+   *  vanished tab is removed. */
+  ackSeq: number;
+  /** The occurrence whose ack last failed with a non-404, 0 when none; the
+   *  automatic ack skips it so a failing server sees one PUT per occurrence. */
+  failedSeq: number;
+  /** The occurrence a banner this page posted for the session belongs to, 0
+   *  when none. */
+  bannerSeq: number;
+  /** The stream epoch at which a status-stream record last updated this tab, 0
+   *  when none: a list requested before it is older. */
+  streamAt: number;
   /** Monotonic per-tab rename counter. A rename or clear increments it and
    *  captures the value; the response is applied only if it is still current when
    *  it lands, so a slow failure cannot roll back a newer rename, a later clear,
@@ -518,6 +493,12 @@ interface SessionAPI {
   /** Replace the shared pane layout. Throws on non-2xx as `setOrder` does: a 409
    *  means a side names a session that is not live. */
   setLayout(layout: PaneLayout): Promise<void>;
+  /** Acknowledge `seq` for every reader. The server keeps the higher floor and
+   *  caps it at its own statusSeq, so a resolve confirms the floor reached `seq`
+   *  only for a `seq` this page received. Throws a SessionAPIError on non-2xx; a
+   *  404 means the session is gone. Sent with `keepalive`, so a read just before
+   *  the page goes away still lands. */
+  markSeen(id: string, seq: number): Promise<void>;
 }
 
 /** The server's pane-layout record: which session each pane shows, the handle's
@@ -754,6 +735,17 @@ export function createSessionAPI(apiBase: string, realm: SessionAPIRealm): Sessi
         throw await sessionError("set layout", r);
       }
     },
+    async markSeen(id: string, seq: number): Promise<void> {
+      const r = await request(`${apiBase}/${encodeURIComponent(id)}/seen`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ seq }),
+        keepalive: true,
+      });
+      if (!r.ok) {
+        throw await sessionError("mark seen", r);
+      }
+    },
   };
 }
 

package/src/kernel/attention.ts

@@ -40,17 +40,18 @@ export function iconVariantHref(href: string, variant: string): string | null {
   return `${href.slice(0, at)}-${variant}${href.slice(at)}`;
 }
 
-/** Render reports onto `sinks`, change-gated on the last rendered value: the
- *  title doubles as the browser-tab label and the bookmark name, and
- *  re-assigning an icon href makes some browsers re-fetch it. `pagehide` restores
- *  the surfaces (a browser remembers ONE icon per URL for the bookmark and the
- *  history row, so a tab closed on a lit cue would leave a status variant standing
- *  in for the app), `pageshow` repaints the last report for a page that came back
- *  from the back-forward cache, and `freeze` changes nothing because a frozen tab
- *  is still in the strip rendering its icon. */
+/** Render reports onto `sinks`. The title and icon are change-gated: the title is
+ *  also the tab label and bookmark name, and re-assigning an icon href makes some
+ *  browsers re-fetch it. The badge is OS state a platform may drop a write to
+ *  without rejecting, so it is also re-asserted on `resync`, a return to visible,
+ *  window focus and `pageshow`. `pagehide` restores the title and icon (a browser
+ *  remembers ONE icon per URL) but leaves the badge, which means "unread" for the
+ *  whole app rather than for this page. */
 export function createAttention(sinks: AttentionSinks, win: Window): AttentionSurface {
-  let reported: AttentionState = NO_ATTENTION;
+  let reported: AttentionState | null = null;
   let rendered: AttentionState | null = null;
+  let badged: number | null = null;
+  let pendingResync: number | null = null;
 
   function render(next: AttentionState): void {
     const countChanged = next.count !== rendered?.count;
@@ -58,24 +59,58 @@ export function createAttention(sinks: AttentionSinks, win: Window): AttentionSu
     rendered = next;
     if (countChanged) {
       sinks.setTitleMark(titleMarkFor(next.count));
-      sinks.setBadge?.(next.count);
     }
     if (iconChanged) {
       sinks.setIcon?.(next.icon);
     }
   }
+  function cancelResync(): void {
+    if (pendingResync !== null) {
+      win.clearTimeout(pendingResync);
+      pendingResync = null;
+    }
+  }
+  function writeBadge(count: number): void {
+    cancelResync();
+    badged = count;
+    sinks.setBadge?.(count);
+  }
+  const listeners = new AbortController();
+  const { signal } = listeners;
+  // Deferred a task so this surface's listener and the caller's report on one
+  // event write once. Before the first report, a write would wipe the badge
+  // another page or a previous run set; after dispose, it would raise a cleared one.
+  function resync(): void {
+    if (reported === null || signal.aborted || pendingResync !== null) {
+      return;
+    }
+    pendingResync = win.setTimeout(() => {
+      pendingResync = null;
+      if (reported !== null && !signal.aborted) {
+        writeBadge(reported.count);
+      }
+    }, 0);
+  }
 
   function onPageGone(): void {
     render(NO_ATTENTION);
   }
   function onPageBack(): void {
-    render(reported);
+    if (reported !== null) {
+      render(reported);
+    }
+    resync();
+  }
+  function onVisibility(): void {
+    if (win.document.visibilityState !== "hidden") {
+      resync();
+    }
   }
-  const listeners = new AbortController();
-  const { signal } = listeners;
   try {
     win.addEventListener("pagehide", onPageGone, { signal });
     win.addEventListener("pageshow", onPageBack, { signal });
+    win.addEventListener("focus", resync, { signal });
+    win.document.addEventListener("visibilitychange", onVisibility, { signal });
   } catch (err) {
     listeners.abort();
     throw err;
@@ -85,10 +120,15 @@ export function createAttention(sinks: AttentionSinks, win: Window): AttentionSu
     report(state) {
       reported = state;
       render(state);
+      if (state.count !== badged) {
+        writeBadge(state.count);
+      }
     },
+    resync,
     dispose() {
       listeners.abort();
       render(NO_ATTENTION);
+      writeBadge(0);
     },
   };
 }

package/src/kernel/notify.ts

@@ -38,24 +38,41 @@ export function shouldNotify(sessionIsActive: boolean, pageVisible: boolean): bo
   return !(sessionIsActive && pageVisible);
 }
 
-/** Bound on the per-session dedupe map: each key is a live session server-side,
- *  so a real page is nowhere near this and a hostile stream cannot grow it. */
+/** Bound on each per-session map: each key is a live session server-side, so a
+ *  real page is nowhere near this and a hostile stream cannot grow it. */
 const MAX_TRACKED_SESSIONS = 200;
 
 export function createNotifier(env: NotifierEnv): Notifier {
   // Highest sequence delivered per session. The engine never replays a
   // notification; this makes a doubled frame unable to notify twice for one event.
   const lastSeq = new Map<string, number>();
+  // The banner on screen per session. A page notification is invisible to
+  // ServiceWorkerRegistration.getNotifications(), so only this reference can
+  // close it once its session is read.
+  const shown = new Map<string, NotificationLike>();
   let armed = false;
   let requested = false;
 
-  function evict(): void {
-    while (lastSeq.size > MAX_TRACKED_SESSIONS) {
-      const oldest = lastSeq.keys().next().value;
+  // `drop` must remove the key, or this never ends.
+  function evict(map: Map<string, unknown>, drop: (id: string) => void): void {
+    while (map.size > MAX_TRACKED_SESSIONS) {
+      const oldest = map.keys().next().value;
       if (oldest === undefined) {
         return;
       }
-      lastSeq.delete(oldest);
+      drop(oldest);
+    }
+  }
+  function retract(id: string): void {
+    const posted = shown.get(id);
+    if (posted === undefined) {
+      return;
+    }
+    shown.delete(id);
+    try {
+      posted.close();
+    } catch {
+      /* a banner the platform already took down */
     }
   }
 
@@ -71,7 +88,7 @@ export function createNotifier(env: NotifierEnv): Notifier {
           return false;
         }
         lastSeq.set(ev.id, seq);
-        evict();
+        evict(lastSeq, (id) => lastSeq.delete(id));
       }
       if (!shouldNotify(view.sessionIsActive, env.pageVisible())) {
         return false;
@@ -90,7 +107,16 @@ export function createNotifier(env: NotifierEnv): Notifier {
         posted.onclick = (): void => {
           view.activate();
           posted.close();
+          if (shown.get(ev.id) === posted) {
+            shown.delete(ev.id);
+          }
         };
+        // Re-inserted so map order is banner age, and the banner evicted is
+        // closed: a dropped reference would leave it (and Android's launcher
+        // dot) up with nothing able to retract it.
+        shown.delete(ev.id);
+        shown.set(ev.id, posted);
+        evict(shown, retract);
         return true;
       } catch {
         // Safari throws on `new Notification` outside an installed PWA.
@@ -117,8 +143,10 @@ export function createNotifier(env: NotifierEnv): Notifier {
         /* a browser that refuses to be asked is a tab-only browser */
       }
     },
+    retract,
     forget(id): void {
       lastSeq.delete(id);
+      retract(id);
     },
   };
 }

package/src/kernel/shell.ts

@@ -438,7 +438,7 @@ function createShellInto(
   function attention(options: AttentionOptions): AttentionReporter {
     // A setup still running past destroy() gets a reporter that writes nothing.
     if (destroyed) {
-      return { report: () => undefined };
+      return { report: () => undefined, resync: () => undefined };
     }
     const surface = createAttention(
       browserAttentionSinks(

package/src/kernel/types.ts

@@ -240,6 +240,12 @@ export interface AttentionReporter {
   /** Render `state`. Idempotent: a state equal to the last one reported touches
    *  nothing, so a status sweep may call it every tick. */
   report(state: AttentionState): void;
+  /** Write the latest reported count to the app badge again on the next task,
+   *  changed or not; a `report` that writes the badge before then satisfies it.
+   *  The page cannot read the badge back and a platform may drop a write
+   *  silently, so a caller resyncs wherever the two may have diverged, ahead of
+   *  the report that follows. A no-op before the first report. */
+  resync(): void;
 }
 
 /** The notification a session status event carries (OSC 9 `<message>`). Both
@@ -276,7 +282,10 @@ export interface Notifier {
   arm(): void;
   /** Note a user gesture: the ONLY moment a permission prompt may be raised. */
   gesture(): void;
-  /** Drop a closed session's dedupe state. */
+  /** Close the notification delivered for `id`, if one is still up: the user has
+   *  seen that session, so the banner no longer reports anything unread. */
+  retract(id: string): void;
+  /** Drop a closed session's dedupe state and retract its notification. */
   forget(id: string): void;
 }