dsh-rewind-plugin 0.15.0 → 0.15.1

package/docs/format.md

@@ -1,271 +0,0 @@
-# Durable format
-
-The on-disk format of the dsh-rewind checkpoint store, pinned as a spec. The
-implementation is `src/snapshot.ts`; this document is the reference for what
-readers may rely on and what a future incompatible change must do. If the code
-and this spec disagree, the code wins and this spec is a bug.
-
-## State root
-
-The store root defaults to `<dsh home>/rewind-snapshots/` — the dsh data
-directory (`~/.dsh/rewind-snapshots/` when `DSH_HOME` is unset) — overridable in
-order by the `snapshotDir` plugin config, then the `DSH_REWIND_SNAPSHOT_DIR`
-environment variable. It is a sibling of the workspace, never a subtree of it.
-Deleting the root only removes file backups; the store rebuilds from scratch.
-
-```
-<root>/
-└── <sessionId>/                        # safeSessionId(sessionId)
-    ├── store                           # store-format marker ("2")
-    ├── format                          # DSH session-format marker (session.header.version)
-    ├── <anchorSeq>/                    # decimal seq of the anchoring user/message
-    │   ├── <base>.json                 # one committed before-backup (metadata)
-    │   └── <base>.before               # its raw byte sidecar (the before content)
-    ├── .pending/                       # captures staged but not yet committed
-    │   └── <base>.before
-    ├── rescue/<opId>/<n>.before        # one pre-restore ("rescue") copy per op
-    └── journal-<opId>.json             # one restore-op journal
-```
-
-- `sessionId` is sanitized to `[a-zA-Z0-9._-]`; the bare values `.` and `..`
-  are replaced (`safeSessionId`) so a hostile id cannot traverse out of the
-  root.
-- `callId` is sanitized to `[a-zA-Z0-9._-]` (`safeFileId`) and extended with an
-  8-hex digest of the unsanitized id — `<base>` is
-  `<safeFileId(callId)>-<sha256(callId)[0..8]>`, so two call ids that sanitize
-  to the same name (e.g. `a:b` / `a_b`) cannot collide. Readers never infer a
-  name: every reference names its file, so pre-digest (released v1) names keep
-  resolving.
-- `<anchorSeq>` is a decimal integer; directories with non-integer names are
-  ignored by readers.
-- Checkpoint entries are read from those numeric directories only
-  (`<anchorSeq>/<base>.json`). Neither marker is `.json`, and a stray `.json` in
-  the session root is ignored.
-- Journal files are recognized by the `journal-` prefix (current format) or the
-  released `restore-journal-` prefix (read-only compatibility).
-- `store` is the session's store-format marker (a decimal version, written
-  atomically); a missing marker means the released v1 string format. `format` is
-  the DSH **session**-format marker the snapshots were anchored under (see
-  `SECURITY.md`) — the two are independent.
-
-## Checkpoint entry
-
-One JSON file per before-backup, named `<base>.json` next to its `<base>.before`
-sidecar:
-
-```ts
-interface CheckpointEntryJson {   // one `<base>.json`
-  store: 2              // on-disk store format (absent/1 = the released v1 string format)
-  callId: string        // the tool call that mutated the file
-  file: string          // resolved display path (absolute)
-  parent?: string       // realpath of the file's directory at commit time (the location pin)
-  blob: string | null   // sibling sidecar file name; null = the file was created
-  size: number          // byte length of the sidecar (0 when `blob` is null)
-  mode?: number         // permission bits, applied when content is restored
-  lossy?: true          // recorded from v1 content that had already lost bytes
-  time: number          // epoch ms, strictly increasing within a store instance
-}
-```
-
-A dedup link (see below) carries `callId`, `file`, `ref`, `time` and an
-optional `parent` instead of `blob` and `size`.
-
-Semantics:
-
-- **`blob` is the pre-edit state**: a string names the sidecar holding the exact
-  before bytes (copied raw, never through a JS string, so binary and non-UTF-8
-  files round-trip byte-exactly); `null` means the call created the file — valid
-  only with `size: 0` and never with `lossy`. The name is an invariant: it must
-  equal the entry's own file name minus `.json` plus `.before`.
-- **`anchorSeq` is the parent directory**, deliberately not a field of the
-  entry: rewinding to message N applies every entry anchored at or after N (the
-  boundary is inclusive).
-- **`parent` is the location pin**: the `realpath` of `dirname(file)` at commit
-  time. A restore refuses the path when its directory no longer resolves there.
-  Only the path's FINAL component is checked for links (`lstat().nlink > 1` or a
-  symlink; see `SECURITY.md`), so a repointed ancestor directory would otherwise
-  redirect the write — or the unlink of a recorded creation — outside the
-  recorded location. Absent means "no pin" and falls back to the final-component
-  check alone.
-- **`time` is the ordering key within an anchor group**: it is monotonic per
-  store instance (bumped past the previous commit), so same-millisecond
-  commits stay capture-ordered and a re-read always picks the same "earliest"
-  entry per path.
-- **`mode` never decides an action** (a mode-only difference is a no-op); it is
-  applied, best-effort, only when content is written back.
-- **`lossy` marks a record that had already lost bytes** (v1 content that was
-  decoded lossily, or a materialized link to one): it is comparable but never
-  written back, so a lossy record can never overwrite a live file.
-- Synthetic re-check entries (external edits/deletions seen at a user-message
-  boundary) use `callId = recheck-<anchorSeq>-<sha256(path) first 8 hex>`.
-
-### Dedup link entry
-
-A tracked file that records the same `before` content as its immediately-prior
-entry for that path is stored as a **link** instead of a second byte copy: the
-entry carries a `ref` (the `<anchorSeq>/<base>.json` of that prior entry) and
-omits `blob`/`size`, so identical content is never duplicated across entries. A
-reader resolves the `ref` back to the terminal real snapshot; `blob: null` (i.e.
-a recorded creation) still means "the file was created". A `ref` is validated as
-a single-level, `<digits>/<file>.json` relative reference (no traversal) so a
-corrupt or hostile ref cannot escape the store root when followed; because refs
-name the actual file, a link may point at a released-v1 entry. Because links
-reference prior entries, `prune` materializes a surviving link whose `ref` lands
-on a group it is about to drop before deleting that group, so no kept link is
-left dangling; the materialized entry keeps the bytes and the link's own
-location pin, but not the referent's `mode` (a link records no permissions of
-its own).
-
-## Restore journal
-
-One JSON file per restore operation, written **before any mutation** and
-updated as the pass applies:
-
-```ts
-type ByteRef = { blob: string } | { text: string }   // session-relative byte file, or inline text
-
-interface RestoreJournal {
-  version: 2
-  id: string                    // `op-<base36 ms>-<random>`; file name suffix
-  sessionId: string
-  targetSeq: number             // rewind target the restore belongs to
-  startedAt: number             // epoch ms
-  finishedAt?: number           // set on a terminal state
-  state: 'running' | 'rollback-running' | 'completed' | 'rolled-back' | 'recovery-required'
-  actions: RestoreJournalAction[]
-  rollbackError?: string        // set when a rollback pass failed partway
-}
-
-interface RestoreJournalAction {
-  path: string
-  action: 'restore' | 'delete'  // restore = write the content back; delete = unlink
-  before: ByteRef | null        // target content for restore; null for delete
-  rescue: ByteRef | null        // pre-restore disk state; null = file was absent
-  mode?: number                 // recorded target permissions
-  rescueMode?: number           // recorded pre-restore permissions
-  parent?: string               // checkpoint-time location pin (see the entry)
-  rescueError?: string          // set when the rescue capture failed (rollback skips it)
-  done: boolean                 // true once the action's fs op completed and was marked
-  failed?: string               // per-action failure message (the pass never aborts)
-}
-```
-
-A `{blob}` reference is safe and session-relative: `<anchorSeq>/<base>.before`
-(an entry sidecar) or `rescue/<opId>/<n>.before` (a rescue copy), validated on
-both write and read so a corrupt or hostile journal can never point a restore or
-a rollback outside the store. `{text}` refs carry content that has no sidecar:
-released-v1 entry content, or a legacy journal's inline strings.
-
-States: `running` and `rollback-running` are non-terminal; `completed` /
-`rolled-back` are terminal. Reconciliation *reports* a still non-terminal op as
-`interrupted` (or `recovery-required` when the journal is corrupt or a rollback
-could not complete), while the journal itself stays `running` /
-`rollback-running`. A journal read back from a legacy file (`restore-journal-`
-prefix, `version: 1`, inline strings) is rewritten IN PLACE as `version: 2` once
-a redo or rollback pass completes, so the same op never leaves two divergent
-versions on disk.
-
-## Write guarantees
-
-- **Atomicity**: every JSON write serializes to a sibling `<target>.tmp` and
-  renames over the target. A crash between the two steps leaves only the temp
-  file — never a readable half-written target — and readers ignore temp files
-  (they do not end in `.json`). The next write of the same target overwrites
-  a leftover temp.
-- **Bytes before metadata**: a checkpoint commit places the sidecar first
-  (a staged capture is `rename`d out of `.pending/`; other sources are written
-  temp-then-rename) and only then publishes the entry JSON, so a crash can
-  leave an unreferenced sidecar but never an entry whose bytes are missing.
-  A sidecar that is missing or shorter than `size` is a per-file failure, never
-  a silent "the file was created".
-- **Pinned location**: every record this build writes — entry, link and journal
-  action — carries where the tracked file's directory resolved at commit time
-  (the `parent` pin, best-effort), and a restore re-checks it before touching the
-  path — the initial pass, a post-restart `continueRestore` and a
-  `rollbackRestore` alike (the journal carries the pin). A directory that
-  resolves elsewhere is refused and reported, so a restore can never write or
-  unlink outside the recorded location; a record with no pin (released-v1 data,
-  or a commit whose parent could not be resolved) falls back to the
-  final-component link check alone. A parent chain that is GONE is still
-  recreated — the plugin restores files whose directory was deleted — but only
-  while its nearest surviving ancestor resolves inside the pin. A stable
-  symlinked ancestor is never refused: both sides of the comparison are
-  `realpath`s.
-- **Journal before mutation**: the rescue state of every planned path is
-  captured as a raw byte copy and the intent journal — references only —
-  persisted atomically BEFORE the first fs mutation; each action is marked
-  `done` as it is applied.
-- **Disk is truth**: after a restart, reconciliation compares the real disk
-  against each action's goal (the restore target for `running` journals, the
-  rescue state for `rollback-running` / `recovery-required` ones). A path
-  whose disk already matches is marked done without being touched.
-- **Bounded storage**: `prune` keeps the newest 100 anchor groups per session
-  (`MAX_ANCHOR_GROUPS`), materializing any surviving dedup link that references
-  a group being dropped before deleting whole anchor directories; it also
-  recycles terminal journals (`completed` / `rolled-back`) together with their
-  `rescue/<opId>/` bytes, and collects `.pending/` captures older than 24 h that
-  no commit consumed. A group a non-terminal journal still references is pinned
-  — evicting it would make "continue finishes the interrupted op" impossible —
-  so the effective window may exceed `keep` until that op is resolved.
-  Non-terminal and corrupt journals are always kept. Across sessions,
-  `pruneStale` removes whole long-inactive session directories whose newest
-  member stamp is older than a configurable idle cutoff (default off), so the
-  store root does not grow without bound either.
-
-## Validation and failure policy
-
-- **Entries**: a missing, malformed, or self-contradictory entry is read as
-  `undefined` (silently skipped) — losing one backup, never the recovery path.
-  Contradictions are never guessed at: a `blob: null` with `size !== 0` or with
-  `lossy`, a `blob` that is not this entry's sidecar name, and a non-string
-  `before` in a v1 record are all corruption, and guessing an entry's kind is
-  how a restore turns into a delete. An absent or malformed `parent` is not
-  corruption: it means "no pin", so the entry falls back to the released
-  final-component rule. Two cases are *not* silent skips: an entry
-  whose `store` is newer than this build fails the whole operation closed (see
-  Versioning), and a record whose sidecar is missing or too short is a per-file
-  failure that the restore reports — never a delete of the live file.
-- **Journals**: a corrupt or schema-invalid journal **fails loud** —
-  `reconcileRestores` reports it as `recovery-required` and never drops it,
-  because dropping it would silently erase the interrupted restore's recovery
-  record. A `ref` with a traversal, absolute, or unknown-root segment counts as
-  corrupt.
-- **Journal IO**: best-effort by design — if a journal cannot be written, the
-  restore proceeds with pre-journal semantics (crash safety degrades,
-  behavior does not).
-
-## Versioning policy
-
-The format is versioned twice: a session-level `store` marker (the value is the
-current `CURRENT_STORE_VERSION`, 2) and a self-describing field on every record
-(`store` on entries, `version` on journals). A missing `store` marker (or `1`)
-means the released v1 string format, which is still read but never migrated. A
-`store` **above** the current version fails the whole operation closed — no file
-restore and no new entry written into a store a newer build owns (an explicit
-clear or the age-based sweep is not version-gated) — while the conversation
-rewind itself keeps working (it does not depend on snapshots). A journal whose
-`version` is present but neither 1 nor 2 is corrupt and is reported
-`recovery-required` (see Validation).
-
-Because compatibility is not safe in both directions, the byte format reuses
-none of v1's path/state keys (`path`, `anchorSeq`, `before`) and does not carry
-`anchorSeq` (it equals the parent directory). A released v1 build therefore
-rejects each such entry instead of reading it as "the file was created", so a
-downgrade cannot delete workspace files; that field-name contract is pinned by
-`tests/downgrade-safety.test.ts`. Compatibility means reading old data, not
-repairing it: bytes the v1 build had already lost cannot be recovered.
-
-A future incompatible format should raise the marker/version (readers already
-fail closed above their own version) or move the state root and ship an explicit
-migration tool. Old-format data is never silently re-interpreted.
-
-## Cleanup policy persistence
-
-The snapshot auto-cleanup policy (the `autoCleanupEnabled` switch and the
-`autoCleanupMaxAgeDays` idle cutoff) is no longer a file: it is this plugin
-entry's own live configuration (both fields declared `.volatile()`, validated by
-the entry's schemastery `Config` schema, defaults on the schema). The policy was
-previously persisted in a legacy `<dsh home>/snapshot-cleanup.json` file; that
-file store and its one-time startup migration have been removed. The last-sweep
-clock stays in its own `<dsh home>/snapshot-cleanup-last-sweep.json` state file,
-which is unchanged.

package/docs/harness-reference.md

@@ -1,75 +0,0 @@
-# DeepSeek Harness interface reference
-
-> Maintainer doc: the harness subsystems this plugin depends on, and the key
-> source files behind each interface. Official repo:
-> [github.com/deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)
-
-## Subsystem docs (`docs/subsystems/`)
-
-- [session.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/session.md) — `Session` / `SessionStore` / event model (`Session.append`, `surfaceOp`, `sourceEventSeqs`)
-- [core.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/core.md) — `Agent` (`status`, `session`) and other core types
-- [commands.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/commands.md) — command registration (`ctx.commands.register`, `CommandInvocation`, `CommandResult`)
-- [tools.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/tools.md) — tool execution seam (`tools/pre-execute` / `tools/post-execute`, `ToolExecution`)
-- [session-query.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/session-query.md) — session query / `foldSurface` read-only interfaces
-- [token-meter.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/token-meter.md) — replay-aware token meter (`TokenMeter.measure`, surface pricing)
-- [compaction.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/compaction.md) — compaction seam / `compaction/*` events / `BasicCompactionEngine` (`summarize()` hook)
-- [session-projection.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/session-projection.md) — projection registry (`SessionProjectionRegistry.snapshot/checkpoint`)
-- [session-stats](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/session/session-stats) — whole-log stats projection (folds ALL events; rewind does not roll back counts)
-- [session-title.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/session-title.md) — durable title state (`foldSessionTitle`)
-- [goal.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/goal.md) — goal fold (`foldGoal`) and round admission
-
-Compatibility probes against these subsystems (test-driven investigation, the
-`compat-invariants` / `compat-interop` vitest suites + the `verify-host` real
-`/compact` chain): [compat/audit.md](compat/audit.md).
-
-Also in the harness repo's `docs/`: `persistence-catalog.md` (full
-`SessionEventMap`), `tool-catalog.md` (tool inventory), `config-catalog.md`
-(configuration inventory).
-
-## Key source (`packages/`)
-
-| Interface | File |
-|---|---|
-| `Session.append`, surface validation | [packages/core/session/src/index.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/core/session/src/index.ts) |
-| `foldSurface`, replacement rules | [packages/core/session/src/surface.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/core/session/src/surface.ts) |
-| `SessionEventMap`, `SurfaceOp` | [packages/core/session/src/types.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/core/session/src/types.ts) |
-| `createUserMessage`, `MessageSource` | [packages/llm/llm/src/message.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/llm/llm/src/message.ts) |
-| `CommandDefinition`, `CommandInvocation` | [packages/interaction/commands/src/index.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/interaction/commands/src/index.ts) |
-| `Agent` (`status` / `session`) | [packages/core/agent/src/runtime-types.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/core/agent/src/runtime-types.ts) |
-| `tools/pre-execute` / `execute` / `post-execute` | [packages/core/tools/src/index.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/core/tools/src/index.ts) |
-| Client DOM anchors (`data-chat-flow-kind` / `data-chat-anchor-key`) | [packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx) |
-| User bubble rendering | [packages/client/ui-chat/src/client/chat/MessageItem.tsx](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/ui-chat/src/client/chat/MessageItem.tsx) |
-| Client `SessionFace` (`command` / `cancel`) | [packages/api/session-controller/src/client/contract/session.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/api/session-controller/src/client/contract/session.ts) |
-| Client pending interaction (SessionPendingInteraction) | [packages/client/ui-session/src/client/index.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/ui-session/src/client/index.ts) |
-
-## Plugin source layout
-
-The module map below duplicates `AGENTS.md` (`Layout at a glance`), which is
-the canonical source; this block only adds the finer-grained client-side files
-and packaging entries.
-
-```
-src/client/index.ts     client plugin: /rewind command decoration + per-message ↶ button portals;
-                        re-exports the client contract (hiddenSeqsOf / targetSeqOfArgs / HiddenChat)
-src/client/popover.ts   mode-selection popover (both-mode impact confirm)
-src/client/hidden.ts    withdrawn-span computation (hiddenSeqsOf), pure
-src/client/candidates.ts  rewind candidate listing (rewindCandidatesOf), pure
-src/client/pending.ts   pending-steering bubble ↔ inbox next-step (user-sourced) matching, pure
-src/client/portals.tsx  per-user-message ↶ button portals (React bridge into the actions row)
-src/client/settings-card.tsx  snapshot-cleanup form on the bundle page (plugins.bundle.config)
-src/client/locales.ts   zh / en copy (LocaleNamespaceMap)
-src/client/styles.ts    injected styles (dsh design tokens)
-src/client/build-info.ts  client build identity (__DSH_REWIND_VERSION__ / __DSH_REWIND_BUILD__)
-src/client/log.ts       client logger (namespaced, dsh-rewind.debug-gated)
-scripts/build.mjs       esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
-scripts/check-dsh-version.mjs  DSH peer-tuple check (latest dist-tag vs peers)
-scripts/update-badge.mjs       regenerate the tests badge (CI only)
-scripts/verify-host.mjs end-to-end host verification (full check suite)
-scripts/session-decode.mjs / session-encode.mjs  `.jsonl.zstd` codec (test fixtures)
-tests/                  vitest suites (rewind / snapshot / hidden / session-cwd / integration)
-docs/                   maintainer docs: contract/, compat/, release/ subdirectories
-assets/screenshots/     UI screenshots
-cordis.patch.yml        bundle patch (mounts the dual-face plugin row)
-package.json            dsh.bundle + dsh.client manifests, optional peerDependencies
-```
-

package/docs/release/release.md

@@ -1,136 +0,0 @@
-# Release
-
-[简体中文](release.zh.md)
-
-## First release (manual, one-time)
-
-Trusted Publisher can only be configured once the package exists, so the first
-version is published locally:
-
-```sh
-npm login
-npm publish --access public
-```
-
-- If prompted for `EOTP`: complete the browser auth link the CLI prints, or
-  retry with a 6-digit code — `npm publish --otp=<code>`.
-- The first version carries no provenance (local path) — acceptable; every CI
-  release after that publishes with Sigstore/SLSA provenance automatically.
-
-## Configure Trusted Publisher (npmjs.com, one-time)
-
-Open `https://www.npmjs.com/package/dsh-rewind-plugin` → package **settings** →
-**Trusted Publisher**:
-
-| Field | Value |
-| --- | --- |
-| Provider | GitHub Actions |
-| Organization or user | `SiriLee` |
-| Repository | `dsh-rewind` (the GitHub repo, not the npm name) |
-| Workflow filename | `publish.yml` |
-| Environment | empty |
-| Allowed actions | `npm publish` |
-
-## Subsequent releases (CI, automatic)
-
-The release workflow is **version-driven**: it derives the npm dist-tag from the
-version in `package.json`, independent of branch. A stable version publishes to
-`latest`; a pre-release publishes to the dist-tag named by its pre-release
-identifier (e.g. `0.9.0-alpha.1` → `alpha`, `0.9.0-rc.1` → `rc`). The dist-tag is
-never passed by hand.
-
-The line being released determines the branch and the bump:
-
-| Release | Branch | Bump | dist-tag |
-| --- | --- | --- | --- |
-| Stable patch (current line) | `release/<line>.x` | `npm version patch` | `latest` |
-| Pre-release (next line) | `main` | `npm version prerelease --preid=alpha` | `alpha` |
-| Stable (next line) | `main` | `npm version <next>` | `latest` |
-
-Each release is `git push <branch>` followed by `git push <branch> --tags`.
-
-- The release commit is **`chore: release vX.Y.Z`**; the **lightweight `vX.Y.Z`
-  tag** sits on it. Do **not** create tag/release first with `gh release create
-  <tag>` (it tags the remote `main` head and breaks the tag/version match).
-- **Before bumping, manually confirm there is no newer DSH version the plugin
-  has not been verified against** (a pre-release can ship in DSH Desktop
-  without being on npm; see docs/compat/audit.md).
-- The workflow verifies the tag matches `package.json`, runs typecheck + tests +
-  a full build + artifact verification, publishes with `--provenance` (Sigstore)
-  to the version-derived dist-tag, and creates a GitHub Release (a pre-release
-  is created as a GitHub pre-release, not `latest`). It is **idempotent** — an
-  already published version is skipped.
-- CI (`.github/workflows/ci.yml`) runs `npm run check` — typecheck + tests +
-  build + artifact verification + a `npm pack --dry-run` — on every push / PR
-  across both Node engines boundary versions; the tarball layout is guarded by
-  `tests/package-layout.test.ts`.
-- The GitHub Release body is auto-created with `--generate-notes` as a
-  **placeholder** (`--latest` / `--prerelease` per version). After the publish
-  run succeeds, overwrite the body by hand in the repo's bilingual style
-  (Chinese first, then English) — never keep the auto text as the final note.
-
-## DSH version alignment (single peer tuple)
-
-DSH is still in rc; npm's prerelease matching rules require a peer range to
-share the host version's `[major, minor, patch]` tuple. So `peerDependencies`
-uses one peer tuple per DSH line (e.g. `^0.2.0-rc.1`). The range is
-conservative: it declares only what was verified, and guarantees nothing
-outside it.
-
-- **When to update**: when the verified range changes — a new DSH tuple, or a
-  deliberate narrowing (e.g. dropping the internal `alpha` series); a release
-  already inside the range changes nothing **unless it changes interfaces inside
-  the tuple** (`0.1.6-alpha.2` removed the client session-ownership and
-  queue-mirror APIs, so the floor moved with it). All `@deepseek-ai/*` packages
-  release together; `npm view @deepseek-ai/dsh dist-tags` is the signal.
-- **Published-tuple check (optional)**: `node scripts/check-dsh-version.mjs`
-  compares the `latest` dist-tag version against the tuple the peers cover
-  (exit 0 = nothing to do, exit 1 = update). It reads the `latest` tag only; a
-  pre-release published under another tag or bundled without
-  going to npm is a manual pre-release check — see the "Before bumping" step above.
-- **Update steps**: point every `@deepseek-ai/dsh-*` peer and devDependency at
-  the verified range → `npm install` → `npm run check` → release.
-- **After DSH goes final**: final releases are not bound by the prerelease
-  tuple rule, so the peers can converge to a single stable range (e.g.
-  `^0.1.x`); this section can then be deleted.
-- **Declared minimum (`engines.dsh`)**: alongside the peer tuple, each
-  release declares the DSH runtime floor under `engines.dsh` (e.g.
-  `>=0.2.0-rc.1`). No runtime consumer reads it; its form and its alignment with
-  the peer tuple are pinned by `tests/package-layout.test.ts`. Bump it in
-  the same release that changes the peer range; never leave code raised while
-  the declared floor stays behind. Only the `>=X.Y.Z[-pre]` form is used.
-- **The peers are enforced at startup (`0.1.7-rc.1`)**: DSH checks a profile
-  bundle's own `@deepseek-ai/dsh-*` peers against the running version and skips
-  the whole bundle when one does not satisfy it, so a peer range that is merely
-  stale now costs the plugin its load instead of a warning. See
-  `docs/compat/audit.md`.
-
-## Versioned-line release model
-
-**One release targets one DSH version line.** The plugin's own version is
-independent of the host; a release declares its DSH line through the peer
-constraint (a single companion tuple), never through the plugin version.
-
-The DSH line a release targets is the peer constraint, and its npm dist-tag is
-derived from the version (see above), so this model does not track the plugin's
-own version number.
-
-**Versioning.** A DSH version-line break is a MAJOR bump (incompatible with the
-prior DSH line). Within a line, MINOR/PATCH remain compatible.
-
-**Branching (trunk-based).** `main` is the single integration and release line
-and is always releasable. The currently-shipped stable is cut into a short-lived
-`release/<version>.x` maintenance branch from its release commit; that branch
-receives backported fixes while `main` advances to the next line. The prior
-(broad-compat) line is frozen as a tag, with no branch.
-
-**Support window / EOL.** A DSH line is supported within a declared window. By
-default the window runs until the next DSH line ships as `latest`; after that
-the line is EOL, frozen, and receives no further patches.
-
-**Bug-fix flow (forward-fix then backport).** A fix affecting multiple supported
-lines is applied on `main` first, then backported to each still-supported
-release branch. A fix specific to one line is applied only on that line.
-
-The single-line model uses one peer tuple per release (see DSH version
-alignment above); the OR-union multi-line practice it replaced is not used.

package/docs/release/release.zh.md

@@ -1,124 +0,0 @@
-# 发布流程
-
-[English](release.md)
-
-## 首次发布（手动，一次性）
-
-Trusted Publisher 要求**包已存在**才能配置，因此首个版本走本地发布：
-
-```sh
-npm login
-npm publish --access public
-```
-
-- 若提示 `EOTP`（一次性密码）：按 CLI 输出的浏览器认证链接完成认证，或用
-  authenticator 的 6 位码 `npm publish --otp=<code>` 重试。
-- 首个版本无 provenance（本地路径），合规；之后每次 CI 发布自动带
-  Sigstore/SLSA provenance。
-
-## 配置 Trusted Publisher（npmjs.com，一次性）
-
-打开 `https://www.npmjs.com/package/dsh-rewind-plugin` → 包右上角 **settings**
-→ **Trusted Publisher**：
-
-| 字段 | 值 |
-| --- | --- |
-| Provider | GitHub Actions |
-| Organization or user | `SiriLee` |
-| Repository | `dsh-rewind`（GitHub 仓库名，与 npm 包名可不同） |
-| Workflow filename | `publish.yml` |
-| Environment | 留空 |
-| Allowed actions | `npm publish` |
-
-## 后续发布（CI 自动）
-
-发布 workflow 为**版本驱动**：npm dist-tag 由 `package.json` 中的版本号决定、与分支无关。
-稳定版发 `latest`；pre-release 发到与其 pre-release 标识符同名的 dist-tag
-（如 `0.9.0-alpha.1` → `alpha`、`0.9.0-rc.1` → `rc`）。dist-tag 无需手传。
-
-按要发布的版本线选择分支与版本步进：
-
-| 发布类型 | 分支 | 版本步进 | dist-tag |
-| --- | --- | --- | --- |
-| 当前线稳定补丁 | `release/<line>.x` | `npm version patch` | `latest` |
-| 下一线 pre-release | `main` | `npm version prerelease --preid=alpha` | `alpha` |
-| 下一线正式版 | `main` | `npm version <next>` | `latest` |
-
-每次发布为 `git push <分支>`，再 `git push <分支> --tags`。
-
-- 发布提交为 **`chore: release vX.Y.Z`**，**轻量 `vX.Y.Z` tag** 落在该提交上。
-  **不要**用 `gh release create <tag>` 事先建 tag/release（会打到远端 `main`
-  HEAD，导致 tag/版本校验失败）。
-- **升版前手动确认**：确认无插件未针对其验证过的更新 DSH 版本（pre-release
-  可能只随 Desktop 捆绑、而不发到 npm；见 docs/compat/audit.md）。
-- workflow 校验 tag 与 `package.json` 版本一致，跑 typecheck + 测试 + 完整
-  构建 + 产物验证，以 `--provenance`（Sigstore）发布到版本推导出的 dist-tag，
-  并创建 GitHub Release（pre-release 会建成 GitHub pre-release，而非 `latest`）。
-  **幂等**——已发布的版本会跳过。
-- CI（`.github/workflows/ci.yml`）在每次 push / PR 跑 `npm run check`——
-  typecheck + 测试 + 构建 + 产物验证 + `npm pack --dry-run`，且覆盖
-  engines 两个边界版本；tarball 布局由 `tests/package-layout.test.ts` 守护。
-- GitHub Release 正文由 workflow 以 `--generate-notes` 自动生成，仅是**占位**
-  （按版本取 `--latest` / `--prerelease`）。发布运行成功后，请用**手写双语**
-  正文（中文在前、英文在后）覆盖——切勿把自动文本当作最终发布说明。
-
-## DSH 版本适配（单一 peer 元组）
-
-DSH 仍在 rc 阶段，npm 的 prerelease 匹配规则要求 peer 范围与宿主版本
-**同 `[major, minor, patch]` 元组**才能匹配。因此 peerDependencies 采用
-**每一条 DSH 线一个 peer 元组**（如 `^0.1.2-rc.1`）；范围是保守的，只声明实际验证过的内容。
-
-- **何时需要更新**：**已验证范围**变化时——DSH 发新元组，或主动收窄（例如不再
-  声明内测的 DSH `alpha` 系列）；落在已声明范围内的发布不改变任何东西，**除非它在
-  同一元组内改变了接口**（`0.1.6-alpha.2` 删除了客户端会话所有权与 queue 镜像
-  API，下限随之移动）。DSH 所有包同版本发布；信号是
-  `npm view @deepseek-ai/dsh dist-tags`。
-- **已发布元组检查（可选）**：`node scripts/check-dsh-version.mjs` 用 npm `latest`
-  dist-tag 版本对比 peer 覆盖的元组（exit 0 无需动作，exit 1 需要）。它**只读
-  `latest` tag**；发布在其它 tag 的 pre-release 走**手动发布前检查**
-  ——见上文"升版前手动确认"。
-- **更新步骤**：把每个 `@deepseek-ai/dsh-*` peer 与 devDependency 指向已验证
-  范围 → `npm install` → `npm run check` → 发版。
-- **正式版后收敛**：DSH 发布 final 版本后，正式版不受 prerelease 元组规则
-  限制，peer 可收敛为稳定的 `^0.1.x` 单范围，此节即可删除。
-- **声明的最低运行时（`engines.dsh`）**：与 peer 元组一起，每个发布在
-  `engines.dsh` 声明 DSH 运行时下限（如 `>=0.1.2-rc.1`）。当前线上还没有
-  任何读取方，因此它只是前置声明、尚未被强制执行。**与 peer 范围持平的同一发布里
-  一并 bump**；不可只升代码、声明下限停留在旧值。仅使用 `>=X.Y.Z[-pre]` 形式。
-- **peer 在启动时会被强制执行（`0.1.7-rc.1`）**：DSH 会拿 bundle 自身的
-  `@deepseek-ai/dsh-*` peer 与运行版本比对，只要有一个不满足就**整包跳过**，
-  因此过期的 peer 范围不再是"仅告警"，而是直接导致插件不加载。见
-  `docs/compat/audit.md`。
-
-## 发布版本线模型
-
-**一个发布对准一条 DSH 版本线。** 插件自身版本号与宿主解耦；某发布所对准的
-DSH 线由 peer 约束（单一 companion 元组）声明，而非插件版本号。
-
-| 插件版本 | DSH 线 | 角色（示例） |
-| --- | --- | --- |
-| `0.7.x` | `0.1.1` + `0.1.2`（广兼容） | 冻结 / EOL |
-| `0.8.x` | `0.1.2-rc.1`（单线） | 当前线 |
-| `0.9.x` | `0.1.3`（单线） | 后续线 |
-
-各行仅为示例——某个发布对准的 DSH 线由 peer 约束声明，其 npm dist-tag 按版本号
-派生（见上文），因此本模型不跟随插件自身版本号变化。
-
-**版本号。** DSH 版本线破坏性变更 ＝ MAJOR 升版（与更早 DSH 线向后不兼容）。
-同一线内 MINOR/PATCH 保持向后兼容。
-
-**分支（主干开发）。** `main` 是唯一集成与发布线，始终可发版。当前已发布
-稳定版从发布提交点切出短命 `release/<版本>.x` 维护分支；该分支承接
-backport 修复，同时 `main` 前进到下一线。更早的（广兼容）线冻结成 tag，无分支。
-
-**dist-tag 路由。** 发布 workflow 按版本号取 npm dist-tag：稳定版发 `latest`；
-pre-release 发到与其 pre-release 标识符同名的 dist-tag（`0.9.0-alpha.1` →
-`alpha`、`0.9.0-rc.1` → `rc`）。pre-release 不占据 `latest`。
-
-**支持窗口 / EOL。** 一条 DSH 线仅在声明的窗口内受支持。默认窗口到下一
-DSH 线作为 `latest` 发布为止；此后该线 EOL、冻结、不再发补丁。
-
-**Bug 修复流程（先向前修，再回迁）。** 跨多条支持线的修复，先在 `main` 上
-修复，再回迁到各仍受支持的 release 分支。仅特定线的修复，只在对应线修复。
-
-单线模型每个发布使用单一 peer 元组（见上文「DSH 版本适配」）；其取代的 OR 并集多线做法已不使用。