dsh-autorestart 0.6.0 → 0.6.1

package/README.md

@@ -76,7 +76,7 @@ what it adds before you install it.
 
 ## Install
 
-Current version: **0.6.0**.
+Current version: **0.6.1**.
 
 From npm — the package is published under the name `dsh-autorestart`:
 
@@ -284,9 +284,25 @@ once, in the same composer dock, as a small card:
   already shown (`seenFeatureVersions` in the checkpoint file). A fresh installation never sees the
   card: the install question already explains the features, and answering it marks the announcement
   as seen.
-- **Once per version, for ever.** "Got it" records the version, the card disappears at once, and it
-  never comes back — not with the next restart of the host, and not with the next version of the
-  plugin (a *new* version of a feature is announced again, of course).
+- **"Seen" means "not older", not "equal".** The card counts as answered as soon as the recorded
+  version is **not older** than the current feature version — a record of `0.6.0` counts as seen
+  while the feature itself stands at `0.5.0`. Why not equality? Because the record does not say
+  *which* release the user answered on (until 0.6.0 the card carried the version of the package),
+  so an equality check would tell a user who already dismissed the card that they never saw it. A
+  record that is not a version at all counts as seen as well: a broken record must not make the
+  card come back for ever.
+- **Once per feature version, for ever.** "Got it" records the version, the card disappears at once,
+  and it never comes back — not with the next restart of the host, and not with the next release of
+  the plugin (a *newer version of the feature* is announced again, of course).
+- **The announcement follows the FEATURE, not the release.** The version it carries is a constant in
+  the source (`SLEEP_FEATURE_VERSION` in `index.js`), **not** the version of the package: a release
+  never brings the card back. Until 0.6.0 the card carried the package version, and every release
+  (0.5.0 → 0.6.0) brought "graceful shutdown" back to the users who had already answered it.
+- **How to announce it again on purpose.** Raise `SLEEP_FEATURE_VERSION` to a version **newer** than
+  the one that was recorded last: the card is then shown exactly once more. Do that **only** when
+  the feature itself changed so much that the user has to hear about it again (the shutdown became a
+  completely different thing, the button moved somewhere else, …). A release, a bug fix or a small
+  addition must **not** touch it — that is exactly the bug this constant exists to prevent.
 - **An unanswered card is not swallowed.** The card stays until it is answered, and it comes back with
   the next start of DSH.
 - **The countdown is read, not written.** The seconds in the card are the ones that are really in
@@ -294,7 +310,8 @@ once, in the same composer dock, as a small card:
   ("The button is currently switched off; you can turn it on in the settings").
 - **Where the state lives.** `<DSH_HOME>/storages/dsh-autorestart/state.json`, next to the checkpoint
   of the plugin. The host serves it on `GET /announcements` (`{ ok, pending: [{ feature, version }] }`)
-  and records it on `POST /announcements` (`{ feature }`).
+  and records it on `POST /announcements` (`{ feature }`). The `version` in that answer is the feature
+  version — the same number that `SLEEP_FEATURE_VERSION` holds.
 
 ## Graceful shutdown (收工关机)
 

package/docs/README.zh.md

@@ -98,10 +98,13 @@ session resume on boot, durable-goal re-arm, and an agent-callable idle-aware gr
 > **知道了**
 
 - **只有升级才会看到**：宿主把「这个功能的版本」和「已经展示过的版本」比一比（记在检查点文件的 `seenFeatureVersions` 里）。**新装**的用户不会看到这张卡 —— 安装提问已经把功能讲清楚了，答完就等于"已看过"。
-- **每个版本只弹一次**：点「知道了」→ 宿主记下版本 → 卡片立刻消失 → **以后再也不出现**（重启宿主不会，升级到下一个版本也不会 —— 除非那个新版本又改了同一个功能，那时才再公告一次）。
+- **「看过」= 记录版本不低于当前功能版本，不是「等于」**：记录的版本只要**不低于**当前的功能版本就算看过 —— 功能停在 `0.5.0` 时，记录是 `0.6.0` 也算看过。**为什么不按等值判**：记录里写的是「当时公告带的版本」，而 0.6.0 之前公告带的是**包版本**，所以按等值判就会告诉一个早就点过「知道了」的用户「你还没见过」；那条记录只说明他在哪个版本上点过，不说明他没看过这个功能。记录根本不是版本号（比如坏记录）时也算看过 —— 宁可少打扰，也不要因为一条坏记录天天弹卡片。
+- **每个功能版本只弹一次**：点「知道了」→ 宿主记下版本 → 卡片立刻消失 → **以后再也不出现**（重启宿主不会，升级发下一个版本也不会 —— 除非功能的版本比记录的更新，那时才再公告一次）。
+- **公告跟的是「功能」，不是「发版」**：公告带的版本号是源码里的常量 `SLEEP_FEATURE_VERSION`（`index.js`），**不是** `package.json` 里的包版本 —— 所以发版不会把老用户已经点过「知道了」的卡片再弹回来。（0.6.0 之前公告带的是包版本，于是 0.5.0 → 0.6.0 每发一次版，「收工关机」就重弹一次。）
+- **想主动再公告一次**：把 `SLEEP_FEATURE_VERSION` 调到**比最后记录的版本更新**的数即可 —— 卡片就再出现一次。但**只在功能本身变化大到必须再讲一遍时**才调（比如关机改成了完全不同的用法、按钮换了位置）；**发版、修 bug、加小功能都不要动它** —— 那正是这个常量要防的坑。
 - **没点不会静默吞掉**：卡片一直挂在那里等你回答；不回答，下次启动还会再出现一次。
 - **秒数是读出来的，不是写死的**：卡片里的秒数就是当前生效的 `sleepCountdownSeconds`；月亮按钮被关掉时，卡片还会补一句「按钮目前关闭，可在设置里打开。」
-- **状态存在哪**：`<DSH_HOME>/storages/dsh-autorestart/state.json`（和插件的检查点同一个文件）。宿主用 `GET /announcements` 报（`{ ok, pending: [{ feature, version }] }`），用 `POST /announcements`（body `{ feature }`）记。
+- **状态存在哪**：`<DSH_HOME>/storages/dsh-autorestart/state.json`（和插件的检查点同一个文件）。宿主用 `GET /announcements` 报（`{ ok, pending: [{ feature, version }] }`），用 `POST /announcements`（body `{ feature }`）记。里面的 `version` 就是功能版本，跟 `SLEEP_FEATURE_VERSION` 是同一个数。
 
 ## 工作方式
 
@@ -134,7 +137,7 @@ agent/status(running) ──► 写 checkpoint（<DSH_HOME>\storages\dsh-autores
 
 ## 安装
 
-当前版本：**0.6.0**。
+当前版本：**0.6.1**。
 
 ```powershell
 # 在 dsh 里（或对 Agent 说）：把工作区里的这个包安装为 profile bundle
@@ -515,6 +518,7 @@ lib/checkpoint.js    原子 JSON 检查点，容错读取，boot/restart/session
 lib/lifecycle.js     纯决策：bootPlan / restartDecision / selectGoalDisarms / continuationPrompt / describeState
 lib/restart.js       Windows 脱离重启（WMI 主、schtasks 兜底、dryRun、自定义命令）
 lib/sleep.js         收工关机：识别真宿主机（含 WSL）、关机命令、等待→倒数→关机的状态机
+lib/semver.js        版本号比较（公告去重用：只看"记录版本是否低于当前功能版本"）
 locale/{en,zh}.json  Plugin Manager 显示用标题/描述
 icon.svg             插件图标
 LICENSE              MIT 许可（发布到插件市场需要）

package/index.js

@@ -75,6 +75,7 @@ import {
   runCommandNow,
   scheduleDetachedRestart,
 } from './lib/restart.js'
+import { compareSemver } from './lib/semver.js'
 import {
   createSleepController,
   COUNTDOWN_CHOICES,
@@ -133,17 +134,36 @@ function snapGraceChoice(value) {
  * `pluginVersion()`), but a bundled installation may not ship that file — so
  * the constant below is the last resort. A test keeps the two in sync.
  */
-const PLUGIN_VERSION_FALLBACK = '0.6.0'
+const PLUGIN_VERSION_FALLBACK = '0.6.1'
+
+/**
+ * The version of the graceful-shutdown FEATURE, not the version of the package.
+ *
+ * The one-time announcement is bound to this constant. It used to follow the
+ * version in package.json, and that made every release resurrect the card the
+ * user had already answered (0.5.0 -> 0.6.1 brought "收工关机" back). A release
+ * is not news about the feature, so the two are decoupled.
+ *
+ * WHEN TO RAISE IT: only when the feature itself changed so much that the
+ * user has to hear about it again (the shutdown became a completely different
+ * thing, the button moved to another place, ...). Any new value works: the
+ * recorded version no longer matches, so the announcement is shown once more.
+ *
+ * WHEN NOT TO RAISE IT: a release, a bug fix, a small addition, a new option
+ * that the documentation explains. None of those deserve a card that
+ * interrupts the user a second time.
+ */
+const SLEEP_FEATURE_VERSION = '0.5.0'
 
 /** The cached version of this plugin (read once per process). */
 let pluginVersionCache = null
 
 /**
- * The version of this plugin.
+ * The version of this plugin (the PACKAGE version).
  *
- * It is the version of the package itself: the feature announcements are
- * bound to it, so a new version of the plugin can announce a new feature (and
- * the announcement of an old version never comes back).
+ * It says which release is installed - not what the user has been told about.
+ * The feature announcements are bound to `SLEEP_FEATURE_VERSION`, so a release
+ * never brings an answered announcement back.
  *
  * @returns {string}
  */
@@ -169,19 +189,51 @@ function pluginVersion() {
  *
  * The install prompt only ever reaches a fresh installation, so an
  * installation that already existed would never learn about a new feature.
- * Every entry of this list is therefore announced once per version: the
- * announcement is shown until the user presses "知道了", and the Host records
- * the version it has shown, so it never comes back.
+ * Every entry of this list is therefore announced once per FEATURE version:
+ * the announcement is shown until the user presses "知道了", and the Host
+ * records the feature version it has shown, so it never comes back.
+ *
+ * The version of an entry is the version of the FEATURE, never the version of
+ * the package - see `SLEEP_FEATURE_VERSION`.
  *
  * @returns {{ feature: string, version: string }[]}
  */
 function featureAnnouncements() {
   return [
     // The graceful shutdown ("收工关机") and its moon button.
-    { feature: 'sleep', version: pluginVersion() },
+    { feature: 'sleep', version: SLEEP_FEATURE_VERSION },
   ]
 }
 
+/**
+ * Whether the user has already seen the announcement of one feature.
+ *
+ * The record is the version that was announced when the user answered. It
+ * counts as seen as soon as it is NOT OLDER than the current feature version
+ * - not only when it is exactly that version:
+ *
+ *   - the announcement used to carry the version of the PACKAGE, so a user
+ *     who answered it on the release 0.6.1 recorded "0.6.1" while the feature
+ *     itself stands at "0.5.0". With an equality check that record would
+ *     look stale, and the very same card would be shown to a user who already
+ *     dismissed it;
+ *   - a record that is not a version at all counts as seen as well: a broken
+ *     record must not make the card come back for ever.
+ *
+ * A missing record counts as NOT seen: a missing record must never swallow an
+ * announcement.
+ *
+ * @param {unknown} recorded the version in the state file
+ * @param {string} current the current feature version
+ * @returns {boolean} true when the user has seen it
+ */
+function isFeatureSeen(recorded, current) {
+  if (typeof recorded !== 'string' || recorded.trim() === '') return false
+  const order = compareSemver(recorded, current)
+  if (order === null) return true
+  return order >= 0
+}
+
 /**
  * `@deepseek-ai/schemastery` resolves inside modules that live in the dsh installation,
  * but NOT from this bundle: a profile-installed bundle is a symlink into the user's
@@ -2132,11 +2184,16 @@ const titleOfSummary = (item) => {
   /**
    * The feature announcements the user has not seen yet.
    *
-   * A feature is pending when the recorded version is not the current one: a
-   * user who has seen the announcement of version 0.6.0 never sees it again,
-   * and a user who upgrades to a newer version sees the announcement of that
-   * version. A feature without a record is always pending — a missing record
-   * must never swallow an announcement.
+   * A feature is pending when the recorded version is OLDER than the current
+   * one: a user who has seen the announcement of the feature version 0.5.0
+   * never sees it again - not with the next release of the plugin, because
+   * the announcement follows the FEATURE and not the package. A user who
+   * answered the card on an intermediate release (the announcement used to
+   * carry the package version) has seen it as well: a record that is not
+   * older than the current version never brings the card back.
+   *
+   * A feature without a record is always pending - a missing record must
+   * never swallow an announcement.
    *
    * @returns {{ feature: string, version: string }[]}
    */
@@ -2144,7 +2201,7 @@ const titleOfSummary = (item) => {
     const seen = state.seenFeatureVersions && typeof state.seenFeatureVersions === 'object'
       ? state.seenFeatureVersions
       : {}
-    return featureAnnouncements().filter((entry) => seen[entry.feature] !== entry.version)
+    return featureAnnouncements().filter((entry) => !isFeatureSeen(seen[entry.feature], entry.version))
   }
 
   /**
@@ -3834,7 +3891,8 @@ function buildHandoffRoute(ctx, runtime, config) {
  *
  * The record lives in the checkpoint file, so an announcement that was shown
  * once never comes back — not with the next boot and not with the next
- * version of the plugin.
+ * release of the plugin. Only a new FEATURE version (see
+ * `SLEEP_FEATURE_VERSION`) brings it back, on purpose.
  */
 function buildAnnouncementsRoute(ctx, runtime, config) {
   const routePath = resolveAnnouncementsPath(config)
@@ -4967,4 +5025,6 @@ export {
   resolveAnnouncementsPath,
   featureAnnouncements,
   pluginVersion,
+  PLUGIN_VERSION_FALLBACK,
+  SLEEP_FEATURE_VERSION,
 }

package/lib/semver.js

@@ -0,0 +1,49 @@
+/**
+ * dsh-autorestart — the smallest semver comparison this plugin needs.
+ *
+ * The feature announcements are de-duplicated by VERSION, not by equality: a
+ * record counts as "seen" as soon as it is not older than the current feature
+ * version. That comparison has to be numeric — the string comparison of
+ * "0.10.0" and "0.9.0" says the opposite of the truth, because "10" sorts
+ * before "9".
+ *
+ * Only the plain `x.y.z` triple is understood. Anything else (a build
+ * metadata suffix, a pre-release tag, a broken record) has no order at all,
+ * and the caller decides what to do with that.
+ *
+ * @module lib/semver
+ */
+
+/** A version is three numbers and nothing else. */
+const VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/
+
+/**
+ * Split a version into its three numbers.
+ *
+ * @param {unknown} value
+ * @returns {[number, number, number]|null} null when it is not a version
+ */
+function parseVersion(value) {
+  if (typeof value !== 'string') return null
+  const match = VERSION_PATTERN.exec(value.trim())
+  if (!match) return null
+  return [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+/**
+ * Compare two versions numerically.
+ *
+ * @param {unknown} a the left version
+ * @param {unknown} b the right version
+ * @returns {-1|0|1|null} -1 when `a` is older, 1 when it is newer, 0 when they
+ *   are the same, and null when one of them is not a version at all
+ */
+export function compareSemver(a, b) {
+  const left = parseVersion(a)
+  const right = parseVersion(b)
+  if (left === null || right === null) return null
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1
+  }
+  return 0
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-autorestart",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "DeepSeek Harness plugin: restart without losing work. Waits until every conversation is idle, restarts the host, then automatically resumes the interrupted sessions. AI-generated, not human-reviewed: use with caution.",
   "license": "MIT",