dsh-workspace-status 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,19 +1,59 @@
 # Changelog
 
-## 0.1.0 — 2026-10-25
-
-### Added
-
-- First public release: coloured status marks on workspace rows (waiting, running,
-  recently finished) with locale-aware labels and a settings toggle.
-- Declares `dsh.catalog` so plugin markets place it under UI with a real summary.
-
 All notable changes to this package are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-26
+
+### Added
+
+- Pinned-only notifications. The pinned section watches the live status of
+  pinned conversations and notifies on transitions: a pinned conversation
+  starts waiting for you (approval, plan review or question) or finishes
+  unread. Running → idle with an unread completion fires once; repeated
+  renders, kind changes and late unread states are deduplicated, and the
+  first observation after a reload stays silent.
+- Desktop/OS notifications when the window is in the background, plus in-app
+  notices inside the pinned section so a focused window still surfaces the
+  event. Clicking a row-shaped notice opens that pinned conversation; notices
+  auto-dismiss after eight seconds or via the close button.
+- A bell toggle in the pinned section header turns pinned notifications on or
+  off and requests notification permission on first use; a speaker toggle
+  enables an optional two-note chime. Both preferences persist in browser
+  storage. The bell falls back to in-app notices when the OS blocks
+  notifications, and enabling notifications shows a one-off test notice.
+- Notifications are only emitted for transitions while the app is running;
+  they are not external push and do not notify sessions outside the pin set.
+
+## [0.2.0] - 2026-10-26
+
+### Added
+
+- Pinned conversations section above the Workspaces list. Pinned conversations
+  are lifted out of the regular workspace groups and rendered per workspace
+  with the shipped folder-header treatment, their live status dot, relative
+  time, current-session highlight, group counts and a filled pin icon on every
+  row. Clicking the pin unpins immediately.
+- Section and group collapse state persisted in browser storage; the section
+  caps its height and scrolls independently.
+- The section is driven by the registry-global `pinnedSessionIds` Workspace
+  feed, so pins survive restarts and stay in sync with the official browser;
+  unpin uses `ctx.workspaces.unpinSession`, opening a row uses
+  `ctx.uiWorkspace.openSession`.
+- Pinned rows are hidden from the official grouped/flat tree with generated
+  `display:none` rules; search-result rows are untouched.
+
+### Changed
+
+- Component now renders a React portal into a container inserted before the
+  sidebar browsing region, in addition to the emitted row stylesheet. The
+  official Workspace browser is still not replaced.
+- The workspace-mark mount now always publishes the stylesheet and portal
+  anchor, so pins added while mounted appear without a reload.
+
 ## [0.1.0] - 2026-10-25
 
 ### Added
@@ -29,3 +69,4 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Zero-fork implementation: an additive `sidebar.footer.action` entry that
   publishes row CSS keyed on `data-row-key="workspace:<id>"`, with no DOM
   writes, observers or host services.
+- Declares `dsh.catalog` so plugin markets place it under UI with a real summary.

package/README.md

@@ -1,13 +1,30 @@
 # dsh-workspace-status
 
-Colored status marks on the **workspace rows** of the DeepSeek Harness sidebar:
-waiting for you, running, and just finished.
+[![npm](https://img.shields.io/npm/v/dsh-workspace-status?label=npm&color=blue)](https://www.npmjs.com/package/dsh-workspace-status)
+[![npm provenance](https://img.shields.io/badge/npm%20provenance-SLSA%20v1-brightgreen)](https://www.npmjs.com/package/dsh-workspace-status)
+[![test](https://github.com/Stijnus/dsh-workspace-status/actions/workflows/test.yml/badge.svg)](https://github.com/Stijnus/dsh-workspace-status/actions/workflows/test.yml)
+[![license](https://img.shields.io/npm/l/dsh-workspace-status)](LICENSE)
+
+[English](./README.md) · [中文](./README.zh-CN.md)
+
+Sidebar upgrades for DeepSeek Harness:
+
+1. **Workspace status marks** — colored status on the workspace (folder) row:
+   waiting for you, running, and just finished, aggregated from the sessions
+   inside it.
+2. **Pinned conversations section** — conversations pinned through the shipped
+   pin action leave the regular workspace groups and appear in a dedicated
+   section above the browsing region, grouped per workspace with the same
+   header treatment and a pin icon on every row.
+3. **Pinned notifications** — when a pinned conversation starts waiting for
+   you or finishes unread, the plugin can raise a desktop notification (when the
+   window is in the background) and always shows an in-app notice in the pinned
+   section. Bell and chime toggles sit in the section header.
 
 Harness draws a status dot on every conversation row, but nothing on the
-workspace (folder) row above it. Collapse a group, or scroll it out of view, and
-the folder row cannot tell you that an agent inside is stuck waiting for an
-approval or still working. This plugin gives the folder row the same kind of
-mark, aggregated from its sessions:
+workspace row above it. Collapse a group, or scroll it out of view, and the
+folder cannot tell you that an agent inside is stuck waiting for an approval or
+still working. This plugin gives the folder row the same kind of mark.
 
 | Mark | Meaning | Color |
 |---|---|---|
@@ -21,6 +38,86 @@ for expanded and collapsed groups alike, and its state is described to
 screen-reader users in a hidden sentence ("Workspace activity: 2 running, 1
 waiting for you — api, web").
 
+## Pinned conversations
+
+Pinning is the shipped Harness action (row hover button or the row **…** menu).
+Once a conversation is pinned:
+
+- its row is lifted out of the regular workspace groups and listed in a
+  **Pinned** section between the global panel rows and the **Workspaces**
+  header;
+- the section is grouped per workspace, each group using the same 34px folder
+  row, blue active-folder color, disclosure triangle and radius as the shipped
+  browser, with a small count at the end;
+- every pinned row shows its live status dot, relative time, current-session
+  highlight, and a filled **pin icon** at its trailing edge; clicking the pin
+  unpins the conversation immediately — no restart, and it reappears in its
+  workspace group;
+- the Pinned header and each workspace group are collapsible, and that state is
+  remembered in browser storage;
+- the section caps its height and scrolls on its own, so a large pin set cannot
+  push the browsing region away;
+- the pin set is the registry-global `pinnedSessionIds` feed, persisted by the
+  Host in the profile workspace registry — after relaunch the same pins come
+  back and the section renders again;
+- search is untouched: pinned conversations still appear in search results,
+  while the regular grouped/flat tree hides the lifted rows.
+
+The pinned rows are hidden from the regular tree with generated
+`display:none` rules. The workspace header itself stays (so its *New session*
+action remains reachable), which means a workspace whose sessions are all
+pinned may read as an empty group under **Workspaces** while its sessions sit in
+the Pinned section.
+
+## Pinned notifications
+
+The bell in the Pinned header (next to the count) controls notifications; the
+speaker enables an optional two-note chime. Both preferences persist in browser
+storage and default to **notifications on, sound off**.
+
+What fires an event:
+
+- a pinned conversation **starts waiting for you** — approval, plan review or a
+  question (the notification names the reason and workspace);
+- a pinned conversation **finishes unread** — a running session stops and its
+  completion mark is still unread.
+
+Only transitions fire, only for pinned conversations. The first observation of
+a session after mount is silent, so reloading the app does not replay old
+events; repeated renders of the same waiting state are quiet, while a change of
+reason (approval → question) is a new event. Finished fires once per run.
+
+Delivery:
+
+- when the window is in the background and the platform has granted
+  notification permission, a **desktop/OS notification** is raised — clicking it
+  focuses the app and opens that conversation;
+- an **in-app notice** is always added inside the pinned section (also when the
+  OS blocks notifications), with a status icon, title and reason; click it to
+  open the conversation or dismiss it with **×**. Notices auto-dismiss after
+  eight seconds.
+
+The first click on the bell requests notification permission and shows a
+one-off test notice. If the OS denies or blocks notifications, the plugin falls
+back to the in-app notices and the bell tooltip says so. Notifications are
+client-side only: they fire while the app is running and are not external push
+(no email, IM or web push), and sessions outside the pin set never trigger
+them.
+
+## Quick start
+
+```sh
+dsh plugin --profile web add dsh-workspace-status
+```
+
+Restart the Harness (or refresh the Web UI). Workspace rows gain a colored status
+mark; pin a conversation to see the Pinned section and its bell/speaker
+controls.
+
+<sub>More from this suite: [Moodboard](https://github.com/Stijnus/dsh-moodboard) · [Composer Predictions](https://github.com/Stijnus/dsh-composer-predictions) · [Move to Workspace](https://github.com/Stijnus/dsh-move-to-workspace) · [Workspace Status](https://github.com/Stijnus/dsh-workspace-status) · [Prompt Rewrite](https://github.com/Stijnus/dsh-prompt-optimizer)</sub>
+
+<sub>⭐ If this saves you a step, a star helps the next DSH user find it.</sub>
+
 ## Preview
 
 ![Four sidebar rows: api waiting (amber dot), web running (blue ring), docs recently finished (green dot), sandbox idle (no mark)](docs/preview-mock.png)
@@ -29,7 +126,7 @@ This is the plugin's own stylesheet rendered over a local reproduction of the
 sidebar row DOM and theme tokens — a design preview, not a live screenshot. The
 shipped app draws the same marks on the real rows.
 
-## Rules
+## Rules for workspace marks
 
 - **Precedence matches the shipped session row:** waiting for the user beats
   running, which beats the finished reminder. A workspace therefore shows one
@@ -48,12 +145,13 @@ shipped app draws the same marks on the real rows.
   updated time only.
 - **Ungrouped sessions** mark the "Ungrouped" bucket row, which behaves like a
   workspace row in the sidebar.
-- **No mark when everything is idle.** The plugin renders nothing at all in
-  that case — no stylesheet, no hidden text.
+- **No mark when everything is idle.** The plugin renders nothing visible in
+  that case — no mark and no hidden activity sentence.
 
 The active workspace (the one containing the open conversation) is already
-marked natively: Harness paints the folder icon of the active chain blue. This
-plugin does not duplicate that.
+marked natively: Harness paints the folder icon of the active chain blue. The
+Pinned section mirrors that color on the group header that contains the current
+conversation.
 
 ## Install
 
@@ -85,6 +183,8 @@ profile's patch layer.
 
 ## Verify
 
+Workspace marks:
+
 1. Start a session in a workspace and collapse that group while it runs — a
    blue ring appears at the end of the folder row.
 2. Trigger an approval (or a plan review / question) in a session of another
@@ -93,42 +193,86 @@ profile's patch layer.
    hour later.
 4. Expand the group: the mark stays on the folder row; the session rows keep
    their own dots unchanged.
-5. With every session idle, no extra element appears in the sidebar.
 
-The client half writes nothing into the sidebar DOM — it reacts to the public
-Workspace/Session feeds and emits CSS keyed on the row the browser already
-renders. If the mark is missing, check the browser console for a failed client
-bundle load first; nothing else in the sidebar is affected.
+Pinned section:
+
+1. Pin any conversation from its row hover button or **…** menu — the Pinned
+   section appears above **Workspaces** without a restart, grouped under that
+   conversation's workspace, with a filled pin icon on the row.
+2. Pin a conversation from a second workspace — a second group header appears;
+   both groups keep the workspace header treatment and their own count.
+3. Click a pinned row — the conversation opens. Click the pin icon — the row
+   disappears from the Pinned section and returns to its workspace group
+   immediately.
+4. Collapse the Pinned header or a group — the state persists across reloads.
+5. Restart the Harness — the same pins are listed again, because the Host
+   persists the registry pin set in the profile workspace registry.
+
+Pinned notifications:
+
+1. Click the bell in the Pinned header. On first use it requests notification
+   permission and shows a test notice; the bell is highlighted while enabled.
+2. Pin a conversation that is running, then let it finish without opening it —
+   an in-app notice appears in the Pinned section; if the app window is in the
+   background, a desktop notification is raised as well. Clicking either opens
+   the conversation.
+3. Trigger an approval, plan review or question in a pinned conversation — the
+   notice names the reason and workspace and remains until dismissed.
+4. Click the bell again to turn notifications off, or the **×** on a notice to
+   dismiss it early. Reload: the bell, speaker and notification preferences
+   persist.
+
+If the plugin is missing, check the browser console for a failed client bundle
+load first; nothing else in the sidebar is affected.
 
 ## How it works
 
-- The mount is an entry in the additive `sidebar.footer.action` seat. It renders
-  only a `<style>` element and a visually hidden `<span>`; it is not a control
-  and adds nothing visible at the foot.
-- Aggregation reads the same public data the browser uses: `useWorkspaces`
-  (`items`, `archivedSessionIds`), `useSessions` (`byId`) and
+- The mount is an entry in the additive `sidebar.footer.action` seat. It
+  publishes a stylesheet, a visually hidden activity description, and a portal
+  anchor; it adds no control of its own at the foot.
+- Workspace marks read the same public data the browser uses: `useWorkspaces`
+  (`items`, `archivedSessionIds`, `pinnedSessionIds`), `useSessions` (`byId`) and
   `useSessionStatus` (`running`, `pendingInteraction`, `completionUnread`).
-- The visible mark is the workspace row's trailing pseudo-element, emitted as a
+- The workspace mark is the folder row's trailing pseudo-element, emitted as a
   rule targeting `[data-row-key="workspace:<id>"]::after`.
-- Removing the plugin removes the mount, which removes the stylesheet; no state
-  is written anywhere.
-
-### The one internal dependency
-
-`data-row-key="workspace:<id>"` is an internal detail of
-`@deepseek-ai/dsh-client-ui-workspace`, not a public slot contract. A future
-Harness release could rename it, in which case the marks would silently stop
-appearing until this package is updated. The failure mode is deliberately
-**"no indicator"**, not "broken sidebar": the plugin never touches the DOM, so a
-stale selector can only produce a missing dot.
+- The Pinned section is rendered through a React portal into a container
+  inserted immediately before the sidebar's `regionArea` element. The official
+  browser is not replaced: search, menus, drag ordering, dialogs and directory
+  picking stay native.
+- Pinned rows are lifted by hiding their `[data-row-key="session:<id>"]` rows
+  with generated CSS (`display:none!important`); search-result rows carry no
+  `data-row-key`, so they remain visible.
+- Unpin calls `ctx.workspaces.unpinSession(id)`; opening a pinned row calls
+  `ctx.uiWorkspace.openSession(id)`. The pin set itself comes from the
+  Workspace snapshot, so both the official tree and this section stay in sync.
+- Collapse memories and notification preferences live in browser
+  `localStorage`; no plugin settings are written. Notification delivery uses the
+  renderer's standard `Notification` API (and Web Audio for the optional chime);
+  the plugin does not add a host service.
+- Removing the plugin removes the mount, the stylesheet and the inserted
+  section container; no profile or session data is changed by the plugin.
+
+### Internal dependencies
+
+Two details belong to `@deepseek-ai/dsh-client-ui-workspace` / `ui-sidebar`
+rather than a public slot contract:
+
+- `data-row-key="workspace:<id>"` / `session:<id>` for row targeting;
+- the `…_regionArea` class token for the portal insertion point.
+
+A future Harness release could rename either; the failure modes are
+deliberately **"no mark / no section"**, not "broken sidebar": the plugin never
+replaces the browser and its DOM writes are limited to one inserted container.
+`react-dom` is a shared client platform module (the same baseline the shell
+seeds for every bundle), used only for the portal.
 
 ## Compatibility
 
 - DeepSeek Harness `>=0.2.1-rc.2 <0.3.0-0` (developed and verified against
   `0.2.1-rc.3`); Web and Desktop clients.
 - Node `>=22.18.0` for the build-free package and its tests.
-- No runtime dependencies, no host services, no settings, no model-visible
-  tools or prompt changes.
+- No host-side services, no settings, no model-visible tools or prompt changes.
+  Pins are the shipped Workspace registry pin set.
 
 ## Development
 
@@ -139,8 +283,10 @@ npm test
 The suite loads the classic-script client envelope in a sandbox, drives the slot
 component with fake standard hooks, and asserts the emitted stylesheet and
 hidden description across waiting/running/finished, subagent, archived,
-ungrouped, expiry and selector-escaping cases. A manifest test checks the bundle
-patch, export map, locale parity and the loader envelope.
+ungrouped, expiry, pinned grouping (workspace order, ungrouped bucket, archived
+/ blank / subagent exclusion), hide rules, pin precedence and selector
+escaping cases. A manifest test checks the bundle patch, export map, locale
+parity and the loader envelope.
 
 There is no build step: `index.js` and `client.js` are the published artifacts.
 
@@ -150,7 +296,9 @@ There is no build step: `index.js` and `client.js` are the published artifacts.
 dsh plugin --profile <profile> remove dsh-workspace-status
 ```
 
-Restart the Host. The sidebar returns to stock; nothing else is left behind.
+Restart the Host. The sidebar returns to stock; the inserted section container
+is removed with the plugin, and pins remain the shipped workspace registry
+state (unpin them through the normal pin action).
 
 ## License
 

package/README.zh-CN.md

@@ -0,0 +1,83 @@
+# dsh-workspace-status · 工作区状态与置顶会话
+
+[English](./README.md) · [中文](./README.zh-CN.md)
+
+为 DeepSeek Harness 侧边栏增加三层能力：
+
+1. **工作区状态标记**：在侧边栏的**工作区（文件夹）行**上显示彩色状态——等待你处理、正在运行、刚刚完成，由该工作区内的会话聚合而来。
+2. **已置顶会话区**：通过 Harness 原生置顶操作置顶的会话，会从常规工作区分组中提取出来，显示在工作区列表上方的独立区域；按工作区分组，沿用原生工作区行的样式，并在行尾显示置顶图标。
+3. **已置顶会话通知**：置顶会话开始等待你处理或运行结束未读时，窗口在后台会发系统通知，同时置顶区内始终显示应用内提醒；通知开关与提示音按钮位于置顶区标题栏。
+
+侧边栏本来就会在每个会话行上显示状态点，但上方的文件夹行什么都没有。收起分组或滚动之后，就看不出里面是否还有等待审批、仍在运行的会话。本插件补上这一层，并把置顶会话集中到列表上方。
+
+## 功能
+
+### 工作区状态标记
+
+| 标记 | 含义 | 颜色 |
+|---|---|---|
+| 实心点 | 有会话在等你：审批 / 计划评审 / 回答 | 琥珀 `--dsw-alias-state-warn-primary` |
+| 旋转圆环 | 有会话或子代理正在运行 | 蓝 `--dsw-static-deepseek-450` |
+| 实心点 | 有会话刚刚结束且尚未打开（1 小时提示窗口） | 绿 `--dsw-alias-state-success-primary` |
+
+- 状态优先级与原生会话行一致：等待 > 运行 > 刚刚完成；一个工作区同时只显示一个主标记。
+- 子代理的运行状态计入其父会话所在工作区；子代理行本身不产生标记。
+- 已归档会话忽略；未分组会话落在「未分组」行。
+- 标记固定在行尾时间戳的位置，不挤动标题；展开或收起都可见。
+- 提供隐藏的无障碍描述（如「工作区状态：2 个运行中、1 个等待你处理 — api、web」）。
+
+### 已置顶会话区
+
+- 使用 Harness 原生置顶操作（会话行悬停按钮或 **…** 菜单）；置顶后无需重启即可出现在 **Pinned / 已置顶** 区域。
+- 按工作区分组，每组沿用原生 34px 工作区行：文件夹图标、当前工作区蓝色高亮、折叠三角、圆角与计数。
+- 每行显示实时状态点、相对时间、当前会话高亮，以及行尾的实心**置顶图标**；点击图标立即取消置顶，行会回到原工作区分组。
+- Pinned 标题和各工作区分组都可折叠，折叠状态保存在浏览器本地。
+- 区块限高并可独立滚动，不会把工作区列表挤走。
+- 置顶集合来自 Harness 的 `pinnedSessionIds`（保存在 profile 的工作区注册表），重启后仍会显示同样的置顶会话与图标。
+- 搜索不受影响：已置顶会话仍然出现在搜索结果中；常规分组列表则隐藏被提取的行。
+- 常规列表中的工作区标题会保留（其「新会话」按钮仍可用），因此当某个工作区的会话全部被置顶时，常规列表里可能出现一个空分组，而会话显示在上方。
+
+### 已置顶会话通知
+
+- 触发条件（仅限已置顶会话）：开始等待你（审批 / 计划评审 / 提问），或运行结束且完成标记未读。
+- 只对状态**变化**发通知：刷新后的第一次观察保持安静，同一等待原因不会重复提醒，原因变化（审批 → 提问）会再次提醒，完成只在每次运行结束时提醒一次。
+- 窗口在后台且系统已授权时发**桌面通知**；点击通知会聚焦应用并打开对应会话。
+- 置顶区**始终**显示应用内提醒（系统阻止通知时同样可用），带状态图标、标题与原因；点击打开会话，点 **×** 或等待 8 秒自动消失。
+- 标题栏的铃铛开关通知并在首次点击时申请权限、显示一条测试提醒；喇叭开关可选的两声提示音。两项偏好保存在浏览器本地，默认通知开、提示音关。
+- 通知是客户端行为：应用运行期间才会触发，不提供邮件 / IM / Web Push 等外部推送，也不会提醒置顶以外的会话。
+
+## 快速开始
+
+```sh
+dsh plugin --profile web add dsh-workspace-status
+```
+
+重启 Harness（或刷新 Web 界面）。工作区行会出现状态标记；置顶任意会话即可看到上方的置顶区域与铃铛/喇叭开关。
+
+## 要求
+
+- DeepSeek Harness `>=0.2.1-rc.2 <0.3.0-0`，Web 或桌面版。
+- Node `>=22.18.0`（仅测试需要；无构建步骤）。
+- 不修改 Host 行为、不提供 Host 设置项、不向模型注册工具或提示词；置顶状态使用 Harness 原生工作区置顶集合，通知偏好与折叠状态保存在浏览器本地。
+
+## 验证
+
+1. 在某工作区运行会话并收起分组：工作区行尾出现蓝色圆环。
+2. 在另一个工作区触发审批：即使展开，该行也显示琥珀点。
+3. 让会话跑完但不打开：出现绿点，约一小时后消失。
+4. 置顶任意会话：列表上方立即出现 Pinned 区，按工作区分组，行尾有置顶图标。
+5. 再置顶另一个工作区的会话：出现第二个分组标题。
+6. 点击行尾置顶图标取消置顶：该行立即从 Pinned 区消失并回到原工作区分组。
+7. 重启 Harness：同样的置顶会话仍在，图标也仍显示。
+8. 点击置顶区标题栏的铃铛：首次会申请通知权限并显示测试提醒；再次点击关闭。
+9. 让置顶会话结束或开始等待：置顶区出现应用内提醒；窗口在后台时还会收到系统通知。
+
+## 相关链接
+
+- 英文说明（完整细节）：[README.md](./README.md)
+- npm：<https://www.npmjs.com/package/dsh-workspace-status>
+- 更新记录：[CHANGELOG.md](./CHANGELOG.md)
+
+<sub>同系列插件：[情绪板](https://github.com/Stijnus/dsh-moodboard) · [输入补全](https://github.com/Stijnus/dsh-composer-predictions) · [移动到工作区](https://github.com/Stijnus/dsh-move-to-workspace) · [工作区状态](https://github.com/Stijnus/dsh-workspace-status) · [提示词改写](https://github.com/Stijnus/dsh-prompt-optimizer)</sub>
+
+<sub>⭐ 如果它帮你省了一步，点个 star 能让更多 DSH 用户发现它。</sub>