dsh-session-sync 0.2.31 → 0.2.33
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.
- package/CHANGELOG.md +19 -0
- package/PRIVACY.md +11 -0
- package/README.en.md +430 -0
- package/{README-es.md → README.es.md} +214 -176
- package/README.hi.md +430 -0
- package/README.md +248 -216
- package/README.pt.md +430 -0
- package/icon.svg +1 -0
- package/index.mjs +13 -1
- package/lib/constants.mjs +4 -1
- package/lib/engine.mjs +9 -2
- package/lib/git.mjs +25 -1
- package/package.json +42 -33
- package/README-hi.md +0 -392
- package/README-pt.md +0 -392
- package/README-zh.md +0 -394
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,24 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.2.33] - 2026-11-13
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
|
|
7
|
+
- **`pull()` no longer dies on `fatal: stash failed`.** A tracked DSH atomic-write staging file (`.l2s.<payload>.<hash>.tmp<seq>.<seq>`) keeps the work tree stat-dirty while its content is unchanged; `git merge` then takes the autostash path, `git stash create` prints nothing, and git aborts. The index is refreshed before every merge, and host staging artifacts are now excluded from the mirror and the delete set at the source. Fixes #29.
|
|
8
|
+
- **A merge that never started is no longer reported as "already up to date".** `beginMerge()` treated any non-zero merge exit without `MERGE_HEAD` as a no-op, so `pull()` returned `ok: true`, `lastPullAt` advanced, and the repository stayed divergent forever. It now throws `GIT_FAILED` with the sanitized stderr tail. Fixes #29.
|
|
9
|
+
- **`lastError` is cleared by the next successful pull or push**, so a days-old failure no longer frames the current symptom. Fixes #29.
|
|
10
|
+
- **`sync_status` returns lossless JSON.** Undefined `lastPullAt` / `lastPushAt` / `lastError` (and `head` / `remoteHead` / `error` from an empty repo) were spread into the tool result, which the host rejects with `value is not lossless JSON`; undefined keys are now omitted. Fixes #29.
|
|
11
|
+
|
|
12
|
+
## [0.2.32] - 2026-11-05
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
|
|
16
|
+
- **Host 0.2.2 line support.** devDependencies move from 0.2.1-rc.2 to 0.2.2-rc.1, cordis to 4.1.0 / include 1.1.0 / loader 1.1.0, and schemastery to ~3.19.0 so a single copy resolves against `@deepseek-ai/dsh-llm` 0.2.2. `engines.dsh` appends `>=0.2.2-0 <0.3.0` (append-only) and `engines.node` becomes `^22.19.0 || >=24.9.0`.
|
|
17
|
+
|
|
18
|
+
### Fixed
|
|
19
|
+
|
|
20
|
+
- Add `@deepseek-ai/dsh-package-manifest`: `@deepseek-ai/dsh-llm` 0.2.2's published types import it but its manifest does not declare it.
|
|
21
|
+
|
|
3
22
|
## [0.2.31] - 2026-10-24
|
|
4
23
|
|
|
5
24
|
### Fixed
|
package/PRIVACY.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Privacy
|
|
2
|
+
|
|
3
|
+
`dsh-session-sync` is a local DeepSeek Harness plugin.
|
|
4
|
+
|
|
5
|
+
- It reads only the workspace files, configuration and tool inputs needed for its documented features.
|
|
6
|
+
- It does not add telemetry, analytics, advertising or a hosted account, and it sends no data to PerryLink.
|
|
7
|
+
- Any network access or external service used by the plugin is documented in its README and is controlled by the user's own configuration.
|
|
8
|
+
- It writes no data outside the DSH profile, the workspace, and the host's own session/log storage. The host controls that storage and its retention.
|
|
9
|
+
- Removing the package removes its code; it does not delete host logs, workspace files or documents you already created.
|
|
10
|
+
|
|
11
|
+
This statement covers the npm package, not the DSH host or any other plugin in the profile.
|
package/README.en.md
ADDED
|
@@ -0,0 +1,430 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-session-sync-hero-en-dark.webp">
|
|
5
|
+
<img src="docs/assets/dsh-session-sync-hero-en-light.webp" width="100%" alt="dsh-session-sync: two devices mirror $DSH_HOME/sessions as opaque bytes into a git worktree, commit and sync to a remote you own; pull runs a per-file three-way merge that keeps both sides (the remote version as a fork file) and never force-pushes.">
|
|
6
|
+
</picture>
|
|
7
|
+
|
|
8
|
+
# dsh-session-sync
|
|
9
|
+
|
|
10
|
+
**Mirror your session store into a git repository you control — sync across devices, keep both sides on conflict, never lose a turn.**
|
|
11
|
+
|
|
12
|
+
A pure host-side sync plugin for DeepSeek Harness: session files are copied as opaque bytes, divergence is resolved by an append-only three-way merge, and the remote is yours (plaintext git by default, optional age encryption) — no cloud service, no third-party storage.
|
|
13
|
+
|
|
14
|
+
[Install](#three-step-setup) · [Configuration](#configuration) · [FAQ](#faq) · [简体中文](README.md) · [English](README.en.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
15
|
+
|
|
16
|
+
[](LICENSE)
|
|
17
|
+
[](#compatibility)
|
|
18
|
+
[](https://www.npmjs.com/package/dsh-session-sync)
|
|
19
|
+
[](https://github.com/PerryLink/dsh-session-sync/actions/workflows/ci.yml)
|
|
20
|
+
[](#compatibility)
|
|
21
|
+
|
|
22
|
+
[](https://github.com/PerryLink/dsh-session-sync/stargazers)
|
|
23
|
+
[](https://www.npmjs.com/package/dsh-session-sync)
|
|
24
|
+
[](https://dshfind.com/plugins/PerryLink/dsh-session-sync?ref=badge)
|
|
25
|
+
[](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-session-sync)
|
|
26
|
+
[](https://dsh.market/)
|
|
27
|
+
[](https://gitee.com/perrylink/dsh-session-sync)
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
dsh plugin --profile <name> add dsh-session-sync
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
</div>
|
|
34
|
+
|
|
35
|
+
<sub>Community plugin, not affiliated with DeepSeek. This is the only official repository, maintained by PerryLink; same-name repositories under other accounts are not affiliated. Gitee is a mirror.</sub>
|
|
36
|
+
|
|
37
|
+
## What it is
|
|
38
|
+
|
|
39
|
+
`dsh-session-sync` mirrors the DSH session store (`$DSH_HOME/sessions`) into a dedicated git worktree and syncs it to a remote **you** control: no cloud service, no third-party storage. Session files are copied as opaque bytes — the plugin never parses JSONL/zstd, since the physical encoding belongs to the harness; its job is to move those bytes, merge append-only histories, and report state. On any divergence it runs an append-only three-way merge: **both sides are kept**, the remote version is preserved as fork files, and nothing is silently overwritten. `backend: git` (the default) is a plaintext mirror; `backend: encrypted` adds an age layer above it; every auto mode is configurable and reversible.
|
|
40
|
+
|
|
41
|
+
<p align="center">
|
|
42
|
+
<picture>
|
|
43
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-session-sync-flow-v5-dark.svg">
|
|
44
|
+
<img src="docs/assets/dsh-session-sync-flow-v5-light.svg" width="100%" alt="dsh-session-sync structure: device A byte-mirrors and commits $DSH_HOME/sessions, then push crosses the confirmation gate into the git remote you own; device B fetches, runs a per-file three-way merge (base/ours/theirs) and restores the sessions locally, keeping divergent remote bytes as fork files at the original path; fork files are never deleted or overwritten.">
|
|
45
|
+
</picture>
|
|
46
|
+
</p>
|
|
47
|
+
|
|
48
|
+
## Three-step setup
|
|
49
|
+
|
|
50
|
+
1. **Install** (pick one channel):
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
# git channel (latest main; equivalent to git+https://github.com/PerryLink/dsh-session-sync.git)
|
|
54
|
+
dsh plugin --profile web add github:PerryLink/dsh-session-sync
|
|
55
|
+
# npm channel (published releases)
|
|
56
|
+
dsh plugin --profile web add dsh-session-sync
|
|
57
|
+
# tarball channel: pnpm pack in this repo, then
|
|
58
|
+
dsh plugin --profile web add ./dsh-session-sync-<version>.tgz
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
No build step — `index.mjs` and `lib/` are the shipped artifacts.
|
|
62
|
+
|
|
63
|
+
2. **Minimal config** (point it at a **private** git remote in your profile patch):
|
|
64
|
+
|
|
65
|
+
```yaml
|
|
66
|
+
- insert:
|
|
67
|
+
- id: session-sync
|
|
68
|
+
name: dsh-session-sync
|
|
69
|
+
config:
|
|
70
|
+
remote: git@github.com:you/your-dsh-sessions.git
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
3. **Verify it mounts**:
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
dsh --profile web --dump-config | grep -A2 'id: session-sync'
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
> /sync status
|
|
81
|
+
> /sync pull
|
|
82
|
+
> /sync push
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
**Uninstall**: `dsh plugin --profile web remove dsh-session-sync` (or remove the row from the profile patch).
|
|
86
|
+
|
|
87
|
+
## Core capabilities
|
|
88
|
+
|
|
89
|
+
`dsh-session-sync` turns the session store into a versioned git mirror on the host and hands the sync action to your remote:
|
|
90
|
+
|
|
91
|
+
- **`/sync` command** — `status` (branch, sanitized remote, ahead/behind, dirty files, forks), `diff`, `log`, `pull`, `push`, `help`.
|
|
92
|
+
- **`sync_status` / `sync_pull` / `sync_push` tools** — the same surface for the model, inside a turn.
|
|
93
|
+
- **Append-only conflict resolution** — session logs are append-only; on any divergence the plugin keeps **both** sides (local version kept, remote version preserved as fork files) and never silently overwrites. Diverged sessions can also fork at the session level.
|
|
94
|
+
- **Auto modes** — pull on start, push after every closed turn, and periodic pull, all configurable and all reversible.
|
|
95
|
+
- **Confirmation-gated writes** — `pull`/`push` ask first (through `userQuestions` or `approval`); read-only surfaces never ask; with no answerer the operation fails closed.
|
|
96
|
+
|
|
97
|
+
```text
|
|
98
|
+
device A remote (your git repo) device B
|
|
99
|
+
$DSH_HOME/sessions ──mirror──▶ commit ──push──▶ [sessions] ──pull──▶ merge (keep-both + fork)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Commands & tools surface
|
|
103
|
+
|
|
104
|
+
| Surface | Read-only | Needs confirmation | Notes |
|
|
105
|
+
|---|---|---|---|
|
|
106
|
+
| `/sync status` | ✅ | — | Branch, sanitized remote, ahead/behind, dirty files, fork files, last pull/push |
|
|
107
|
+
| `/sync diff` | ✅ | — | Uncommitted changes + `HEAD..remote` stat (read-only) |
|
|
108
|
+
| `/sync log` | ✅ | — | Last commits in the sync repository |
|
|
109
|
+
| `/sync pull` | | ✅ | Fetch + merge with keep-both semantics; local kept, remote preserved as forks |
|
|
110
|
+
| `/sync push` | | ✅ | Mirror + commit + push; never force-pushes, reconciles and retries once on rejection |
|
|
111
|
+
| `sync_status` | ✅ | — | Same facts as `/sync status` for the model |
|
|
112
|
+
| `sync_pull` | | ✅ | Model-callable pull |
|
|
113
|
+
| `sync_push` | | ✅ | Model-callable push |
|
|
114
|
+
|
|
115
|
+
### Examples
|
|
116
|
+
|
|
117
|
+
These are the plugin's real entry points; install once, then call one.
|
|
118
|
+
|
|
119
|
+
**Detailed example** — command `/sync help`:
|
|
120
|
+
|
|
121
|
+
```text
|
|
122
|
+
sync: usage — /sync [status | pull | push | diff | log | help]
|
|
123
|
+
status show mirror state (default): branch, remote, ahead/behind, dirty, forks
|
|
124
|
+
pull fetch + merge remote changes (keep-both; confirms first)
|
|
125
|
+
push mirror + commit + push local changes (confirms first)
|
|
126
|
+
diff uncommitted changes + HEAD..remote stat (read-only)
|
|
127
|
+
log last commits in the sync repository
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
*Observed from `index.mjs:754-765 (registered /sync handler)`*
|
|
131
|
+
|
|
132
|
+
**Failure branch** — input `/sync push`:
|
|
133
|
+
|
|
134
|
+
```text
|
|
135
|
+
sync: cancelled: approval requires an open turn; /sync commands run between turns — mount userQuestions or set confirmVia: userQuestions
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
*Observed from `plugins/dsh-session-sync/lib/gate.mjs:134-137; plugins/dsh-session-sync/index.mjs:792-794; plugins/dsh-session-sync/test/gate.test.mjs:80-88; plugins/dsh-session-sync/README.md:246`*
|
|
139
|
+
|
|
140
|
+
**Brief examples**: `/sync diff` · `/sync pull`
|
|
141
|
+
|
|
142
|
+
## Configuration
|
|
143
|
+
|
|
144
|
+
All tunables are Schemastery `Config` fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need. `cordis.patch.yml` documents each key inline.
|
|
145
|
+
|
|
146
|
+
Most-used keys:
|
|
147
|
+
|
|
148
|
+
| Key | Default | Meaning |
|
|
149
|
+
|---|---|---|
|
|
150
|
+
| `remote` | `''` | Remote address (required before pull/push; status/diff work without one) |
|
|
151
|
+
| `backend` | `git` | Sync backend: `git` (plaintext mirror) or `encrypted` (age-encrypted mirror content) |
|
|
152
|
+
| `sessionRoot` | `''` | Session store root; empty = `$DSH_HOME/sessions` (both missing fails load) |
|
|
153
|
+
| `repoDir` | `''` | Sync worktree root; empty = `$DSH_HOME/dsh-session-sync/repo` |
|
|
154
|
+
| `branch` | `main` | Remote branch name |
|
|
155
|
+
| `autoPushOnTurnEnd` | `false` | Push after every closed turn |
|
|
156
|
+
| `pullIntervalMinutes` | `0` | Periodic pull every N minutes (`0` = off, max `10080`) |
|
|
157
|
+
| `confirmVia` | `auto` | Confirmation channel: `auto` (userQuestions first, then approval), `userQuestions`, `approval` |
|
|
158
|
+
|
|
159
|
+
<details>
|
|
160
|
+
<summary>Full configuration table (21 keys)</summary>
|
|
161
|
+
|
|
162
|
+
| Key | Default | Meaning |
|
|
163
|
+
|---|---|---|
|
|
164
|
+
| `enabled` | `true` | Master switch; `false` unregisters the command, tools, listeners, and auto modes |
|
|
165
|
+
| `backend` | `git` | Sync backend: `git` (plaintext mirror) or `encrypted` (age-encrypted mirror content) |
|
|
166
|
+
| `sessionRoot` | `''` | Session store root; empty = `$DSH_HOME/sessions` (both missing fails load) |
|
|
167
|
+
| `repoDir` | `''` | Sync worktree root; empty = `$DSH_HOME/dsh-session-sync/repo` |
|
|
168
|
+
| `remote` | `''` | Remote address (required before pull/push; status/diff work without one) |
|
|
169
|
+
| `branch` | `main` | Remote branch name |
|
|
170
|
+
| `gitBin` | `git` | git executable path |
|
|
171
|
+
| `ageBin` | `age` | age executable path (probed for `backend: encrypted`; missing degrades to plaintext) |
|
|
172
|
+
| `ageRecipient` | `''` | age recipient (public key or identity string); empty = cannot encrypt, degrades to plaintext |
|
|
173
|
+
| `ageIdentity` | `''` | Path to a passphrase-less age secret key for decryption; empty = cannot decrypt, degrades to plaintext |
|
|
174
|
+
| `autoPullOnStart` | `false` | Pull once when the plugin mounts (config is the grant; no re-confirm) |
|
|
175
|
+
| `autoPushOnTurnEnd` | `false` | Push after every closed turn |
|
|
176
|
+
| `pullIntervalMinutes` | `0` | Periodic pull every N minutes (`0` = off, max `10080`) |
|
|
177
|
+
| `confirmVia` | `auto` | Confirmation channel: `auto` (userQuestions first, then approval), `userQuestions`, `approval` |
|
|
178
|
+
| `graceMs` | `10000` | Grace period for git kills (ms) |
|
|
179
|
+
| `commandTimeoutMs` | `120000` | Per-command timeout (ms) |
|
|
180
|
+
| `maxOutputBytes` | `262144` | Per-stream collected-output cap (bytes) |
|
|
181
|
+
| `commitName` | `dsh-session-sync` | Commit author name |
|
|
182
|
+
| `commitEmail` | `dsh-session-sync@localhost` | Commit author email |
|
|
183
|
+
| `registerCommand` | `true` | Register the `/sync` command |
|
|
184
|
+
| `registerTools` | `true` | Register the `sync_*` tools when the tools service is present |
|
|
185
|
+
|
|
186
|
+
</details>
|
|
187
|
+
|
|
188
|
+
Example override in your profile patch:
|
|
189
|
+
|
|
190
|
+
```yaml
|
|
191
|
+
- insert:
|
|
192
|
+
- id: session-sync
|
|
193
|
+
name: dsh-session-sync
|
|
194
|
+
config:
|
|
195
|
+
remote: git@github.com:you/your-dsh-sessions.git
|
|
196
|
+
branch: main
|
|
197
|
+
autoPushOnTurnEnd: true
|
|
198
|
+
pullIntervalMinutes: 30
|
|
199
|
+
confirmVia: userQuestions
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## FAQ
|
|
203
|
+
|
|
204
|
+
<details>
|
|
205
|
+
<summary>Where does the data actually live? Is anything uploaded to a cloud?</summary>
|
|
206
|
+
|
|
207
|
+
No cloud service and no third-party storage. Two copies stay on your machine: `$DSH_HOME/sessions` (the harness session store) and the `repoDir` worktree you configure (default `$DSH_HOME/dsh-session-sync/repo`); the remote is **your own** git repository. `backend: encrypted` only turns the pushed/remote copy into age ciphertext — the local mirror stays plaintext.
|
|
208
|
+
|
|
209
|
+
</details>
|
|
210
|
+
|
|
211
|
+
<details>
|
|
212
|
+
<summary>Can a conflict overwrite or lose a session?</summary>
|
|
213
|
+
|
|
214
|
+
Nothing is silently overwritten. Session logs are append-only, and the three-way merge keeps both sides on any divergence: the local version is kept and the remote version is preserved as a fork file named `<basename>.remote-fork-<UTC 14-digit stamp>-<device8>`; fork files are never deleted or overwritten, and git never force-pushes, resets, rebases, or switches branches. A diverged session is also forked at the session level, with a persistent notice injected into the child.
|
|
215
|
+
|
|
216
|
+
</details>
|
|
217
|
+
|
|
218
|
+
<details>
|
|
219
|
+
<summary>Is encryption on by default? What happens when age is missing?</summary>
|
|
220
|
+
|
|
221
|
+
No — the default is `backend: git`, so session bytes sit unencrypted in your remote: use a private repository. `backend: encrypted` needs `age` plus non-empty `ageRecipient`/`ageIdentity`; if anything is missing the plugin warns explicitly and falls back to plaintext git — it never pretends to encrypt. Check the warning in `/sync status` before treating the remote as encrypted.
|
|
222
|
+
|
|
223
|
+
</details>
|
|
224
|
+
|
|
225
|
+
<details>
|
|
226
|
+
<summary>What happens without git, or with no confirmation answerer?</summary>
|
|
227
|
+
|
|
228
|
+
Without the `git` executable or the `subprocess` service, sync operations fail with a clear reason (profiles keep booting). `/sync` runs between turns, where the `approval` channel has no open turn to attach to: use `confirmVia: userQuestions`, or drive sync through the `sync_*` tools inside a turn; with no answerer at all the operation fails closed.
|
|
229
|
+
|
|
230
|
+
</details>
|
|
231
|
+
|
|
232
|
+
<details>
|
|
233
|
+
<summary>How much overhead is there? Do the auto modes run forever?</summary>
|
|
234
|
+
|
|
235
|
+
Session files are copied as opaque bytes and never parsed; every git command has a timeout, a kill grace period, and a per-stream output cap. Auto push is off by default, periodic pull is off by default (`pullIntervalMinutes: 0`), and pull-on-start is off by default — once enabled they are covered by the config grant and never re-confirm. Cost depends on session-store size and remote latency; this repository has no benchmark data, so no invented numbers.
|
|
236
|
+
|
|
237
|
+
</details>
|
|
238
|
+
|
|
239
|
+
## Security boundaries
|
|
240
|
+
|
|
241
|
+
- **Never silently overwrite.** The append-only three-way merge keeps both sides on any divergence, including delete/modify (modified bytes kept, deletion intent honored); fork files are never deleted, and git never force-pushes, resets, rebases, or switches branches.
|
|
242
|
+
- **Path containment.** Files are mirrored as opaque bytes with symlinks refused and every joined path containment-checked (`PATH_UNSAFE` fails loud).
|
|
243
|
+
- **Sanitized output.** Remote-URL credentials, tokens, and `key=value` secrets are redacted before reaching the model or the log; path display refuses anything outside its root.
|
|
244
|
+
- **No credential storage.** The plugin stores no credentials; git credentials live in your normal git credential helper. age identities/recipients are yours to manage, and keys never enter the sync repository.
|
|
245
|
+
- **Git hardening.** Git runs with `GIT_TERMINAL_PROMPT=0` and `GIT_OPTIONAL_LOCKS=0`, deadline- and signal-bounded, with a per-stream output cap.
|
|
246
|
+
- **Fail closed.** A missing confirmation answerer, a missing remote, or an unsafe path refuses the operation loudly.
|
|
247
|
+
|
|
248
|
+
## Permissions & data
|
|
249
|
+
|
|
250
|
+
- **Permissions**: mutating operations cross the confirmation gate (`confirmVia`); the plugin never re-implements or bypasses the harness's `userQuestions`/`approval` services. Auto modes are covered by the config grant and never re-confirm.
|
|
251
|
+
- **Data**: sync metadata (device id, last pull/push, last push head, last error) lives in the `session-sync` storage domain. Session files are copied as opaque bytes — the plugin never parses them. The device id is also written to `device.txt` in the sync repository for cross-device fork attribution.
|
|
252
|
+
- **Session log**: `sync/push`, `sync/pull`, and `sync/conflict` are declared in `types.d.ts`; they are appended only when the host records the types (see Known limitations). Everything written or shown is sanitized. The one durable message the plugin writes — the conflict fork notice — carries the plugin's own producer-owned source kind (`dsh-session-sync`); the harness retired the shared `plugin` kind and refuses it when a session is read back.
|
|
253
|
+
|
|
254
|
+
## Encryption & threat model
|
|
255
|
+
|
|
256
|
+
`backend: encrypted` adds an optional **age** layer above the mirror: session bytes are encrypted into `encrypted/**/*.age` files before they are committed and pushed, and decrypted back to the local plaintext mirror before merging. The three-way merge always runs on plaintext locally, so the append-only keep-both semantics are unchanged.
|
|
257
|
+
|
|
258
|
+
What the encryption **protects**:
|
|
259
|
+
|
|
260
|
+
- **Mirror content at rest in the remote.** The session files you push are age ciphertext; the remote host, its operators, and anyone who clones the repository do not see plaintext session bytes without the private key.
|
|
261
|
+
|
|
262
|
+
What it does **not** protect (the boundary):
|
|
263
|
+
|
|
264
|
+
- **Keys and age identities are yours to manage.** The recipient/identity files are never shipped, stored, or rotated by the plugin. If a key leaks, the mirror content it protects is exposed. Use a passphrase-less identity and keep it out of the repository.
|
|
265
|
+
- **The remote is still a private repository in practice.** git metadata — commit messages, the `.gitignore`, the `encrypted/` path structure, branch names, and push/fetch activity — remains visible to the remote host. Encryption hides the *content*, not the fact that you sync, nor the shape of your session tree.
|
|
266
|
+
- **Plaintext still exists locally.** The mirror at `<repoDir>/sessions/` is plaintext on disk; encryption protects the transmitted/remote copy, not local disk encryption or the live session store.
|
|
267
|
+
- **Graceful degradation means plaintext.** With `backend: encrypted`, if `age` is missing, or `ageRecipient`/`ageIdentity` is empty, the plugin falls back to the plaintext git path **and warns explicitly** in the status/log — it never silently pretends to encrypt. Check `/sync status` for the warning before trusting the remote as encrypted.
|
|
268
|
+
|
|
269
|
+
Baseline: with `backend: git` (the default), session bytes are stored unencrypted in **your** git remote — use a private repository.
|
|
270
|
+
|
|
271
|
+
## Known limitations
|
|
272
|
+
|
|
273
|
+
- **Encryption is optional, and age is an external dependency.** `backend: encrypted` adds an age layer (see "Encryption & threat model" above); a missing `age` or empty `ageRecipient`/`ageIdentity` warns explicitly and degrades to plaintext, and a passphrase-protected identity cannot be used (decryption would block on a TTY prompt, so it fails closed). With `backend: git` (the default), session bytes are stored unencrypted in **your** git remote — use a private repository.
|
|
274
|
+
- **`object-storage` is a reserved interface.** It is an interface placeholder and fails loudly at load; only `git` and `encrypted` are implemented.
|
|
275
|
+
- **git required.** The plugin needs the `git` executable and the `subprocess` service; without them, sync operations fail with a clear reason (profiles keep booting).
|
|
276
|
+
- **One `repoDir` per backend.** Switching between `git` and `encrypted` on the same `repoDir` is not supported; use a fresh worktree per backend.
|
|
277
|
+
- **Session events on `0.1.0-rc.6`/`0.1.0-rc.8`/`0.1.1-rc.2`/`0.1.2-alpha.2`/`0.1.2-alpha.3`/`0.1.2-rc.1`/`0.1.7-alpha.2`.** The harness does not record `sync/*` event types, so the session-log appends are skipped (sessions keep loading); the plugin enables them automatically once a host records the types or exposes the `ignorable` envelope on `Session.append`.
|
|
278
|
+
- **`approval` between turns.** `/sync` runs between turns, where the `approval` channel has no open turn to attach to; use `confirmVia: userQuestions` for command-driven sync, or drive sync through the tools inside a turn. The open-turn check reads the host `turnBoundary` session projection: a composition without `@deepseek-ai/dsh-session-projection` cannot verify the turn state and fails closed with that reason.
|
|
279
|
+
- **Host-private artifacts stay host-private.** `session.lock` (the harness session lease) and `session.migration.*.tmp` staging files are never mirrored or deleted — they are runtime state, not syncable content. Session logs (`session.jsonl`, `session.v[1-9]*.jsonl[.zstd]`) remain the mirrored payload.
|
|
280
|
+
|
|
281
|
+
## Compatibility
|
|
282
|
+
|
|
283
|
+
| Surface | Status |
|
|
284
|
+
|---|---|
|
|
285
|
+
| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (GitHub tag, verified 2026-09-25: full gate chain against the pinned `0.1.7-rc.2` peers). npm dependency line `0.1.7-rc.2`, peers `>=0.1.2-rc.1 <0.2.0 \|\| >=0.1.5-alpha.1 <0.2.0 \|\| >=0.1.6-0 <0.2.0 \|\| >=0.1.7-0 <0.2.0`. (adapted 2026-10-04): the conflict fork notice carries the plugin's own producer-owned message source kind — the harness retired the shared `plugin` kind and refuses it on read-back. |
|
|
286
|
+
| Node | `^22.19.0 \|\| >=24.9.0` |
|
|
287
|
+
| Platforms | Anywhere `git` and DSH run (git-based mirror; no platform-specific code) |
|
|
288
|
+
| Model | Text-only models fully supported; no vision or extra model capability required |
|
|
289
|
+
|
|
290
|
+
## Ecosystem and quality
|
|
291
|
+
|
|
292
|
+
- [Gitee mirror](https://gitee.com/perrylink/dsh-session-sync) (synced mirror; GitHub is canonical)
|
|
293
|
+
- [dshfind plugin page](https://dshfind.com/plugins/PerryLink/dsh-session-sync) (installs and ranking)
|
|
294
|
+
- [OpenSSF Scorecard report](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-session-sync) (driven by [.github/workflows/scorecard.yml](.github/workflows/scorecard.yml))
|
|
295
|
+
- [dsh-plugin-doctor verification report](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章) (historical K10–K13 verification badge)
|
|
296
|
+
- [DSH Market](https://dsh.market/) (listed)
|
|
297
|
+
- **1024 store channel**: run `npm i -g dsh1024` once, then `dsh1024 plugin --profile web add dsh-session-sync` (counts toward the [deepseek1024.com](https://deepseek1024.com) install ranking)
|
|
298
|
+
- [Ecosystem knowledge base](https://perrylink.github.io/dsh-plugin-guide/): plugin development guide · measured selection data · maintenance trade-off criteria
|
|
299
|
+
|
|
300
|
+
## Development
|
|
301
|
+
|
|
302
|
+
```sh
|
|
303
|
+
pnpm install # node ^22.19 || >=24.9
|
|
304
|
+
pnpm run typecheck && pnpm run typecheck:ci # tsc --checkJs: checkout face + published-line face
|
|
305
|
+
pnpm test # node --test (14 test files; the engine git suite skips without git)
|
|
306
|
+
pnpm run verify:self-contained # dependency specs resolve from the registry
|
|
307
|
+
pnpm run verify:artifacts # shipped files present + index.mjs importable
|
|
308
|
+
pnpm run check:readmes # five-language README consistency
|
|
309
|
+
pnpm pack # the published tarball
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
No build step: pure ESM, `index.mjs` and `lib/` are the shipped artifacts. README images are generated programmatically by [`scripts/gen-readme-assets.py`](scripts/gen-readme-assets.py) (Python + Pillow) and can be re-run safely.
|
|
313
|
+
|
|
314
|
+
Topics: `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `session-sync`, `session`, `git`, `sync`, `cross-device`
|
|
315
|
+
|
|
316
|
+
## Family and thanks
|
|
317
|
+
|
|
318
|
+
This project is part of the DeepSeek Harness plugin family from [PerryLink](https://github.com/PerryLink) (all Apache-2.0). If it is useful, **a star helps the next person find it** — nothing is gated behind it.
|
|
319
|
+
|
|
320
|
+
- [@BlakrPander](https://github.com/BlakrPander) — PAT-as-username redaction and the delete/modify keep-both analysis (#14); both halves shipped in 0.2.27/0.2.28.
|
|
321
|
+
- [@PerryLink](https://github.com/PerryLink) — creator and maintainer: git mirror engine, append-only keep-both merge, `/sync` command and `sync_*` tools, auto modes, sanitizers, and the five-language docs.
|
|
322
|
+
|
|
323
|
+
<details>
|
|
324
|
+
<summary>Expand all plugins</summary>
|
|
325
|
+
|
|
326
|
+
| Plugin | Status |
|
|
327
|
+
|---|---|
|
|
328
|
+
| **[dsh-aqua-input-check](https://github.com/PerryLink/dsh-aqua-input-check)** | |
|
|
329
|
+
| **[dsh-archive-check](https://github.com/PerryLink/dsh-archive-check)** | |
|
|
330
|
+
| **[dsh-auto-review](https://github.com/PerryLink/dsh-auto-review)** | |
|
|
331
|
+
| **[dsh-autotier](https://github.com/PerryLink/dsh-autotier)** | 🧊 FROZEN — see the repo README |
|
|
332
|
+
| **[dsh-bid-ca-precheck](https://github.com/PerryLink/dsh-bid-ca-precheck)** | |
|
|
333
|
+
| **[dsh-bid-qual-check](https://github.com/PerryLink/dsh-bid-qual-check)** | |
|
|
334
|
+
| **[dsh-cert-mcp](https://github.com/PerryLink/dsh-cert-mcp)** | 🧊 FROZEN — see the repo README |
|
|
335
|
+
| **[dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind)** | |
|
|
336
|
+
| **[dsh-click](https://github.com/PerryLink/dsh-click)** | |
|
|
337
|
+
| **[dsh-composer-history](https://github.com/PerryLink/dsh-composer-history)** | |
|
|
338
|
+
| **[dsh-contract-stance](https://github.com/PerryLink/dsh-contract-stance)** | |
|
|
339
|
+
| **[dsh-customs-doc-check](https://github.com/PerryLink/dsh-customs-doc-check)** | |
|
|
340
|
+
| **[dsh-data-quality](https://github.com/PerryLink/dsh-data-quality)** | 🧊 FROZEN — see the repo README |
|
|
341
|
+
| **[dsh-demurrage-ledger](https://github.com/PerryLink/dsh-demurrage-ledger)** | |
|
|
342
|
+
| **[dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck)** | |
|
|
343
|
+
| **[dsh-drill-script-check](https://github.com/PerryLink/dsh-drill-script-check)** | |
|
|
344
|
+
| **[dsh-eia-guide-check](https://github.com/PerryLink/dsh-eia-guide-check)** | |
|
|
345
|
+
| **[dsh-emergency-plan](https://github.com/PerryLink/dsh-emergency-plan)** | |
|
|
346
|
+
| **[dsh-essay-rubric-check](https://github.com/PerryLink/dsh-essay-rubric-check)** | |
|
|
347
|
+
| **[dsh-evidence-check](https://github.com/PerryLink/dsh-evidence-check)** | |
|
|
348
|
+
| **[dsh-export-ctl-check](https://github.com/PerryLink/dsh-export-ctl-check)** | |
|
|
349
|
+
| **[dsh-fast](https://github.com/PerryLink/dsh-fast)** | |
|
|
350
|
+
| **[dsh-fmea-table-check](https://github.com/PerryLink/dsh-fmea-table-check)** | |
|
|
351
|
+
| **[dsh-forecast-penalty](https://github.com/PerryLink/dsh-forecast-penalty)** | |
|
|
352
|
+
| **[dsh-fund-research](https://github.com/PerryLink/dsh-fund-research)** | |
|
|
353
|
+
| **[dsh-github](https://github.com/PerryLink/dsh-github)** | |
|
|
354
|
+
| **[dsh-gongwen-flow-check](https://github.com/PerryLink/dsh-gongwen-flow-check)** | |
|
|
355
|
+
| **[dsh-gongwen-word-check](https://github.com/PerryLink/dsh-gongwen-word-check)** | |
|
|
356
|
+
| **[dsh-guard-plan-qc](https://github.com/PerryLink/dsh-guard-plan-qc)** | |
|
|
357
|
+
| **[dsh-hazchem-check](https://github.com/PerryLink/dsh-hazchem-check)** | |
|
|
358
|
+
| **[dsh-hazplan-check](https://github.com/PerryLink/dsh-hazplan-check)** | |
|
|
359
|
+
| **[dsh-hidden-risk-map](https://github.com/PerryLink/dsh-hidden-risk-map)** | |
|
|
360
|
+
| **[dsh-hs-classify](https://github.com/PerryLink/dsh-hs-classify)** | |
|
|
361
|
+
| **[dsh-icd-rule-check](https://github.com/PerryLink/dsh-icd-rule-check)** | |
|
|
362
|
+
| **[dsh-industry-research](https://github.com/PerryLink/dsh-industry-research)** | |
|
|
363
|
+
| **[dsh-lawcite-adapter](https://github.com/PerryLink/dsh-lawcite-adapter)** | |
|
|
364
|
+
| **[dsh-laya](https://github.com/PerryLink/dsh-laya)** | |
|
|
365
|
+
| **[dsh-lc-doc-check](https://github.com/PerryLink/dsh-lc-doc-check)** | |
|
|
366
|
+
| **[dsh-learning-gap-check](https://github.com/PerryLink/dsh-learning-gap-check)** | |
|
|
367
|
+
| **[dsh-library](https://github.com/PerryLink/dsh-library)** | |
|
|
368
|
+
| **[dsh-local-ai](https://github.com/PerryLink/dsh-local-ai)** | |
|
|
369
|
+
| **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | |
|
|
370
|
+
| **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | |
|
|
371
|
+
| **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | |
|
|
372
|
+
| **[dsh-medrec-qc](https://github.com/PerryLink/dsh-medrec-qc)** | |
|
|
373
|
+
| **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | 🧊 FROZEN — see the repo README |
|
|
374
|
+
| **[dsh-nsfc-form-check](https://github.com/PerryLink/dsh-nsfc-form-check)** | |
|
|
375
|
+
| **[dsh-nurse-record-check](https://github.com/PerryLink/dsh-nurse-record-check)** | |
|
|
376
|
+
| **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | |
|
|
377
|
+
| **[dsh-origin-rvc-check](https://github.com/PerryLink/dsh-origin-rvc-check)** | |
|
|
378
|
+
| **[dsh-ota-review-check](https://github.com/PerryLink/dsh-ota-review-check)** | |
|
|
379
|
+
| **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | |
|
|
380
|
+
| **[dsh-paper-doc-adapter](https://github.com/PerryLink/dsh-paper-doc-adapter)** | |
|
|
381
|
+
| **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | |
|
|
382
|
+
| **[dsh-permit-report-check](https://github.com/PerryLink/dsh-permit-report-check)** | |
|
|
383
|
+
| **[dsh-pipeline-check](https://github.com/PerryLink/dsh-pipeline-check)** | |
|
|
384
|
+
| **[dsh-pleading-draft](https://github.com/PerryLink/dsh-pleading-draft)** | |
|
|
385
|
+
| **[dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor)** | 🚫 RETIRED (repo archived) |
|
|
386
|
+
| **[dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide)** | |
|
|
387
|
+
| **[dsh-plugin-kit](https://github.com/PerryLink/dsh-plugin-kit)** | 🚫 RETIRED (repo archived) |
|
|
388
|
+
| **[dsh-plugin-upgrade](https://github.com/PerryLink/dsh-plugin-upgrade)** | 🚫 RETIRED (repo archived) |
|
|
389
|
+
| **[dsh-policy-brief-draft](https://github.com/PerryLink/dsh-policy-brief-draft)** | |
|
|
390
|
+
| **[dsh-power-loss-split](https://github.com/PerryLink/dsh-power-loss-split)** | |
|
|
391
|
+
| **[dsh-power-ticket-check](https://github.com/PerryLink/dsh-power-ticket-check)** | |
|
|
392
|
+
| **[dsh-ppap-check](https://github.com/PerryLink/dsh-ppap-check)** | |
|
|
393
|
+
| **[dsh-protest-deadline](https://github.com/PerryLink/dsh-protest-deadline)** | |
|
|
394
|
+
| **[dsh-railway-window](https://github.com/PerryLink/dsh-railway-window)** | |
|
|
395
|
+
| **[dsh-repair-order-qc](https://github.com/PerryLink/dsh-repair-order-qc)** | |
|
|
396
|
+
| **[dsh-research-report](https://github.com/PerryLink/dsh-research-report)** | |
|
|
397
|
+
| **[dsh-review-reply-check](https://github.com/PerryLink/dsh-review-reply-check)** | |
|
|
398
|
+
| **[dsh-rulefile-check](https://github.com/PerryLink/dsh-rulefile-check)** | |
|
|
399
|
+
| **[dsh-safety-brief-check](https://github.com/PerryLink/dsh-safety-brief-check)** | |
|
|
400
|
+
| **[dsh-score](https://github.com/PerryLink/dsh-score)** | 🧊 FROZEN — see the repo README |
|
|
401
|
+
| **[dsh-session-sync](https://github.com/PerryLink/dsh-session-sync)** | |
|
|
402
|
+
| **[dsh-site-log-check](https://github.com/PerryLink/dsh-site-log-check)** | |
|
|
403
|
+
| **[dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security)** | |
|
|
404
|
+
| **[dsh-soe-decision-check](https://github.com/PerryLink/dsh-soe-decision-check)** | |
|
|
405
|
+
| **[dsh-soilwater-check](https://github.com/PerryLink/dsh-soilwater-check)** | |
|
|
406
|
+
| **[dsh-sop-sync-check](https://github.com/PerryLink/dsh-sop-sync-check)** | |
|
|
407
|
+
| **[dsh-spc-gbt-adapter](https://github.com/PerryLink/dsh-spc-gbt-adapter)** | |
|
|
408
|
+
| **[dsh-talk](https://github.com/PerryLink/dsh-talk)** | |
|
|
409
|
+
| **[dsh-tender-extract](https://github.com/PerryLink/dsh-tender-extract)** | |
|
|
410
|
+
| **[dsh-tender-matrix](https://github.com/PerryLink/dsh-tender-matrix)** | |
|
|
411
|
+
| **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** | |
|
|
412
|
+
| **[dsh-ticktick](https://github.com/PerryLink/dsh-ticktick)** | 🚫 RETIRED (repo archived) |
|
|
413
|
+
| **[dsh-translate](https://github.com/PerryLink/dsh-translate)** | |
|
|
414
|
+
| **[dsh-warranty-calc](https://github.com/PerryLink/dsh-warranty-calc)** | |
|
|
415
|
+
| **[dsh-budget](https://github.com/PerryLink/dsh-budget)** | 🧊 FROZEN — see the repo README |
|
|
416
|
+
| **[dsh-claude-move](https://github.com/PerryLink/dsh-claude-move)** | 🧊 FROZEN — see the repo README |
|
|
417
|
+
| **[dsh-defend](https://github.com/PerryLink/dsh-defend)** | 🧊 FROZEN — see the repo README |
|
|
418
|
+
| **[dsh-draw](https://github.com/PerryLink/dsh-draw)** | 🧊 FROZEN — see the repo README |
|
|
419
|
+
| **[dsh-reach](https://github.com/PerryLink/dsh-reach)** | 🧊 FROZEN — see the repo README |
|
|
420
|
+
| **[dsh-background-agents](https://github.com/PerryLink/dsh-background-agents)** | 🚫 RETIRED (repo archived) |
|
|
421
|
+
| **[dsh-session-pin](https://github.com/PerryLink/dsh-session-pin)** | 🚫 RETIRED (repo archived) |
|
|
422
|
+
| **[dsh-team-rooms](https://github.com/PerryLink/dsh-team-rooms)** | 🚫 RETIRED (repo archived) |
|
|
423
|
+
|
|
424
|
+
</details>
|
|
425
|
+
|
|
426
|
+
## License
|
|
427
|
+
|
|
428
|
+
[LICENSE](LICENSE) (Apache License 2.0) © 2026 dsh-session-sync contributors
|
|
429
|
+
|
|
430
|
+
<p align="center"><sub>Apache-2.0 · Community plugin, not affiliated with DeepSeek.</sub></p>
|