@cowwo/dsh-icon-custom 0.10.1 → 0.11.1

package/README.md

@@ -43,6 +43,38 @@ Notes:
 - It can be toggled at any time after upload — no re-upload needed.
 - This only affects the sidebar brand mark (the one next to `deepseek HARNESS`); PWA/installed-app icons are a separate option above.
 
+## App icon badge (the red dot on the system icon)
+
+Once the page is **installed as an app**, the same unread number is also shown on the **system icon**. The switch lives in **Settings → icon管理 → unread badge** ("Badge the system app icon") and is **on by default**; the number is **exactly the page number** (one computation, no extra clamping), so the two can never disagree.
+
+> ⚠️ **What it looks like on Windows depends on which browser installed the app**:
+> - **Installed with Chrome**: Chrome **draws its own overlay icon** on the taskbar button — a **dark circle with the white number**, at the lower-right of the icon. **Not a red dot, and not part of our artwork.** Above 99 it shows `99+`.
+> - **Installed with Edge**: Edge goes through the **Windows badge channel**, so the badge uses the system style. Microsoft's docs say both empty and numeric badges are supported, but on Windows 11 this machine still drew only a system-blue dot when calling `navigator.setAppBadge(7)` directly from DevTools (2026-10-01). The plugin now has a **5-second low-frequency watchdog** that keeps re-asserting a positive number, but whether Edge/Windows renders it as a number or a dot is ultimately up to the system. For a reliable number, installing with Chrome is the current workaround.
+>
+> Either way it exists **only while the app window is open**: close the window and it is gone (that is not a bug), and nothing can refresh it afterwards (there is no push server, so with no page running there is no code running).
+
+Platform support as of 0.11.1:
+
+| Platform | Badge | Status |
+|---|---|---|
+| Windows **Chrome** 81+ | Dark circle + **white number** (Chrome's own overlay icon, lower-right) | Confirmed by Chrome's docs screenshot + Chromium source; **not yet measured on this machine** |
+| Windows **Edge** 81+ | Goes through the Windows badge channel; Microsoft's docs support numbers, but this machine measured the number being drawn as a dot | **Measured anomaly** (2026-10-01) |
+| macOS Chrome / Edge 81+ | Dock badge | Unverified (the code is ready; same single call) |
+| macOS Safari 17+ ("Add to Dock") | Dock badge | Unverified |
+| iOS / iPadOS Safari 16.4+ (Add to Home Screen) | Number on the home-screen icon | Unverified; and it appears **only after notifications have been granted** — this plugin does not request that permission yet, so no badge on iOS for now |
+| Android Chrome / Edge | — | **Not supported by the system**: Chromium compiles the badge implementation out on Android, and a launcher dot can only come from a **notification** (this plugin posts none) |
+| HarmonyOS | — | No public evidence of any implementation; **expected unsupported** (native badges there are ArkTS-only) |
+| Firefox / Linux Chromium | — | No API / no OS API — calls resolve and do nothing |
+
+The "Current environment" line in the settings page reports **local facts only** (secure context? API present? installed as an app?). It never promises a badge will appear, because **detecting the API is not delivery** (that is exactly the Android and Linux case, and iOS adds a permission on top). Whether it really shows is up to the system.
+
+Two behaviours that look like bugs but are not:
+
+- **A "manual test" number typed in a normal browser tab produces no taskbar badge** — correct: the badge belongs to the **installed app window**; a plain tab's call is silently ignored.
+- **No badge when the page is reached over LAN `http://192.168.x.x`** — the Badging API requires a secure context; the settings page then says to use localhost or https.
+
+The reasoning (why no notifications, why no service worker, why no platform gating) is recorded in [`docs/adr/0005-app-icon-badge.md`](./docs/adr/0005-app-icon-badge.md).
+
 ## Format support
 
 - **SVG** — recognized by content (`<svg`), validated against script / event‑handler / `javascript:` injection. Rasterized to PNG in the browser before upload.

package/README.zh.md

@@ -58,14 +58,47 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
 规则:
 
 - 数字 = **几个会话**在等你(不是几件事);同一个会话只占一格。
-- 只有子代理会话不计。**你正开着的那个会话也算**——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分;要清掉它,切走再切回来即可。
+- 只有子代理会话不计。**你正开着的那个会话也算**——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分;**要清掉它,切走再切回来即可**(你人已经在里面时又结束的那一轮不会自动消,见下一条)。
 - **已读记在每个浏览器自己身上**(localStorage):进过 = 处理过,刷新/重启不会"复活";装插件之前的历史结束也不算。
-- **可以要求"待够才算已读"**:设置页填一个秒数(默认 0)。填 0 = 进去就算已读(红点立即消失);填 N = 你要在那个会话里**连续待满 N 秒**它才算看过——中途切走、或它又跑完一轮,都清零重数,刷新页面也重新数。上限 600 秒。
+- **可以要求"待够才算已读"**:设置页填一个秒数(默认 0)。填 0 = 进去就算已读(红点立即消失);填 N = 你要在那个会话里**连续待满 N 秒**它才算看过,中途切走就清零重数,刷新页面也重新数。上限 600 秒。
+  **计时只认"你进入会话时已经存在的那次结束"**:你人已经在会话里的时候它又跑完一轮,那一轮**不算数**——红点会一直亮着,等你**切走再进来**才消。这样"我正看着的会话跑完了"这件事不会被几秒钟后自动抹掉(0.11.1 起;此前是"停留满 N 秒就把最新那次结束也标成已读",红点只闪一下)。
 - 数据全部来自官方:`turn/end` 事件经官方 session projection 折叠,加上官方的"等待交互"注册表——**不依赖任何其他插件**。
 - 设置页的**数据来源**可以切到"手动测试",手填数字试看效果。
 - **工作区和会话行上的红点(实验)**:侧栏每个**工作区**那一行的文件夹图标右上角一个小红点,每个**有未读的会话**在标题右边跟一个小红点——一眼看出"事情在哪个工作区的哪个会话"。这一项是**贴着页面结构**做的——DSH 大版本升级后**可能失效**,失效时只会变成"不显示",**不影响**红点数字、清单和跳转;设置页里有一个开关可以随时关掉它。
 - **想知道具体是哪个会话?** 侧栏「工作区」标题的**右上角**有一个**红底数字**(没有待处理时是灰色 0,位置不变);点开是待处理会话清单,**按工作区分组**(工作区名 · 会话名 · 在等你/刚结束),点其中一条**直接跳到那个会话**。
 
+## 应用图标角标(系统图标上的红点)
+
+把网页**安装为应用**后,同一个未读数字也会显示在**系统图标**上。设置在**设置 → icon管理 → 未读红点**里的「在系统应用图标上显示红点」,**默认打开**;数字与页内红点**严格同值**(同一份计算,不额外截断),所以两个地方永远一致。
+
+> ⚠️ **Windows 上它长什么样——取决于你用什么浏览器装**:
+> - **Chrome 装的**:Chrome **自己画**一张覆盖图标贴在任务栏按钮上——**深灰圆 + 白色数字**,位置在图标右下角。**不是红色圆点,也不是我们图标的一部分**。数字超过 99 显示 `99+`。
+> - **Edge 装的**:Edge 走 **Windows 系统徽章通道**,外观是系统样式。官方文档说支持数字和空角标,但本机在 Windows 11 上实测(2026-10-01)控制台直接 `navigator.setAppBadge(7)` 也只出现一个系统蓝点。插件已加 **5 秒低频看门狗**,会持续重设正向数字,但最终画成数字还是点由 Edge/Windows 决定;想要稳定数字,可用 Chrome 安装。
+>
+> 两种情况下都:**只在应用窗口开着的时候存在**——关掉窗口角标就消失(这不是插件坏了),窗口全关之后也不会再更新数字(没有推送服务,页面不在就没有代码在跑)。
+
+平台支持情况(截至 0.11.1):
+
+| 平台 | 角标 | 状态 |
+|---|---|---|
+| Windows **Chrome** 81+ | 深灰圆 + **白色数字**(Chrome 自己画的覆盖图标,右下角) | 官方文档示例图 + 源码印证;**本机待实测** |
+| Windows **Edge** 81+ | 走 Windows 系统徽章通道;官方文档支持数字,但本机实测数字被画成点(待 Edge/Windows 侧修复) | **本机实测异常**(2026-10-01) |
+| macOS Chrome / Edge 81+ | Dock 角标 | 未验证(代码已就绪,同一行不会额外做事) |
+| macOS Safari 17+(「添加到程序坞」) | Dock 角标 | 未验证 |
+| iOS / iPadOS Safari 16.4+(加到主屏) | 主屏图标上的数字 | 未验证;且**必须先授予通知权限**才会显示——本插件目前不申请通知权限,所以 iOS 上暂时不会出现 |
+| Android Chrome / Edge | —— | **系统不支持**:Chromium 在安卓上把角标实现编译掉了;启动器上的圆点只能由**通知**产生(本插件不发通知) |
+| 鸿蒙 | —— | 无任何公开实现证据,**预计不支持**(鸿蒙的原生角标只能用 ArkTS 设) |
+| Firefox / Linux Chromium | —— | 不支持 / 没有系统 API,调用静默无效 |
+
+设置页里那行「当前环境」只报**本机此刻的事实**(是不是安全上下文、有没有这个 API、是不是已安装的应用),它**不**承诺角标一定会出现——因为**探测到 API ≠ 会显示**(安卓、Linux 上就是如此;iOS 还多一道通知权限)。是否真正显示由系统决定。
+
+顺便说明两个容易被当成 bug 的现象:
+
+- **在浏览器标签页里填「手动测试」数字,任务栏没有角标** —— 这是对的:角标只属于**安装后的应用窗口**,普通标签页调用是静默无操作。
+- **局域网 `http://192.168.x.x` 访问时没有角标** —— Badging API 要求安全上下文,这时设置页会提示"请用 localhost 或 https 访问"。
+
+设计取舍(为什么不做通知、不做 service worker、为什么不按平台门禁)记在 [`docs/adr/0005-app-icon-badge.md`](./docs/adr/0005-app-icon-badge.md)。
+
 ## 支持的格式
 
 - **SVG** — 按内容(`<svg`)识别,并拦截 `<script>` / 事件属性 / `javascript:` 注入。上传前会在浏览器里栅格化成 PNG。

package/client/client.js

@@ -60,12 +60,27 @@ window.__ModuleLoader__.load({
 			unreadWaiting: "在等你",
 			unreadEnded: "刚结束,还没看",
 			unreadPanelOther: "其他",
+			unreadMarkAllRead: "全部标记已读",
+			/** 与官方侧栏同一形状("13小时"),方便和列表里的时间戳逐字对上。 */
+			ageNow: "刚刚",
+			ageMinutes: "{n}分钟",
+			ageHours: "{n}小时",
+			ageDays: "{n}天",
+			ageMonths: "{n}个月",
+			ageYears: "{n}年",
 			workspaceDotLabel: "在工作区和会话行上显示红点(实验)",
 			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 秒。"
 		};
 		const en = {
 			nav: "Favicon",
@@ -118,12 +133,27 @@ window.__ModuleLoader__.load({
 			unreadWaiting: "waiting for you",
 			unreadEnded: "ended, not seen yet",
 			unreadPanelOther: "Other",
+			unreadMarkAllRead: "Mark all read",
+			/** Same shape as the shipped sidebar ("13h"), so the two can be read side by side. */
+			ageNow: "now",
+			ageMinutes: "{n}min",
+			ageHours: "{n}h",
+			ageDays: "{n}d",
+			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.",
+			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."
 		};
 		//#endregion
 
@@ -239,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) {
@@ -260,33 +292,83 @@ 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);
 			return () => { unreadConfigListeners.delete(fn); };
 		}
 
-		const SEEN_STORE_KEY = "dsh-icon-custom.unread-seen.v1";
+		/**
+		 * The seen watermark lives in the HOST's clock domain.
+		 *
+		 * 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
+		 * browser a few seconds behind the Host therefore wrote marks that never
+		 * reached `endAt`, so the dot could not be cleared by entering the session at
+		 * 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.
+		 */
+		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";
 		const SEEN_MAX = 400;
+		/** 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). */
+		function hostNow() {
+			return Date.now() + (hostClockOffset === null ? 0 : hostClockOffset);
+		}
 		function loadSeenState() {
 			try {
 				const raw = JSON.parse(window.localStorage.getItem(SEEN_STORE_KEY) || "null");
-				if (raw === null || typeof raw !== "object") return { lastActiveAt: 0, seen: {} };
-				const seen = raw.seen !== null && typeof raw.seen === "object" ? raw.seen : {};
-				return { lastActiveAt: typeof raw.lastActiveAt === "number" ? raw.lastActiveAt : 0, seen };
-			} catch { return { lastActiveAt: 0, seen: {} }; }
+				if (raw !== null && typeof raw === "object" && raw.domain === "host") {
+					const seen = raw.seen !== null && typeof raw.seen === "object" ? raw.seen : {};
+					return { domain: "host", lastActiveAt: typeof raw.lastActiveAt === "number" ? raw.lastActiveAt : 0, seen };
+				}
+				const legacy = JSON.parse(window.localStorage.getItem(LEGACY_SEEN_STORE_KEY) || "null");
+				if (legacy !== null && typeof legacy === "object") {
+					const seen = legacy.seen !== null && typeof legacy.seen === "object" ? legacy.seen : {};
+					return { domain: "browser", lastActiveAt: typeof legacy.lastActiveAt === "number" ? legacy.lastActiveAt : 0, seen };
+				}
+			} catch { /* fall through to an empty store */ }
+			return { domain: "host", lastActiveAt: 0, seen: {} };
 		}
 		const seenState = loadSeenState();
-		/** When this browser last had the app open before this page load. */
+		/** When this browser last had the app open before this page load (host domain). */
 		const seenBootAt = seenState.lastActiveAt > 0 ? seenState.lastActiveAt : 0;
 		function saveSeenState() {
-			try { window.localStorage.setItem(SEEN_STORE_KEY, JSON.stringify(seenState)); } catch {}
+			try {
+				window.localStorage.setItem(SEEN_STORE_KEY, JSON.stringify({ domain: "host", lastActiveAt: seenState.lastActiveAt, seen: seenState.seen }));
+			} catch {}
+		}
+		/**
+		 * Learn the Host↔browser clock offset from a Host timestamp, and fold a
+		 * legacy browser-domain store into the host domain. Idempotent: the fold
+		 * happens once, on the first sample that carries a usable `hostNow`.
+		 * @param hostAt - the Host's `Date.now()`, or anything else (ignored).
+		 */
+		function noteHostClock(hostAt) {
+			if (typeof hostAt !== "number" || !Number.isFinite(hostAt) || hostAt <= 0) return;
+			const offset = hostAt - Date.now();
+			hostClockOffset = offset;
+			if (seenState.domain === "host") return;
+			seenState.domain = "host";
+			if (seenState.lastActiveAt > 0) seenState.lastActiveAt += offset;
+			for (const id of Object.keys(seenState.seen)) {
+				if (typeof seenState.seen[id] === "number") seenState.seen[id] += offset;
+			}
+			saveSeenState();
 		}
 		function pruneSeenState() {
 			const ids = Object.keys(seenState.seen);
@@ -294,10 +376,20 @@ window.__ModuleLoader__.load({
 			ids.sort((a, b) => seenState.seen[b] - seenState.seen[a]);
 			for (const id of ids.slice(SEEN_MAX)) delete seenState.seen[id];
 		}
-		/** Record that this browser is looking at a session right now. */
-		function noteSeen(sessionId) {
+		/**
+		 * Record that this browser has seen a session up to `seenAt` — the
+		 * host-domain `endAt` being acknowledged. Marks never move backwards, so a
+		 * late attempt cannot undo a newer one.
+		 * @param sessionId - the session that was looked at.
+		 * @param seenAt - host-domain watermark to store; defaults to the Host's now.
+		 * @returns whether the mark actually advanced.
+		 */
+		function noteSeen(sessionId, seenAt) {
 			if (typeof sessionId !== "string" || sessionId === "") return false;
-			seenState.seen[sessionId] = Date.now();
+			const mark = typeof seenAt === "number" && Number.isFinite(seenAt) ? seenAt : hostNow();
+			const previous = seenState.seen[sessionId];
+			if (typeof previous === "number" && previous >= mark) return false;
+			seenState.seen[sessionId] = mark;
 			return true;
 		}
 		/**
@@ -307,7 +399,7 @@ window.__ModuleLoader__.load({
 		 * @returns whether anything was learned (callers persist only then).
 		 */
 		function ensureSeenBaseline(ids) {
-			const fallback = seenBootAt > 0 ? seenBootAt : Date.now();
+			const fallback = seenBootAt > 0 ? seenBootAt : hostNow();
 			let changed = false;
 			for (const id of ids) {
 				if (typeof id !== "string" || id === "") continue;
@@ -318,53 +410,46 @@ window.__ModuleLoader__.load({
 			return changed;
 		}
 		/**
-		 * The session the main view is showing.
+		 * Every session the main view is showing.
 		 *
-		 * DSH 0.2.x carries NO `current` field in the session-list snapshot — it is
-		 * written with exactly `ids` / `byId` / `phase` / `projectionsBySession`. The
-		 * official signal is the row's `retainedBy.mainView` retention count, the same
-		 * one ui-layout's DocumentTitle, ui-cordis, ui-open-in-app and ui-session read.
-		 * Reading `list.current` here made `noteSeen()` a no-op, so the seen watermark
-		 * never advanced and an unread dot could never be cleared by opening the
-		 * session. Runtimes that do expose `current` are still honoured first.
+		 * The official signal is the row's `retainedBy.mainView` retention count, the
+		 * same one ui-layout's DocumentTitle, ui-cordis, ui-open-in-app and ui-session
+		 * read (`list.current` is honoured first for runtimes that expose it).
+		 *
+		 * It returns ALL of them, not one. The pane retains the incoming session
+		 * BEFORE it releases the outgoing one, and a retention that outlives its pane
+		 * can leave an old session looking "current" for good — and picking a single
+		 * id then meant the session you were actually reading was never marked read:
+		 * the dot stayed red however long you stayed in it. Each retained session
+		 * gets its own stay clock instead.
 		 * @param list - the session list snapshot (may be absent).
-		 * @returns the id being viewed, or undefined.
+		 * @returns the ids being viewed, in list order; `[]` when there are none.
 		 */
-		function currentSessionId(list) {
-			if (list === null || typeof list !== "object") return undefined;
-			if (typeof list.current === "string" && list.current !== "") return list.current;
+		function currentSessionIds(list) {
+			if (list === null || typeof list !== "object") return [];
+			if (typeof list.current === "string" && list.current !== "") return [list.current];
 			const byId = list.byId;
-			if (byId === null || typeof byId !== "object") return undefined;
+			if (byId === null || typeof byId !== "object") return [];
+			const ids = [];
 			for (const session of Object.values(byId)) {
 				if (session === null || typeof session !== "object") continue;
 				const retainedBy = session.retainedBy;
 				const count = retainedBy !== null && typeof retainedBy === "object" ? retainedBy.mainView : undefined;
-				if (typeof count === "number" && count > 0) return session.id;
+				if (typeof count === "number" && count > 0 && typeof session.id === "string" && session.id !== "") ids.push(session.id);
 			}
-			return undefined;
+			return ids;
 		}
 		/**
-		 * 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.
+		 * One session's last `turn/end` timestamp (host domain), or 0 when it has
+		 * none. The projection is what the Host folded; an unknown reason still
+		 * carries the time.
+		 * @param entry - the session-list row (may be absent).
+		 * @returns the epoch milliseconds, or 0.
 		 */
-		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 : {};
-			const entry = byId[sessionId];
+		function lastTurnEndAt(entry) {
 			const values = entry !== null && typeof entry === "object" ? entry.projectionValues : undefined;
 			const value = values !== null && typeof values === "object" ? values[LAST_TURN_END_KEY] : undefined;
-			const endAt = value !== null && typeof value === "object" && typeof value.endAt === "number" ? value.endAt : 0;
-			return `${sessionId}\u0000${endAt}`;
+			return value !== null && typeof value === "object" && typeof value.endAt === "number" ? value.endAt : 0;
 		}
 		/**
 		 * How many sessions deserve the badge right now: endings whose reason is
@@ -473,6 +558,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) {
@@ -504,6 +591,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
@@ -724,6 +985,19 @@ window.__ModuleLoader__.load({
 			unreadPanelListeners.add(fn);
 			return () => { unreadPanelListeners.delete(fn); };
 		}
+		/**
+		 * Tells the badge source that the marks moved somewhere it did not touch —
+		 * the panel's "mark all read". It must re-render to re-emit the number (which
+		 * also repaints the row dots and rebuilds the tab badge).
+		 */
+		const unreadPokeListeners = new Set();
+		function emitUnreadPoke() {
+			unreadPokeListeners.forEach((fn) => { try { fn(); } catch {} });
+		}
+		function subscribeUnreadPoke(fn) {
+			unreadPokeListeners.add(fn);
+			return () => { unreadPokeListeners.delete(fn); };
+		}
 		function toggleUnreadPanel(anchor) {
 			emitUnreadPanel(!unreadPanelOpen, anchor === undefined ? null : anchor);
 		}
@@ -773,6 +1047,97 @@ window.__ModuleLoader__.load({
 			}
 			return groups;
 		}
+		/**
+		 * Age buckets, in the shipped sidebar's own units.
+		 *
+		 * Same thresholds as the official `relativeTime`: under a minute "now", then
+		 * minutes / hours / days / months / years. Deliberately copied instead of
+		 * imported — a display plugin must not depend on a Harness Client package —
+		 * but the SHAPE has to match the sidebar's, because the whole point of
+		 * showing it here is that a reader can line the panel's "13小时" up with the
+		 * timestamp on the row itself.
+		 * @param at - host-domain epoch milliseconds.
+		 * @param now - host-domain now.
+		 * @returns `{ unit, n }`, `unit` in `now|minutes|hours|days|months|years`.
+		 */
+		function relativeAgeParts(at, now) {
+			const MINUTE = 60000, HOUR = 3600000, DAY = 86400000;
+			const diff = Math.max(0, now - at);
+			if (diff < MINUTE) return { unit: "now", n: 0 };
+			if (diff < HOUR) return { unit: "minutes", n: Math.floor(diff / MINUTE) };
+			if (diff < DAY) return { unit: "hours", n: Math.floor(diff / HOUR) };
+			if (diff < 30 * DAY) return { unit: "days", n: Math.floor(diff / DAY) };
+			if (diff < 365 * DAY) return { unit: "months", n: Math.floor(diff / (30 * DAY)) };
+			return { unit: "years", n: Math.floor(diff / (365 * DAY)) };
+		}
+		/**
+		 * One ending's age as text ("13小时" / "13h"), or "" when there is no time.
+		 * @param at - host-domain epoch milliseconds, 0/absent for "unknown".
+		 * @param now - host-domain now.
+		 * @param t - locale binder.
+		 * @returns the label.
+		 */
+		function unreadAgeLabel(at, now, t) {
+			if (typeof at !== "number" || !Number.isFinite(at) || at <= 0) return "";
+			const { unit, n } = relativeAgeParts(at, now);
+			// Same shape as the shipped sidebar's own label: the "now" bucket carries
+			// no number.
+			return unit === "now" ? t("ageNow") : t(`age${unit[0].toUpperCase()}${unit.slice(1)}`, { n });
+		}
+		/**
+		 * A short, unambiguous handle for a session: the first 8 characters of its id.
+		 *
+		 * Two sessions can share a title — that is precisely what made one red dot look
+		 * unclearable, because the row could not be told apart from its namesake — and
+		 * this is what distinguishes them when the titles do not.
+		 * @param id - the session id.
+		 * @returns the short form, or "".
+		 */
+		function shortSessionId(id) {
+			if (typeof id !== "string" || id === "") return "";
+			const bare = id.startsWith("session-") ? id.slice("session-".length) : id;
+			return bare.slice(0, 8);
+		}
+		/**
+		 * The dim second line of one panel row: why it is listed, how long ago that
+		 * was, and which session it is.
+		 * @param item - a row from `collectUnread`.
+		 * @param now - host-domain now.
+		 * @param t - locale binder.
+		 * @returns the line, already joined.
+		 */
+		function unreadRowSubtitle(item, now, t) {
+			const parts = [item.waiting === true ? t("unreadWaiting") : t("unreadEnded")];
+			// A "waiting" row's `at` is Date.now() (it has no ending of its own), so only
+			// turn-end rows carry a readable age.
+			if (item.waiting !== true) {
+				const age = unreadAgeLabel(item.at, now, t);
+				if (age !== "") parts.push(age);
+			}
+			const short = shortSessionId(item.id);
+			if (short !== "") parts.push(short);
+			return parts.join(" · ");
+		}
+		/**
+		 * What "mark all read" may actually acknowledge: the turn-end rows.
+		 *
+		 * A "waiting for you" row is not watermark-based at all — it is listed while
+		 * that interaction is live, and no mark can clear it — so the caller must
+		 * leave it alone.
+		 * @param items - rows from `collectUnread`.
+		 * @returns `[{ id, seenAt }]`, each carrying the `endAt` it acknowledges.
+		 */
+		function unreadAckTargets(items) {
+			const targets = [];
+			for (const item of Array.isArray(items) ? items : []) {
+				if (item === null || typeof item !== "object") continue;
+				if (item.waiting === true) continue;
+				if (typeof item.id !== "string" || item.id === "") continue;
+				if (typeof item.at !== "number" || !Number.isFinite(item.at) || item.at <= 0) continue;
+				targets.push({ id: item.id, seenAt: item.at });
+			}
+			return targets;
+		}
 		//#endregion
 
 		//#region workspace dots
@@ -834,6 +1199,11 @@ window.__ModuleLoader__.load({
 			if (workspaceDotFailures < WS_MAX_FAILURES || workspaceDotGivenUp) return;
 			workspaceDotGivenUp = true;
 			try { console.warn("dsh-icon-custom: 工作区红点连续失败,本次会话内已自动关闭,可在设置里关掉这一项。"); } catch {}
+			// Take the markers OUT rather than leaving them frozen: a stale red dot
+			// that no longer reflects the rule (or that can never be cleared) is worse
+			// than no marker at all, and "breaks down to not showing" is this feature's
+			// stated posture.
+			clearWorkspaceDots();
 		}
 		/** The marker already sitting in this host for that key, or null. */
 		function existingMarker(host, attribute, key) {
@@ -898,6 +1268,38 @@ window.__ModuleLoader__.load({
 			if (rect.height < WS_ROW_MIN_H || rect.height > WS_ROW_MAX_H || rect.width < WS_ROW_MIN_W) return null;
 			return { title: label, row };
 		}
+		/**
+		 * The DOM row of one session, by the official row key.
+		 *
+		 * ui-workspace stamps every row with `data-row-key` (`session:<id>`,
+		 * `workspace:<id>`, `overflow:<id>`), which is the only stable, unambiguous
+		 * handle on a row: titles are neither unique (two sessions can share one) nor
+		 * stable (a generated title lands later). Matching by title text used to find
+		 * two rows and refuse, so a session whose title collided with another's could
+		 * never be marked at all.
+		 * @param container - the browsing region root.
+		 * @param id - the session id.
+		 * @returns the row element, or null.
+		 */
+		function sessionRowElement(container, id) {
+			if (typeof id !== "string" || id === "") return null;
+			try { return container.querySelector(`[data-row-key="session:${id}"]`); } catch { return null; }
+		}
+		/**
+		 * 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.
+		 * @returns `{ title, row }`, or null when this row cannot be trusted.
+		 */
+		function sessionRowTarget(container, id, title) {
+			const row = sessionRowElement(container, id);
+			if (row !== null) {
+				const inside = labelElementFor(row, title);
+				return inside === null ? null : titleTargetFor(inside, title);
+			}
+			return titleTargetFor(labelElementFor(container, title), title);
+		}
 		function paintWorkspaceDots() {
 			if (workspaceDotGivenUp) return;
 			const enabled = unreadConfig.workspaceDot !== false;
@@ -950,8 +1352,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 label = labelElementFor(container, entry.title);
-					const target = titleTargetFor(label, entry.title);
+					const target = sessionRowTarget(container, entry.id, entry.title);
 					if (target === null) { missed++; continue; }
 					if (existingMarker(target.row, ROW_DOT_ATTR, entry.id) !== null) { placed++; continue; }
 					const dot = document.createElement("span");
@@ -1031,26 +1432,78 @@ window.__ModuleLoader__.load({
 				pruneSeenState();
 				saveSeenState();
 			}, [list]);
-			const currentId = currentSessionId(list);
+			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). The timer 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 timer only lives in this page.
-			const currentUnread = items.some((item) => item.id === currentId);
-			const stayKey = currentUnread ? stayKeyFor(currentId, list) : "";
+			// 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 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
+			// ("mark all read"); re-render so the number, the row dots and the tab
+			// badge all follow immediately.
+			const [, bumpPoke] = React.useState(0);
+			React.useEffect(() => subscribeUnreadPoke(() => bumpPoke((n) => n + 1)), []);
+			// 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(() => {
-				if (stayKey === "") return undefined;
-				const markRead = () => { if (noteSeen(currentId)) { saveSeenState(); bumpStay((n) => n + 1); } };
-				if (delayMs <= 0) { markRead(); return undefined; }
-				const timer = window.setTimeout(markRead, delayMs);
-				return () => window.clearTimeout(timer);
-			}, [stayKey, currentId, delayMs]);
+				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 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;
+					let changed = false;
+					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); }
+				};
+				if (delayMs <= 0) attempt();
+				else timer = window.setTimeout(attempt, delayMs);
+				return () => {
+					cancelled = true;
+					if (timer !== 0) window.clearTimeout(timer);
+				};
+			}, [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.
@@ -1187,6 +1640,9 @@ window.__ModuleLoader__.load({
 			if (headerBadgeFailures < HEAD_BADGE_MAX_FAILURES || headerBadgeGivenUp) return;
 			headerBadgeGivenUp = true;
 			try { console.warn("dsh-icon-custom: 工作区标题红点连续失败,本次会话内已自动关闭。"); } catch {}
+			// Same posture as the row dots: give up by disappearing, never by freezing a
+			// number that has stopped following the rule.
+			clearHeaderBadge();
 		}
 
 		/**
@@ -1339,8 +1795,16 @@ window.__ModuleLoader__.load({
 		function UnreadPopup(props) {
 			const [snapshot, setSnapshot] = React.useState(badgeSnapshot);
 			const [open, setOpen] = React.useState(unreadPanelOpen);
+			// Ages are computed against the HOST's clock (the endings are host
+			// timestamps); re-tick while open so "刚刚" does not stay stale.
+			const [, tick] = React.useState(0);
 			React.useEffect(() => subscribeBadge(setSnapshot), []);
 			React.useEffect(() => subscribeUnreadPanel(() => setOpen(unreadPanelOpen)), []);
+			React.useEffect(() => {
+				if (!open) return undefined;
+				const interval = window.setInterval(() => tick((n) => n + 1), 30000);
+				return () => window.clearInterval(interval);
+			}, [open]);
 			React.useEffect(() => {
 				if (!open) return undefined;
 				const onKey = (event) => { if (event.key === "Escape") emitUnreadPanel(false); };
@@ -1374,6 +1838,22 @@ window.__ModuleLoader__.load({
 				boxShadow: "0 10px 30px rgba(0,0,0,.18)", color: "var(--dsw-alias-label-primary)", fontSize: "12px"
 			};
 			const items = Array.isArray(snapshot.items) ? snapshot.items : [];
+			const ackTargets = unreadAckTargets(items);
+			/**
+			 * Acknowledge every turn-end row at once.
+			 *
+			 * "Waiting for you" rows cannot be acknowledged (they are not watermark
+			 * based), so the panel stays open while any of them remain — closing it
+			 * would hide the one thing that still needs the reader.
+			 */
+			const markAllRead = () => {
+				let changed = false;
+				for (const target of ackTargets) if (noteSeen(target.id, target.seenAt)) changed = true;
+				if (!changed) return;
+				saveSeenState();
+				emitUnreadPoke();
+				if (ackTargets.length === items.length) emitUnreadPanel(false);
+			};
 			return React.createElement("div", { "data-icon-custom-unread": "1", style },
 				React.createElement("div", { style: { fontWeight: 600, padding: "2px 6px 8px" } }, t("unreadPanelTitle")),
 				items.length === 0
@@ -1389,10 +1869,17 @@ window.__ModuleLoader__.load({
 								style: { display: "block", width: "100%", textAlign: "left", padding: "6px 8px", border: "0", borderRadius: "8px", background: "transparent", color: "inherit", font: "inherit", cursor: "pointer" }
 							},
 								React.createElement("span", { style: { display: "block", overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" } }, item.title),
-								React.createElement("span", { style: { display: "block", opacity: 0.6, fontSize: "11px" } }, item.waiting === true ? t("unreadWaiting") : t("unreadEnded"))
+								React.createElement("span", { style: { display: "block", opacity: 0.6, fontSize: "11px" } }, unreadRowSubtitle(item, hostNow(), t))
 							))
 						))
-					)
+					),
+				ackTargets.length > 0 && React.createElement("div", { style: { marginTop: "6px", paddingTop: "6px", borderTop: "1px solid var(--dsw-alias-border-l2)" } },
+					React.createElement("button", {
+						type: "button",
+						onClick: markAllRead,
+						style: { display: "block", width: "100%", padding: "5px 8px", border: "0", borderRadius: "8px", background: "transparent", color: "inherit", font: "inherit", cursor: "pointer", opacity: 0.85 }
+					}, t("unreadMarkAllRead"))
+				)
 			);
 		}
 
@@ -1477,6 +1964,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).
@@ -1547,7 +2037,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
@@ -1562,6 +2052,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.
@@ -1830,6 +2325,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,
@@ -1853,12 +2362,21 @@ window.__ModuleLoader__.load({
 				.then((resp) => { if (resp && resp.ok === true) syncStatus(resp.value); })
 				.catch(() => {});
 			rpc.call("/api", "iconCustom/getUnreadRule", { args: {} })
-				.then((resp) => { if (resp && resp.ok === true) emitUnreadConfig(resp.value); })
+				.then((resp) => {
+					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);
+					emitUnreadConfig(resp.value);
+				})
 				.catch(() => {});
 			// Keep "the last moment this browser was here" fresh, so an ending that
 			// happens while the app is closed still counts as unread when you return.
 			ctx.effect(() => {
-				const touch = () => { seenState.lastActiveAt = Date.now(); saveSeenState(); };
+				// Host domain (see the seen store): "the last moment this browser was
+				// here" must be comparable with `turn/end.time`, not with the browser's
+				// own clock.
+				const touch = () => { seenState.lastActiveAt = hostNow(); saveSeenState(); };
 				const interval = window.setInterval(touch, 20000);
 				window.addEventListener("visibilitychange", touch);
 				window.addEventListener("beforeunload", touch);
@@ -1869,6 +2387,22 @@ window.__ModuleLoader__.load({
 					touch();
 				};
 			}, "dsh-icon-custom: unread watermark");
+			// 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).
+			ctx.effect(() => {
+				let sampledAt = 0;
+				const sample = () => {
+					if (document.visibilityState === "hidden") return;
+					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); })
+						.catch(() => {});
+				};
+				window.addEventListener("visibilitychange", sample);
+				return () => window.removeEventListener("visibilitychange", sample);
+			}, "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
 			// official package's mark steps aside). The brand NAME text is a
@@ -1947,7 +2481,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);

package/lib/index.js

@@ -459,17 +459,17 @@ export class FaviconCustomService extends TypertRemoteService {
 	 * icon RPCs (`getStatus` / `setIcon` / `setPwa` / `setLogo` / `resetIcon`)
 	 * keep their EXACT pre-badge response shape, so a problem in this feature
 	 * can never break the icon itself.
-	 * @returns `{ reasons, pending }`.
+	 * @returns `{ reasons, pending, workspaceDot, appBadge, clearDelaySec, hostNow }`.
 	 */
 	async getUnreadRule() {
-		return { reasons: this.unread.reasons, pending: this.unread.pending, workspaceDot: this.unread.workspaceDot, clearDelaySec: this.unread.clearDelaySec }
+		return this._unreadRuleView()
 	}
 
 	/**
 	 * typert endpoint: replace the unread-badge rule — which turn-end reasons
 	 * light the badge. The rule is applied on the client, so this takes effect
 	 * without re-folding any session log.
-	 * @param request - `{ reasons, pending?, workspaceDot?, clearDelaySec? }`; unknown or missing keys fall back to defaults.
+	 * @param request - `{ reasons, pending?, workspaceDot?, appBadge?, clearDelaySec? }`; unknown or missing keys fall back to defaults.
 	 * @returns the stored rule.
 	 */
 	async setUnreadRule(request) {
@@ -478,7 +478,28 @@ export class FaviconCustomService extends TypertRemoteService {
 		}
 		this.unread = normalizeUnreadConfig(request)
 		await this._saveUnread().catch(() => {}) // rule file is advisory
-		return { reasons: this.unread.reasons, pending: this.unread.pending, workspaceDot: this.unread.workspaceDot, clearDelaySec: this.unread.clearDelaySec }
+		return this._unreadRuleView()
+	}
+
+	/**
+	 * The rule as the client reads it, plus the Host's clock.
+	 *
+	 * `hostNow` is here because the badge compares the Host's `turn/end.time`
+	 * against a watermark this browser keeps: without a Host time sample the
+	 * browser has to guess that domain from its own clock, and a browser a few
+	 * seconds behind the Host then clears nothing. It rides this existing
+	 * response instead of a new endpoint, so an older client simply ignores it.
+	 * @returns the stored rule with `hostNow`.
+	 */
+	_unreadRuleView() {
+		return {
+			reasons: this.unread.reasons,
+			pending: this.unread.pending,
+			workspaceDot: this.unread.workspaceDot,
+			appBadge: this.unread.appBadge,
+			clearDelaySec: this.unread.clearDelaySec,
+			hostNow: Date.now()
+		}
 	}
 
 	/** typert endpoint: store a new icon uploaded as a data URL and make it active. */

package/lib/typert.host.js

@@ -53,14 +53,23 @@ const unreadRuleSchema = z.object({
 	pending: z.boolean(),
 	/** 实验项:工作区图标上的红点(贴产品 DOM,可一键关闭)。 */
 	workspaceDot: z.boolean(),
+	/** 在系统应用图标上显示角标(安装为应用后生效);只决定"设几/清空",样子由系统决定。 */
+	appBadge: z.boolean(),
 	/** 进入会话后要连续待满多少秒才算"看过";0 = 进入即已读。上限 10 分钟。 */
-	clearDelaySec: z.number().int().nonnegative().max(600)
+	clearDelaySec: z.number().int().nonnegative().max(600),
+	/**
+	 * 宿主此刻的 `Date.now()`。
+	 * 客户端用它把"看过"水位换算进宿主时钟域(`turn/end.time` 也是宿主时钟):
+	 * 浏览器与宿主差几秒,红点就会永远清不掉。
+	 */
+	hostNow: z.number()
 })
 
 const setUnreadRuleRequestSchema = z.object({
 	reasons: z.record(z.string(), z.boolean()),
 	pending: z.boolean().optional(),
 	workspaceDot: z.boolean().optional(),
+	appBadge: z.boolean().optional(),
 	clearDelaySec: z.number().int().nonnegative().max(600).optional()
 })
 
@@ -272,7 +281,7 @@ export const TYPERT = {
 					{
 						kind: 'method',
 						name: 'getUnreadRule',
-						signature: 'async getUnreadRule(): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; clearDelaySec: number }>',
+						signature: 'async getUnreadRule(): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; appBadge: boolean; clearDelaySec: number; hostNow: number }>',
 						description: "Read the unread-badge rule.",
 						summary: "Read the unread-badge rule.",
 						jsDoc: "/** Read the unread-badge rule. */",
@@ -281,7 +290,7 @@ export const TYPERT = {
 					{
 						kind: 'method',
 						name: 'setUnreadRule',
-						signature: 'async setUnreadRule(request: { reasons: Record<string, boolean>; pending?: boolean; workspaceDot?: boolean; clearDelaySec?: number }): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; clearDelaySec: number }>',
+						signature: 'async setUnreadRule(request: { reasons: Record<string, boolean>; pending?: boolean; workspaceDot?: boolean; appBadge?: boolean; clearDelaySec?: number }): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; appBadge: boolean; clearDelaySec: number; hostNow: number }>',
 						description: "Replace the unread-badge rule: which turn-end reasons light the red dot.",
 						summary: "Set the unread-badge rule.",
 						jsDoc: "/** Set the unread-badge rule. */",

package/lib/unread.js

@@ -52,6 +52,16 @@ export const UNREAD_PENDING_DEFAULT = true
  */
 export const UNREAD_WORKSPACE_DOT_DEFAULT = true
 
+/**
+ * 默认:在系统应用图标上显示角标(安装为应用后生效)。
+ *
+ * 它只是"同一个数字在系统图标上的投影",所以默认跟随红点一起打开;
+ * 关掉它等于"不要这个投影",而不等于"这个功能不存在"。
+ * 注意:**探测到 API ≠ 角标会出现**(安卓与 Linux 上方法存在但静默无效,
+ * iOS 上还额外要求通知权限),详见 docs/adr/0005-app-icon-badge.md。
+ */
+export const UNREAD_APP_BADGE_DEFAULT = true
+
 /**
  * 默认:进入会话即视为已读(0 秒)。
  * 大于 0 时,你必须在那个会话里**连续**待满这么多秒它才算"看过";中途切走会
@@ -87,8 +97,8 @@ export function normalizeReasons(input) {
 
 /**
  * 把任意输入夹成完整设置。
- * @param input - `{ reasons?, pending?, workspaceDot?, clearDelaySec? }`,可以是脏的、缺项的、null
- * @returns `{ reasons, pending, workspaceDot, clearDelaySec }` —— 每一项都完整
+ * @param input - `{ reasons?, pending?, workspaceDot?, appBadge?, clearDelaySec? }`,可以是脏的、缺项的、null
+ * @returns `{ reasons, pending, workspaceDot, appBadge, clearDelaySec }` —— 每一项都完整
  */
 export function normalizeUnreadConfig(input) {
 	const source = input !== null && typeof input === 'object' ? input : {}
@@ -96,6 +106,7 @@ export function normalizeUnreadConfig(input) {
 		reasons: normalizeReasons(source.reasons),
 		pending: typeof source.pending === 'boolean' ? source.pending : UNREAD_PENDING_DEFAULT,
 		workspaceDot: typeof source.workspaceDot === 'boolean' ? source.workspaceDot : UNREAD_WORKSPACE_DOT_DEFAULT,
+		appBadge: typeof source.appBadge === 'boolean' ? source.appBadge : UNREAD_APP_BADGE_DEFAULT,
 		clearDelaySec: normalizeClearDelay(source.clearDelaySec)
 	}
 }

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@cowwo/dsh-icon-custom",
-  "version": "0.10.1",
-  "description": "自定义浏览器标签页图标:在设置页上传 SVG/PNG/ICO,立即生效并持久保存,自动适配安卓/iOS/平板 PWA 图标。· Custom browser tab favicon: upload SVG/PNG/ICO from the settings page, applies instantly and persists, auto-sizes PWA icons for Android/iOS/tablets.",
+  "version": "0.11.1",
+  "description": "自定义浏览器标签页图标:在设置页上传 SVG/PNG/ICO,立即生效并持久保存,自动适配安卓/iOS/平板 PWA 图标,并可把未读数字显示为系统应用图标角标(Windows 任务栏)。· Custom browser tab favicon: upload SVG/PNG/ICO from the settings page, applies instantly and persists, auto-sizes PWA icons for Android/iOS/tablets, and projects the unread count onto the system app-icon badge (Windows taskbar).",
   "type": "module",
   "main": "lib/index.js",
   "license": "MIT",
+  "scripts": {
+    "test": "node test/app-badge.mjs && node test/unread-panel.mjs && node test/unread-clear.mjs"
+  },
   "dependencies": {
     "jimp": "^1.6.1",
     "zod": "^4.4.3"