dsh-retrace 0.4.148 → 0.4.150

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +13 -13
  2. package/README.zh.md +16 -9
  3. package/bin/retrace.mjs +0 -0
  4. package/lib/adapter/dsh-writer.js +2 -2
  5. package/lib/adapter/dsh.js +8 -508
  6. package/lib/archaeology-cli.js +3 -3
  7. package/lib/boot-pin.js +1 -1
  8. package/lib/client-i18n.js +22 -13
  9. package/lib/client.bundle.js +3 -3
  10. package/lib/client.js +136 -205
  11. package/lib/close-guard-client.js +2 -2
  12. package/lib/dynamic-client.js +3 -3
  13. package/lib/dynamic-host.js +8 -257
  14. package/lib/host-core.js +2 -193
  15. package/lib/http.js +3 -132
  16. package/lib/index.js +347 -862
  17. package/lib/marker-carrier.js +4 -4
  18. package/lib/platform/session-paths.js +11 -43
  19. package/lib/prewrite-guard.js +0 -28
  20. package/lib/span-semantics.js +1 -1
  21. package/lib/versioning.js +34 -2
  22. package/package.json +5 -7
  23. package/lib/adapter/compaction-backend.js +0 -92
  24. package/lib/adapter/register-compaction-backend.js +0 -93
  25. package/lib/auto-fold-scheduler.js +0 -519
  26. package/lib/badge.js +0 -65
  27. package/lib/cache-metrics.js +0 -358
  28. package/lib/context-level.js +0 -139
  29. package/lib/core-contract.js +0 -77
  30. package/lib/fold-auto.js +0 -621
  31. package/lib/fold-boundary.js +0 -1051
  32. package/lib/fold-core-text.js +0 -52
  33. package/lib/fold-core.js +0 -191
  34. package/lib/fold-summary.js +0 -168
  35. package/lib/hw3-fallback.js +0 -262
  36. package/lib/identity/code-assign.js +0 -228
  37. package/lib/identity/dedupe.js +0 -168
  38. package/lib/identity/shortcode.js +0 -782
  39. package/lib/identity/sidebar-badge.js +0 -270
  40. package/lib/identity-check-cli.js +0 -379
  41. package/lib/ledger-guard.js +0 -491
  42. package/lib/token-estimate.js +0 -91
package/README.md CHANGED
@@ -35,7 +35,7 @@ it cannot dirty the log, and new markers create **no token-meter pairing debt**
35
35
 
36
36
  > Versions: [VERSIONS.md](./VERSIONS.md)
37
37
 
38
- > **0.4.148 is the current release** — install/pin `0.4.148` (the **GitHub Release is out; the npm package is still pending** — the latest npm version is `0.4.139`; see [VERSIONS.md](./VERSIONS.md)). The `dsh-retrace@0.4.148` examples below apply to this release.
38
+ > **0.4.150 is the current release** — install/pin `0.4.150` (the **GitHub Release is out; the npm package is still pending** — the latest npm version is `0.4.139`; see [VERSIONS.md](./VERSIONS.md)). The `dsh-retrace@0.4.150` examples below apply to this release.
39
39
 
40
40
  ## ⚡ One-minute install
41
41
 
@@ -93,7 +93,7 @@ Full steps in [📦 Installation](#-installation).
93
93
  | ↩️ | **Rollback** | **three-way choice: context-only / artifacts-only / both**, with a dry-run preview. Rollback is **always available**; when an entry has no file preimage only context rollback is selectable (the other two are disabled with a reason). A **confirm dialog** lists the round, messages removed, file actions and a risk note (export first). Preview refuses while the agent is running; preview/rollback failures are shown instead of failing silently; a rollback is itself a new checkpoint (`restore`) |
94
94
  | ⤓ | **Export as…** | **read-only** zip of exactly that entry (`manifest.json` + the captured file preimages + the original text); it **never rolls anything back**. Uses the host preimage store when available, otherwise a manifest-only archive with a visible note |
95
95
  | 🎛 | **Three fixed actions per row** | **Jump to conversation / Rollback / Export as…**, always in that order; an **older host** shows an explicit "upgrade and restart" notice instead of silently missing features |
96
- | 🧬 | **Lineage identity** | every new session gets a stable lineage id automatically; the sidebar shows one badge per conversation (no duplicates on refresh) |
96
+ | 🧬 | **External binding id (optional)** | a **read-only** per-session binding id for stable cross-view references; the plugin **does not generate identifiers, keeps no mapping table, and never renames or prefixes conversation titles** |
97
97
  | 🧭 | **Jump-to-conversation** | one click from a checkpoint to that point in the conversation (auto-loads history, anchor highlight); when the point is out of the auto-load budget the reason is reported instead of nothing happening |
98
98
  | 🧹 | **Bounded storage** | snapshots keep the most recent N checkpoints (default 50); throttled background sweep prunes truncated ones |
99
99
 
@@ -153,7 +153,7 @@ The same result with plain file edits and `pnpm` — exactly the steps
153
153
  ```json
154
154
  {
155
155
  "dependencies": {
156
- "dsh-retrace": "^0.4.148"
156
+ "dsh-retrace": "^0.4.150"
157
157
  },
158
158
  "dsh": {
159
159
  "profile": {
@@ -257,12 +257,12 @@ Before you exit or reload, know what is still running:
257
257
  > handler, or a pre-quit prompt hook). If the app cannot quit, turning off "Exit
258
258
  > confirmation (close guard)" recovers immediately (no restart).
259
259
 
260
- ### Session badge & display name
260
+ ### External binding id (optional)
261
261
 
262
- - The sidebar shows **one badge per conversation**; the conversation title keeps the plain name. The stable identifier is **derived deterministically from the session id** (no random suffix).
263
- - **There is no setting for this yet.** Two runtime switches exist:
264
- - `DSH_RETRACE_SHOW_CODES=0` — hide lineage codes (host-side, takes effect on restart);
265
- - Custom display names and a settings-page toggle are **planned** — see [docs/PLAN.md](./docs/PLAN.md) and [docs/ROADMAP.md](./docs/ROADMAP.md).
262
+ - The plugin **does not generate or assign conversation identifiers**, keeps **no mapping table**, and **never renames or prefixes conversation titles**.
263
+ - A **read-only** per-session binding id surface remains for integrations: host ops **`sessionBadge`** (one session) and **`badgeMap`** (all sessions). Reading it has no write path.
264
+ - How such an id is produced or mapped is **maintained by the integrator** — the plugin does not document or ship a generation algorithm, table, or format.
265
+ - Titles written by **earlier versions** that still carry a plugin prefix can be restored with the maintenance op **`restoreSessionTitles`** (rename only; conversation content is never touched).
266
266
 
267
267
  ## ⚙️ Settings → General
268
268
 
@@ -345,7 +345,7 @@ The host occasionally removes APIs this plugin relied on. These are **host-side
345
345
 
346
346
  - Boot loop / recovery screen after a host upgrade → switch to a clean session and restart DSH; the plugin falls back to degraded mode instead of blocking.
347
347
  - Version/checkpoint panels empty after an upgrade → run `dsh plugin --profile <p> add dsh-retrace` to refresh the bundle.
348
- - Title/rename behaves differently → automatic title bootstrap is guarded by the host; manual rename keeps working.
348
+ - Title/rename behaves differently → the plugin **does not touch conversation titles**; historical plugin prefixes can be cleaned with `restoreSessionTitles` (rename only).
349
349
  - Dependency floor: `dsh-log-contract >= 0.3.18`.
350
350
 
351
351
  Historical details and exact error strings live in [CHANGELOG.md](./CHANGELOG.md); compatibility matrix in [docs/COMPAT.md](./docs/COMPAT.md).
@@ -353,7 +353,7 @@ Historical details and exact error strings live in [CHANGELOG.md](./CHANGELOG.md
353
353
  ### Upgrading
354
354
 
355
355
  ```bash
356
- dsh plugin --profile desktop add dsh-retrace@0.4.148
356
+ dsh plugin --profile desktop add dsh-retrace@0.4.150
357
357
  # then restart DSH — plugins are not hot-reloaded
358
358
  ```
359
359
 
@@ -377,7 +377,7 @@ whole tree down, so recover first and diagnose second:
377
377
 
378
378
  ### Pinning
379
379
 
380
- Pin an exact plugin version (`dsh-retrace@0.4.148`) and let `dsh-log-contract` resolve to
380
+ Pin an exact plugin version (`dsh-retrace@0.4.150`) and let `dsh-log-contract` resolve to
381
381
  `>=0.3.18`. Do not rely on `^0.4` across a host upgrade: compatibility here is decided by
382
382
  the **host surface**, not by semver alone.
383
383
 
@@ -440,8 +440,8 @@ the **host surface**, not by semver alone.
440
440
  (`fix --neutralize` / `--clip-crossstep`) for sessions that would fail `/compact`.
441
441
  - Read-only host surfaces for integration: `retrace/versions` and `retrace/forkmap`
442
442
  projections, `GET /api/plugins/retrace/{versions,forkmap,lineage,event,surface,doctor,snapshot}`,
443
- `POST /api/plugins/retrace/{rollback/preview,rollback,git/init}`, plus the badge
444
- ops (`sessionBadge` / `setBadgeTitle` / `initBadgeTitles` / `badgeMap`) and the
443
+ `POST /api/plugins/retrace/{rollback/preview,rollback,git/init}`, plus the
444
+ **read-only** session binding id ops (`sessionBadge` / `badgeMap`) and the
445
445
  `retrace` CLI (see below).
446
446
 
447
447
  **What's next** — see [docs/PLAN.md](./docs/PLAN.md) (next steps) and
package/README.zh.md CHANGED
@@ -30,7 +30,7 @@
30
30
 
31
31
  > 版本索引:[VERSIONS.md](./VERSIONS.md)
32
32
 
33
- > **0.4.148 为当前版本**——安装/固定请用 `0.4.148`(**GitHub Release 已发,npm 待发**;npm 最新可安装版本仍为 `0.4.139`,见 [VERSIONS.md](./VERSIONS.md));下文的 `dsh-retrace@0.4.148` 示例适用于该版本。
33
+ > **0.4.150 为当前版本**——安装/固定请用 `0.4.150`(**GitHub Release 已发,npm 待发**;npm 最新可安装版本仍为 `0.4.139`,见 [VERSIONS.md](./VERSIONS.md));下文的 `dsh-retrace@0.4.150` 示例适用于该版本。
34
34
 
35
35
  ## ⚡ 一分钟安装
36
36
 
@@ -88,7 +88,7 @@ dsh plugin --profile desktop add dshmarket # 只需一次
88
88
  | ↩️ | **回档** | **三选一:仅对话 / 仅产物 / 两者**,先干跑预览。回档**始终可用**;该条没有文件前像时只能选「仅对话」(另两项置灰并给出原因)。**确认弹窗**列明轮次、移除消息数、文件动作与风险提示(建议先导出)。预览在会话运行中直接拒绝;预览/回档失败都会在界面上显示,不静默;回档本身是新读档点(`restore`) |
89
89
  | ⤓ | **导出另存为** | 把该条内容打成**只读** zip(`manifest.json` + 捕获的文件前像 + 原文),**只导出、不回档**。宿主提供前像存储时用真实前像,否则退化为仅 manifest 的归档并显式提示 |
90
90
  | 🎛 | **每行固定三个动作** | **回到会话 / 回档 / 导出另存为**,顺序固定;**旧宿主**会显式提示「请升级并重启」,而不是静默缺少功能 |
91
- | 🧬 | **谱系标识** | 新建会话自动分配稳定谱系标识;侧栏每个会话只显示一个标识(刷新不重复) |
91
+ | 🧬 | **外部绑定标识(可选)** | **只读**的每会话绑定标识,便于跨视图稳定引用;插件**不生成标识、不维护映射表、不重命名/不加标题前缀** |
92
92
  | 🧭 | **跳转对话** | 从读档点一键跳转到对应位置(自动翻页加载更早历史 + 锚点高亮);该点超出自动加载预算时,给出可诊断原因,而不是点了没反应 |
93
93
  | 🧹 | **存储有界** | 快照只保留最近 N 个读档点(默认 50);节流后台扫掠回收被截断的旧档 |
94
94
 
@@ -137,7 +137,7 @@ dsh plugin --profile <name> add dsh-retrace
137
137
  ```json
138
138
  {
139
139
  "dependencies": {
140
- "dsh-retrace": "^0.4.148"
140
+ "dsh-retrace": "^0.4.150"
141
141
  },
142
142
  "dsh": {
143
143
  "profile": {
@@ -230,6 +230,13 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
230
230
  > (`will-prevent-unload` 处理,或退出前的询问钩子)。**桌面端退不掉时**,把设置里的
231
231
  > 「退出确认(关闭守卫)」关掉即退回官方形态(**不用重启**)。
232
232
 
233
+ ## 🧬 外部绑定标识(可选)
234
+
235
+ - 插件**不生成、不分配会话标识**,**不维护映射表**,也**不重命名会话标题、不给标题加前缀**。
236
+ - 供集成使用的**只读**每会话绑定标识接口保留:宿主 op **`sessionBadge`**(单会话)与 **`badgeMap`**(全会话)。读取没有写入路径。
237
+ - 这类标识如何生成、如何映射,由**使用方自行维护**——插件不提供、也不文档化任何生成算法、表或格式。
238
+ - 历史版本写入过标题前缀的会话,可用维护 op **`restoreSessionTitles`** 恢复原标题(只重命名,不碰会话内容)。
239
+
233
240
  ## ⚙️ 设置 → 通用
234
241
 
235
242
  | 设置项 | 默认 | 说明 |
@@ -299,7 +306,7 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
299
306
 
300
307
  - 升级后开机循环/恢复界面 → 切到干净会话并重启 DSH(插件降级而非阻断)。
301
308
  - 版本/检查点面板为空 → `dsh plugin --profile <p> add dsh-retrace` 刷新 bundle。
302
- - 标题/重命名行为变化 → 自动标题路径由宿主守卫,手动重命名不受影响。
309
+ - 标题/重命名行为变化 → 插件**不改写会话标题**;历史版本留下的前缀可用 `restoreSessionTitles` 恢复原标题(只重命名、不碰会话内容)。
303
310
  - 依赖下限:`dsh-log-contract >= 0.3.18`。
304
311
 
305
312
  历史细节与原始报错见 [CHANGELOG.md](./CHANGELOG.md);兼容矩阵见 [docs/COMPAT.md](./docs/COMPAT.md)。
@@ -307,7 +314,7 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
307
314
  ### 升级
308
315
 
309
316
  ```bash
310
- dsh plugin --profile desktop add dsh-retrace@0.4.148
317
+ dsh plugin --profile desktop add dsh-retrace@0.4.150
311
318
  # 然后重启 DSH —— 插件不会热重载
312
319
  ```
313
320
 
@@ -326,7 +333,7 @@ dsh plugin --profile desktop add dsh-retrace@0.4.148
326
333
 
327
334
  ### 版本固定建议
328
335
 
329
- 请固定到确切版本(`dsh-retrace@0.4.148`),并让 `dsh-log-contract` 解析到 `>=0.3.18`。
336
+ 请固定到确切版本(`dsh-retrace@0.4.150`),并让 `dsh-log-contract` 解析到 `>=0.3.18`。
330
337
  **不要在跨宿主升级时依赖 `^0.4` 这种范围**:这里的兼容性由**宿主的面**决定,光看 semver 不够。
331
338
 
332
339
  ---
@@ -361,8 +368,8 @@ dsh plugin --profile desktop add dsh-retrace@0.4.148
361
368
  - 配套 **`dsh-log-contract`**:30+ 条离线契约规则 + 原地修复(`fix --neutralize` / `--clip-crossstep`),能处理会让 /compact 永久失败的会话。
362
369
  - 供集成使用的只读宿主面:`retrace/versions`、`retrace/forkmap` 投影,
363
370
  `GET /api/plugins/retrace/{versions,forkmap,lineage,event,surface,doctor,snapshot}`,
364
- `POST /api/plugins/retrace/{rollback/preview,rollback,git/init}`,以及谱系标识操作
365
- (`sessionBadge` / `setBadgeTitle` / `initBadgeTitles` / `badgeMap`)与 `retrace` CLI(见文末)。
371
+ `POST /api/plugins/retrace/{rollback/preview,rollback,git/init}`,以及**只读**的
372
+ 会话绑定标识接口(`sessionBadge` / `badgeMap`)与 `retrace` CLI(见文末)。
366
373
 
367
374
  **未来计划**——agent 业务层规划(运行时守护、中断治理、生态开放接口)**尚未发布**,此节是**计划**而非已上线能力。本 README 描述的是**开发线(main)**,可能领先于 npm 上最新发布版。
368
375
 
@@ -481,4 +488,4 @@ retrace lineage <session> # 会话 parent 链谱系
481
488
  | **失败边界** | 所有写入(撤回/编辑/恢复/回档)均在**目标文件之外先备份**、写后做帧级校验与折叠重放;失败即中止并保留原文件;不可判定时按"拒绝 + 可操作提示"处理,不静默降级 |
482
489
  | **可回退** | 每个操作都有可逆路径;本地管理脚本可一键回退到上一快照 |
483
490
 
484
- - 稳定标识由会话 id 确定性导出(无随机后缀);对同一会话重复读取得到同一个标识。
491
+ - 只读**会话绑定标识**:对同一会话重复读取得到同一个标识;如何映射/生成由消费方自行决定(不属公开契约),插件不重命名会话标题。
package/bin/retrace.mjs CHANGED
File without changes
@@ -214,7 +214,7 @@ export function createDshMarkerWriter({ validateMarker, log = () => {}, meter, d
214
214
  * @returns {Promise<object>} 第 2 段事件(调用方读 seq/surfaceOp)。
215
215
  */
216
216
  async writeMarker(session, span, meta) {
217
- // ── 自动折叠默认关闭(最底层闸,需显式开启)─────────────────────────
217
+ // ── 自动收起默认关闭(最底层闸,需显式开启)─────────────────────────
218
218
  // 判定收敛在 marker-carrier.isAutoFoldSource(op='fold' 且未声明用户发起);
219
219
  // AUTOFOLD_HARD_DISABLED=true ⇒ 拒写并返回显式错误码,零落盘(审计段/载体段
220
220
  // 都不写)。拒写留一行可核日志:走注入的宿主 logger(console.log 进不了宿主
@@ -363,7 +363,7 @@ export function createDshMarkerWriter({ validateMarker, log = () => {}, meter, d
363
363
  * 与 assertPairing)原样保留;本路径一条 claim 都不写 —— 回收副本不遮蔽任何
364
364
  * 节点,写 claim 会留下无人消费的孤儿审计行(真实会话里出现过的
365
365
  * 形态)。单段 append 无第 1 段 ⇒ 无"半对"可言;
366
- * ③ 自动折叠默认关闭的闸(AUTOFOLD_HARD_DISABLED + isAutoFoldSource)只判
366
+ * ③ 自动收起默认关闭的闸(AUTOFOLD_HARD_DISABLED + isAutoFoldSource)只判
367
367
  * `op === 'fold'`:本写入的 op 是回收,不落在该闸上;那道闸的代码一行不动;
368
368
  * ④ 写入前过注入的 `validateMarker`(prewrite-guard 完整契约校验,信封不带 seq
369
369
  * —— 与 unhide 取消标记同规),与 marker 写入共用同一条校验链;