dsh-plugin-desktop-notify 0.6.1 → 0.6.3

package/README.en.md

@@ -2,6 +2,14 @@
 
 Desktop notifications and an app-icon badge for DSH: a finished turn, a pending approval or question, and a failure, with click-through back to that session.
 
+[![npm](https://img.shields.io/npm/v/dsh-plugin-desktop-notify)](https://www.npmjs.com/package/dsh-plugin-desktop-notify)
+[![license](https://img.shields.io/npm/l/dsh-plugin-desktop-notify)](LICENSE)
+[![DeepSeek Harness plugin](https://img.shields.io/badge/DSH-plugin-4D6BFE)](https://github.com/chendaleiQ/dsh-plugin-desktop-notify)
+
+![The notification banner that appears when a turn finishes (real screen recording)](https://raw.githubusercontent.com/chendaleiQ/dsh-plugin-desktop-notify/main/assets/demo.gif)
+
+*(A real screen recording, cropped to the notification area.)*
+
 ## What it does
 
 - **Turn finished** — including while the window is backgrounded or another app is in front
@@ -36,6 +44,7 @@ Stored in localStorage under `dsh-plugin-desktop-notify.preferences`:
 | `notifyError` | `true` | Notify when a turn fails |
 | `notifyViewed` | `false` | Also notify for the session you are looking at |
 | `badge` | `true` | Show the badge |
+| `pinAttention` | `true` | pin what needs you to the top of its group (uses the app's own pin) |
 | `excludeSubagents` | `true` | Ignore subagent sessions |
 | `titleComplete` / `titlePending` / `titleError` | empty | Custom titles; empty keeps the built-in copy |
 | `maxBodyChars` | `140` | Body length limit |
@@ -64,6 +73,7 @@ jobs:
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `POST` | `/desktop-notify/request` | Post one notification: `{"title": "...", "body": "...", "sessionId": "optional"}` |
+| `GET` | `/desktop-notify/turn?sessionId=...` | the renderer asks how the last turn ended (callers do not need it) |
 | `GET` | `/desktop-notify/pending` | The renderer drains what is waiting (scripts do not call it) |
 
 The address is written to `~/.dsh/desktop-notify.endpoint`, so callers never guess
@@ -94,7 +104,12 @@ Notes:
 - The banner is posted by **DSH itself** (attributed to DeepSeek Harness), not by
   a script host
 - Clicking it raises the window; with `sessionId` it also switches to that session
-- The interface binds loopback only and needs no login; `enabled: false` switches
+- The endpoint URL carries a random token; post to the whole URL as printed, and
+  requests without it (or cross-site ones) are refused. The renderer's `/pending`
+  uses the Host's own login instead
+- Reopening or reloading the window restores the badge but does not re-post
+  banners for facts that were already there
+- The interface binds loopback only; `enabled: false` switches
   off the osascript fallback, not the interface
 
 ## Known limits

package/README.md

@@ -2,11 +2,21 @@
 
 给 DSH 加**桌面通知 + 应用图标小红点**：任务完成、等待你操作、任务失败时提醒你，点通知直接回到那个会话。
 
+[![npm](https://img.shields.io/npm/v/dsh-plugin-desktop-notify)](https://www.npmjs.com/package/dsh-plugin-desktop-notify)
+[![license](https://img.shields.io/npm/l/dsh-plugin-desktop-notify)](LICENSE)
+[![DeepSeek Harness plugin](https://img.shields.io/badge/DSH-plugin-4D6BFE)](https://github.com/chendaleiQ/dsh-plugin-desktop-notify)
+
+![任务跑完时右上角弹出的通知横幅（真实录屏）](https://raw.githubusercontent.com/chendaleiQ/dsh-plugin-desktop-notify/main/assets/demo.gif)
+
+*（真实录屏，只截取了通知区域）*
+
 ## 它做什么
 
 - **任务完成**——包括窗口切到后台、你在别的应用里的时候
 - **等待你操作**——工具审批、提问、执行计划确认
 - **任务失败**——这一轮出错时提示
+- **说清楚怎么结束的**——正常完成、被拦截、输出到上限、被中止，各自一句话，不把中断说成「已完成」
+- **需要你的排在前面**——运行中、待你审批/回答、出错、未读完成的会话自动置顶到所属分组第一条，处理完自动放开
 - **小红点**——应用图标上显示「需要你的会话数」，你看过之后才清零
 - **点击通知**——切到对应会话，而不是只把应用叫到前面
 
@@ -36,6 +46,7 @@ dsh-plugin-desktop-notify
 | `notifyViewed` | `false` | 正在看的会话也通知（默认跳过） |
 | `badge` | `true` | 显示小红点 |
 | `excludeSubagents` | `true` | 忽略子智能体会话 |
+| `pinAttention` | `true` | 把需要你处理的会话自动置顶到所属分组第一条（用 DSH 自带置顶，处理完自动取消） |
 | `titleComplete` / `titlePending` / `titleError` | 空 | 自定义标题，空 = 用内置文案 |
 | `maxBodyChars` | `140` | 正文长度上限 |
 
@@ -51,6 +62,7 @@ dsh-plugin-desktop-notify
 __DSH_DESKTOP_NOTIFY__.capabilities()   // 平台、通知权限、小红点、服务可达性
 __DSH_DESKTOP_NOTIFY__.state()          // 小红点、待处理会话、最近一次通知/点击
 __DSH_DESKTOP_NOTIFY__.report()         // 上面全部 + 窗口焦点，便于排查
+__DSH_DESKTOP_NOTIFY__.pinState()       // 插件置顶了哪些、你自己又置顶了哪些
 ```
 
 
@@ -62,6 +74,8 @@ __DSH_DESKTOP_NOTIFY__.report()         // 上面全部 + 窗口焦点，便于
 | --- | --- | --- |
 | `POST` | `/desktop-notify/request` | 发一条通知，body：`{"title": "...", "body": "...", "sessionId": "可选"}` |
 | `GET` | `/desktop-notify/pending` | 渲染层取走待显示的通知（脚本不用调） |
+| `GET` | `/desktop-notify/turn?sessionId=...` | 渲染层确认这一轮是怎么结束的（脚本不用调） |
+| `GET`/`POST` | `/desktop-notify/pins` | 渲染层读写「插件自己置顶了哪些会话」（脚本不用调） |
 
 地址写在 `~/.dsh/desktop-notify.endpoint`，所以调用方不用猜端口：
 
@@ -89,10 +103,18 @@ urllib.request.urlopen(request, timeout=3).read()
 
 - 通知由 **DSH 自己弹出**（归属 DeepSeek Harness），不是 Script Editor
 - 点通知会把窗口叫到前面；带 `sessionId` 时会切到那个会话
-- 接口只监听回环地址，不需要登录；`enabled: false` 只关 osascript 兜底，不影响接口
+- 接口只监听回环地址；地址里带一个随机 token，**照抄文件里的整条 URL** 就行。
+  没有 token 的请求、以及其它网页发起的跨站请求都会被拒绝
+- 渲染层那条 `/pending` 走的是 DSH 自己的登录态，不需要 token
+- 窗口刷新或重开**不会**补发历史未读的横幅，但小红点还在；`enabled: false` 只关 osascript 兜底，不影响接口
 
 ## 已知限制
 
+- 重启或刷新窗口时，已经存在的「未读 / 待审批」只恢复小红点，不再补弹横幅
+- 自动置顶用的是 DSH 自己的置顶，所以会话行上会出现置顶标记，右键里也有「取消置顶」。
+  插件只取消**自己**置顶的会话，你手动置顶的一律不动；想一次清干净可在控制台跑
+  `__DSH_DESKTOP_NOTIFY__.clearPins()`
+
 - **Windows**：点通知会切到对应会话，但窗口不一定到前台——`AppUserModelID` 和主进程 focus 通道属于桌面端，渲染层插件做不到
 - **通知归属**：系统通知中心里显示为 DeepSeek Harness（用的是渲染层原生通知）
 - **宿主半边**（`index.js`，osascript 兜底）默认关闭；只有渲染层拿不到 `Notification` 时才需要打开

package/cordis.patch.yml

@@ -29,6 +29,7 @@
         titleApproval: 'DSH 需要你确认'
         notifyOnTurnEndKinds:
           - completed
+          - aborted
           - error
           - blocked
           - max-tokens

package/index.js

@@ -15,6 +15,8 @@
  */
 
 import { execFile, spawn } from "node:child_process"
+import { randomBytes } from "node:crypto"
+import { readFileSync } from "node:fs"
 import { appendFile, mkdir, rm, writeFile } from "node:fs/promises"
 import { homedir } from "node:os"
 import { basename, dirname, join } from "node:path"
@@ -36,7 +38,7 @@ const DEFAULTS = {
   soundFile: "/System/Library/Sounds/Glass.aiff",
   titleTurnEnd: "DSH 任务完成",
   titleApproval: "DSH 需要你确认",
-  notifyOnTurnEndKinds: ["completed", "error", "blocked", "max-tokens"],
+  notifyOnTurnEndKinds: ["completed", "aborted", "error", "blocked", "max-tokens"],
   maxBodyChars: 140,
   logPath: "~/.dsh/desktop-notify.log",
   maxTrackedSessions: 64,
@@ -46,6 +48,8 @@ const DEFAULTS = {
   api: true,
   /** Where the endpoint URL is written for those tools. */
   endpointPath: "~/.dsh/desktop-notify.endpoint",
+  /** Where the sessions this plugin pinned are remembered across window lives. */
+  pinsPath: "~/.dsh/desktop-notify-pins.json",
   /** Longest accepted request body. */
   apiBodyLimit: 8192,
   /** How many unread requests the interface keeps. */
@@ -60,9 +64,11 @@ const TURN_END_BODIES = {
   "max-tokens": () => "输出达到上限，本轮结束",
 }
 
-/** The URL path tools post to, and the path the renderer drains. */
+/** The URL path tools post to, and the paths the renderer drains and asks. */
 const API_REQUEST_PATH = "/desktop-notify/request"
 const API_PENDING_PATH = "/desktop-notify/pending"
+const API_TURN_PATH = "/desktop-notify/turn"
+const API_PINS_PATH = "/desktop-notify/pins"
 
 /** Read one JSON request body, bounded by `limit` bytes. */
 function readBody(request, limit) {
@@ -96,8 +102,6 @@ function answer(response, status, payload) {
     "content-type": "application/json; charset=utf-8",
     "content-length": Buffer.byteLength(body),
     "cache-control": "no-store",
-    "access-control-allow-origin": "*",
-    "access-control-allow-headers": "content-type",
   })
   response.end(body)
 }
@@ -106,118 +110,240 @@ function answer(response, status, payload) {
  * Mount the local notification interface other tools (a watch script, a
  * browser agent, a cron job) post to.
  *
- * The interface is two loopback HTTP routes on the Host's own web server: POST
- * a request, and the renderer drains the queue over the app protocol. The
- * renderer shows the banner, so it is attributed to DeepSeek Harness rather
- * than to a script host. Nothing here needs authentication: the server binds
- * loopback, and the endpoint URL is written to a file the caller can read.
+ * Three routes on the Host's own web server: POST a request, the renderer
+ * drains the queue over the app protocol, and the renderer asks how the turn
+ * that just ended actually ended so it can word the banner. `ctx.inject` waits
+ * for the `webServer` service instead of reading it once: the server finishes
+ * binding after this plugin applies, and a single `ctx.get` loses that race
+ * almost every launch.
+ *
+ * Requests are fenced: the external route demands the token the endpoint file
+ * carries (loopback plus token, no login), while the renderer routes rely on
+ * the Host's own `connection` admission, so a cross-site page cannot post
+ * banners or drain the queue.
  */
-function mountInterface(ctx, config) {
+function mountInterface(ctx, config, state) {
   if (!config.api) return
-  const server = (() => {
-    try {
-      return ctx.get?.("webServer")
-    } catch {
-      return undefined
+
+  const mount = (hostCtx) => {
+    const server = (() => {
+      try {
+        const injected = hostCtx.webServer
+        if (injected !== undefined) return injected
+      } catch {
+        /* a context without the service in `inject` throws on property access */
+      }
+      return hostCtx.get?.("webServer")
+    })()
+    if (server === undefined || typeof server.register !== "function") {
+      void noteToLog(config.logPath, "interface: the Host has no webServer service; the interface is unavailable")
+      return
     }
-  })()
-  if (server === undefined || typeof server.register !== "function") {
-    void noteToLog(config.logPath, "interface: the Host has no webServer service; the interface is unavailable")
-    return
-  }
 
-  const queue = []
-  const disposers = []
+    const token = randomBytes(16).toString("hex")
+    const queue = []
 
-  const post = async (request, response) => {
-    if (request.method === "OPTIONS") {
-      answer(response, 204, {})
-      return
+    const urlOf = (request) => {
+      try {
+        return new URL(String(request?.url ?? "/"), "http://127.0.0.1")
+      } catch {
+        return undefined
+      }
     }
-    if (request.method !== "POST") {
-      answer(response, 405, { ok: false, error: "use POST" })
-      return
+    const tokenOf = (request) => {
+      const fromQuery = urlOf(request)?.searchParams.get("token")
+      if (typeof fromQuery === "string" && fromQuery !== "") return fromQuery
+      const header = request?.headers?.["x-dsh-notify-token"]
+      return typeof header === "string" ? header : undefined
     }
-    let payload
-    try {
-      payload = await readBody(request, Math.max(1024, config.apiBodyLimit))
-    } catch (error) {
-      answer(response, 400, { ok: false, error: String(error?.message ?? error) })
-      return
+    const connectionOf = () => {
+      try {
+        return hostCtx.get?.("connection")
+      } catch {
+        return undefined
+      }
     }
-    const title = typeof payload?.title === "string" ? payload.title.trim() : ""
-    const body = typeof payload?.body === "string" ? payload.body.trim() : ""
-    if (title === "" && body === "") {
-      answer(response, 400, { ok: false, error: "title or body is required" })
-      return
+
+    /**
+     * Answer a caller that may not use this interface; false when it may.
+     * `external` routes demand the endpoint token; renderer routes accept the
+     * Host's own admission (its login cookie) or the token.
+     */
+    const rejected = (request, response, external) => {
+      if (tokenOf(request) === token) return false
+      if (external) {
+        answer(response, 401, { ok: false, error: "a token is required; post to the URL in ~/.dsh/desktop-notify.endpoint" })
+        return true
+      }
+      const connection = connectionOf()
+      let status
+      try {
+        status = typeof connection?.requestRejection === "function" ? connection.requestRejection(request) : undefined
+      } catch {
+        status = undefined
+      }
+      if (status === undefined) return false
+      answer(response, status, { ok: false, error: "unauthorized" })
+      return true
     }
-    queue.push({
-      at: new Date().toISOString(),
-      title: title === "" ? "DeepSeek Harness" : title,
-      body: body.slice(0, 400),
-      ...typeof payload?.sessionId === "string" && payload.sessionId !== "" ? { sessionId: payload.sessionId } : {},
-    })
-    while (queue.length > Math.max(1, config.apiQueueLimit)) queue.shift()
-    answer(response, 202, { ok: true, queued: queue.length })
-  }
 
-  const pending = (request, response) => {
-    if (request.method === "OPTIONS") {
-      answer(response, 204, {})
-      return
+    const post = async (request, response) => {
+      if (rejected(request, response, true)) return
+      if (request.method === "OPTIONS") {
+        answer(response, 204, {})
+        return
+      }
+      if (request.method !== "POST") {
+        answer(response, 405, { ok: false, error: "use POST" })
+        return
+      }
+      let payload
+      try {
+        payload = await readBody(request, Math.max(1024, config.apiBodyLimit))
+      } catch (error) {
+        answer(response, 400, { ok: false, error: String(error?.message ?? error) })
+        return
+      }
+      const title = typeof payload?.title === "string" ? payload.title.trim() : ""
+      const body = typeof payload?.body === "string" ? payload.body.trim() : ""
+      if (title === "" && body === "") {
+        answer(response, 400, { ok: false, error: "title or body is required" })
+        return
+      }
+      queue.push({
+        at: new Date().toISOString(),
+        title: title === "" ? "DeepSeek Harness" : title,
+        body: body.slice(0, 400),
+        ...typeof payload?.sessionId === "string" && payload.sessionId !== "" ? { sessionId: payload.sessionId } : {},
+      })
+      while (queue.length > Math.max(1, config.apiQueueLimit)) queue.shift()
+      answer(response, 202, { ok: true, queued: queue.length })
     }
-    if (request.method !== "GET") {
-      answer(response, 405, { ok: false, error: "use GET" })
-      return
+
+    const pending = (request, response) => {
+      if (rejected(request, response, false)) return
+      if (request.method !== "GET") {
+        answer(response, 405, { ok: false, error: "use GET" })
+        return
+      }
+      const items = queue.splice(0, queue.length)
+      answer(response, 200, items)
     }
-    const items = queue.splice(0, queue.length)
-    answer(response, 200, items)
-  }
 
-  try {
-    disposers.push(server.register({ kind: "exact", path: API_REQUEST_PATH, handler: (request, response) => {
-      void post(request, response).catch(() => answer(response, 500, { ok: false }))
-    } }))
-    disposers.push(server.register({ kind: "exact", path: API_PENDING_PATH, handler: (request, response) => {
-      try {
-        pending(request, response)
-      } catch {
-        answer(response, 500, [])
+    const turn = (request, response) => {
+      if (rejected(request, response, false)) return
+      if (request.method !== "GET") {
+        answer(response, 405, { ok: false, error: "use GET" })
+        return
       }
-    } }))
-  } catch (error) {
-    void noteToLog(config.logPath, `interface: cannot register routes: ${String(error)}`)
-    return
-  }
+      const sessionId = urlOf(request)?.searchParams.get("sessionId") ?? ""
+      const entry = state.lastTurnEnds.get(sessionId)
+      answer(response, 200, entry === undefined ? {} : { kind: entry.kind, at: entry.at })
+    }
 
-  // Hand the caller an address to post to; the port is whatever the Host took.
-  const endpointPath = expandHome(config.endpointPath)
-  const origin = (() => {
+    /**
+     * Remember which sessions this plugin pinned. The renderer's origin (and so
+     * its localStorage) changes with every launch, while the sidebar pins live
+     * on the Host; this file is what lets a restart release the pins it owns
+     * instead of mistaking them for the user's own.
+     */
+    const pins = (request, response) => {
+      if (rejected(request, response, false)) return
+      if (request.method === "GET") {
+        answer(response, 200, { ids: [...state.pinnedByPlugin] })
+        return
+      }
+      if (request.method !== "POST") {
+        answer(response, 405, { ok: false, error: "use GET or POST" })
+        return
+      }
+      void readBody(request, Math.max(1024, config.apiBodyLimit))
+        .then((payload) => {
+          const ids = Array.isArray(payload?.ids) ? payload.ids.filter((id) => typeof id === "string" && id !== "") : []
+          state.pinnedByPlugin = new Set(ids.slice(0, Math.max(1, config.maxTrackedSessions)))
+          const path = expandHome(config.pinsPath)
+          if (path !== "") {
+            void mkdir(dirname(path), { recursive: true })
+              .then(() => writeFile(path, `${JSON.stringify({ ids: [...state.pinnedByPlugin] })}\n`, "utf8"))
+              .catch(() => {})
+          }
+          answer(response, 200, { ok: true, tracked: state.pinnedByPlugin.size })
+        })
+        .catch((error) => answer(response, 400, { ok: false, error: String(error?.message ?? error) }))
+    }
+
+    let disposers
     try {
-      return typeof server.getOrigin === "function" ? server.getOrigin() : undefined
-    } catch {
-      return undefined
+      disposers = [
+        server.register({ kind: "exact", path: API_REQUEST_PATH, handler: (request, response) => {
+          void post(request, response).catch(() => answer(response, 500, { ok: false }))
+        } }),
+        server.register({ kind: "exact", path: API_PENDING_PATH, handler: (request, response) => {
+          try {
+            pending(request, response)
+          } catch {
+            answer(response, 500, [])
+          }
+        } }),
+        server.register({ kind: "exact", path: API_TURN_PATH, handler: (request, response) => {
+          try {
+            turn(request, response)
+          } catch {
+            answer(response, 500, {})
+          }
+        } }),
+        server.register({ kind: "exact", path: API_PINS_PATH, handler: (request, response) => {
+          try {
+            pins(request, response)
+          } catch {
+            answer(response, 500, { ok: false })
+          }
+        } }),
+      ]
+    } catch (error) {
+      void noteToLog(config.logPath, `interface: cannot register routes: ${String(error)}`)
+      return
     }
-  })() ?? (typeof server.port === "number" ? `http://127.0.0.1:${server.port}` : undefined)
-  if (endpointPath !== "" && origin !== undefined) {
-    void mkdir(dirname(endpointPath), { recursive: true })
-      .then(() => writeFile(endpointPath, `${origin}${API_REQUEST_PATH}\n`, "utf8"))
-      .then(() => noteToLog(config.logPath, `interface: ${origin}${API_REQUEST_PATH}`))
-      .catch((error) => noteToLog(config.logPath, `interface: cannot write the endpoint file: ${String(error)}`))
-  } else {
-    void noteToLog(config.logPath, `interface: routes registered but the address is unknown (origin=${String(origin)})`)
-  }
 
-  ctx.effect(() => () => {
-    for (const dispose of disposers) {
+    // Hand the caller an address to post to; the port is whatever the Host
+    // took, and the token keeps every other local page out.
+    const endpointPath = expandHome(config.endpointPath)
+    const origin = (() => {
       try {
-        dispose()
+        return typeof server.getOrigin === "function" ? server.getOrigin() : undefined
       } catch {
-        /* the route table is being torn down anyway */
+        return undefined
       }
+    })() ?? (typeof server.port === "number" ? `${typeof server.protocol === "string" ? server.protocol : "http:"}//127.0.0.1:${server.port}` : undefined)
+    if (endpointPath !== "" && origin !== undefined) {
+      void mkdir(dirname(endpointPath), { recursive: true })
+        .then(() => writeFile(endpointPath, `${origin}${API_REQUEST_PATH}?token=${token}\n`, "utf8"))
+        .then(() => noteToLog(config.logPath, `interface: ${origin}${API_REQUEST_PATH}`))
+        .catch((error) => noteToLog(config.logPath, `interface: cannot write the endpoint file: ${String(error)}`))
+    } else {
+      void noteToLog(config.logPath, "interface: routes registered but the address is unknown")
     }
-    if (endpointPath !== "") void rm(endpointPath, { force: true }).catch(() => {})
-  }, "desktop-notify: local interface")
+
+    hostCtx.effect(() => () => {
+      for (const dispose of disposers) {
+        try {
+          dispose()
+        } catch {
+          /* the route table is being torn down anyway */
+        }
+      }
+      if (endpointPath !== "") void rm(endpointPath, { force: true }).catch(() => {})
+    }, "desktop-notify: local interface")
+  }
+
+  // A Host without `inject` (older composition) still gets one best-effort try.
+  if (typeof ctx.inject !== "function") {
+    mount(ctx)
+    return
+  }
+  ctx.inject(["webServer"], (hostCtx) => {
+    mount(hostCtx)
+  })
 }
 
 /** Append one best-effort line to the log from outside the session machinery. */
@@ -322,8 +448,21 @@ function runDetached(command, args) {
  */
 export function apply(ctx, rawConfig) {
   const config = resolveConfig(rawConfig)
-  mountInterface(ctx, config)
-  if (!config.enabled) return
+  /** The newest turn-end kind per session, read by the renderer over the local interface. */
+  const state = { lastTurnEnds: new Map(), pinnedByPlugin: new Set() }
+  // Seeded synchronously: the renderer asks for it as soon as it applies.
+  try {
+    const pinsPath = expandHome(config.pinsPath)
+    if (pinsPath !== "") {
+      const remembered = JSON.parse(readFileSync(pinsPath, "utf8"))
+      if (Array.isArray(remembered?.ids)) {
+        for (const id of remembered.ids) if (typeof id === "string" && id !== "") state.pinnedByPlugin.add(id)
+      }
+    }
+  } catch {
+    /* no remembered pins yet */
+  }
+  mountInterface(ctx, config, state)
 
   const logPath = expandHome(config.logPath)
   const pendingText = new Map()
@@ -339,6 +478,27 @@ export function apply(ctx, rawConfig) {
     }
   }
 
+  /**
+   * Keep the real reason of the last turn. The renderer's session status only
+   * carries `running` / `completionUnread`, so without this every ending —
+   * blocked, max-tokens, aborted — would be announced as "completed".
+   */
+  function rememberTurnEnd(session, event) {
+    if (event?.type !== "turn/end") return
+    const sessionId = session?.id
+    if (typeof sessionId !== "string" || sessionId === "") return
+    state.lastTurnEnds.delete(sessionId)
+    state.lastTurnEnds.set(sessionId, {
+      kind: event?.data?.reason?.kind ?? "completed",
+      at: new Date().toISOString(),
+    })
+    while (state.lastTurnEnds.size > Math.max(1, config.maxTrackedSessions)) {
+      const oldest = state.lastTurnEnds.keys().next()
+      if (oldest.done === true) break
+      state.lastTurnEnds.delete(oldest.value)
+    }
+  }
+
   /** Remember the newest assistant text per session, trimmed to a small cache. */
   function remember(sessionId, text) {
     if (text === "") return
@@ -406,8 +566,18 @@ export function apply(ctx, rawConfig) {
     }
   }
 
-  /** One dispatch per committed event; work stays off the append path. */
+  /**
+   * One dispatch per committed event; work stays off the append path. The
+   * turn-end record is kept even with the osascript fallback switched off,
+   * because the renderer asks for it to word its own banner.
+   */
   ctx.on("session/event", (session, event) => {
+    try {
+      rememberTurnEnd(session, event)
+    } catch (error) {
+      void writeLog(`error session=${session?.id ?? "-"} ${String(error)}`)
+    }
+    if (!config.enabled) return
     try {
       handleEvent(session, event)
     } catch (error) {
@@ -415,11 +585,14 @@ export function apply(ctx, rawConfig) {
     }
   })
 
-  /** A disposed session must not keep its remembered text alive. */
+  /** A disposed session must not keep its remembered text or turn kind alive. */
   ctx.on("session/disposed", (session) => {
     const sessionId = session?.id
-    if (typeof sessionId === "string") pendingText.delete(sessionId)
+    if (typeof sessionId !== "string") return
+    pendingText.delete(sessionId)
+    state.lastTurnEnds.delete(sessionId)
   })
 
+  if (!config.enabled) return
   void writeLog(`plugin started pid=${process.pid} platform=${process.platform} onlyWhenUnfocused=${config.onlyWhenUnfocused}`)
 }

package/lib/client.js

@@ -30,8 +30,10 @@ window.__ModuleLoader__.load({
   factory: (require) => {
     const NS = "dsh-plugin-desktop-notify"
     /** Reported by capabilities(); keep in step with package.json (cross-machine support). */
-    const VERSION = "0.6.1"
+    const VERSION = "0.6.3"
     const PREFERENCES_KEY = `${NS}:preferences`
+    /** Sessions this plugin pinned itself; a reload reads it back so it never drops a user's own pin. */
+    const PINNED_KEY = `${NS}:pinned`
 
     /** Defaults; override per field with the localStorage JSON described in README. */
     const DEFAULTS = {
@@ -42,6 +44,8 @@ window.__ModuleLoader__.load({
       notifyViewed: false,
       badge: true,
       excludeSubagents: true,
+      // Keep the sessions that need you at the top of their sidebar group.
+      pinAttention: true,
       // Empty means "use the built-in copy for the active UI language".
       titleComplete: "",
       titlePending: "",
@@ -57,6 +61,12 @@ window.__ModuleLoader__.load({
       zh: {
         completeTitle: "任务已完成",
         complete: (name, duration) => withName(name, duration === "" ? "已完成" : `已完成，用时 ${duration}`),
+        blockedTitle: "任务被拦截",
+        blocked: (name) => withName(name, "本轮被拦截结束"),
+        maxTokensTitle: "输出达到上限",
+        maxTokens: (name) => withName(name, "本轮达到输出上限"),
+        abortedTitle: "任务已中止",
+        aborted: (name) => withName(name, "本轮已中止"),
         approvalTitle: "等待你的批准",
         approval: (name, tool) => withName(name, tool === "" ? "有一项操作等待你批准" : `请求使用 ${tool}，等待你的批准`),
         questionTitle: "等待你的回答",
@@ -72,6 +82,12 @@ window.__ModuleLoader__.load({
       en: {
         completeTitle: "Task completed",
         complete: (name, duration) => withName(name, duration === "" ? "Completed" : `Completed in ${duration}`),
+        blockedTitle: "Task blocked",
+        blocked: (name) => withName(name, "the turn ended blocked"),
+        maxTokensTitle: "Output limit reached",
+        maxTokens: (name) => withName(name, "the turn hit the output limit"),
+        abortedTitle: "Turn stopped",
+        aborted: (name) => withName(name, "the turn was stopped"),
         approvalTitle: "Approval needed",
         approval: (name, tool) => withName(name, tool === "" ? "A tool is waiting for your approval" : `${tool} is waiting for your approval`),
         questionTitle: "Your reply is needed",
@@ -122,6 +138,31 @@ window.__ModuleLoader__.load({
     /** Pending-interaction kinds the plugin reports. */
     const PENDING_KINDS = ["approval", "question", "plan-review"]
 
+    /**
+     * The local route that answers how a session's newest turn ended, and how
+     * long the banner waits for it. Session status only carries `running` and
+     * `completionUnread`, so without this ask every ending reads as "completed".
+     */
+    const TURN_KIND_PATH = "/desktop-notify/turn"
+    const TURN_LOOKUP_TIMEOUT_MS = 800
+    /** Where the Host remembers the sessions this plugin pinned. */
+    const PINS_PATH = "/desktop-notify/pins"
+
+    /** Ask the Host how one turn ended; undefined when it cannot answer in time. */
+    function lookupTurnKind(sessionId) {
+      const lookup = fetch(`${TURN_KIND_PATH}?sessionId=${encodeURIComponent(sessionId)}`, {
+        headers: { accept: "application/json" },
+        cache: "no-store",
+      })
+        .then((response) => (response.ok ? response.json() : undefined))
+        .then((payload) => (typeof payload?.kind === "string" ? payload.kind : undefined))
+        .catch(() => undefined)
+      const timeout = new Promise((resolve) => {
+        setTimeout(() => resolve(undefined), TURN_LOOKUP_TIMEOUT_MS)
+      })
+      return Promise.race([lookup, timeout])
+    }
+
     /** Read the browser storage when this renderer has one. */
     function storage() {
       try {
@@ -157,6 +198,18 @@ window.__ModuleLoader__.load({
       return preferences
     }
 
+    /** The session ids this plugin pinned in an earlier window life. */
+    function readPinnedIds() {
+      try {
+        const raw = storage()?.getItem(PINNED_KEY)
+        if (typeof raw !== "string" || raw === "") return []
+        const parsed = JSON.parse(raw)
+        return Array.isArray(parsed) ? parsed.filter((id) => typeof id === "string") : []
+      } catch {
+        return []
+      }
+    }
+
     /** Collapse whitespace and cut to the body budget. */
     function bodyText(text, maxChars) {
       const collapsed = String(text).replace(/\s+/gu, " ").trim()
@@ -275,6 +328,128 @@ window.__ModuleLoader__.load({
       /** sessionId -> ms timestamp when the current turn was first seen running. */
       const turnStartedAt = new Map()
       let lastBadge
+      /** Sessions this plugin pinned itself, so unpinning never touches the user's own pins. */
+      const selfPinned = new Set(readPinnedIds())
+      /** Whether the Host has answered with its remembered pins; nothing is pinned before that. */
+      let pinsReady = false
+      /** The most recent wanted set, so hydration can reconcile the moment it lands. */
+      let lastWanted = new Set()
+
+      /**
+       * Write the pinned-by-this-plugin set back. localStorage covers a reload of
+       * the same origin; the Host file covers a new launch, whose URL (and so
+       * this origin) has changed and taken localStorage with it.
+       */
+      function persistPins() {
+        try {
+          storage()?.setItem(PINNED_KEY, JSON.stringify([...selfPinned]))
+        } catch {
+          /* a storage-less renderer keeps the set for this life only */
+        }
+        if (typeof fetch !== "function") return
+        try {
+          void fetch(PINS_PATH, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ ids: [...selfPinned] }),
+          }).catch(() => {})
+        } catch {
+          /* the local interface may not be mounted */
+        }
+      }
+
+      /**
+       * Read back the pins an earlier launch left behind. Until this answers the
+       * plugin pins nothing: acting first would make its own pins look like the
+       * user's and leave them in the sidebar forever.
+       */
+      async function hydratePins() {
+        if (typeof fetch !== "function") {
+          pinsReady = true
+          return
+        }
+        try {
+          const response = await fetch(PINS_PATH, { headers: { accept: "application/json" }, cache: "no-store" })
+          if (response.ok) {
+            const payload = await response.json()
+            if (Array.isArray(payload?.ids)) {
+              for (const sessionId of payload.ids) if (typeof sessionId === "string" && sessionId !== "") selfPinned.add(sessionId)
+            }
+          }
+        } catch {
+          /* no Host half: this life reconciles from localStorage alone */
+        }
+        pinsReady = true
+        reconcilePins(lastWanted)
+      }
+
+      /** The sidebar's pinned snapshot, or undefined on a build without the workspace service. */
+      function pinnedSnapshot() {
+        try {
+          return ctx.uiWorkspace?.workspaces?.list?.getSnapshot?.()
+        } catch {
+          return undefined
+        }
+      }
+
+      /** Pin or unpin one session, best effort: a refused call must not disturb notifications. */
+      function callPin(sessionId, pin) {
+        const service = ctx.uiWorkspace
+        const method = pin ? "pinSession" : "unpinSession"
+        if (typeof service?.[method] !== "function") return
+        try {
+          const pending = service[method](sessionId)
+          if (pending !== null && typeof pending === "object" && typeof pending.catch === "function") pending.catch(() => {})
+        } catch {
+          /* the view keeps its order */
+        }
+      }
+
+      /**
+       * Keep what needs you at the top of its group. The sidebar's own pin seats
+       * a session ahead of the rest of the group, so this pins exactly the ones
+       * the plugin would notify about and unpins each once that reason is gone —
+       * never a session the user pinned by hand, and never one this plugin did
+       * not pin in the first place.
+       */
+      function reconcilePins(wanted) {
+        lastWanted = wanted
+        if (!pinsReady) return
+        let changed = false
+        if (!preferences.pinAttention) {
+          for (const sessionId of [...selfPinned]) {
+            selfPinned.delete(sessionId)
+            callPin(sessionId, false)
+            changed = true
+          }
+          if (changed) persistPins()
+          return
+        }
+        const snapshot = pinnedSnapshot()
+        if (snapshot === undefined) return
+        const pinned = new Set(Array.isArray(snapshot.pinnedSessionIds) ? snapshot.pinnedSessionIds : [])
+        // An archived session is out of the tree anyway, and pinning it is not
+        // this plugin's business.
+        const archived = new Set(Array.isArray(snapshot.archivedSessionIds) ? snapshot.archivedSessionIds : [])
+        for (const sessionId of wanted) {
+          if (archived.has(sessionId)) continue
+          if (selfPinned.has(sessionId) || pinned.has(sessionId)) continue
+          selfPinned.add(sessionId)
+          changed = true
+          callPin(sessionId, true)
+        }
+        for (const sessionId of [...selfPinned]) {
+          if (wanted.has(sessionId) && !archived.has(sessionId)) continue
+          selfPinned.delete(sessionId)
+          changed = true
+          callPin(sessionId, false)
+        }
+        if (changed) persistPins()
+      }
+
+      // Ask the Host which pins an earlier launch left; nothing is pinned until it answers.
+      void hydratePins()
+
       /** The last banner attempt and its outcome — Windows has several ways to swallow it. */
       let lastNotify
       /** The last banner click and what it managed to do — Windows/macOS differ here. */
@@ -412,6 +587,27 @@ window.__ModuleLoader__.load({
         void pollExternal()
       }
 
+      /**
+       * Post the completion banner, worded by the turn's real ending when the
+       * Host can still answer for it. A blocked, max-tokens or aborted turn is
+       * not "finished", and calling it that is what makes the banner wrong.
+       */
+      function deliverCompletion(sessionId, table, name, duration) {
+        const completed = () => {
+          notify("complete", sessionId, preferences.titleComplete || table.completeTitle, bodyText(table.complete(name, duration), preferences.maxBodyChars))
+        }
+        if (typeof fetch !== "function") {
+          completed()
+          return
+        }
+        void lookupTurnKind(sessionId).then((kind) => {
+          if (kind === "blocked") return notify("complete:blocked", sessionId, table.blockedTitle, bodyText(table.blocked(name), preferences.maxBodyChars))
+          if (kind === "max-tokens") return notify("complete:max-tokens", sessionId, table.maxTokensTitle, bodyText(table.maxTokens(name), preferences.maxBodyChars))
+          if (kind === "aborted") return notify("complete:aborted", sessionId, table.abortedTitle, bodyText(table.aborted(name), preferences.maxBodyChars))
+          return completed()
+        })
+      }
+
       /** Post one banner; clicking it opens the session and raises the window. */
       function notify(kind, sessionId, title, body) {
         if (!preferences.notifications) {
@@ -495,6 +691,8 @@ window.__ModuleLoader__.load({
         const statuses = ctx.uiSession.sessionStatus.getSnapshot()
         const summaries = ctx.sessions.list.getSnapshot().byId ?? {}
         const seen = new Set()
+        /** Sessions that should sit at the top of their group. */
+        const wanted = new Set()
 
         for (const [sessionId, status] of statuses) {
           const summary = summaries[sessionId]
@@ -504,6 +702,11 @@ window.__ModuleLoader__.load({
             continue
           }
           seen.add(sessionId)
+          // The first sighting of a session only records the baseline: every
+          // unread completion and every waiting approval that already existed
+          // when the window (re)loaded would otherwise fire as a fresh edge,
+          // one burst of banners per launch.
+          const observed = previous.has(sessionId)
           const before = previous.get(sessionId) ?? {}
           const entry = attention.get(sessionId) ?? {}
           // A failure already recorded for this turn owns the banner and the
@@ -515,9 +718,9 @@ window.__ModuleLoader__.load({
           const pendingKind = pendingKindOf(status)
           const running = status?.running === true
           const justFinished = before.running === true && running === false
-          const finishedNow = justFinished || (completed && before.completed !== true)
+          const finishedNow = justFinished || (observed && completed && before.completed !== true)
           const completionEdge = finishedNow && !failurePending
-          const pendingEdge = pendingKind !== undefined && pendingKind !== before.pendingKind
+          const pendingEdge = observed && pendingKind !== undefined && pendingKind !== before.pendingKind
 
           if (running) {
             if (!turnStartedAt.has(sessionId)) turnStartedAt.set(sessionId, Date.now())
@@ -530,14 +733,9 @@ window.__ModuleLoader__.load({
             const started = turnStartedAt.get(sessionId)
             turnStartedAt.delete(sessionId)
             const duration = started === undefined ? "" : durationText(Date.now() - started, languageOf())
-            const title = preferences.titleComplete || table.completeTitle
-            const body = bodyText(table.complete(name, duration), preferences.maxBodyChars)
-            if (looking) {
-              // Watching it finish is only worth a banner when the user opted in.
-              if (preferences.notifyViewed && preferences.notifyComplete) notify("complete", sessionId, title, body)
-            } else if (preferences.notifyComplete) {
-              notify("complete", sessionId, title, body)
-            }
+            // Watching it finish is only worth a banner when the user opted in.
+            const shouldNotify = preferences.notifyComplete && (looking ? preferences.notifyViewed : true)
+            if (shouldNotify) deliverCompletion(sessionId, table, name, duration)
           }
 
           if (looking) {
@@ -564,6 +762,13 @@ window.__ModuleLoader__.load({
             })
           }
 
+          // The pin follows the same facts the banner and badge use, plus a
+          // running turn: anything that would make you look belongs on top.
+          const current = attention.get(sessionId) ?? {}
+          if (!looking && (running || current.completed === true || current.pendingKind !== undefined || current.error !== undefined)) {
+            wanted.add(sessionId)
+          }
+
           previous.set(sessionId, { running, completed, pendingKind })
         }
 
@@ -572,6 +777,7 @@ window.__ModuleLoader__.load({
           previous.delete(sessionId)
           turnStartedAt.delete(sessionId)
         }
+        reconcilePins(wanted)
         applyBadge()
       }
 
@@ -706,10 +912,29 @@ window.__ModuleLoader__.load({
             badge: lastBadge ?? 0,
             attention: [...attention.entries()].map(([sessionId, entry]) => ({ sessionId, ...entry })),
             tracked: [...previous.keys()],
+            pins: [...selfPinned],
             lastNotify: lastNotify ?? null,
             lastClick: lastClick ?? null,
           }
         },
+        /** What this plugin pinned, next to what the sidebar currently shows. */
+        pinState() {
+          const snapshot = pinnedSnapshot()
+          return {
+            enabled: preferences.pinAttention,
+            pinnedByPlugin: [...selfPinned],
+            pinnedByUser: Array.isArray(snapshot?.pinnedSessionIds) ? snapshot.pinnedSessionIds.filter((id) => !selfPinned.has(id)) : null,
+          }
+        },
+        /** Release every pin this plugin owns — leaves manual pins alone. */
+        clearPins() {
+          for (const sessionId of [...selfPinned]) {
+            selfPinned.delete(sessionId)
+            callPin(sessionId, false)
+          }
+          persistPins()
+          return this.pinState()
+        },
         simulateComplete(sessionId = "desktop-notify-simulation") {
           const table = copy(languageOf())
           setAttention(sessionId, { completed: true })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-desktop-notify",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "type": "module",
   "description": "Desktop notifications and a Dock/taskbar badge for DeepSeek Harness: a finished turn, a pending approval or question, and a failure, with click-through back to the session",
   "license": "MIT",
@@ -58,5 +58,8 @@
   },
   "scripts": {
     "test": "node test/client.test.mjs && node test/host.test.mjs /tmp/dsh-notify-host-test.log"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }