v0.7.7 — the two README preview images now ship inside the package

Packaging only; no runtime change. lib/ is identical to 0.7.6.

package.json's files list did not include docs/, so the README's relative image paths (docs/ui-badge-and-banner.png, docs/badge-and-banner.png) had no file to resolve to on the npm page — the two screenshots shown there were broken links.

• files now lists those two images explicitly, so they are published with the package and the README renders them on npm.
• They are listed one by one rather than as docs/: docs/preview-1.png and docs/preview-2.png are byte-identical duplicates used by the marketplace listing, and shipping them would add ~400 KB to every install for nothing.
• The tarball grows from 192 KB to 568 KB (nearly 3×) and unpacks to 965 KB; 27 files instead of 25. That is the price of two 180–220 KB PNGs; a WebP pass or dropping one image would bring it back down if size ever matters.

Install: npm i @2jumpsina/dsh-context-guard@0.7.7 — or skip it if you are on 0.7.6 and do not care about the npm page.

Assets: 2jumpsina-dsh-context-guard-0.7.7.tgz is the exact tarball published to npm (sha512 verified against the registry dist.integrity), plus a .sha256 sidecar. SHA-256 895bcd95709d8e4fcacf28b39aabd0b6f9e8dc1405d26c14d69ffcb03f69b91e.

中文

只动打包清单，运行时零变化：lib/ 与 0.7.6 完全相同。

package.json 的 files 里没有 docs/，所以 README 的相对图片路径（docs/ui-badge-and-banner.png、docs/badge-and-banner.png）在 npm 页面上没有文件可解析——那里显示的两张截图是坏链。

• 现在 files 显式列出这两张图，随包发布，README 在 npm 上能正常渲染。
• 逐张列出而不是写 docs/：docs/preview-1.png 与 docs/preview-2.png 是和它们逐字节相同的副本，只服务于市场列表页；随包发出等于每次安装都多背约 400 KB。
• 包体从 192 KB 涨到 568 KB（接近 3 倍），解包 965 KB；文件数 25 → 27。这是随包带两张 180–220 KB PNG 的代价；真在意体积的话，转 WebP 或只留一张都能压回去。

安装：npm i @2jumpsina/dsh-context-guard@0.7.7；如果你在 0.7.6 且不在意 npm 页面那两张图，可以不升。

附件：2jumpsina-dsh-context-guard-0.7.7.tgz 就是发布到 npm 的那个 tarball（sha512 已对 registry 的 dist.integrity 核过），外加 .sha256 边车。SHA-256 895bcd95709d8e4fcacf28b39aabd0b6f9e8dc1405d26c14d69ffcb03f69b91e。

v0.7.6 — docs only: refreshed preview images + restored provenance (code identical to v0.7.5)

v0.7.6 changes no code. lib/ is byte-for-byte identical to v0.7.5 — git diff v0.7.5..v0.7.6 -- lib test scripts is empty, and the two published tarballs unpack to the same files (only package.json's version differs). If you are already on 0.7.5 there is nothing to upgrade for; install 0.7.6 only if you care about the images on the npm page.

What did change, all of it outside the running code:

• Preview images are now element-level crops of the real UI (docs/ui-badge-and-banner.png, docs/preview-1.png, docs/preview-2.png), and the handover-draft image is rendered by the plugin's own composeHandoverBlock() rather than redrawn by hand.
• README (en / zh) links updated to match.
• Publishing went back to npm Trusted Publishing (OIDC): the registry entry carries SLSA provenance attestations again, so the artifact traces back to this repository's workflow.

Assets: 2jumpsina-dsh-context-guard-0.7.6.tgz is the exact tarball published to npm (its sha512 was verified against the registry dist.integrity before upload), plus a .sha256 sidecar. SHA-256 b78d16b329591efcd12951e063664e110a6f329210adbbf674aac101d80dec98.

中文

0.7.6 没有改一行代码。lib/ 与 v0.7.5 逐字节相同——git diff v0.7.5..v0.7.6 -- lib test scripts 为空，两个已发布 tarball 解包后文件也完全一致（只有 package.json 的 version 不同）。已经在 0.7.5 的，不必为它升级；只有在乎 npm 页面上那几张图时才需要装 0.7.6。

变的东西全在运行代码之外：

• 预览图改成真实界面的元素级裁剪（docs/ui-badge-and-banner.png、docs/preview-1.png、docs/preview-2.png）；交接草稿那张改由插件自身的 composeHandoverBlock() 渲染，不再是手工重画。
• 中英 README 的图片链接随之更新。
• 发布通道回到 npm Trusted Publishing（OIDC）：registry 上的条目重新带上 SLSA provenance 证明，产物可溯源到本仓库的 workflow。

附件：2jumpsina-dsh-context-guard-0.7.6.tgz 就是发布到 npm 的那个 tarball 本身（上传前已用 registry 的 dist.integrity 核对 sha512），外加 .sha256 边车。SHA-256 b78d16b329591efcd12951e063664e110a6f329210adbbf674aac101d80dec98。

v0.7.5 — the reading from just before compaction, kept as one ledger row

A long session is not paid once: every turn re-reads the whole context, so the bill grows as it goes. The platform compacts on its own, without asking, and the reading from just before that moment is gone.

There are 77 entries in the market's "handoff" family: some write a summary with a model on a button press, some move the work into a new session, and compaction plugins rewrite what you send. This release takes none of those positions; it does four things:

• A ctx 63% badge in the session header; hover to see where it comes from: window, reserve, model, compaction point, source.
• From 45% it silently drafts HANDOVER.md; exactly one reminder at 60%.
• On compaction/end it saves the pre-compaction reading as a ledger row (idempotent by compactionId, capped).
• The compaction point is min(window×0.8, window − reserve − 64K); marked "estimated" when the platform config is unreadable.

Two principles. Cost: money goes into re-reading context, so warn early and act once; the plugin itself calls no model and injects no prompt. Fidelity: the draft holds machine facts only — session id, occupancy, spend, changed files with added/removed lines — verified at write time (exists / missing / unverifiable), so the next session can check it instead of trusting it.

It does not prevent compaction and cannot bring back what was dropped; if you override the threshold parameters, the point will be off.

中文

长会话不是一次付清：每轮重读全部上下文，越往后越贵。平台到点自己压缩，不问人，压缩前的读数随之消失。

市场里「交接」类有 77 条：有的点按钮让模型写摘要，有的换新会话，做压缩的直接改你发出去的内容。这一版只做四件事：

• 会话头挂 ctx 63%，悬停显示来历：窗口、预留、模型、压缩点、来源。
• 45% 起静默起草 HANDOVER.md，60% 才提醒一次。
• 压缩那刻（compaction/end）抢存一行读数进账，按 compactionId 幂等、有上限淘汰。
• 压缩点按 min(窗口×0.8, 窗口−预留−64K) 算，读不到配置就标「推算」。

两条原则：成本上，钱花在每轮重读上下文，所以提醒要早、动作只做一次；工具自己也不调模型、不注入 prompt。保真上，草稿只写机器事实——会话 id、占用、花费、改过文件的增删行，写盘时顺手核一遍文件在不在（存在/不存在/核不了），下一棒能自己核。

它不阻止压缩，也拿不回被压掉的内容；改过阈值参数时点数会偏。

v0.4.5 — seed existing sessions at startup so restored sessions warn without a new turn

v0.4.5 — a restored high session warns immediately, not after your next message

After upgrading to DSH 0.2.1-rc.2 the badge showed ctx 67% but the banner only appeared once the
user sent a message. At plugin start the session/created snapshot may not yet contain
contextPressure (restore is async), so the engine state stayed none; the browser's page-load
baseline reads that mirror, so the banner stayed hidden until a new event recomputed the state.

Fix: after registering the wire projection and subscribing to changes, the host now enumerates the
existing sessions once, snapshots contextPressure for each and folds it into the state —
silently (no log, no push), skipping any session without a known reading.

Tests: 82/82 unit (new: seed folds state without emitting a signal; an unknown reading is a no-op),
selftest 95 checks, bundle same-source check OK.

中文

v0.4.5 —— 恢复的高水位会话会立刻提示，而不是等你发下一条消息

升级到 DSH 0.2.1-rc.2 后真机复现：徽标 ctx 67%、banner 不弹，发一条消息后才弹。原因是插件刚启动时
session/created 的快照可能还没回放出 contextPressure（恢复异步），引擎状态停在 none，
而浏览器页面加载的基线读的就是这个状态。

修法：注册投影并订阅变更之后，启动时枚举一次现有会话，把已知读数折进状态（silent：不记日志、
不外推），拿不到读数的会话跳过。

测试：82/82 单测（新增 seed 的 silent 语义与未知读数 no-op）、自检 95 项、bundle 同源 OK。

v0.4.4 — host-owned guard state via a wire projection + resume seed fix

v0.4.4 — one judge instead of two

The host now registers its verdict as a contextGuard wire projection
(level / armed / turn / cooldown / ratio) and the browser half only renders it. The client's state machine,
its host-sync fetch and the settleTurn-on-button timer are gone; /state stays as a read-only debug mirror.

Two live bugs fixed:

• a restored session never warned: onResume returned a signal but wrote nothing into the state, so a
  67% session stayed none while the badge showed 67% (it reads contextPressure). It now folds the reading
  into the state first, then decides whether to emit the resume signal (>= hardRatio only).
• the mirror view never updated for restored sessions: it read the registry's folded state, which is only
  driven by new events. It now reads the live engine state, cached by its five fields so unchanged values keep
  the same reference.

Build fix: the Windows CRLF worktree made the generated bundle differ from the Linux one (63,403 vs 62,533
chars), so CI's clean-tree gate always failed. Sources are now read through a CRLF→LF normalizer and the
bundle is written as LF.

Tests: 80/80 (new test/resume.test.mjs pins the exact failure: a 67% resume must produce level: hard in
both engine state and mirror view; 48% seeds warn without a resume signal; unknown reading changes nothing).

中文

v0.4.4 —— 一个裁判，而不是两个

宿主把判定结果注册成 contextGuard wire 投影（level / armed / turn / cooldown / ratio），浏览器只负责显示。
客户端的整台状态机、宿主同步 fetch、挂在按钮上的 settleTurn 全部删除；/state 降级为只读调试镜像。

修了两个真机 bug：

• 恢复的会话从不提示：onResume 只返回信号、不写状态，于是 67% 的会话在投影里是 none
  （徽标仍显示 67%，因为它读的是官方 contextPressure）。现在先把读数折进状态，再决定是否发恢复信号。
• 镜像对恢复的会话永远不更新：它读的是注册表那份只在新事件里更新的折叠态。现在读引擎当前判定，
  按五字段缓存保证「值没变就返回同一引用」。

构建修复：Windows 检出是 CRLF、脚本写 LF ⇒ 生成物字符数不同，CI 的 clean-tree 永远红。现在读写都归一成 LF。

测试：80/80（新增 test/resume.test.mjs 把这次故障形状钉死）。

v0.4.1 — declare the DSH host requirement (engines.dsh)

v0.4.1 — the listing can now show what host this plugin needs

Marketplaces derive a plugin's host requirement from engines.dsh (or dsh.engines.dsh) and from
peerDependencies on @deepseek-ai/dsh-* packages. A peer on @deepseek-ai/schemastery is explicitly
ignored there — it says nothing about the DSH release line — so the listing read "host requirement not
declared".

package.json now declares engines.dsh: ">=0.1.6-alpha.2 <0.2.0" (developed on 0.1.6-alpha.2, verified on
0.1.7-rc.2). No runtime code changed.

中文

v0.4.1 —— 市场终于能显示这个插件需要什么宿主

插件市场从 engines.dsh（或 dsh.engines.dsh）和 @deepseek-ai/dsh-* 的 peerDependencies 推导宿主要求；
而 @deepseek-ai/schemastery 的 peer 被明确排除（它说不清 DSH 版本），所以列表一直显示「未声明宿主要求」。

现在 package.json 声明了 engines.dsh: ">=0.1.6-alpha.2 <0.2.0"（开发于 0.1.6-alpha.2、验证于 0.1.7-rc.2）。
运行时零改动。

提示：市场的版本号与宿主要求来自它的 npm 探测缓存（24h TTL / nightly），
发布后等下一次探测即可看到 v0.4.1 与「需要 DSH >=0.1.6-alpha.2 <0.2.0」。

v0.4.0 — two copy blocks, todoFilled, pre-compaction snapshot + review fixes

v0.4.0 — the handoff becomes an action

Two copy-ready texts. At a level crossing the banner now offers two blocks: one to paste back into the
old session ("write the conclusions into the to-fill-in area") — the agent that still has the context writes
them — and one for the new session (@HANDOVER.md ...). The draft route also returns todoFilled, so the UI
can show whether the to-fill-in area is still the empty template.

Pre-compaction snapshot. Compaction is a black box: DSH's own dsh-compaction-basic triggers at 80% of the
window, retains ~16%, and can force an idle-session compaction below the threshold. Once it runs, the numbers
from before compaction are gone. The plugin now writes a separate block (own marker, replaced per session) with
the peak reading before compaction — occupancy, ledger spend, changed files, time — zero LLM.

Review fixes (two P0, four P1): cooldown no longer swallows a hard escalation; levels are compared by rank and
never downgraded; respectCompaction is no longer a dead switch (one-shot pendingCompaction flag consumed by the
next observation); concurrent writes to the same HANDOVER.md no longer lose blocks (unique temp names + a
per-target-file serial queue); warnRatio <= hysteresisRatio can no longer arm the guard forever.

CI note: the engine test imported lib/index.js, which pulls in the host-provided @deepseek-ai/schemastery;
CI installs no dependencies, so the test failed to load. createGuardEngine now lives in lib/engine.mjs
(policy.mjs only) — the test passes with no node_modules.

Tests: 64/64 unit tests (engine + concurrency + hysteresis regressions), 86/86 selftest checks,
client bundle same-source check OK.

中文

v0.4.0 —— 交接从"提醒"变成"动作"

两段可复制文本：跨档时 ① 贴回旧会话（让还有上下文的 agent 写结论）、② 贴到新会话开场。
路由新增 todoFilled，界面能显示「待补」填没填。

压缩前快照：平台压缩是黑盒（dsh-compaction-basic：80% 阈值、保留 ~16%、空闲可低于阈值强制压缩）。
压缩后压缩前的读数就查不到了 —— 插件在压缩发生时把压缩前峰值（水位/花费/文件/时间）写进独立块，零 LLM。

审查修项（2 个 P0、4 个 P1）：冷却不再吞 hard 升级；档位按 rank 比较且绝不降级；respectCompaction 不再是死开关；
多会话并发写同一 HANDOVER.md 不再丢块（唯一临时名 + 按文件串行队列）；warnRatio <= hysteresisRatio 不再永久武装。

CI 说明：引擎测试曾 import lib/index.js，它依赖宿主提供的 @deepseek-ai/schemastery，而 CI 不装依赖 ⇒ 加载失败。
createGuardEngine 已抽到 lib/engine.mjs（只依赖 policy.mjs），无 node_modules 也能跑。

测试：单测 64/64、自检 86/86、bundle 同源检查 OK。

v0.3.6 — the "to fill in" area now survives refreshes

v0.3.6 — a fidelity fix, not a feature

The auto-draft block is replaced between its begin/end markers. So: an agent fills in the
"to fill in" slots → occupancy climbs 5 points → the refresh wipes what it wrote. A wrong
conclusion can be corrected; a vanished one is not even noticed.

Fixed: the to-fill-in area now sits between <!-- dsh-context-guard:todo:begin/end -->. On refresh the
plugin re-emits that region byte-for-byte into the new block, while the machine facts above it are
updated. Blocks written by ≤0.3.5 have no sub-markers and are rescued once via a - [ ] line anchor
(language-independent, so zh and en blocks both work).

Docs: both READMEs gain a "How faithful is the handoff?" table — machine facts are verifiable,
the turn summary is truncated (a clue, not evidence), and the to-fill-in slots are empty because
the plugin has no idea what you did. Two consequences are spelled out: an agent that only sees the
summary will infer (read its conclusions as a draft), and the old session's agent writes better
conclusions because it still has the context. The banner button's tooltip now says it writes machine
facts only.

Tests: +2 (manual notes survive a refresh; a legacy block is rescued via the - [ ] anchor), and
composeHandoverBlock now asserts the sub-markers and their order. 54/54 unit tests, selftest 81/81,
client bundle byte-identical (70,200 bytes).

中文

v0.3.6 —— 一次保真修复，不是新功能

自动草稿块是按 begin/end 标记整块替换的。于是：agent 填好「待补」→ 水位再涨 5 个点 → 刷新
→ 刚写的内容被冲掉。补错还能改，丢了你还不知道。

已修：待补区现在包在 <!-- dsh-context-guard:todo:begin/end --> 之间；刷新时插件把这一段
原样搬进新块，只更新上面的机器事实。≤0.3.5 写的旧块没有子标记，靠 - [ ] 行锚点兼容抢救一次。

文档：两版 README 都补了「保真的边界」表 —— 机器事实可核对、轮次摘要是截断的（线索而非证据）、
待补是空的（插件不知道你干了什么）。并写明两条推论：只看到摘要的 agent 会推断（当草稿读）；
旧会话的 agent 写结论更准（它还有上下文）。按钮 tooltip 也改成「只写机器事实」。

测试：新增 2 项（刷新后人工内容仍在；旧块靠 - [ ] 锚点抢救），compose 另加子标记与顺序断言。
单测 54/54、自检 81/81、bundle 逐字节同源（70,200 字节）。

v0.3.5 — write the handoff now, copy the opener

v0.3.5 — the banner now gives you two choices

At a level crossing the banner used to offer only "got it". Now:

• Write the handoff, I will copy it — the host writes one machine-facts handoff draft
  immediately (skipping the "only refresh after another step" gate) and surfaces a copy-ready opener.
• Got it — unchanged: close the banner, no side effect.

The opener (English UI):

@HANDOVER.md Continue from this handoff. Fill in the "to fill in" slots first, then carry on with the task.

Paste it as the first message of the new session. That is what makes the model finish the
conclusions — the plugin still registers no tool and injects no prompt, so context tax stays zero.

Under the hood: POST /api/context-guard/draft?sessionId=… forces one draft; it honours
handoverOnWarn and the pending lock, writes machine facts only, and returns a file name only
(never an absolute path — same rule as the state route).

Tests: the fake-host selftest now drives the real handler (405/400, no-reading, a real write at 10%
occupancy, and a check that no absolute path leaks). 73 → 81 checks; unit 51 pass / 1 skipped.

中文

v0.3.5 —— banner 现在给你两个选择

上下文跨档时，原来只能点「知道了」；现在：

• 写好交接，我复制 —— 宿主立刻写一次机器事实交接草稿（跳过"水位涨够才刷"的步进闸门），
  并把一段可复制的开场白摆出来。
• 知道了 —— 与旧版一致：关闭提示，无附带动作。

可复制的开场白（中文界面）：

@HANDOVER.md 接着这份交接继续。请先把「待补」补完再继续任务。

贴进新会话的第一条输入即可。让模型动手的那一下发生在你粘贴时 ——
插件仍然不注册工具、不注入 prompt，上下文税保持为 0。

实现：POST /api/context-guard/draft?sessionId=… 强制起草一次；尊重 handoverOnWarn 与 pending 锁，
只写机器事实，响应里只有文件名（绝不回绝对路径，与状态路由同一条规矩）。

测试：假宿主自检现在驱动真 handler（405/400、no-reading、10% 水位下真写文件、以及"响应不含绝对路径"）。
自检 73 → 81 项；单测 51 通过 / 1 跳过。

v0.3.4 — cross-platform path fix + CI and OIDC publishing

v0.3.4

Fix (affects Linux/macOS users): resolveHandoverPath() decided "is this an absolute path?"
with the platform-dependent path.isAbsolute(). On Linux, D:\other\H.md is not absolute, so it
was joined onto the session working directory and became D:\proj/D:\other\H.md — a path that
exists nowhere. The inverse was broken too (on Windows, /home/x/H.md). It now recognises three
root forms explicitly — the platform's own, a drive letter or UNC (C:\x, \\srv\share), and a
leading POSIX slash — with six regression assertions.

Engineering (transparent to users, but it makes the package more trustworthy): the repository
now runs GitHub Actions on every push (unit tests + byte-identical client-bundle check + a package
contents guard, on both Node 22.19 and 24), and publishing moved to npm Trusted Publishing
(OIDC) — no long-lived local token, and released artifacts carry a provenance attestation.

Feature-wise identical to v0.3.3: bilingual (zh/en) runtime copy, session-header badge, the
two-threshold reminder at 45% / 60%, the zero-LLM handoff draft from 45%, the host state route
GET /api/context-guard/state, the optional WeChat push (off by default), and the hardened
file-write path. Context tax is zero: no model-facing tool, no injected prompt section.

中文

v0.3.4

修复（Linux/macOS 用户会受影响）：resolveHandoverPath() 用平台相关的 path.isAbsolute()
判断「是不是绝对路径」。在 Linux 上 D:\other\H.md 不是绝对路径，于是被拼到会话工作目录后面，
变成 D:\proj/D:\other\H.md —— 一个在任何平台上都不存在的路径。反方向（Windows 上的
/home/x/H.md）同样是错的。现在显式认三种「自带根」形态：本平台绝对路径 / 盘符或 UNC
（C:\x、\\srv\share）/ POSIX 斜杠开头，并加了 6 条回归断言。

工程侧（对使用者透明，但让这个包更可信）：仓库接入 GitHub Actions，每次推送都跑
（单测 + client bundle 逐字节同源 + 包内容守卫，Node 22.19 与 24 两个版本）；发布改为
npm Trusted Publishing (OIDC) —— 不再依赖长期有效的本地 token，发布产物带 provenance 证明。

功能面与 v0.3.3 完全一致：双语（中/英）运行时文案、会话头徽标、45% / 60% 双档提醒、
45% 起零 LLM 自动起草交接、宿主状态路由 GET /api/context-guard/state、可选微信外推（默认关）、
加固过的写文件路径。上下文税为 0：不注册 model-facing 工具、不注入 prompt 段落。