dsh-session-sync 0.2.32 → 0.3.0

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/README.pt.md ADDED
@@ -0,0 +1,455 @@
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: dois dispositivos copiam $DSH_HOME/sessions como bytes opacos para um worktree git e sincronizam com um remoto próprio; o pull faz um merge de três vias por arquivo que mantém os dois lados (a versão remota como arquivo fork) e nunca faz force-push.">
6
+ </picture>
7
+
8
+ # dsh-session-sync
9
+
10
+ **Transforme seu armazenamento de sessões em um repositório git que você controla — sincronize entre dispositivos, mantenha os dois lados em qualquer conflito e nunca perca um turno.**
11
+
12
+ Um plugin de sincronização puramente host-side para DeepSeek Harness: os arquivos de sessão são copiados como bytes opacos, a divergência é resolvida por um merge de três vias append-only e o remoto é seu (git em texto plano por padrão, criptografia age opcional) — sem serviço na nuvem, sem armazenamento de terceiros.
13
+
14
+ [Instalar](#instalação-em-três-passos) · [Configuração](#configuração) · [FAQ](#faq) · [简体中文](README.md) · [English](README.en.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
15
+
16
+ [![License](https://img.shields.io/badge/license-Apache--2.0-3366CC?style=flat-square&labelColor=2B3245)](LICENSE)
17
+ [![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.1.2%20%3C0.3.0-4B67B4?style=flat-square&labelColor=2B3245)](#compatibilidade)
18
+ [![npm](https://img.shields.io/npm/v/dsh-session-sync?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-session-sync)
19
+ [![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-session-sync/ci.yml?branch=main&label=CI&style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-session-sync/actions/workflows/ci.yml)
20
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24.9-339933?style=flat-square&labelColor=2B3245)](#compatibilidade)
21
+
22
+ [![Stars](https://img.shields.io/github/stars/PerryLink/dsh-session-sync?style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-session-sync/stargazers)
23
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-session-sync?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-session-sync)
24
+ [![dshfind](https://dshfind.com/api/badge/PerryLink/dsh-session-sync?metric=downloads)](https://dshfind.com/plugins/PerryLink/dsh-session-sync?ref=badge)
25
+ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-session-sync/badge)](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-session-sync)
26
+ [![DSH Market](https://img.shields.io/badge/DSH_Market-listed-4B67B4?style=flat-square&labelColor=2B3245)](https://dsh.market/)
27
+ [![Gitee](https://img.shields.io/badge/Gitee-mirror-C71D23?style=flat-square&labelColor=2B3245&logo=gitee)](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>Plugin da comunidade, não afiliado à DeepSeek. Este é o único repositório oficial, mantido por PerryLink; repositórios com o mesmo nome em outras contas não são afiliados. O Gitee é um espelho.</sub>
36
+
37
+ ## O que é
38
+
39
+ O `dsh-session-sync` espelha o armazenamento de sessões do DSH (`$DSH_HOME/sessions`) em um worktree git dedicado e o sincroniza com um remoto que **você** controla: sem serviço na nuvem, sem armazenamento de terceiros. Os arquivos de sessão são copiados como bytes opacos — o plugin nunca analisa JSONL/zstd, porque a codificação física pertence ao harness; o trabalho dele é mover esses bytes, mesclar históricos append-only e relatar o estado. Diante de qualquer divergência ele executa um merge de três vias append-only: **os dois lados são mantidos**, a versão remota é preservada como arquivos fork e nada é sobrescrito em silêncio. `backend: git` (o padrão) é um espelho em texto plano; `backend: encrypted` adiciona uma camada age por cima; todos os modos automáticos são configuráveis e reversíveis.
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="Estrutura do dsh-session-sync: o dispositivo A espelha os bytes e confirma $DSH_HOME/sessions, e o push cruza o portão de confirmação até o seu remoto git; o dispositivo B faz fetch, executa um merge de três vias por arquivo (base/ours/theirs) e restaura as sessões localmente, mantendo os bytes remotos divergentes como arquivos fork no caminho original; arquivos fork nunca são apagados nem sobrescritos.">
45
+ </picture>
46
+ </p>
47
+
48
+ ## Instalação em três passos
49
+
50
+ 1. **Instale** (escolha um canal):
51
+
52
+ ```sh
53
+ # canal git (último main; equivalente a git+https://github.com/PerryLink/dsh-session-sync.git)
54
+ dsh plugin --profile web add github:PerryLink/dsh-session-sync
55
+ # canal npm (versões publicadas)
56
+ dsh plugin --profile web add dsh-session-sync
57
+ # canal tarball: pnpm pack neste repo e depois
58
+ dsh plugin --profile web add ./dsh-session-sync-<version>.tgz
59
+ ```
60
+
61
+ Sem etapa de build: `index.mjs` e `lib/` são os artefatos enviados.
62
+
63
+ 2. **Configuração mínima** (aponte para um remoto git **privado** no seu 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. **Verifique que ele monta**:
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
+ **Desinstalar**: `dsh plugin --profile web remove dsh-session-sync` (ou remova a linha do profile patch).
86
+
87
+ ## Capacidades principais
88
+
89
+ O `dsh-session-sync` transforma o armazenamento de sessões em um espelho git versionado no host e entrega a ação de sincronização ao seu remoto:
90
+
91
+ - **Comando `/sync`** — `status` (branch, remoto higienizado, à frente/atrás, arquivos sujos, arquivos fork), `diff`, `log`, `pull`, `push`, `help`.
92
+ - **Ferramentas `sync_status` / `sync_pull` / `sync_push`** — a mesma superfície para o modelo, dentro de um turno.
93
+ - **Resolução de conflitos append-only** — os registros de sessão são append-only; diante de qualquer divergência o plugin mantém **os dois** lados (a versão local é mantida, a remota é preservada como arquivos fork) e nunca sobrescreve em silêncio. Sessões divergentes também podem bifurcar no nível da sessão.
94
+ - **Modos automáticos** — pull ao iniciar, push após cada turno fechado e pull periódico, tudo configurável e reversível.
95
+ - **Escritas com porta de confirmação** — `pull`/`push` perguntam primeiro (via `userQuestions` ou `approval`); superfícies somente leitura nunca perguntam; sem respondedor a operação falha fechada.
96
+
97
+ ```text
98
+ dispositivo A remoto (seu repositório git) dispositivo B
99
+ $DSH_HOME/sessions ──espelho──▶ commit ──push──▶ [sessions] ──pull──▶ merge (manter ambos + fork)
100
+ ```
101
+
102
+ ### Comandos e ferramentas
103
+
104
+ | Superfície | Somente leitura | Requer confirmação | Notas |
105
+ |---|---|---|---|
106
+ | `/sync status` | ✅ | — | Branch, remoto higienizado, à frente/atrás, arquivos sujos, arquivos fork, último pull/push |
107
+ | `/sync diff` | ✅ | — | Alterações não commitadas + estatística `HEAD..remote` (somente leitura) |
108
+ | `/sync log` | ✅ | — | Últimos commits do repositório de sincronização |
109
+ | `/sync pull` | | ✅ | Fetch + merge com semântica de manter ambos; o local é mantido, o remoto é preservado como forks |
110
+ | `/sync push` | | ✅ | Espelho + commit + push; nunca força push, reconcilia e tenta de novo uma vez em caso de rejeição |
111
+ | `sync_status` | ✅ | — | Os mesmos fatos de `/sync status` para o modelo |
112
+ | `sync_pull` | | ✅ | Pull invocável pelo modelo |
113
+ | `sync_push` | | ✅ | Push invocável pelo modelo |
114
+
115
+ ### Exemplos
116
+
117
+ Estes são os pontos de entrada reais do plugin; instale uma vez e chame um deles.
118
+
119
+ **Exemplo detalhado** — comando `/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
+ **Ramo de falha** — entrada `/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
+ **Exemplos curtos**: `/sync diff` · `/sync pull`
141
+
142
+ ## Configuração
143
+
144
+ Todos os ajustes são campos `Config` do Schemastery (alteráveis a partir do cordis.yml). Uma sobreposição direcionada por id substitui a linha inteira — repita todas as chaves necessárias. O `cordis.patch.yml` documenta cada chave em linha.
145
+
146
+ Chaves mais usadas:
147
+
148
+ | Chave | Padrão | Significado |
149
+ |---|---|---|
150
+ | `remote` | `''` | Endereço do remoto (obrigatório antes de pull/push; status/diff funcionam sem ele) |
151
+ | `backend` | `git` | Backend de sincronização: `git` (espelho em texto plano) ou `encrypted` (conteúdo do espelho criptografado com age) |
152
+ | `sessionRoot` | `''` | Raiz do armazenamento de sessões; vazio = `$DSH_HOME/sessions` (faltando ambas, a carga falha) |
153
+ | `repoDir` | `''` | Raiz do worktree de sincronização; vazio = `$DSH_HOME/dsh-session-sync/repo` |
154
+ | `branch` | `main` | Nome do branch remoto |
155
+ | `autoPushOnTurnEnd` | `false` | Push após cada turno fechado |
156
+ | `pullIntervalMinutes` | `0` | Pull periódico a cada N minutos (`0` = desligado, máximo `10080`) |
157
+ | `cwdMap` | `[]` | Projeção de cwd na restauração `[{from, to}]` (o prefixo mais longo vence; cwds multiplataforma sem entrada ficam somente leitura em `<sessionRoot>/--unmapped--`) |
158
+ | `followSessionSymlinks` | `false` | Segue links simbólicos cujo realpath permanece dentro de `sessionRoot` (diagnóstico Android/proot) |
159
+ | `confirmVia` | `auto` | Canal de confirmação: `auto` (userQuestions primeiro, depois approval), `userQuestions`, `approval` |
160
+
161
+ <details>
162
+ <summary>Tabela de configuração completa (23 chaves)</summary>
163
+
164
+ | Chave | Padrão | Significado |
165
+ |---|---|---|
166
+ | `enabled` | `true` | Interruptor mestre; `false` desregistra o comando, as ferramentas, os listeners e os modos automáticos |
167
+ | `backend` | `git` | Backend de sincronização: `git` (espelho em texto plano) ou `encrypted` (conteúdo do espelho criptografado com age) |
168
+ | `sessionRoot` | `''` | Raiz do armazenamento de sessões; vazio = `$DSH_HOME/sessions` (faltando ambas, a carga falha) |
169
+ | `repoDir` | `''` | Raiz do worktree de sincronização; vazio = `$DSH_HOME/dsh-session-sync/repo` |
170
+ | `remote` | `''` | Endereço do remoto (obrigatório antes de pull/push; status/diff funcionam sem ele) |
171
+ | `branch` | `main` | Nome do branch remoto |
172
+ | `gitBin` | `git` | Caminho do executável git |
173
+ | `ageBin` | `age` | Caminho do executável age (sondado com `backend: encrypted`; se faltar, degrada para texto plano) |
174
+ | `ageRecipient` | `''` | Destinatário age (chave pública ou string de identidade); vazio = não consegue criptografar, degrada para texto plano |
175
+ | `ageIdentity` | `''` | Caminho de uma chave secreta age sem frase de senha para descriptografar; vazio = não consegue descriptografar, degrada para texto plano |
176
+ | `autoPullOnStart` | `false` | Pull uma vez ao montar o plugin (a configuração é a autorização; sem reconfirmação) |
177
+ | `autoPushOnTurnEnd` | `false` | Push após cada turno fechado |
178
+ | `pullIntervalMinutes` | `0` | Pull periódico a cada N minutos (`0` = desligado, máximo `10080`) |
179
+ | `cwdMap` | `[]` | Projeção de cwd na restauração `[{from, to}]` (o prefixo mais longo vence; cwds multiplataforma sem entrada ficam somente leitura em `<sessionRoot>/--unmapped--`) |
180
+ | `followSessionSymlinks` | `false` | Segue links simbólicos cujo realpath permanece dentro de `sessionRoot` (diagnóstico Android/proot) |
181
+ | `confirmVia` | `auto` | Canal de confirmação: `auto` (userQuestions primeiro, depois approval), `userQuestions`, `approval` |
182
+ | `graceMs` | `10000` | Período de carência para matar o git (ms) |
183
+ | `commandTimeoutMs` | `120000` | Timeout por comando (ms) |
184
+ | `maxOutputBytes` | `262144` | Teto de saída coletada por fluxo (bytes) |
185
+ | `commitName` | `dsh-session-sync` | Nome do autor do commit |
186
+ | `commitEmail` | `dsh-session-sync@localhost` | E-mail do autor do commit |
187
+ | `registerCommand` | `true` | Registra o comando `/sync` |
188
+ | `registerTools` | `true` | Registra as ferramentas `sync_*` quando o serviço tools está presente |
189
+
190
+ </details>
191
+
192
+ Exemplo de sobreposição no seu profile patch:
193
+
194
+ ```yaml
195
+ - insert:
196
+ - id: session-sync
197
+ name: dsh-session-sync
198
+ config:
199
+ remote: git@github.com:you/your-dsh-sessions.git
200
+ branch: main
201
+ autoPushOnTurnEnd: true
202
+ pullIntervalMinutes: 30
203
+ confirmVia: userQuestions
204
+ ```
205
+
206
+ ## FAQ
207
+
208
+ <details>
209
+ <summary>Onde os dados realmente ficam? Algo é enviado para a nuvem?</summary>
210
+
211
+ Não há serviço na nuvem nem armazenamento de terceiros. Duas cópias ficam na sua máquina: `$DSH_HOME/sessions` (o armazenamento de sessões do harness) e o worktree `repoDir` que você configurar (padrão `$DSH_HOME/dsh-session-sync/repo`); o remoto é **seu próprio** repositório git. `backend: encrypted` só transforma a cópia enviada/remota em texto cifrado age — o espelho local continua em texto plano.
212
+
213
+ </details>
214
+
215
+ <details>
216
+ <summary>Um conflito pode sobrescrever ou perder uma sessão?</summary>
217
+
218
+ Nada é sobrescrito em silêncio. Os registros de sessão são append-only e o merge de três vias mantém os dois lados diante de qualquer divergência: a versão local é mantida e a remota é preservada como arquivo fork chamado `<basename>.remote-fork-<carimbo UTC de 14 dígitos>-<device8>`; arquivos fork nunca são apagados nem sobrescritos, e o git nunca força push, reseta, faz rebase ou troca de branch. Uma sessão divergente também bifurca no nível da sessão, com um aviso persistente injetado na filha.
219
+
220
+ </details>
221
+
222
+ <details>
223
+ <summary>A criptografia vem ativada por padrão? O que acontece se o age faltar?</summary>
224
+
225
+ Não — o padrão é `backend: git`, então os bytes de sessão ficam sem criptografia no seu remoto: use um repositório privado. `backend: encrypted` precisa de `age` e de `ageRecipient`/`ageIdentity` não vazios; se faltar algo, o plugin avisa explicitamente e cai para git em texto plano — nunca finge criptografar. Verifique o aviso em `/sync status` antes de confiar no remoto como criptografado.
226
+
227
+ </details>
228
+
229
+ <details>
230
+ <summary>O que acontece sem git ou sem respondedor de confirmação?</summary>
231
+
232
+ Sem o executável `git` ou o serviço `subprocess`, as operações de sincronização falham com um motivo claro (os perfis continuam iniciando). O `/sync` roda entre turnos, onde o canal `approval` não tem um turno aberto ao qual se anexar: use `confirmVia: userQuestions`, ou conduza a sincronização pelas ferramentas `sync_*` dentro de um turno; sem nenhum respondedor a operação falha fechada.
233
+
234
+ </details>
235
+
236
+ <details>
237
+ <summary>Qual é a sobrecarga? Os modos automáticos rodam para sempre?</summary>
238
+
239
+ Os arquivos de sessão são copiados como bytes opacos e nunca analisados; cada comando git tem timeout, carência de término e teto de saída por fluxo. O push automático vem desligado, o pull periódico vem desligado (`pullIntervalMinutes: 0`) e o pull ao iniciar vem desligado — uma vez ativados, ficam cobertos pela autorização de configuração e não reconfirmam. O custo depende do tamanho do armazenamento de sessões e da latência do remoto; este repositório não tem dados de benchmark, então não damos números inventados.
240
+
241
+ </details>
242
+
243
+ ## Limites de segurança
244
+
245
+ - **Nunca sobrescreve em silêncio.** O merge de três vias append-only mantém os dois lados diante de qualquer divergência, incluindo delete/modify (os bytes modificados são mantidos, a intenção de exclusão é respeitada); arquivos fork nunca são apagados e o git nunca força push, reseta, faz rebase ou troca de branch.
246
+ - **Contenção de caminhos.** Os arquivos são espelhados como bytes opacos com links simbólicos recusados e cada caminho unido é verificado por contenção (`PATH_UNSAFE` falha alto).
247
+ - **Saída higienizada.** Credenciais de URL remota, tokens e segredos `key=value` são redigidos antes de chegar ao modelo ou ao log; a exibição de caminhos recusa tudo fora da sua raiz.
248
+ - **Sem armazenamento de credenciais.** O plugin não armazena credenciais; as credenciais git ficam no seu helper de credenciais normal. As identidades/destinatários age são gerenciados por você, e as chaves nunca entram no repositório de sincronização.
249
+ - **Endurecimento do git.** O git roda com `GIT_TERMINAL_PROMPT=0` e `GIT_OPTIONAL_LOCKS=0`, limitado por prazo e sinal, com teto de saída por fluxo.
250
+ - **Falha fechada.** A falta de respondedor de confirmação, de remoto ou um caminho inseguro recusa a operação alto.
251
+
252
+ ## Permissões e dados
253
+
254
+ - **Permissões**: operações que mudam estado cruzam a porta de confirmação (`confirmVia`); o plugin nunca reimplementa nem contorna os serviços `userQuestions`/`approval` do harness. Os modos automáticos são cobertos pela autorização de configuração e nunca reconfirmam.
255
+ - **Dados**: os metadados de sincronização (id do dispositivo, último pull/push, última cabeça de push, último erro) vivem no domínio de armazenamento `session-sync`. Os arquivos de sessão são copiados como bytes opacos — o plugin nunca os analisa. O id do dispositivo também é gravado em `device.txt` no repositório de sincronização para atribuição de forks entre dispositivos.
256
+ - **Log de sessão**: `sync/push`, `sync/pull` e `sync/conflict` são declarados em `types.d.ts`; só são anexados quando o host registra os tipos (ver Limitações conhecidas). Tudo o que é escrito ou exibido passa por higienização. A única mensagem durável que o plugin escreve — o aviso de fork por conflito — carrega o source kind próprio do plugin (producer-owned, `dsh-session-sync`); o harness aposentou o kind compartilhado `plugin` e o recusa ao reler uma sessão.
257
+
258
+ ## Criptografia e modelo de ameaças
259
+
260
+ `backend: encrypted` adiciona uma camada **age** opcional sobre o espelho: os bytes de sessão são criptografados em arquivos `encrypted/**/*.age` antes de serem commitados e enviados, e descriptografados de volta ao espelho local em texto plano antes da mesclagem. O merge de três vias sempre roda em texto plano localmente, então a semântica append-only de manter ambos não muda.
261
+
262
+ O que a criptografia **protege**:
263
+
264
+ - **O conteúdo do espelho em repouso no remoto.** Os arquivos de sessão que você envia são texto cifrado age; o host remoto, seus operadores e qualquer pessoa que clone o repositório não veem os bytes de sessão em claro sem a chave privada.
265
+
266
+ O que ela **não** protege (a fronteira):
267
+
268
+ - **As chaves e identidades age são suas.** Os arquivos de destinatário/identidade nunca são distribuídos, armazenados ou rotacionados pelo plugin. Se uma chave vazar, o conteúdo do espelho que ela protege fica exposto. Use uma identidade sem frase de senha e mantenha-a fora do repositório.
269
+ - **O remoto continua sendo, na prática, um repositório privado.** Metadados do git — mensagens de commit, o `.gitignore`, a estrutura de caminhos `encrypted/`, nomes de branch e a atividade de push/fetch — continuam visíveis para o host remoto. A criptografia esconde o *conteúdo*, não o fato de você sincronizar, nem a forma da sua árvore de sessões.
270
+ - **O texto plano ainda existe localmente.** O espelho em `<repoDir>/sessions/` é texto plano no disco; a criptografia protege a cópia transmitida/remota, não a criptografia do disco local nem o armazenamento de sessões em uso.
271
+ - **Degradação graciosa significa texto plano.** Com `backend: encrypted`, se o `age` faltar, ou `ageRecipient`/`ageIdentity` estiverem vazios, o plugin cai para o caminho git em texto plano **e avisa explicitamente** no status/log — nunca finge criptografar. Verifique o aviso em `/sync status` antes de confiar no remoto como criptografado.
272
+
273
+ Linha de base: com `backend: git` (o padrão), os bytes de sessão são armazenados sem criptografia no **seu** remoto git — use um repositório privado.
274
+
275
+ ### Sessões multiplataforma e projeção de cwd
276
+
277
+ Uma sessão do Windows sincronizada no Linux (ou o contrário) carrega um `header.cwd` que não é um caminho absoluto nativo no host receptor: o `dsh-workspace` indexa sessões via `realpath(header.cwd)`, e o `session-persistence-jsonl` nem consegue analisar um header cujo cwd não seja absoluto nativo. Mapeie o prefixo de origem para um caminho local:
278
+
279
+ ```yaml
280
+ cwdMap:
281
+ - from: 'C:\Users\me'
282
+ to: /home/me/win
283
+ ```
284
+
285
+ - O prefixo mais longo vence, e os prefixos terminam num limite de segmento (`C:\Users\me2` não corresponde a `C:\Users\me`).
286
+ - A restauração projeta apenas a **cópia local**: o primeiro frame leva o cwd local e cai no diretório de projeto do host, então a sessão aparece na lista de workspaces. O espelho mantém os bytes do dispositivo de origem; um push reanexa o frame de cabeçalho original, então o outro dispositivo continua vendo appends idênticos byte a byte e nunca recebe conflitos sem sentido.
287
+ - Um cwd multiplataforma sem entrada vai para `<sessionRoot>/--unmapped--`: **visível mas somente leitura** (`sync_status` o informa como `cwdUnmapped`, e edições locais nunca são enviadas). Adicione uma entrada `cwdMap` e faça pull de novo para torná-lo uma sessão local continuável.
288
+
289
+ ### Links simbólicos (Android/proot)
290
+
291
+ O espelho **nunca segue links simbólicos** por padrão (limite de segurança). O `link2symlink` do Android/proot informa os arquivos de sessão escritos pelo host como links simbólicos (`readdir` diz link, `readlink` está vazio, os bytes são legíveis), então as sessões do próprio telefone nunca chegam ao espelho. Diagnóstico e seguimento opcional:
292
+
293
+ - `sync_status` informa `skippedSymlinks` / `skippedSymlinkPaths` (contagem e amostras de caminhos) e `followedSymlinks`; o resultado do push leva o mesmo aviso.
294
+ - `followSessionSymlinks: true` (padrão `false`) segue apenas links cujo `realpath` permanece dentro de `sessionRoot`; links que escapam são sempre ignorados e contados.
295
+
296
+ ## Limitações conhecidas
297
+
298
+ - **A criptografia é opcional e o age é uma dependência externa.** `backend: encrypted` adiciona uma camada age (ver «Criptografia e modelo de ameaças» acima); se o `age` faltar ou `ageRecipient`/`ageIdentity` estiverem vazios, avisa explicitamente e cai para texto plano, e uma identidade protegida por frase de senha não pode ser usada (a descriptografia bloquearia num prompt TTY, então falha fechada). Com `backend: git` (o padrão), os bytes de sessão são armazenados sem criptografia no **seu** remoto git — use um repositório privado.
299
+ - **`object-storage` é uma interface reservada.** É um marcador de posição de interface e falha alto ao carregar; só `git` e `encrypted` estão implementados.
300
+ - **Requer git.** O plugin precisa do executável `git` e do serviço `subprocess`; sem eles, as operações de sincronização falham com um motivo claro (os perfis continuam iniciando).
301
+ - **Um `repoDir` por backend.** Trocar entre `git` e `encrypted` no mesmo `repoDir` não é suportado; use um worktree novo por backend.
302
+ - **Eventos de sessão em `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`.** O harness não registra os tipos `sync/*`, então os anexos ao log de sessão são pulados (as sessões continuam carregando); o plugin os habilita automaticamente quando um host registra os tipos ou expõe o envelope `ignorable` em `Session.append`.
303
+ - **`approval` entre turnos.** O `/sync` roda entre turnos, onde o canal `approval` não tem um turno aberto ao qual se anexar; use `confirmVia: userQuestions` para sincronização por comando, ou conduza a sincronização pelas ferramentas dentro de um turno. A verificação de turno aberto lê a projeção de sessão `turnBoundary` do host: uma composição sem `@deepseek-ai/dsh-session-projection` não consegue verificar o estado do turno e falha fechada com esse motivo.
304
+ - **Artefatos privados do host não são sincronizados.** `session.lock` (o lease de sessão do harness) e os arquivos de staging `session.migration.*.tmp` nunca são espelhados nem apagados: são estado de execução, não conteúdo sincronizável. Os logs de sessão (`session.jsonl`, `session.v[1-9]*.jsonl[.zstd]`) continuam sendo a carga útil espelhada.
305
+
306
+ ## Compatibilidade
307
+
308
+ | Superfície | Estado |
309
+ |---|---|
310
+ | Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (tag do GitHub, verificado em 2026-09-25: cadeia completa de portas contra os peers fixados `0.1.7-rc.2`). Linha de dependência npm `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`. (adaptado em 2026-10-04): o aviso de fork por conflito carrega o source kind próprio do plugin (producer-owned) — o harness aposentou o kind compartilhado `plugin` e o recusa ao reler. |
311
+ | Node | `^22.19.0 \|\| >=24.9.0` |
312
+ | Plataformas | Onde quer que `git` e DSH rodem (espelho baseado em git; sem código específico de plataforma) |
313
+ | Modelo | Modelos apenas de texto totalmente suportados; nenhuma visão ou capacidade extra de modelo é necessária |
314
+
315
+ ## Ecossistema e qualidade
316
+
317
+ - [Espelho no Gitee](https://gitee.com/perrylink/dsh-session-sync) (espelho sincronizado; o GitHub é canônico)
318
+ - [Página do dshfind](https://dshfind.com/plugins/PerryLink/dsh-session-sync) (instalações e ranking)
319
+ - [Relatório do OpenSSF Scorecard](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-session-sync) (movido por [.github/workflows/scorecard.yml](.github/workflows/scorecard.yml))
320
+ - [Relatório de verificação do dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章) (selo histórico de verificação K10–K13)
321
+ - [DSH Market](https://dsh.market/) (listado)
322
+ - **Canal da loja 1024**: rode `npm i -g dsh1024` uma vez e depois `dsh1024 plugin --profile web add dsh-session-sync` (conta para o ranking de instalações do [deepseek1024.com](https://deepseek1024.com))
323
+ - [Base de conhecimento do ecossistema](https://perrylink.github.io/dsh-plugin-guide/): guia de desenvolvimento de plugins · dados medidos de seleção · critérios de manutenção
324
+
325
+ ## Desenvolvimento
326
+
327
+ ```sh
328
+ pnpm install # node ^22.19 || >=24.9
329
+ pnpm run typecheck && pnpm run typecheck:ci # tsc --checkJs: face do checkout + face da linha publicada
330
+ pnpm test # node --test (14 arquivos de teste; a suíte git do motor é pulada sem git)
331
+ pnpm run verify:self-contained # as specs de dependências resolvem a partir do registry
332
+ pnpm run verify:artifacts # arquivos enviados presentes + index.mjs importável
333
+ pnpm run check:readmes # consistência dos README em cinco idiomas
334
+ pnpm pack # o tarball publicado
335
+ ```
336
+
337
+ Sem etapa de build: ESM puro, `index.mjs` e `lib/` são os artefatos enviados. As imagens do README são geradas programaticamente por [`scripts/gen-readme-assets.py`](scripts/gen-readme-assets.py) (Python + Pillow) e podem ser reexecutadas com segurança.
338
+
339
+ Topics: `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `session-sync`, `session`, `git`, `sync`, `cross-device`
340
+
341
+ ## Família e agradecimentos
342
+
343
+ Este projeto faz parte da família de plugins de DeepSeek Harness da [PerryLink](https://github.com/PerryLink) (todos Apache-2.0). Se ele for útil, **uma estrela ajuda a próxima pessoa a encontrá-lo** — nada fica bloqueado atrás dela.
344
+
345
+ - [@BlakrPander](https://github.com/BlakrPander) — redação de PAT-como-usuário e a análise delete/modify de manter ambos (#14); as duas partes saíram em 0.2.27/0.2.28.
346
+ - [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: motor de espelho git, merge append-only de manter ambos, comando `/sync` e ferramentas `sync_*`, modos automáticos, higienizadores e a documentação em cinco idiomas.
347
+
348
+ <details>
349
+ <summary>Expandir todos os plugins</summary>
350
+
351
+ | Plugin | Estado |
352
+ |---|---|
353
+ | **[dsh-aqua-input-check](https://github.com/PerryLink/dsh-aqua-input-check)** | |
354
+ | **[dsh-archive-check](https://github.com/PerryLink/dsh-archive-check)** | |
355
+ | **[dsh-auto-review](https://github.com/PerryLink/dsh-auto-review)** | |
356
+ | **[dsh-autotier](https://github.com/PerryLink/dsh-autotier)** | 🧊 CONGELADO — ver o README do repo |
357
+ | **[dsh-bid-ca-precheck](https://github.com/PerryLink/dsh-bid-ca-precheck)** | |
358
+ | **[dsh-bid-qual-check](https://github.com/PerryLink/dsh-bid-qual-check)** | |
359
+ | **[dsh-cert-mcp](https://github.com/PerryLink/dsh-cert-mcp)** | 🧊 CONGELADO — ver o README do repo |
360
+ | **[dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind)** | |
361
+ | **[dsh-click](https://github.com/PerryLink/dsh-click)** | |
362
+ | **[dsh-composer-history](https://github.com/PerryLink/dsh-composer-history)** | |
363
+ | **[dsh-contract-stance](https://github.com/PerryLink/dsh-contract-stance)** | |
364
+ | **[dsh-customs-doc-check](https://github.com/PerryLink/dsh-customs-doc-check)** | |
365
+ | **[dsh-data-quality](https://github.com/PerryLink/dsh-data-quality)** | 🧊 CONGELADO — ver o README do repo |
366
+ | **[dsh-demurrage-ledger](https://github.com/PerryLink/dsh-demurrage-ledger)** | |
367
+ | **[dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck)** | |
368
+ | **[dsh-drill-script-check](https://github.com/PerryLink/dsh-drill-script-check)** | |
369
+ | **[dsh-eia-guide-check](https://github.com/PerryLink/dsh-eia-guide-check)** | |
370
+ | **[dsh-emergency-plan](https://github.com/PerryLink/dsh-emergency-plan)** | |
371
+ | **[dsh-essay-rubric-check](https://github.com/PerryLink/dsh-essay-rubric-check)** | |
372
+ | **[dsh-evidence-check](https://github.com/PerryLink/dsh-evidence-check)** | |
373
+ | **[dsh-export-ctl-check](https://github.com/PerryLink/dsh-export-ctl-check)** | |
374
+ | **[dsh-fast](https://github.com/PerryLink/dsh-fast)** | |
375
+ | **[dsh-fmea-table-check](https://github.com/PerryLink/dsh-fmea-table-check)** | |
376
+ | **[dsh-forecast-penalty](https://github.com/PerryLink/dsh-forecast-penalty)** | |
377
+ | **[dsh-fund-research](https://github.com/PerryLink/dsh-fund-research)** | |
378
+ | **[dsh-github](https://github.com/PerryLink/dsh-github)** | |
379
+ | **[dsh-gongwen-flow-check](https://github.com/PerryLink/dsh-gongwen-flow-check)** | |
380
+ | **[dsh-gongwen-word-check](https://github.com/PerryLink/dsh-gongwen-word-check)** | |
381
+ | **[dsh-guard-plan-qc](https://github.com/PerryLink/dsh-guard-plan-qc)** | |
382
+ | **[dsh-hazchem-check](https://github.com/PerryLink/dsh-hazchem-check)** | |
383
+ | **[dsh-hazplan-check](https://github.com/PerryLink/dsh-hazplan-check)** | |
384
+ | **[dsh-hidden-risk-map](https://github.com/PerryLink/dsh-hidden-risk-map)** | |
385
+ | **[dsh-hs-classify](https://github.com/PerryLink/dsh-hs-classify)** | |
386
+ | **[dsh-icd-rule-check](https://github.com/PerryLink/dsh-icd-rule-check)** | |
387
+ | **[dsh-industry-research](https://github.com/PerryLink/dsh-industry-research)** | |
388
+ | **[dsh-lawcite-adapter](https://github.com/PerryLink/dsh-lawcite-adapter)** | |
389
+ | **[dsh-laya](https://github.com/PerryLink/dsh-laya)** | |
390
+ | **[dsh-lc-doc-check](https://github.com/PerryLink/dsh-lc-doc-check)** | |
391
+ | **[dsh-learning-gap-check](https://github.com/PerryLink/dsh-learning-gap-check)** | |
392
+ | **[dsh-library](https://github.com/PerryLink/dsh-library)** | |
393
+ | **[dsh-local-ai](https://github.com/PerryLink/dsh-local-ai)** | |
394
+ | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | |
395
+ | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | |
396
+ | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | |
397
+ | **[dsh-medrec-qc](https://github.com/PerryLink/dsh-medrec-qc)** | |
398
+ | **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | 🧊 CONGELADO — ver o README do repo |
399
+ | **[dsh-nsfc-form-check](https://github.com/PerryLink/dsh-nsfc-form-check)** | |
400
+ | **[dsh-nurse-record-check](https://github.com/PerryLink/dsh-nurse-record-check)** | |
401
+ | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | |
402
+ | **[dsh-origin-rvc-check](https://github.com/PerryLink/dsh-origin-rvc-check)** | |
403
+ | **[dsh-ota-review-check](https://github.com/PerryLink/dsh-ota-review-check)** | |
404
+ | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | |
405
+ | **[dsh-paper-doc-adapter](https://github.com/PerryLink/dsh-paper-doc-adapter)** | |
406
+ | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | |
407
+ | **[dsh-permit-report-check](https://github.com/PerryLink/dsh-permit-report-check)** | |
408
+ | **[dsh-pipeline-check](https://github.com/PerryLink/dsh-pipeline-check)** | |
409
+ | **[dsh-pleading-draft](https://github.com/PerryLink/dsh-pleading-draft)** | |
410
+ | **[dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor)** | 🚫 APOSENTADO (repo arquivado) |
411
+ | **[dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide)** | |
412
+ | **[dsh-plugin-kit](https://github.com/PerryLink/dsh-plugin-kit)** | 🚫 APOSENTADO (repo arquivado) |
413
+ | **[dsh-plugin-upgrade](https://github.com/PerryLink/dsh-plugin-upgrade)** | 🚫 APOSENTADO (repo arquivado) |
414
+ | **[dsh-policy-brief-draft](https://github.com/PerryLink/dsh-policy-brief-draft)** | |
415
+ | **[dsh-power-loss-split](https://github.com/PerryLink/dsh-power-loss-split)** | |
416
+ | **[dsh-power-ticket-check](https://github.com/PerryLink/dsh-power-ticket-check)** | |
417
+ | **[dsh-ppap-check](https://github.com/PerryLink/dsh-ppap-check)** | |
418
+ | **[dsh-protest-deadline](https://github.com/PerryLink/dsh-protest-deadline)** | |
419
+ | **[dsh-railway-window](https://github.com/PerryLink/dsh-railway-window)** | |
420
+ | **[dsh-repair-order-qc](https://github.com/PerryLink/dsh-repair-order-qc)** | |
421
+ | **[dsh-research-report](https://github.com/PerryLink/dsh-research-report)** | |
422
+ | **[dsh-review-reply-check](https://github.com/PerryLink/dsh-review-reply-check)** | |
423
+ | **[dsh-rulefile-check](https://github.com/PerryLink/dsh-rulefile-check)** | |
424
+ | **[dsh-safety-brief-check](https://github.com/PerryLink/dsh-safety-brief-check)** | |
425
+ | **[dsh-score](https://github.com/PerryLink/dsh-score)** | 🧊 CONGELADO — ver o README do repo |
426
+ | **[dsh-session-sync](https://github.com/PerryLink/dsh-session-sync)** | |
427
+ | **[dsh-site-log-check](https://github.com/PerryLink/dsh-site-log-check)** | |
428
+ | **[dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security)** | |
429
+ | **[dsh-soe-decision-check](https://github.com/PerryLink/dsh-soe-decision-check)** | |
430
+ | **[dsh-soilwater-check](https://github.com/PerryLink/dsh-soilwater-check)** | |
431
+ | **[dsh-sop-sync-check](https://github.com/PerryLink/dsh-sop-sync-check)** | |
432
+ | **[dsh-spc-gbt-adapter](https://github.com/PerryLink/dsh-spc-gbt-adapter)** | |
433
+ | **[dsh-talk](https://github.com/PerryLink/dsh-talk)** | |
434
+ | **[dsh-tender-extract](https://github.com/PerryLink/dsh-tender-extract)** | |
435
+ | **[dsh-tender-matrix](https://github.com/PerryLink/dsh-tender-matrix)** | |
436
+ | **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** | |
437
+ | **[dsh-ticktick](https://github.com/PerryLink/dsh-ticktick)** | 🚫 APOSENTADO (repo arquivado) |
438
+ | **[dsh-translate](https://github.com/PerryLink/dsh-translate)** | |
439
+ | **[dsh-warranty-calc](https://github.com/PerryLink/dsh-warranty-calc)** | |
440
+ | **[dsh-budget](https://github.com/PerryLink/dsh-budget)** | 🧊 CONGELADO — ver o README do repo |
441
+ | **[dsh-claude-move](https://github.com/PerryLink/dsh-claude-move)** | 🧊 CONGELADO — ver o README do repo |
442
+ | **[dsh-defend](https://github.com/PerryLink/dsh-defend)** | 🧊 CONGELADO — ver o README do repo |
443
+ | **[dsh-draw](https://github.com/PerryLink/dsh-draw)** | 🧊 CONGELADO — ver o README do repo |
444
+ | **[dsh-reach](https://github.com/PerryLink/dsh-reach)** | 🧊 CONGELADO — ver o README do repo |
445
+ | **[dsh-background-agents](https://github.com/PerryLink/dsh-background-agents)** | 🚫 APOSENTADO (repo arquivado) |
446
+ | **[dsh-session-pin](https://github.com/PerryLink/dsh-session-pin)** | 🚫 APOSENTADO (repo arquivado) |
447
+ | **[dsh-team-rooms](https://github.com/PerryLink/dsh-team-rooms)** | 🚫 APOSENTADO (repo arquivado) |
448
+
449
+ </details>
450
+
451
+ ## Licença
452
+
453
+ [LICENSE](LICENSE) (Apache License 2.0) © 2026 dsh-session-sync contributors
454
+
455
+ <p align="center"><sub>Apache-2.0 · Plugin da comunidade, não afiliado à DeepSeek.</sub></p>
package/cordis.patch.yml CHANGED
@@ -40,6 +40,17 @@
40
40
  # auto (userQuestions first, then approval) · userQuestions · approval.
41
41
  # Read-only surfaces (status/diff/log) never ask.
42
42
  confirmVia: auto
43
+ # Restore-time cwd projection (cross-OS sessions). Each entry maps an
44
+ # origin-device prefix to a local path; longest matching prefix wins and
45
+ # prefixes end on a path-segment boundary (C:\Users\me2 does not match
46
+ # C:\Users\me). The mirror keeps the origin device's bytes; only the
47
+ # restored local copy carries the local cwd. Cross-platform cwds with no
48
+ # entry are shown read-only under <sessionRoot>/--unmapped--.
49
+ cwdMap: []
50
+ # Mirror symbolic links whose realpath stays inside sessionRoot
51
+ # (Android/proot link2symlink hosts). Default false keeps "never follow
52
+ # symlinks"; skipped links are counted and listed in sync_status.
53
+ followSessionSymlinks: false
43
54
  # Subprocess tuning: grace period for git kills, per-command timeout,
44
55
  # and the per-stream collected-output cap.
45
56
  graceMs: 10000