@cowwo/dsh-icon-custom 0.10.2 → 0.12.0

package/client/client.js

@@ -69,11 +69,18 @@ window.__ModuleLoader__.load({
 			ageMonths: "{n}个月",
 			ageYears: "{n}年",
 			workspaceDotLabel: "在工作区和会话行上显示红点(实验)",
-			workspaceDotHint: "在侧栏工作区那一行的文件夹图标上点一个小红点。这一项是贴着页面结构做的,DSH 升级后可能失效;失效时只会变成\"不显示\",不会影响红点数字、清单、跳转这些功能,随时可以关掉它。",
+			workspaceDotHint: "在侧栏工作区那一行的文件夹图标上点一个小红点(收起的工作区里有多少未读,就看它),有未读的会话在其标题右边也跟一个小红点。会话行上的点只在那一行真的显示着时才画:折叠起来的会话由工作区那一行的点和「待处理」清单代表。这一项是贴着页面结构做的,DSH 升级后可能失效;失效时只会变成\"不显示\",不会影响红点数字、清单、跳转这些功能,随时可以关掉它。",
+			appBadgeLabel: "在系统应用图标上显示红点",
+			appBadgeHint: "安装为应用后,把同一个数字也放到系统图标上:Windows 是任务栏图标上的角标,macOS 是 Dock 角标,iOS 是主屏图标上的数字。样子由系统决定——Windows 上 Chrome 画深色圆+白字,Edge 走 Windows 系统徽章通道(是否显示数字由 Edge/Windows 决定);插件会周期重设数字,但只在应用窗口开着时更新。",
+			appBadgeFootnote: "角标只在应用窗口开着时由本插件更新;数字超过 99 时由系统显示为 99+。",
+			appBadgeProbeInstalled: "当前环境:已安装为应用,本机可以设置角标。是否真正显示由系统决定。",
+			appBadgeProbeTab: "当前环境:浏览器标签页(不是安装的应用)——安装为应用后才会显示角标。",
+			appBadgeProbeUnsupported: "当前环境:本机没有这个能力(当前浏览器不支持应用角标)。",
+			appBadgeProbeInsecure: "当前环境:不是安全上下文(请用 localhost 或 https 访问),系统角标不可用。",
 			badgeTestHint: "真实未读 = 有会话发生了上面勾选的情况、而且你还没看过它(打开该会话即视为已读)。你正开着的会话也算——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分。只有子代理不计。手动模式:自己填数字试看效果。刷新页面后回到真实未读。",
 			clearDelayLabel: "进入会话后多久算已读:",
 			clearDelayUnit: "秒",
-			clearDelayHint: "填 0 = 进去就算已读(红点立即消失)。大于 0 时,你要在那个会话里连续待满这么多秒它才算看过:中途切走、或它又跑完一轮,都会清零重数;刷新页面也重新数。上限 600 秒。"
+			clearDelayHint: "填 0 = 进去就算已读(红点立即消失)。大于 0 时,你要在那个会话里连续待满这么多秒它才算看过:中途切走会清零重数,刷新页面也重新数。**计时只认\"你进入会话时已经存在的结束\"**——你人已经在里面的时候又跑完一轮,那一轮不算数:它会一直亮着,等你切走再进来才会清。上限 600 秒。已读记在宿主($DSH_HOME/custom-favicon/unread-seen.json):任何一台设备上看过,所有设备都不再提醒;浏览器那份只是缓存,清站点数据不会把已读丢回去。"
 		};
 		const en = {
 			nav: "Favicon",
@@ -135,11 +142,18 @@ window.__ModuleLoader__.load({
 			ageMonths: "{n}mo",
 			ageYears: "{n}y",
 			workspaceDotLabel: "Dots on workspace and session rows (experimental)",
-			workspaceDotHint: "Adds a small red dot to the folder icon of each workspace row. This one reads the page structure, so a DSH upgrade may break it; when it does it simply stops showing, never affecting the counts, the list, or navigation. Turn it off any time.",
+			workspaceDotHint: "Adds a small red dot to the folder icon of each workspace row (a collapsed workspace shows how many of its sessions are unread there), and one beside the title of every unread session row. A session dot is only drawn while that row is really rendered: folded sessions are represented by their workspace row's dot and the pending panel. This one reads the page structure, so a DSH upgrade may break it; when it does it simply stops showing, never affecting the counts, the list, or navigation. Turn it off any time.",
+			appBadgeLabel: "Badge the system app icon",
+			appBadgeHint: "Once installed as an app, the same number also goes to the system icon: a taskbar badge on Windows, a Dock badge on macOS, a number on the iOS home-screen icon. The system decides how it looks — on Windows, Chrome draws a dark circle with white text, while Edge goes through the Windows badge channel (whether it shows the number is up to Edge/Windows). The plugin re-asserts the number periodically, but only while the app window is open.",
+			appBadgeFootnote: "The badge is only updated by this plugin while the app window is open; above 99 the system shows 99+.",
+			appBadgeProbeInstalled: "This environment: installed as an app, so this device can set a badge. Whether it actually appears is up to the system.",
+			appBadgeProbeTab: "This environment: a browser tab (not an installed app) — install as an app to get a badge.",
+			appBadgeProbeUnsupported: "This environment: no app-badge capability in this browser.",
+			appBadgeProbeInsecure: "This environment: not a secure context (use localhost or https) — the system badge is unavailable.",
 			badgeTestHint: "Real unread = a session ended for one of the checked reasons and you have not looked at it yet (opening a session marks it read). The session you are viewing counts too — the window may be minimised or the page in the background, so this half cannot tell whether you are looking, and does not pretend to. Only sub-agents never count. Manual = type a number to preview. Resets to Real on reload.",
 			clearDelayLabel: "Mark read after staying:",
 			clearDelayUnit: "seconds",
-			clearDelayHint: "0 = read as soon as you enter (the dot clears at once). Above 0 you must stay in that session for this many seconds before it counts as read: leaving it, or a fresh ending in it, resets the clock, and so does a reload. Capped at 600 seconds."
+			clearDelayHint: "0 = read as soon as you enter (the dot clears at once). Above 0 you must stay in that session for this many seconds before it counts as read: leaving it resets the clock, and so does a reload. The clock only ever covers **the ending that was already there when you entered** — a turn that finishes while you are sitting in the session does not count: it stays red until you leave and come back. Capped at 600 seconds. Read state lives on the Host ($DSH_HOME/custom-favicon/unread-seen.json): read on any device means read on every device, and the browser's own copy is only a cache — clearing site data no longer throws it away."
 		};
 		//#endregion
 
@@ -255,7 +269,9 @@ window.__ModuleLoader__.load({
 		const UNREAD_FALLBACK_REASONS = { completed: true, error: true, blocked: true, "max-tokens": true, interrupted: true, "aborted:user": false, "aborted:other": true };
 		/** Mirror of the host's cap (see lib/unread.js) — 10 minutes. */
 		const UNREAD_CLEAR_DELAY_MAX_SEC = 600;
-		let unreadConfig = { reasons: { ...UNREAD_FALLBACK_REASONS }, pending: true, workspaceDot: true, clearDelaySec: 0 };
+		/** Mirror of the host's default (see lib/unread.js) — badging the app icon is on. */
+		const UNREAD_APP_BADGE_FALLBACK = true;
+		let unreadConfig = { reasons: { ...UNREAD_FALLBACK_REASONS }, pending: true, workspaceDot: true, appBadge: UNREAD_APP_BADGE_FALLBACK, clearDelaySec: 0 };
 		const unreadConfigListeners = new Set();
 		/** Mirror of the host's normalizer: any input becomes an integer 0..cap seconds. */
 		function normalizeClearDelay(input) {
@@ -276,12 +292,16 @@ window.__ModuleLoader__.load({
 				reasons,
 				pending: typeof source.pending === "boolean" ? source.pending : true,
 				workspaceDot: typeof source.workspaceDot === "boolean" ? source.workspaceDot : true,
+				appBadge: typeof source.appBadge === "boolean" ? source.appBadge : UNREAD_APP_BADGE_FALLBACK,
 				clearDelaySec: normalizeClearDelay(source.clearDelaySec)
 			};
 		}
 		function emitUnreadConfig(input) {
 			unreadConfig = normalizeUnreadConfig(input);
 			unreadConfigListeners.forEach((fn) => { try { fn(unreadConfig); } catch {} });
+			// The rule (or just the app-badge switch) moved: the OS badge follows it
+			// in the same breath, so toggling it applies without a reload.
+			reconcileAppBadge();
 		}
 		function subscribeUnreadConfig(fn) {
 			unreadConfigListeners.add(fn);
@@ -289,7 +309,7 @@ window.__ModuleLoader__.load({
 		}
 
 		/**
-		 * The seen watermark lives in the HOST's clock domain.
+		 * The seen watermark: the HOST owns it, this browser keeps the working copy.
 		 *
 		 * A turn end arrives stamped with the Host's `turn/end.time`; a mark written
 		 * from the browser's `Date.now()` only lines up while both clocks agree. A
@@ -298,11 +318,26 @@ window.__ModuleLoader__.load({
 		 * all — the one failure users report as "点进去也不消". Marks now store the
 		 * `endAt` they acknowledge, and `lastActiveAt` stores a host-domain time, so
 		 * every comparison in `collectUnread` stays inside one clock.
+		 *
+		 * Since 0.11.2 the authoritative table lives in the Host
+		 * (`~/.dsh/custom-favicon/unread-seen.json`, merged max-per-session). This
+		 * copy is what the badge reads — so the page never waits for a round trip and
+		 * keeps working offline — and doubles as the pending queue: every local mark
+		 * is pushed back on the next sync, and a merge can only move marks forward.
+		 * That is what makes "looked at it" survive a cleared browser profile and mean
+		 * the same thing on every device.
 		 */
 		const SEEN_STORE_KEY = "dsh-icon-custom.unread-seen.v2";
 		/** 0.10.1 and earlier wrote browser timestamps here; migrated once. */
 		const LEGACY_SEEN_STORE_KEY = "dsh-icon-custom.unread-seen.v1";
+		/** Mirror of the Host's cap (see lib/unread.js). */
 		const SEEN_MAX = 400;
+		/** Coalescing window for watermark pushes: one small RPC per burst, not per session. */
+		const HOST_SYNC_DEBOUNCE_MS = 2000;
+		/** Retry gap after a failed push (offline, or a Host without the endpoint). */
+		const HOST_SYNC_RETRY_MS = 30000;
+		/** Ceiling for that retry gap: an old Host must not be probed forever every 20 s. */
+		const HOST_SYNC_MAX_RETRY_MS = 300000;
 		/** Host clock minus browser clock, from the last Host sample; null until known. */
 		let hostClockOffset = null;
 		/** This browser's clock expressed in the Host's domain (best effort). */
@@ -327,10 +362,140 @@ window.__ModuleLoader__.load({
 		const seenState = loadSeenState();
 		/** When this browser last had the app open before this page load (host domain). */
 		const seenBootAt = seenState.lastActiveAt > 0 ? seenState.lastActiveAt : 0;
+		/** The connection RPC, once `apply` has one; null keeps every push a no-op. */
+		let seenRpc = null;
+		/** Whether this page load has already converged with the Host once. */
+		let hostSyncedOnce = false;
+		/** Whether local marks changed since the last successful push. */
+		let hostDirty = false;
+		let hostSyncTimer = 0;
+		let hostRetryTimer = 0;
+		let hostSyncInFlight = false;
+		/** Escalating gap between failed pushes; any success resets it. */
+		let hostRetryDelay = HOST_SYNC_RETRY_MS;
+		/** No push is attempted before this moment (the backoff window). */
+		let hostBackoffUntil = 0;
+		/** Whether the current failure streak has been reported (warn once per streak). */
+		let hostSyncWarned = false;
+		/**
+		 * Push the local table soon, unless there is nothing to say.
+		 *
+		 * Called from `saveSeenState`, which is also the 20-second "this browser is
+		 * still here" touch: that touch must NOT count as a change, or the table would
+		 * travel every 20 seconds. `hostSyncedOnce` covers the first push of a page
+		 * load, which is also the migration (local-only marks going up) and the
+		 * self-heal (a lost Host file coming back from this browser).
+		 * @param delayMs - override the coalescing window; non-positive uses the default.
+		 */
+		function scheduleHostSync(delayMs) {
+			if (seenRpc === null || hostSyncInFlight) return;
+			if (!hostDirty && hostSyncedOnce) return;
+			if (hostSyncTimer !== 0) return;
+			// A failed push escalates its own retry; the 20-second touch must not keep
+			// poking a Host that has no such endpoint (an older DSH, or offline).
+			if (Date.now() < hostBackoffUntil) return;
+			const wait = typeof delayMs === "number" && delayMs > 0 ? delayMs : HOST_SYNC_DEBOUNCE_MS;
+			hostSyncTimer = window.setTimeout(() => { hostSyncTimer = 0; flushHostSeen(); }, wait);
+		}
+		/**
+		 * Adopt the Host's table: per session the NEWER of the two wins.
+		 *
+		 * Max-merge (never overwrite) is what makes both directions safe: the Host file
+		 * lost or truncated → this browser's copy wins; this browser's localStorage
+		 * cleared → the Host's copy wins. It is also the whole migration path.
+		 * @param seen - the Host's table (`id → endAt`), or anything.
+		 * @returns whether the local table gained anything.
+		 */
+		function adoptHostSeen(seen) {
+			if (seen === null || typeof seen !== "object") return false;
+			let gained = false;
+			for (const id of Object.keys(seen)) {
+				if (typeof id !== "string" || id === "") continue;
+				const at = seen[id];
+				if (typeof at !== "number" || !Number.isFinite(at) || at <= 0) continue;
+				const previous = seenState.seen[id];
+				if (typeof previous === "number" && previous >= at) continue;
+				seenState.seen[id] = at;
+				gained = true;
+			}
+			return gained;
+		}
+		/**
+		 * Send the whole local table and adopt the merged answer.
+		 *
+		 * Whole-table, not a delta: the payload is a few KB, the Host merges by max (so
+		 * a duplicate or partial round trip is harmless), and any lost message heals on
+		 * the next one. A failure keeps the marks here — they are already in
+		 * localStorage and the badge reads them — and retries later.
+		 */
+		function flushHostSeen() {
+			if (seenRpc === null || hostSyncInFlight) return;
+			if (!hostDirty && hostSyncedOnce) return;
+			hostSyncInFlight = true;
+			const marks = { ...seenState.seen };
+			let pending;
+			try {
+				// Args are nested under the descriptor's parameter name ("request"), which
+				// is what the gateway checks: a flat `{ marks }` is rejected with
+				// `gateway/arguments-invalid` before the method ever runs.
+				pending = seenRpc.call("/api", "iconCustom/setUnreadSeen", { args: { request: { marks } } });
+			} catch (error) {
+				// A carrier that throws synchronously must not wedge the in-flight guard:
+				// that would stop every later push for the life of the page, silently.
+				hostSyncInFlight = false;
+				noteHostSyncFailure(error);
+				return;
+			}
+			Promise.resolve(pending).then(
+				(resp) => {
+					hostSyncInFlight = false;
+					if (resp === null || typeof resp !== "object" || resp.ok !== true) {
+						const reason = resp !== null && typeof resp === "object" && resp.error !== undefined ? JSON.stringify(resp.error) : "resp.ok !== true";
+						noteHostSyncFailure(new Error("setUnreadSeen 被拒绝: " + reason));
+						return;
+					}
+					const value = resp.value !== null && typeof resp.value === "object" ? resp.value : {};
+					const gained = adoptHostSeen(value.seen);
+					hostSyncedOnce = true;
+					hostRetryDelay = HOST_SYNC_RETRY_MS;
+					hostBackoffUntil = 0;
+					hostSyncWarned = false;
+					// The Host knew marks this browser did not: keep them and push the union
+					// once more. The next answer cannot gain anything, so this terminates.
+					// Repaint too: the badge, the row dots and the panel all read this
+					// browser's copy, and nothing else would re-render for a mark that
+					// arrived over the wire.
+					hostDirty = gained;
+					if (gained) { saveSeenState(); emitUnreadPoke(); scheduleHostSync(); }
+				},
+				(error) => { hostSyncInFlight = false; noteHostSyncFailure(error); }
+			);
+		}
+		/**
+		 * One failed push: report it once per streak, then back off and try again later.
+		 *
+		 * Reported (not swallowed) because a watermark that cannot reach the Host is a
+		 * silent, confusing failure — "为什么另一台设备还亮着" — and there is nothing on
+		 * screen to explain it. The badge itself keeps working from the local copy, so
+		 * this must never look fatal, and it warns once rather than on every retry.
+		 * @param error - whatever the carrier rejected with.
+		 */
+		function noteHostSyncFailure(error) {
+			if (!hostSyncWarned) {
+				hostSyncWarned = true;
+				try { console.warn("dsh-icon-custom: 已读水位线同步到宿主失败(红点仍照常工作,会自动重试):", (error && error.message) || error); } catch {}
+			}
+			const wait = hostRetryDelay;
+			hostRetryDelay = Math.min(hostRetryDelay * 2, HOST_SYNC_MAX_RETRY_MS);
+			hostBackoffUntil = Date.now() + wait;
+			if (hostRetryTimer !== 0) window.clearTimeout(hostRetryTimer);
+			hostRetryTimer = window.setTimeout(() => { hostRetryTimer = 0; flushHostSeen(); }, wait);
+		}
 		function saveSeenState() {
 			try {
 				window.localStorage.setItem(SEEN_STORE_KEY, JSON.stringify({ domain: "host", lastActiveAt: seenState.lastActiveAt, seen: seenState.seen }));
 			} catch {}
+			scheduleHostSync();
 		}
 		/**
 		 * Learn the Host↔browser clock offset from a Host timestamp, and fold a
@@ -370,12 +535,20 @@ window.__ModuleLoader__.load({
 			const previous = seenState.seen[sessionId];
 			if (typeof previous === "number" && previous >= mark) return false;
 			seenState.seen[sessionId] = mark;
+			// Only a REAL mark counts as a change: the 20-second "still here" touch also
+			// lands in `saveSeenState`, and it must not drag the whole table to the Host.
+			hostDirty = true;
 			return true;
 		}
 		/**
 		 * First sight of a session is watermarked at the last time this browser was
 		 * here — so an ending that happened while the app was closed still counts as
 		 * unread, while endings from before the plugin was installed do not.
+		 *
+		 * Unchanged by the move to a Host-owned table: a session nobody has a mark for
+		 * still needs a starting value, and "the last time this browser was here" is
+		 * the honest one. A mark dropped by the Host's pruning simply re-baselines here
+		 * on the next load, which is why pruning cannot resurrect old dots.
 		 * @returns whether anything was learned (callers persist only then).
 		 */
 		function ensureSeenBaseline(ids) {
@@ -431,25 +604,6 @@ window.__ModuleLoader__.load({
 			const value = values !== null && typeof values === "object" ? values[LAST_TURN_END_KEY] : undefined;
 			return value !== null && typeof value === "object" && typeof value.endAt === "number" ? value.endAt : 0;
 		}
-		/**
-		 * What the "stay here long enough" timer is armed for, or "" when nothing
-		 * should be armed.
-		 *
-		 * Keyed on the session's own `lastTurnEnd.endAt`, deliberately NOT on the
-		 * collected item's `at`: a "waiting for you" item carries `at: Date.now()`,
-		 * which changes on every evaluation — keying on that would tear the timer
-		 * down and re-arm it forever, and a waiting session could never be marked
-		 * read. Including `endAt` is also what makes a NEW ending restart the clock
-		 * instead of inheriting the previous one's progress.
-		 * @param sessionId - the session being viewed.
-		 * @param list - the session list snapshot.
-		 * @returns the key, or "" when there is no session to arm for.
-		 */
-		function stayKeyFor(sessionId, list) {
-			if (typeof sessionId !== "string" || sessionId === "") return "";
-			const byId = list !== null && typeof list === "object" && list.byId !== null && typeof list.byId === "object" ? list.byId : {};
-			return `${sessionId}\u0000${lastTurnEndAt(byId[sessionId])}`;
-		}
 		/**
 		 * How many sessions deserve the badge right now: endings whose reason is
 		 * enabled and that this browser has not seen since, plus sessions waiting
@@ -557,6 +711,8 @@ window.__ModuleLoader__.load({
 			// The header badge is a DOM node, not a listener, so it is reconciled
 			// here as well as from the mutation watchdog. Idempotent either way.
 			paintHeaderBadge();
+			// Same number, second consumer: the OS badge behind the app icon.
+			reconcileAppBadge();
 		}
 		/** Manual test input. */
 		function emitBadge(value) {
@@ -588,6 +744,180 @@ window.__ModuleLoader__.load({
 			return count > 99 ? "99+" : String(count);
 		}
 
+		//#endregion
+		//#region app badge (OS app icon)
+		// The badge the OPERATING SYSTEM draws on the icon of the installed app: the
+		// taskbar overlay on Windows, the Dock badge on macOS, the number on an iOS
+		// home-screen icon. It is the same number the page badge shows, projected
+		// onto the system icon — one number, two consumers.
+		//
+		// Three facts shape this region (all checked against primary sources; see
+		// docs/adr/0005-app-icon-badge.md):
+		//   * detecting the API is NOT delivery. Chromium on Android exposes
+		//     `setAppBadge` and silently ignores it, and iOS only draws the badge
+		//     once notifications have been granted. So the probe reports LOCAL facts
+		//     and never promises that a badge will appear;
+		//   * the OS owns the rendering. On Windows the badge is a browser-drawn
+		//     overlay on the taskbar button of an OPEN window: closing the window
+		//     drops it, and nothing can refresh it afterwards (no push server);
+		//   * the API is write-only, so this half keeps its own count — the very
+		//     `effectiveCount()` the favicon and the header badge already use.
+		//
+		// Everything that DECIDES is a pure function, so a test drives it with no
+		// browser at all; exactly one function touches the API.
+		/** Display modes that mean "this window IS the installed app", not a tab. */
+		const APP_DISPLAY_MODES = ["standalone", "fullscreen", "minimal-ui", "window-controls-overlay"];
+
+		/**
+		 * Normalize what this device is, as three independent local facts.
+		 *
+		 * Deliberately NOT "does this platform support it": the method that works
+		 * on Windows resolves and does nothing on Android, and Apple draws the
+		 * badge only after notifications are granted. Neither is answerable from
+		 * inside the page, so the probe stays silent about them and the copy says
+		 * "whether it actually appears is up to the system" instead.
+		 * @param env - `{ secure, hasApi, installed }`; anything non-boolean reads false.
+		 * @returns the same three flags, normalized.
+		 */
+		function badgeCapabilityProbe(env) {
+			const source = env !== null && typeof env === "object" ? env : {};
+			return {
+				secure: source.secure === true,
+				hasApi: source.hasApi === true,
+				installed: source.installed === true
+			};
+		}
+
+		/**
+		 * Read those facts off the window this code runs in.
+		 *
+		 * "Installed" is a display-mode match rather than `standalone` alone: the
+		 * platform manifest asks for `fullscreen`, so an installed window matches
+		 * THAT mode, and a standalone-only test would report "browser tab" forever.
+		 * @returns the probe for this device.
+		 */
+		function appBadgeEnv() {
+			const nav = typeof navigator === "object" && navigator !== null ? navigator : {};
+			let installed = nav.standalone === true;
+			if (!installed && typeof window !== "undefined" && typeof window.matchMedia === "function") {
+				for (const mode of APP_DISPLAY_MODES) {
+					try {
+						if (window.matchMedia(`(display-mode: ${mode})`).matches === true) { installed = true; break; }
+					} catch {}
+				}
+			}
+			return badgeCapabilityProbe({
+				secure: typeof window !== "undefined" && window.isSecureContext === true,
+				hasApi: typeof nav.setAppBadge === "function" && typeof nav.clearAppBadge === "function",
+				installed
+			});
+		}
+
+		/**
+		 * What the OS badge should say for a given count.
+		 *
+		 * The number is handed over AS IS (no `99+` clamping here): the system
+		 * saturates it in its own way, and duplicating that rule is how the two
+		 * projections start disagreeing. Switching the feature off clears the
+		 * badge rather than abandoning it — a number left behind after "off"
+		 * reads as a bug.
+		 * @param count - the unread count, i.e. the number the page badge shows.
+		 * @param enabled - the `appBadge` setting; only `true` enables it.
+		 * @returns `{ kind: "set", value }` or `{ kind: "clear" }`.
+		 */
+		function appBadgeEffect(count, enabled) {
+			const value = enabled === true ? normalizeCount(count) : 0;
+			return value > 0 ? { kind: "set", value } : { kind: "clear" };
+		}
+
+		/**
+		 * Which self-check line the settings page shows for this device.
+		 *
+		 * A missing probe is NOT reported as "insecure": that message tells the
+		 * user to change how they reach the page, which would be chasing the
+		 * wrong thing. Only a real reading may claim that.
+		 * @param probe - a `badgeCapabilityProbe` result.
+		 * @returns a locale key.
+		 */
+		function appBadgeCapabilityKey(probe) {
+			if (probe === null || typeof probe !== "object") return "appBadgeProbeUnsupported";
+			const facts = badgeCapabilityProbe(probe);
+			if (facts.secure !== true) return "appBadgeProbeInsecure";
+			if (facts.hasApi !== true) return "appBadgeProbeUnsupported";
+			return facts.installed === true ? "appBadgeProbeInstalled" : "appBadgeProbeTab";
+		}
+
+		/** The last effect actually handed to the API, so a repeat is a no-op. */
+		let lastAppBadgeId = null;
+
+		/**
+		 * The ONE place that talks to the Badging API.
+		 *
+		 * Idempotence is required here, not polish: `notifyBadge` fires on every
+		 * badge change AND again from the DOM watchdog that re-asserts the tab
+		 * badge, and each call costs an IPC to the browser process plus a taskbar
+		 * repaint. Only a real change in the projected effect reaches the API.
+		 * @param effect - an `appBadgeEffect` result.
+		 * @param force - re-send even when the effect is unchanged. Used only by
+		 *   the low-frequency OS-badge watchdog, because Windows/Edge can replace a
+		 *   numeric badge with a notification dot after our call succeeded.
+		 */
+		function applyAppBadge(effect, force) {
+			const intent = effect !== null && typeof effect === "object" ? effect : {};
+			// Anything that is not a positive number is a clear, so a bogus effect
+			// can never hand the system a `setAppBadge(0)`.
+			const id = intent.kind === "set" && typeof intent.value === "number" && intent.value > 0 ? `set:${intent.value}` : "clear";
+			if (id === lastAppBadgeId && force !== true) return;
+			const nav = typeof navigator === "object" && navigator !== null ? navigator : null;
+			if (nav === null || typeof nav.setAppBadge !== "function" || typeof nav.clearAppBadge !== "function") return;
+			lastAppBadgeId = id;
+			try {
+				// Always a number, never the argument-less "flag" form: on WebKit a
+				// no-argument call can REMOVE a badge that is already showing.
+				const settled = id === "clear" ? nav.clearAppBadge() : nav.setAppBadge(intent.value);
+				if (settled !== null && typeof settled === "object" && typeof settled.catch === "function") {
+					settled.catch(() => {
+						// The API rejected: the browser did NOT apply this effect, so
+						// forget it and let the next reconcile/retry try again. Guard
+						// against a newer call having replaced the remembered effect.
+						if (lastAppBadgeId === id) lastAppBadgeId = null;
+					});
+				}
+			} catch {
+				// A synchronous throw means nothing was applied, so the next
+				// reconcile retries instead of remembering a phantom success.
+				lastAppBadgeId = null;
+			}
+		}
+
+		/**
+		 * Reconcile the OS badge with the page badge.
+		 *
+		 * Both inputs are the page's own: the number the favicon and the header
+		 * badge already show, and the rule the host persists. Called from
+		 * `emitUnreadConfig` (rule arrived / switch moved) and `notifyBadge`
+		 * (number moved) — together those cover every way the badge can change.
+		 * @param force - re-send even if the projected effect is unchanged.
+		 */
+		function reconcileAppBadge(force) {
+			applyAppBadge(appBadgeEffect(effectiveCount(), unreadConfig.appBadge === true), force === true);
+		}
+
+		/**
+		 * Keep a positive numeric badge asserted while the app window is alive.
+		 *
+		 * Windows/Edge can render a notification glyph (a dot) over the numeric
+		 * badge after we set it; unlike the favicon, the OS badge then has no
+		 * watcher to put the number back. Re-send only when the plugin's own
+		 * projection says there SHOULD be a number, and never when it says clear —
+		 * so a count of 0 is not repeatedly cleared and no phantom badge appears.
+		 */
+		function reassertAppBadge() {
+			if (unreadConfig.appBadge !== true) return;
+			if (normalizeCount(effectiveCount()) <= 0) return;
+			reconcileAppBadge(true);
+		}
+
 		//#endregion
 		//#region favicon compositing
 		// The browser accepts exactly ONE image per <link rel="icon">, so a tab
@@ -827,22 +1157,32 @@ window.__ModuleLoader__.load({
 		/**
 		 * Roll the pending sessions up to one dot per workspace.
 		 *
-		 * Pure: `titles` maps sessionId → the workspace title the sidebar shows
-		 * (assembled from the official workspace snapshot); a session missing from it
-		 * falls back to the cwd basename `collectUnread` already carries.
-		 * @returns `[{ name, count }]`, busiest workspace first.
+		 * Pure: `owners` maps sessionId → `{ id, title }` from the official workspace
+		 * snapshot. Both halves matter downstream: the ID anchors the marker to the
+		 * row the browser itself keys (`data-row-key="workspace:<id>"`), which is what
+		 * makes the folder dot survive a Workspace whose displayed name differs from
+		 * the stored title, two Workspaces sharing one title, and a title that is
+		 * simply empty. The title stays for the tooltip; a session with neither falls
+		 * back to the cwd basename `collectUnread` already carries.
+		 * @returns `[{ id, name, count }]`, busiest workspace first.
 		 */
-		function dotsFromItems(items, titles) {
+		function dotsFromItems(items, owners) {
 			const counts = new Map();
 			for (const item of Array.isArray(items) ? items : []) {
 				if (item === null || typeof item !== "object") continue;
-				const mapped = titles !== null && typeof titles === "object" ? titles[item.id] : undefined;
-				const name = typeof mapped === "string" && mapped !== "" ? mapped : (typeof item.where === "string" ? item.where : "");
+				const owner = owners !== null && typeof owners === "object" ? owners[item.id] : undefined;
+				const title = owner !== null && typeof owner === "object" && typeof owner.title === "string" ? owner.title : "";
+				const name = title !== "" ? title : (typeof item.where === "string" ? item.where : "");
 				if (name === "") continue;
-				counts.set(name, (counts.get(name) || 0) + 1);
+				const id = owner !== null && typeof owner === "object" && typeof owner.id === "string" ? owner.id : "";
+				// One dot per Workspace: two Sessions of the same Workspace must not
+				// produce two entries that later paint on top of each other.
+				const key = id !== "" ? id : name;
+				const existing = counts.get(key);
+				if (existing === undefined) counts.set(key, { id, name, count: 1 });
+				else existing.count++;
 			}
-			return [...counts.entries()]
-				.map(([name, count]) => ({ name, count }))
+			return [...counts.values()]
 				.sort((a, b) => b.count - a.count || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 		}
 
@@ -1112,17 +1452,101 @@ window.__ModuleLoader__.load({
 		 * Where one session's marker goes: the tight title holder INSIDE that
 		 * session's own row. The row is found by `data-row-key`; the title inside it
 		 * is still matched by text, because that is the element the marker hangs off.
-		 * Falls back to the old whole-region title match on a build without row keys.
+		 *
+		 * A Session whose row is NOT in the DOM — folded behind "Show more", inside a
+		 * collapsed Workspace, or filtered out — gets NO marker. It used to fall back
+		 * to a whole-region title match, and that guess is exactly what puts a dot on
+		 * the wrong row: a DIFFERENT Session with the same title owns the only
+		 * rendered text node of that name, so the folded one's marker landed on the
+		 * visible one's row (two markers on one row, none on the real one). The
+		 * Workspace folder dot and the pending panel already speak for Sessions whose
+		 * rows are not rendered, so skipping loses no information.
+		 *
+		 * `legacyTitleMatch` is reserved for a build that stamps no row keys at all,
+		 * where the title is the only handle that exists.
+		 * @param legacyTitleMatch - whether this build predates `data-row-key`.
 		 * @returns `{ title, row }`, or null when this row cannot be trusted.
 		 */
-		function sessionRowTarget(container, id, title) {
+		function sessionRowTarget(container, id, title, legacyTitleMatch) {
 			const row = sessionRowElement(container, id);
 			if (row !== null) {
 				const inside = labelElementFor(row, title);
 				return inside === null ? null : titleTargetFor(inside, title);
 			}
+			if (legacyTitleMatch !== true) return null;
 			return titleTargetFor(labelElementFor(container, title), title);
 		}
+		/**
+		 * Whether the shipped browser stamps Session rows with `data-row-key`.
+		 *
+		 * Asked once per paint, not once per row: the strict path is only relaxed for
+		 * a build that has no row keys anywhere, never for one unlucky lookup.
+		 * @param container - the browsing region root (non-null).
+		 * @returns true when row keys are in use (and on any probe failure — the
+		 * strict path is the safe default).
+		 */
+		function sessionRowKeysInUse(container) {
+			try { return container.querySelector('[data-row-key^="session:"]') !== null; } catch { return true; }
+		}
+		/**
+		 * The DOM row of one Workspace, by the official row key, or null.
+		 *
+		 * Same handle as `sessionRowElement`, and the reason the folder dot no longer
+		 * depends on the displayed name: DSH renders a Workspace still carrying its
+		 * automatic title under a localized default name, and two Workspaces can share
+		 * one title, so a text match can miss or collide.
+		 * @param container - the browsing region root.
+		 * @param id - the Workspace id.
+		 * @returns the row element, or null.
+		 */
+		function workspaceRowElement(container, id) {
+			if (typeof id !== "string" || id === "") return null;
+			try { return container.querySelector(`[data-row-key="workspace:${id}"]`); } catch { return null; }
+		}
+		/**
+		 * The row box + folder icon a Workspace marker hangs off, from the keyed row.
+		 *
+		 * The key normally sits on the row itself; a build that stamps it on a group
+		 * wrapper fails the row-size check, so a bounded set of that wrapper's own rows
+		 * gets the same test before giving up. Either way the marker must land on a
+		 * row-sized box whose LEADING glyph is the folder — requiring a left-hand icon
+		 * is what keeps the dot off the end of the text.
+		 * @returns `{ row, icon }`, or null when this row cannot be trusted.
+		 */
+		function folderTargetFor(row) {
+			if (row === null || row === undefined) return null;
+			const candidates = [row];
+			try {
+				const inner = row.querySelectorAll("div");
+				for (let i = 0; i < inner.length && candidates.length < 12; i++) candidates.push(inner[i]);
+			} catch { /* the keyed element alone is still worth testing */ }
+			for (const candidate of candidates) {
+				const rect = candidate.getBoundingClientRect();
+				if (rect.height < WS_ROW_MIN_H || rect.height > WS_ROW_MAX_H || rect.width < WS_ROW_MIN_W) continue;
+				const icons = candidate.querySelectorAll("svg");
+				for (const icon of icons) {
+					const iconRect = icon.getBoundingClientRect();
+					if (iconRect.width <= 0 || iconRect.height <= 0) continue;
+					if (iconRect.left - rect.left > rect.width / 3) continue;
+					return { row: candidate, icon };
+				}
+			}
+			return null;
+		}
+		/**
+		 * The stable key a Workspace marker is stored under: its ID when known.
+		 *
+		 * The attribute value used to be the displayed title, which two Workspaces can
+		 * share — the reconcile pass would then treat one of them as a stranger and
+		 * remove a marker that is still wanted.
+		 * @param entry - one `{ id, name }` entry from `dotsFromItems`.
+		 * @returns the key, or undefined when the entry carries neither.
+		 */
+		function workspaceDotKey(entry) {
+			if (entry === null || typeof entry !== "object") return undefined;
+			if (typeof entry.id === "string" && entry.id !== "") return entry.id;
+			return entry.name;
+		}
 		function paintWorkspaceDots() {
 			if (workspaceDotGivenUp) return;
 			const enabled = unreadConfig.workspaceDot !== false;
@@ -1138,7 +1562,7 @@ window.__ModuleLoader__.load({
 				// Reconcile, never wipe-and-redraw: a marker that is already correct is
 				// left untouched, so one unlucky lookup (a re-render in flight, a name
 				// matched twice for a moment) can no longer blink an existing dot away.
-				const wantedNames = new Set(wanted.map((entry) => entry.name));
+				const wantedNames = new Set(wanted.map((entry) => workspaceDotKey(entry)));
 				const wantedIds = new Set(wantedRows.map((entry) => entry.id));
 				document.querySelectorAll("[" + WS_DOT_ATTR + "]").forEach((node) => {
 					if (!node.isConnected || !wantedNames.has(node.getAttribute(WS_DOT_ATTR))) node.remove();
@@ -1147,12 +1571,21 @@ window.__ModuleLoader__.load({
 					if (!node.isConnected || !wantedIds.has(node.getAttribute(ROW_DOT_ATTR))) node.remove();
 				});
 				if (container === null) { workspaceDotPainting = false; return; } // start-up race
+				const legacyTitleMatch = !sessionRowKeysInUse(container);
 				for (const entry of wanted) {
-					const label = labelElementFor(container, entry.name);
-					const target = label === null ? null : markerTargetFor(label);
+					const key = workspaceDotKey(entry);
+					if (key === undefined) { missed++; continue; }
+					// The browser's own row key first; the title walk-up is only for a build
+					// that stamps no Workspace keys (or an entry the snapshot could not name).
+					const keyedRow = workspaceRowElement(container, entry.id);
+					let target = keyedRow === null ? null : folderTargetFor(keyedRow);
+					if (target === null && keyedRow === null) {
+						const label = labelElementFor(container, entry.name);
+						target = label === null ? null : markerTargetFor(label);
+					}
 					if (target === null) { missed++; continue; }
 					const row = target.row;
-					if (existingMarker(row, WS_DOT_ATTR, entry.name) !== null) { placed++; continue; }
+					if (existingMarker(row, WS_DOT_ATTR, key) !== null) { placed++; continue; }
 					const icon = target.icon;
 					const rowRect = row.getBoundingClientRect();
 					const anchorRect = icon.getBoundingClientRect();
@@ -1161,9 +1594,9 @@ window.__ModuleLoader__.load({
 						row.style.position = "relative";
 					}
 					const dot = document.createElement("span");
-					dot.setAttribute(WS_DOT_ATTR, entry.name);
+					dot.setAttribute(WS_DOT_ATTR, key);
 					dot.setAttribute("aria-hidden", "true");
-					dot.title = entry.name + " · " + entry.count;
+					dot.title = (typeof entry.name === "string" && entry.name !== "" ? entry.name : key) + " · " + entry.count;
 					dot.style.cssText = "position:absolute;pointer-events:none;width:8px;height:8px;border-radius:50%;"
 						+ "background:#e5484d;box-shadow:0 0 0 1.5px var(--dsw-alias-bg-layer-1,#fff);"
 						+ "left:" + Math.round(anchorRect.right - rowRect.left - 4) + "px;"
@@ -1175,7 +1608,7 @@ window.__ModuleLoader__.load({
 				// Session rows: the marker rides inline right after the title, so it stays
 				// beside the name whatever the timestamp happens to say.
 				for (const entry of wantedRows) {
-					const target = sessionRowTarget(container, entry.id, entry.title);
+					const target = sessionRowTarget(container, entry.id, entry.title, legacyTitleMatch);
 					if (target === null) { missed++; continue; }
 					if (existingMarker(target.row, ROW_DOT_ATTR, entry.id) !== null) { placed++; continue; }
 					const dot = document.createElement("span");
@@ -1258,20 +1691,26 @@ window.__ModuleLoader__.load({
 			const currentIds = currentSessionIds(list);
 			const items = collectUnread(list, pending, config, seenState.seen);
 			const count = items.length;
-			// Being in a session is what marks it read — but only once you have STAYED
-			// `clearDelaySec` seconds (0 = the moment you enter, the original
-			// behaviour). A clock is torn down whenever you leave, or whenever that
-			// session becomes unread again from a fresh ending, so the clock restarts;
-			// that teardown IS the "continuous stay, leaving resets it" rule. A reload
-			// restarts it too, since the timers only live in this page.
+			// Being in a session is what marks it read — and the clock that does it is
+			// armed by ENTERING the session, never by a new ending.
+			//
+			// `clearDelaySec` still means "stay this long before the ending counts as
+			// seen" (0 = the moment you enter). What is new in 0.11.1 is WHEN the clock
+			// takes its snapshot: the moment the session joins the view. An ending that
+			// lands while you are already sitting there is therefore none of this
+			// clock's business — it stays unread until you leave and come back. The
+			// previous version re-armed on every new ending and chased the newest one,
+			// so a turn that finished while you watched was auto-read `clearDelaySec`
+			// seconds later: the dot for the session in front of you was a flash
+			// nobody could catch. See docs/adr/0006-entry-bounded-stay-clock.md.
+			//
+			// Leaving tears the clock down, which is what makes the stay "continuous".
+			// A reload restarts it too, since the timers only live in this page.
 			//
 			// One clock per session the main view shows: with two retained sessions,
 			// marking only the first left the session you were reading unread forever.
-			const unreadIds = new Set(items.map((item) => item.id));
-			const staySignature = currentIds
-				.filter((id) => unreadIds.has(id))
-				.map((id) => stayKeyFor(id, list))
-				.join("|");
+			const stayIds = currentIds.slice().sort();
+			const staySignature = stayIds.join("|");
 			const delayMs = config.clearDelaySec * 1000;
 			const [, bumpStay] = React.useState(0);
 			// The panel can move the marks without going through this component
@@ -1279,35 +1718,40 @@ window.__ModuleLoader__.load({
 			// badge all follow immediately.
 			const [, bumpPoke] = React.useState(0);
 			React.useEffect(() => subscribeUnreadPoke(() => bumpPoke((n) => n + 1)), []);
-			// The timer chain below is keyed on the signature, but every attempt reads
-			// the CURRENT list and marks; a ref is how the chain sees them.
+			// The effect below is keyed on the signature, but the snapshot it marks is
+			// taken from the CURRENT list; a ref is how it sees that list.
 			const stayLive = React.useRef({ list });
 			stayLive.current = { list };
+			/**
+			 * Entered-at snapshot: `id → endAt` as it stood when that session joined
+			 * the view. Deliberately NOT refreshed while the session stays — that is
+			 * the rule ("an ending during your stay waits for the next entry"). A
+			 * session that leaves is forgotten, so coming back takes a fresh snapshot.
+			 */
+			const stayArmed = React.useRef(new Map());
 			React.useEffect(() => {
+				const snapshot = stayLive.current.list !== null && typeof stayLive.current.list === "object" && stayLive.current.list.byId !== null && typeof stayLive.current.list.byId === "object" ? stayLive.current.list.byId : {};
+				const live = new Set(stayIds);
+				for (const id of Array.from(stayArmed.current.keys())) {
+					if (!live.has(id)) stayArmed.current.delete(id);
+				}
+				for (const id of stayIds) {
+					if (!stayArmed.current.has(id)) stayArmed.current.set(id, lastTurnEndAt(snapshot[id]));
+				}
 				if (staySignature === "") return undefined;
-				const ids = staySignature.split("|").map((key) => key.slice(0, key.indexOf("\u0000")));
+				const armed = stayIds.map((id) => ({ id, endAt: stayArmed.current.get(id) }));
 				let cancelled = false;
 				let timer = 0;
+				// Single-shot on purpose: the snapshot is fixed, so there is nothing to
+				// chase. A newer ending found here belongs to the NEXT entry.
 				const attempt = () => {
 					if (cancelled) return;
-					const byId = stayLive.current.list !== null && typeof stayLive.current.list === "object" && stayLive.current.list.byId !== null && typeof stayLive.current.list.byId === "object" ? stayLive.current.list.byId : {};
 					let changed = false;
-					let stillUnread = false;
-					for (const id of ids) {
-						const endAt = lastTurnEndAt(byId[id]);
-						if (endAt <= 0) continue;
-						const seenAt = seenState.seen[id];
-						if (typeof seenAt === "number" && endAt <= seenAt) continue;
-						stillUnread = true;
-						if (noteSeen(id, endAt)) changed = true;
+					for (const target of armed) {
+						if (typeof target.endAt !== "number" || target.endAt <= 0) continue;
+						if (noteSeen(target.id, target.endAt)) changed = true;
 					}
 					if (changed) { saveSeenState(); bumpStay((n) => n + 1); }
-					// Watchdog. With the mark in the Host's own domain it should always
-					// land, so this normally stops after the first attempt; it exists for
-					// the case the mark DID land and the item is still unread (a fresh
-					// ending raced the timer), instead of leaving the dot red for good.
-					// A "waiting for you" item has no turn end to acknowledge: stop there.
-					timer = stillUnread ? window.setTimeout(attempt, 2000) : 0;
 				};
 				if (delayMs <= 0) attempt();
 				else timer = window.setTimeout(attempt, delayMs);
@@ -1317,19 +1761,21 @@ window.__ModuleLoader__.load({
 				};
 			}, [staySignature, delayMs]);
 			React.useEffect(() => { emitRealBadge(count, items); }, [count, items]);
-			// The workspace rows are labelled with the workspace TITLE, which is not
-			// always the cwd basename, so map session → title from the official snapshot.
+			// Map session → its Workspace from the official snapshot: the ID anchors the
+			// folder dot to the keyed row, the title is what the row displays (not always
+			// the cwd basename, and not always equal to the stored title either).
 			React.useEffect(() => {
-				const titles = {};
+				const owners = {};
 				const list = workspaces !== null && typeof workspaces === "object" && Array.isArray(workspaces.items) ? workspaces.items : [];
 				for (const workspace of list) {
 					if (workspace === null || typeof workspace !== "object") continue;
+					if (!Array.isArray(workspace.sessionIds)) continue;
+					const id = typeof workspace.workspaceId === "string" ? workspace.workspaceId : "";
 					const title = typeof workspace.title === "string" ? workspace.title : "";
-					if (title === "" || !Array.isArray(workspace.sessionIds)) continue;
-					for (const id of workspace.sessionIds) titles[id] = title;
+					for (const sessionId of workspace.sessionIds) owners[sessionId] = { id, title };
 				}
 				emitSidebarMarks({
-					workspaces: dotsFromItems(items, titles),
+					workspaces: dotsFromItems(items, owners),
 					sessions: items.map((item) => ({ id: item.id, title: item.title }))
 				});
 			}, [items, workspaces]);
@@ -1776,6 +2222,9 @@ window.__ModuleLoader__.load({
 			const [badgeSourceValue, setBadgeSourceValue] = React.useState(badgeSource);
 			const [unread, setUnread] = React.useState(unreadConfig);
 			React.useEffect(() => subscribeUnreadConfig(setUnread), []);
+			// Sampled when the section mounts, which is the moment the user is
+			// looking at it. It reports local facts only (see badgeCapabilityProbe).
+			const [appBadgeProbe] = React.useState(() => appBadgeEnv());
 			// Draft text for the delay box: typing must not save on every keystroke,
 			// and the box has to show the CLAMPED value once the save lands (type
 			// 99999 and it settles on the 600 cap instead of lying about it).
@@ -1846,7 +2295,7 @@ window.__ModuleLoader__.load({
 				const next = normalizeUnreadConfig({ ...unreadConfig, ...patch });
 				emitUnreadConfig(next);
 				rpc.call("/api", "iconCustom/setUnreadRule", {
-					args: { request: { reasons: next.reasons, pending: next.pending, workspaceDot: next.workspaceDot, clearDelaySec: next.clearDelaySec } }
+					args: { request: { reasons: next.reasons, pending: next.pending, workspaceDot: next.workspaceDot, appBadge: next.appBadge, clearDelaySec: next.clearDelaySec } }
 				}).catch(() => {});
 			}, [rpc]);
 			// Toggle one unread reason. Applies locally at once; the host keeps the
@@ -1861,6 +2310,11 @@ window.__ModuleLoader__.load({
 			const onWorkspaceDotToggle = React.useCallback((checked) => {
 				saveUnreadRule({ workspaceDot: checked });
 			}, [saveUnreadRule]);
+			// The system-icon projection of the same number. Saved through the same
+			// one save path, so this field can never be dropped by a caller.
+			const onAppBadgeToggle = React.useCallback((checked) => {
+				saveUnreadRule({ appBadge: checked });
+			}, [saveUnreadRule]);
 			// Seconds you must stay in a session before it counts as read; 0 = as soon
 			// as you enter. Clamped by the shared normalizer, so a stray keystroke can
 			// never persist an absurd delay.
@@ -2129,6 +2583,20 @@ window.__ModuleLoader__.load({
 						),
 						React.createElement("div", { style: style.hint }, t("workspaceDotHint"))
 					),
+					React.createElement("div", { style: { marginTop: "10px" } },
+						React.createElement("label", { style: { display: "inline-flex", alignItems: "center", gap: "6px", fontSize: 12, color: "var(--dsw-alias-label-primary)", cursor: "pointer" } },
+							React.createElement("input", {
+								type: "checkbox",
+								checked: unread.appBadge !== false,
+								onChange: (event) => onAppBadgeToggle(event.target.checked === true)
+							}),
+							React.createElement("span", null, t("appBadgeLabel"))
+						),
+						React.createElement("div", { style: style.hint }, t("appBadgeHint")),
+						// What THIS device is — never a claim about the platform.
+						React.createElement("div", { style: style.hint }, t(appBadgeCapabilityKey(appBadgeProbe))),
+						React.createElement("div", { style: style.hint }, t("appBadgeFootnote"))
+					),
 					React.createElement("div", { style: style.hint }, t("badgeTestHint"))
 				),
 				notice ? React.createElement("div", { style: style.notice }, notice) : null,
@@ -2145,6 +2613,10 @@ window.__ModuleLoader__.load({
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "dsh-icon-custom: dictionaries");
 			const t = ctx.locale.bind(NS);
 			const rpc = ctx.connection.rpc;
+			// The watermark's Host half rides the same connection as every other RPC.
+			// Setting it here (not at module scope) is what keeps the store usable in a
+			// test harness with no connection: pushes stay no-ops, the badge still works.
+			seenRpc = rpc;
 			// Pull the host state once, so the brand mark and the badge are correct
 			// before the settings section is ever opened. The unread rule rides its
 			// own endpoint: the icon RPCs keep their pre-badge response shape.
@@ -2156,8 +2628,16 @@ window.__ModuleLoader__.load({
 					if (resp === null || typeof resp !== "object" || resp.ok !== true) return;
 					// The rule response carries the Host's clock; it is what puts the seen
 					// watermark (and a legacy browser-domain store) into the Host's domain.
-					if (resp.value !== null && typeof resp.value === "object") noteHostClock(resp.value.hostNow);
+					// It also carries the Host's watermark table, which merges in here —
+					// then the first push sends the union back, which is both the migration
+					// (marks this browser made before 0.11.2) and the self-heal (a Host file
+					// that was lost or pruned gets this browser's copy back).
+					if (resp.value !== null && typeof resp.value === "object") {
+						noteHostClock(resp.value.hostNow);
+						if (adoptHostSeen(resp.value.seen)) saveSeenState();
+					}
 					emitUnreadConfig(resp.value);
+					scheduleHostSync();
 				})
 				.catch(() => {});
 			// Keep "the last moment this browser was here" fresh, so an ending that
@@ -2180,18 +2660,33 @@ window.__ModuleLoader__.load({
 			// Re-sample the Host↔browser clock offset after a sleep/resume, which is the
 			// one moment the two can drift apart mid-page. Throttled: it is one small
 			// RPC per visible-again, and never on beforeunload (nothing would come back).
+			// The same response carries the Host's watermark, so this is also how a
+			// SECOND device learns that something was read elsewhere — a page that is
+			// simply left open converges within a minute without a reload. Coming back
+			// into view is also the natural moment to retry a failed push.
 			ctx.effect(() => {
 				let sampledAt = 0;
 				const sample = () => {
 					if (document.visibilityState === "hidden") return;
+					scheduleHostSync();
 					if (Date.now() - sampledAt < 60000) return;
 					sampledAt = Date.now();
 					rpc.call("/api", "iconCustom/getUnreadRule", { args: {} })
-						.then((resp) => { if (resp && resp.ok === true && resp.value !== null && typeof resp.value === "object") noteHostClock(resp.value.hostNow); })
+						.then((resp) => {
+							if (resp === null || typeof resp !== "object" || resp.ok !== true) return;
+							const value = resp.value !== null && typeof resp.value === "object" ? resp.value : null;
+							if (value === null) return;
+							noteHostClock(value.hostNow);
+							if (adoptHostSeen(value.seen)) { saveSeenState(); emitUnreadPoke(); }
+						})
 						.catch(() => {});
 				};
 				window.addEventListener("visibilitychange", sample);
-				return () => window.removeEventListener("visibilitychange", sample);
+				const interval = window.setInterval(sample, 60000);
+				return () => {
+					window.removeEventListener("visibilitychange", sample);
+					window.clearInterval(interval);
+				};
 			}, "dsh-icon-custom: host clock sample");
 			// Brand-mark seat: replaces only the whale mark (verified: a
 			// third-party registration wins over the official occupant and the
@@ -2271,7 +2766,10 @@ window.__ModuleLoader__.load({
 				observer.observe(document.head, { childList: true, subtree: true, attributes: true, attributeFilter: ["href", "rel"] });
 				window.addEventListener("visibilitychange", schedule);
 				window.addEventListener("focus", schedule);
-				const interval = window.setInterval(reconcileFavicon, 5000);
+				const interval = window.setInterval(() => {
+					reconcileFavicon();
+					reassertAppBadge();
+				}, 5000);
 				return () => {
 					observer.disconnect();
 					window.removeEventListener("visibilitychange", schedule);