dsh-manage-session 0.3.3 → 0.5.1

package/README.es.md

@@ -0,0 +1,120 @@
+# dsh-manage-session (Session Steward)
+
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Français README](./README.fr.md)
+- [Deutsch README](./README.de.md)
+- [Italiano README](./README.it.md)
+- [Русский README](./README.ru.md)
+- [Español README](./README.es.md)
+
+Plugin web de DSH para **archivos de historial de sesiones + controles de salud de sesiones**.
+
+> **Esta versión (0.5.0) toma la línea DSH 0.2.0 como línea principal** (peer/engines = `>=0.2.0-rc.1 <0.2.1-0`, dist-tag npm `dsh-0.2.0`, rama `compat/0.2.0`).
+> La línea DSH 0.1.7 sigue siendo atendida por 0.4.8 (dist-tag `dsh-0.1.7`, rama `compat/0.1.7`) y ya no evoluciona junto con esta línea.
+> Las superficies del host que consume este plugin (formato de sesión V4 y las listas de productores first-party de `dsh-session-format-v3-to-v4`, las exportaciones de decodificación de `dsh-session`, el contrato del directorio de archivos `session.jsonl.zstd`/`session.v3.jsonl.zstd` en doble ejemplar + `storages/session_projcache` + las dos listas de id de `workspace.json`) fueron verificadas punto por punto: en 0.2.0-rc.1 están **sin cambios, cero modificaciones de código**; esta versión es una adaptación de puros metadatos (cambio de generación de peer/engines, devDependencies fijadas con exactitud en `0.2.0-rc.1`, disciplina de publicación actualizada junto con la versión).
+
+- **Residencia (archivos de historial)**: explorar el conjunto oficial de archivos, con dos operaciones **independientes** —
+  **quitar el estado de archivado** (solo modifica el arreglo, reversible) y **purgar los archivos de archivado** (borra de verdad las entidades en disco, irreversible).
+
+> **Las dos operaciones no son intercambiables y no pueden fusionarse**:
+>
+> | | Quitar el estado de archivado | Purgar los archivos de archivado |
+> |---|---|---|
+> | Ruta | `session-history-prune` | `session-history-purge` |
+> | Qué se modifica | solo `global.archivedSessionIds` | borra las entidades en disco + modifica el arreglo de archivado + modifica la tabla de miembros de los espacios de trabajo |
+> | Destino de la sesión | vuelve al espacio de trabajo original de la barra lateral | desaparece del mundo |
+> | Reversible | ✅ | ❌ |
+>
+> **La purga conlleva necesariamente quitar el estado de archivado** — de lo contrario quedarían id zombis «invisibles en la barra lateral que, en cuanto se les quita el archivado, se convierten en una sesión vacía».
+> El tamaño se muestra **por línea** (comprobado en la práctica: una sola entrada puede ir de 0 a 23 MB), y el botón muestra el subtotal de la selección.
+>
+> **Dos restricciones estrictas** (cúmplalas, o la operación habrá sido en vano):
+> 1. **La lista y la escritura tienen la misma fuente** — ambas reconocen el archivo de almacenamiento `~/.dsh/storages/workspace.json`. El `workspaceRegistry` en memoria del host es una instantánea tomada al arrancar: escribir en el archivo no lo actualiza; solo sirve como superficie de diagnóstico para «ya salió del archivo, sigue vigente en este proceso» (`pendingRestart`).
+> 2. **Reinicie DSH inmediatamente después de la operación** — la capa de almacenamiento reescribe todo el documento y da prioridad a la memoria: antes de que el host termine, **cualquier** cambio de archivado o de espacio de trabajo reescribe el estado antiguo por completo, anulando la operación recién hecha.
+- **Chequeo (control de salud / médico de sesiones)**: chequeo de cuatro puertas → receta (lista de comandos) → alta (intervención reversible + comparación antes/después).
+
+> Frontera de nombres: **este paquete no ofrece búsqueda ni indexación**. La búsqueda/la indexación independiente pertenecen a otro territorio (`dsh-search-index`); ninguna de las dos partes usa los términos de subdominio de la otra, ni interpreta los campos de la otra.
+
+## Vista previa de la interfaz
+
+Una entrada **«Session Steward»** aparece al final de la barra lateral, junto a Búsqueda y Ajustes:
+
+![Entrada de la barra lateral](assets/left-sidebar.png)
+
+**Residencia (archivos de historial)** — panorama del conjunto oficial de archivos; cada línea muestra su tamaño y el estado de la entidad en disco; marque líneas para quitar el archivado o purgar:
+
+![Residencia (estado todo recogido)](assets/archive.png)
+
+**Chequeo** — el punto de entrada del chequeo de cuatro puertas, que termina en una receta reversible:
+
+![Chequeo](assets/doctor.png)
+
+## Instalación
+
+```bash
+dsh plugin --profile web add dsh-manage-session
+# o un directorio de desarrollo local
+dsh plugin --profile web add "link:E:/test/rewrite-agently/mine-dsh-plugins/dsh-manage-session"
+```
+
+Después de instalar, **hay que reiniciar el proceso anfitrión** (refrescar la página no basta).
+
+## Contrato de rutas
+
+Prefijo `/session-steward/api`, nombres de método siempre `session-*` (**nunca** mezclarlos con los `index-*` del índice de búsqueda);
+un método no reconocido devuelve un error explícito, nunca un silencio.
+
+| Método | Subdominio | Función |
+|---|---|---|
+| `session-history-list` | history | listar el conjunto de archivos (prioridad del archivo de almacenamiento; con fuente, degradación, tamaño por línea y anotación `pendingRestart`) |
+| `session-history-prune` | history | **quitar el estado de archivado**: retirar id del arreglo de archivado en lote (copia de seguridad automática, se requiere reinicio) |
+| `session-history-purge` | history | **purgar los archivos de archivado**: borrar de verdad el directorio de transcripciones + la caché de proyección + las dos listas de id (**irreversible**) |
+| `session-health-status` | health | estado de los interruptores y tabla de métodos (para el sondeo del panel) |
+| `session-health-scan` | health | chequeo por lotes (por defecto devuelve solo las sesiones no ok) |
+| `session-health-session` | health | informe de cuatro puertas de una sola sesión + receta |
+| `session-health-repair` | health | intervención reversible (cuarentena del registro de la caché de proyección) + antes/después |
+
+Espacio de nombres de ajustes: `session-steward`; id de la entrada de la barra lateral: `dsh-manage-session`.
+
+## Los dos interruptores (feature gates)
+
+| Interruptor | Campo | Efecto al desactivar |
+|---|---|---|
+| Archivos de historial de sesiones | `historyFiles` (true por defecto) | `session-history-*` no se registra, la pestaña «Residencia» no se renderiza |
+| Control de salud | `healthCheck` (true por defecto) | `session-health-*` no se registra, la pestaña «Chequeo» no se renderiza |
+
+Al desactivarse, el método correspondiente devuelve `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }` — **sin caparazones vacíos**.
+
+## El chequeo de cuatro puertas
+
+| gate | Criterio | level |
+|---|---|---|
+| `log-integrity` | escaneo multitudinario (multi-frame) de zstd → despliegue de la procedencia → desempaquetado de las líneas empaquetadas; seq continuos, sin tramo final desgarrado | `fail` si hay problemas de lectura; `warn` si solo hay un tramo final desgarrado |
+| `projection-cache` | retraso del `minSeq` de `~/.dsh/storages/session_projcache/sessions/<id>.json` respecto al último seq del registro + campos no liquidados (openStep / activeStep.active / pendingTurnStart / turnBoundary=start) | `fail` si hay retraso y no liquidado; `warn` si solo uno de los dos |
+| `lossless-json` | juicio línea a línea del JSON sin pérdidas mediante el `sessionProjections.checkpoint(session)` en caliente (undefined / números no finitos / -0 / huecos dispersos / prototipo no ordinario / funciones·Symbol·BigInt / ciclos) | `fail` al encontrar alguno, con la clave de proyección → paquete responsable |
+| `cold-read` | motivo del último `turn/end`, existencia de un open step sin cerrar, y si tras el último mensaje user hay salida del assistant | `fail` si hay open step; `warn` si interrupted/ausencia de turn/end |
+
+**La receta** solo propone tres cosas reversibles: ① poner en cuarentena el registro dañado de la caché de proyección (primero la copia de seguridad) ② si quedan step sin liquidar, recordar que hay que esperar a que el host los liquide ③ producir una lista de comandos ejecutables.
+**Prohibido**: reescribir los registros de sesión, modificar datos históricos, descartar campos en silencio.
+
+## El único contrato con `dsh-search-index`
+
+Formato del archivo de archivado (`global.archivedSessionIds` de `~/.dsh/storages/workspace.json`):
+**este plugin escribe, el índice de búsqueda solo lee**. Descripción del formato en
+`dsh-docs-deliverables/dsh-归档文件格式契约-20260914.md`.
+
+## Desarrollo
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/client.js
+```
+
+## Licencia
+
+MIT

package/README.fr.md

@@ -0,0 +1,120 @@
+# dsh-manage-session (Session Steward)
+
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Français README](./README.fr.md)
+- [Deutsch README](./README.de.md)
+- [Italiano README](./README.it.md)
+- [Русский README](./README.ru.md)
+- [Español README](./README.es.md)
+
+Plugin web DSH : **fichiers d'historique des sessions + bilan de santé des sessions**.
+
+> **Cette version (0.5.0) prend la ligne DSH 0.2.0 comme ligne principale** (peer/engines = `>=0.2.0-rc.1 <0.2.1-0`, dist-tag npm `dsh-0.2.0`, branche `compat/0.2.0`).
+> La ligne DSH 0.1.7 reste servie par 0.4.8 (dist-tag `dsh-0.1.7`, branche `compat/0.1.7`) et n'évolue plus avec la présente ligne.
+> Les surfaces de l'hôte consommées par ce plugin (format de session V4 et listes de producteurs first-party de `dsh-session-format-v3-to-v4`, exports de décodage de `dsh-session`, contrat du répertoire d'archive `session.jsonl.zstd`/`session.v3.jsonl.zstd` en double exemplaire + `storages/session_projcache` + les deux listes d'id de `workspace.json`) ont été vérifiées point par point comme **inchangées dans 0.2.0-rc.1, zéro modification de code** ; cette version est une adaptation purement métadonnées (rotation des peer/engines, devDependencies épinglées exactement sur `0.2.0-rc.1`, discipline de publication mise à jour avec la version).
+
+- **Maison de retraite (fichiers d'historique)** : parcourir l'ensemble officiel des archives, avec deux opérations **indépendantes** —
+  **retirer le statut d'archivage** (ne modifie que le tableau, réversible) et **purger les fichiers d'archive** (supprime réellement les entités sur disque, irréversible).
+
+> **Les deux opérations ne sont pas interchangeables et ne peuvent pas être fusionnées** :
+>
+> | | Retirer le statut d'archivage | Purger les fichiers d'archive |
+> |---|---|---|
+> | Route | `session-history-prune` | `session-history-purge` |
+> | Ce qui est modifié | uniquement `global.archivedSessionIds` | suppression des entités sur disque + modification du tableau d'archive + modification de la table des membres des espaces de travail |
+> | Devenir de la session | retour dans l'espace de travail d'origine de la barre latérale | disparaît du monde |
+> | Réversible | ✅ | ❌ |
+>
+> **La purge entraîne nécessairement le retrait du statut d'archivage** — sinon subsisteraient des id zombies « invisibles dans la barre latérale et qui, dès qu'on retire leur statut d'archivage, se transforment en session vide ».
+> La taille est affichée **par ligne** (constaté en pratique : une entrée peut aller de 0 à 23 Mo), et le bouton affiche le sous-total de la sélection.
+>
+> **Deux contraintes strictes** (à respecter, sinon l'opération est vaine) :
+> 1. **Liste et écriture ont la même source** — toutes deux se réfèrent au fichier de stockage `~/.dsh/storages/workspace.json`. Le `workspaceRegistry` en mémoire de l'hôte est un instantané pris au démarrage : écrire dans le fichier ne le met pas à jour ; il ne sert que de surface de diagnostic « déjà sorti du fichier, toujours actif en mémoire » (`pendingRestart`).
+> 2. **Redémarrer DSH immédiatement après l'opération** — la couche de stockage réécrit tout le document et donne la priorité à la mémoire : avant l'arrêt de l'hôte, **toute** modification d'archive ou d'espace de travail réécrit l'ancien état en entier, annulant l'opération qui vient d'être faite.
+- **Bilan de santé (contrôle de santé / médecin des sessions)** : bilan à quatre portes → ordonnance (liste de commandes) → sortie (traitement réversible + comparaison avant/après).
+
+> Frontière de nommage : **ce plugin ne fournit ni recherche ni indexation**. La recherche et l'indexation autonome relèvent d'un autre territoire (`dsh-search-index`) ; aucune des deux parties n'emploie les termes de sous-domaine de l'autre et aucune n'interprète les champs de l'autre.
+
+## Aperçu de l'interface
+
+Une entrée **« Session Steward »** apparaît en bas de la barre latérale, aux côtés de Recherche et Paramètres :
+
+![Entrée de la barre latérale](assets/left-sidebar.png)
+
+**Maison de retraite (fichiers d'historique)** — vue d'ensemble de l'ensemble officiel des archives ; chaque ligne indique sa taille et l'état de l'entité sur disque ; cochez des lignes pour retirer le statut d'archivage ou purger :
+
+![Maison de retraite (état tout regroupé)](assets/archive.png)
+
+**Bilan de santé** — le point d'entrée du bilan à quatre portes, qui débouche sur une ordonnance réversible :
+
+![Bilan de santé](assets/doctor.png)
+
+## Installation
+
+```bash
+dsh plugin --profile web add dsh-manage-session
+# ou un répertoire de développement local
+dsh plugin --profile web add "link:E:/test/rewrite-agently/mine-dsh-plugins/dsh-manage-session"
+```
+
+Après l'installation, **il faut redémarrer le processus hôte** (rafraîchir la page ne suffit pas).
+
+## Contrat des routes
+
+Préfixe `/session-steward/api`, noms de méthodes toujours en `session-*` (**jamais** à mélanger avec les `index-*` de l'index de recherche) ;
+une méthode non reconnue renvoie une erreur explicite, jamais un silence.
+
+| Méthode | Sous-domaine | Rôle |
+|---|---|---|
+| `session-history-list` | history | lister l'ensemble des archives (fichier de stockage prioritaire ; avec source, dégradation, taille par ligne et annotation `pendingRestart`) |
+| `session-history-prune` | history | **retirer le statut d'archivage** : retirer des id du tableau d'archives en lot (sauvegarde automatique, redémarrage requis) |
+| `session-history-purge` | history | **purger les fichiers d'archive** : supprimer réellement le répertoire de transcription + le cache de projection + les deux listes d'id (**irréversible**) |
+| `session-health-status` | health | état des interrupteurs et table des méthodes (pour le polling du panneau) |
+| `session-health-scan` | health | bilan en lot (par défaut, ne renvoie que les sessions non ok) |
+| `session-health-session` | health | rapport aux quatre portes d'une seule session + ordonnance |
+| `session-health-repair` | health | traitement réversible (mise en quarantaine de l'enregistrement du cache de projection) + avant/après |
+
+Espace de noms des paramètres : `session-steward` ; id de l'entrée de la barre latérale : `dsh-manage-session`.
+
+## Les deux interrupteurs (feature gates)
+
+| Interrupteur | Champ | Effet à la désactivation |
+|---|---|---|
+| Fichiers d'historique des sessions | `historyFiles` (true par défaut) | `session-history-*` n'est pas enregistré, l'onglet « Maison de retraite » n'est pas rendu |
+| Contrôle de santé | `healthCheck` (true par défaut) | `session-health-*` n'est pas enregistré, l'onglet « Bilan de santé » n'est pas rendu |
+
+Une fois désactivé, la méthode correspondante renvoie `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }` — **aucune coquille vide**.
+
+## Le bilan à quatre portes
+
+| gate | Critère | level |
+|---|---|---|
+| `log-integrity` | balayage multi-trames zstd → déploiement de la provenance → déballage des lignes empaquetées ; seq continues, aucune trame finale déchirée | `fail` en cas de problème de lecture ; `warn` si uniquement une trame finale déchirée |
+| `projection-cache` | retard du `minSeq` de `~/.dsh/storages/session_projcache/sessions/<id>.json` par rapport au dernier seq du journal + champs non soldés (openStep / activeStep.active / pendingTurnStart / turnBoundary=start) | `fail` si retard et non soldé ; `warn` si l'un des deux seulement |
+| `lossless-json` | jugement ligne à ligne du JSON sans perte par le `sessionProjections.checkpoint(session)` à chaud (undefined / nombres non finis / -0 / trous creux / prototype non ordinaire / fonctions·Symbol·BigInt / cycles) | `fail` en cas de correspondance, avec la clé de projection → paquet attribué |
+| `cold-read` | raison du dernier `turn/end`, existence d'un open step non clôturé, présence éventuelle d'une sortie assistant après le dernier message user | `fail` si open step ; `warn` si interrupted/absence de turn/end |
+
+**L'ordonnance** ne propose que trois choses réversibles : ① mettre en quarantaine l'enregistrement endommagé du cache de projection (sauvegarde d'abord) ② s'il reste des steps non soldés, rappeler qu'il faut attendre la soldation par l'hôte ③ produire une liste de commandes exécutables.
+**Interdit** : réécrire les journaux de session, modifier les données historiques, abandonner silencieusement des champs.
+
+## L'unique contrat avec `dsh-search-index`
+
+Format du fichier d'archive (`global.archivedSessionIds` de `~/.dsh/storages/workspace.json`) :
+**ce plugin écrit, l'index de recherche ne fait que lire**. Description du format dans
+`dsh-docs-deliverables/dsh-归档文件格式契约-20260914.md`.
+
+## Développement
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/client.js
+```
+
+## Licence
+
+MIT

package/README.it.md

@@ -0,0 +1,120 @@
+# dsh-manage-session (Session Steward)
+
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Français README](./README.fr.md)
+- [Deutsch README](./README.de.md)
+- [Italiano README](./README.it.md)
+- [Русский README](./README.ru.md)
+- [Español README](./README.es.md)
+
+Plugin web DSH per **file di cronologia delle sessioni + controlli di salute delle sessioni**.
+
+> **Questa versione (0.5.0) adotta la linea DSH 0.2.0 come linea principale** (peer/engines = `>=0.2.0-rc.1 <0.2.1-0`, dist-tag npm `dsh-0.2.0`, ramo `compat/0.2.0`).
+> La linea DSH 0.1.7 resta servita da 0.4.8 (dist-tag `dsh-0.1.7`, ramo `compat/0.1.7`) e non evolve più insieme alla presente linea.
+> Le superfici dell'host consumate da questo plugin (formato sessione V4 e le liste di produttori first-party di `dsh-session-format-v3-to-v4`, le esportazioni di decodifica di `dsh-session`, il contratto della directory di archivio `session.jsonl.zstd`/`session.v3.jsonl.zstd` in doppio esemplare + `storages/session_projcache` + le due liste di id di `workspace.json`) sono state verificate punto per punto come **immutate in 0.2.0-rc.1, zero modifiche al codice**; questa versione è un adattamento di soli metadati (passaggio di generazione di peer/engines, devDependencies fissate esattamente su `0.2.0-rc.1`, disciplina di rilascio aggiornata con la versione).
+
+- **Casa di riposo (file di cronologia)**: sfogliare l'insieme ufficiale degli archivi, con due operazioni **indipendenti** —
+  **rimuovere lo stato di archiviazione** (modifica solo l'array, reversibile) ed **eliminare (purge) i file d'archivio** (cancella davvero le entità su disco, irreversibile).
+
+> **Le due operazioni non sono intercambiabili e non possono essere fuse**:
+>
+> | | Rimuovere lo stato di archiviazione | Eliminare i file d'archivio (purge) |
+> |---|---|---|
+> | Rotta | `session-history-prune` | `session-history-purge` |
+> | Cosa viene modificato | solo `global.archivedSessionIds` | cancella le entità su disco + modifica l'array degli archivi + modifica la tabella dei membri degli spazi di lavoro |
+> | Destinazione della sessione | torna nello spazio di lavoro originale della barra laterale | scompare dal mondo |
+> | Reversibile | ✅ | ❌ |
+>
+> **La purge comporta necessariamente la rimozione dello stato di archiviazione** — altrimenti resterebbero id zombie «invisibili nella barra laterale che, appena si rimuove loro l'archiviazione, diventano una sessione vuota».
+> La dimensione è mostrata **per riga** (riscontrato in pratica: una singola voce può andare da 0 a 23 MB), il pulsante mostra il subtotale della selezione.
+>
+> **Due vincoli rigorosi** (da rispettare, altrimenti l'operazione è vana):
+> 1. **Elenco e scrittura hanno la stessa fonte** — entrambe fanno riferimento al file di archiviazione `~/.dsh/storages/workspace.json`. Il `workspaceRegistry` in memoria dell'host è un'istantanea presa all'avvio: scrivere sul file non lo aggiorna; serve solo come superficie diagnostica per «già tolto dal file, ancora attivo in questo processo» (`pendingRestart`).
+> 2. **Riavviare DSH subito dopo l'operazione** — il livello di archiviazione riscrive tutto e dà priorità alla memoria: prima che l'host termini, **qualsiasi** modifica ad archivi o spazi di lavoro riscrive integralmente il vecchio stato, azzerando l'operazione appena compiuta.
+- **Check-up (controllo di salute / medico delle sessioni)**: check-up a quattro gate → prescrizione (elenco di comandi) → dimissione (intervento reversibile + confronto prima/dopo).
+
+> Confine di denominazione: **questo pacchetto non offre ricerca né indicizzazione**. Ricerca/indicizzazione autonoma appartengono a un altro territorio (`dsh-search-index`); nessuna delle due parti usa i termini di sottodominio dell'altra e nessuna interpreta i campi dell'altra.
+
+## Anteprima dell'interfaccia
+
+Una voce **«Session Steward»** compare in fondo alla barra laterale, accanto a Ricerca e Impostazioni:
+
+![Voce della barra laterale](assets/left-sidebar.png)
+
+**Casa di riposo (file di cronologia)** — panoramica dell'insieme ufficiale degli archivi; ogni riga mostra la propria dimensione e lo stato dell'entità su disco; seleziona le righe per rimuovere l'archiviazione o eliminare (purge):
+
+![Casa di riposo (stato tutto raccordato)](assets/archive.png)
+
+**Check-up** — il punto d'ingresso del check-up a quattro gate, che si conclude con una prescrizione reversibile:
+
+![Check-up](assets/doctor.png)
+
+## Installazione
+
+```bash
+dsh plugin --profile web add dsh-manage-session
+# oppure una directory di sviluppo locale
+dsh plugin --profile web add "link:E:/test/rewrite-agently/mine-dsh-plugins/dsh-manage-session"
+```
+
+Dopo l'installazione **è necessario riavviare il processo host** (ricaricare la pagina non basta).
+
+## Contratto delle rotte
+
+Prefisso `/session-steward/api`, nomi dei metodi sempre `session-*` (**mai** mescolarli con gli `index-*` dell'indice di ricerca);
+un metodo non riconosciuto restituisce un errore esplicito, mai un silenzio.
+
+| Metodo | Sottodominio | Funzione |
+|---|---|---|
+| `session-history-list` | history | elencare l'insieme degli archivi (file di archiviazione prioritario; con fonte, degrado, dimensione per riga e annotazione `pendingRestart`) |
+| `session-history-prune` | history | **rimuovere lo stato di archiviazione**: togliere id dall'array degli archivi in blocco (backup automatico, richiesto riavvio) |
+| `session-history-purge` | history | **eliminare i file d'archivio**: cancellare davvero la directory delle trascrizioni + la cache di proiezione + le due liste di id (**irreversibile**) |
+| `session-health-status` | health | stato degli interruttori e tabella dei metodi (per il polling del pannello) |
+| `session-health-scan` | health | check-up in blocco (per impostazione predefinita restituisce solo le sessioni non ok) |
+| `session-health-session` | health | rapporto a quattro gate di una singola sessione + prescrizione |
+| `session-health-repair` | health | intervento reversibile (messa in quarantena del record della cache di proiezione) + prima/dopo |
+
+Namespace delle impostazioni: `session-steward`; id della voce della barra laterale: `dsh-manage-session`.
+
+## I due interruttori (feature gate)
+
+| Interruttore | Campo | Effetto alla disattivazione |
+|---|---|---|
+| File di cronologia delle sessioni | `historyFiles` (predefinito true) | `session-history-*` non viene registrato, la scheda «Casa di riposo» non viene resa |
+| Controllo di salute | `healthCheck` (predefinito true) | `session-health-*` non viene registrato, la scheda «Check-up» non viene resa |
+
+Una volta disattivato, il metodo corrispondente restituisce `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }` — **nessun guscio vuoto**.
+
+## Il check-up a quattro gate
+
+| gate | Criterio | level |
+|---|---|---|
+| `log-integrity` | scansione multi-frame zstd → dispiegamento della provenance → disimpacchettamento delle righe impacchettate; seq continui, nessun frame finale strappato | `fail` in caso di problemi di lettura; `warn` se solo frame finale strappato |
+| `projection-cache` | ritardo del `minSeq` di `~/.dsh/storages/session_projcache/sessions/<id>.json` rispetto all'ultimo seq del log + campi non saldati (openStep / activeStep.active / pendingTurnStart / turnBoundary=start) | `fail` se ritardo e non saldato; `warn` se uno solo dei due |
+| `lossless-json` | giudizio riga per riga sul JSON senza perdite tramite il `sessionProjections.checkpoint(session)` a caldo (undefined / numeri non finiti / -0 / buchi sparsi / prototipo non ordinario / funzioni·Symbol·BigInt / cicli) | `fail` in caso di riscontro, con chiave di proiezione → pacchetto attribuito |
+| `cold-read` | motivo dell'ultimo `turn/end`, esistenza di un open step non chiuso, eventuale output dell'assistant dopo l'ultimo messaggio user | `fail` se open step; `warn` se interrupted/assenza di turn/end |
+
+**La prescrizione** propone solo tre cose reversibili: ① mettere in quarantena il record danneggiato della cache di proiezione (prima il backup) ② se restano step non saldati, ricordare di attendere la saldazione da parte dell'host ③ produrre un elenco di comandi eseguibili.
+**Vietato**: riscrivere i log di sessione, modificare i dati storici, scartare silenziosamente campi.
+
+## L'unico contratto con `dsh-search-index`
+
+Formato del file d'archivio (`global.archivedSessionIds` di `~/.dsh/storages/workspace.json`):
+**questo plugin scrive, l'indice di ricerca fa solo lettura**. Descrizione del formato in
+`dsh-docs-deliverables/dsh-归档文件格式契约-20260914.md`.
+
+## Sviluppo
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/client.js
+```
+
+## Licenza
+
+MIT

package/README.ja.md

@@ -1,7 +1,19 @@
 # dsh-manage-session（セッション・スチュワード）
 
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Français README](./README.fr.md)
+- [Deutsch README](./README.de.md)
+- [Italiano README](./README.it.md)
+- [Русский README](./README.ru.md)
+- [Español README](./README.es.md)
+
 **セッション履歴ファイル**と**セッション健康チェック**のための DSH Web プラグインです。セッションデータそのものには一切触れません。
 
+> **本版（0.5.0）は DSH 0.2.0 線がメインラインです**（peer/engines `>=0.2.0-rc.1 <0.2.1-0`、npm dist-tag `dsh-0.2.0`、ブランチ `compat/0.2.0`）。DSH 0.1.7 線は 0.4.8（dist-tag `dsh-0.1.7`、ブランチ `compat/0.1.7`）が担当します。本プラグインが消費するホスト面（セッション V4 形式と `dsh-session-format-v3-to-v4` の第一方プロデューサ名簿、`dsh-session` のデコード導出面、アーカイブ配置 `session.jsonl.zstd`/`session.v3.jsonl.zstd` + `storages/session_projcache` + `workspace.json` の 2 つの id 名簿）は 0.2.0-rc.1 で変更ないことを検証済み — **コード変更ゼロ**、メタデータのみの対応です。
+
 - **カルテ室（履歴ファイル）** — 公式アーカイブ集合を閲覧し、ID を一括整理します
   （バックアップ + アトミック置換。ホストに再読み込みさせるには DSH の再起動が必要です）。
 - **健診（健康チェック）** — 四つのゲート → 処方（コマンド一覧）→ 退院（before/after 比較を伴う

package/README.ko.md

@@ -1,7 +1,19 @@
 # dsh-manage-session (세션 스튜어드)
 
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Français README](./README.fr.md)
+- [Deutsch README](./README.de.md)
+- [Italiano README](./README.it.md)
+- [Русский README](./README.ru.md)
+- [Español README](./README.es.md)
+
 **세션 히스토리 파일**과 **세션 상태 점검**을 위한 DSH 웹 플러그인입니다. 세션 데이터 자체는 건드리지 않습니다.
 
+> **이 버전(0.5.0)은 DSH 0.2.0 라인이 메인입니다**(peer/engines `>=0.2.0-rc.1 <0.2.1-0`, npm dist-tag `dsh-0.2.0`, 브랜치 `compat/0.2.0`). DSH 0.1.7 라인은 0.4.8(dist-tag `dsh-0.1.7`, 브랜치 `compat/0.1.7`)이 계속 지원합니다. 이 플러그인이 소비하는 호스트 표면(세션 V4 포맷과 `dsh-session-format-v3-to-v4`의 퍼스트파티 프로듀서 목록, `dsh-session` 디코드 익스포트, 아카이브 레이아웃 `session.jsonl.zstd`/`session.v3.jsonl.zstd` + `storages/session_projcache` + `workspace.json`의 두 id 목록)이 0.2.0-rc.1에서 변하지 않았음을 검증했습니다 — **코드 변경 없음**, 메타데이터만 갱신되었습니다.
+
 - **기록 보관소(히스토리 파일)** — 공식 아카이브 집합을 조회하고 id를 일괄 정리합니다
   (백업 + 원자적 교체, 호스트가 다시 로드하려면 DSH 재시작이 필요합니다).
 - **점검(상태)** — 네 개의 gate → 처방(명령 목록) → 퇴원(전후 비교가 포함된 되돌릴 수 있는 복구).

package/README.md

@@ -1,7 +1,21 @@
 # dsh-manage-session（会话管家 / Session Steward）
 
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Français README](./README.fr.md)
+- [Deutsch README](./README.de.md)
+- [Italiano README](./README.it.md)
+- [Русский README](./README.ru.md)
+- [Español README](./README.es.md)
+
 DSH Web 插件：**会话历史文件 + 会话健康检查**。
 
+> **本版（0.5.0）以 DSH 0.2.0 为主线**（peer/engines = `>=0.2.0-rc.1 <0.2.1-0`，npm dist-tag `dsh-0.2.0`，分支 `compat/0.2.0`）。
+> DSH 0.1.7 线由 0.4.8（dist-tag `dsh-0.1.7`，分支 `compat/0.1.7`）继续服务，不再随本线演进。
+> 0.2.0-rc.1 对本插件消费的宿主面（会话 V4 格式与 `dsh-session-format-v3-to-v4` 第一方名单、`dsh-session` 解码导出面、归档目录契约 `session.jsonl.zstd`/`session.v3.jsonl.zstd` 双份 + `storages/session_projcache` + `workspace.json` 两处 id 名单）逐项对照核验**未变，代码零修改**；本版为纯元数据适配（peer/engines 换代、devDependencies 精确钉 `0.2.0-rc.1`、发布纪律面随版更新）。
+
 - **养老院（会话历史文件）**：浏览官方归档集合，两个**独立**操作 ——
   **取消归档状态**（只改数组，可逆）与 **清理归档文件**（真删磁盘实体，不可逆）。
 

package/README.ru.md

@@ -0,0 +1,120 @@
+# dsh-manage-session (Session Steward)
+
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Français README](./README.fr.md)
+- [Deutsch README](./README.de.md)
+- [Italiano README](./README.it.md)
+- [Русский README](./README.ru.md)
+- [Español README](./README.es.md)
+
+Веб-плагин DSH для **файлов истории сессий + проверки здоровья сессий**.
+
+> **В этой версии (0.5.0) главной линией стала линия DSH 0.2.0** (peer/engines = `>=0.2.0-rc.1 <0.2.1-0`, npm dist-tag `dsh-0.2.0`, ветка `compat/0.2.0`).
+> Линию DSH 0.1.7 продолжает обслуживать 0.4.8 (dist-tag `dsh-0.1.7`, ветка `compat/0.1.7`); вместе с настоящей линией она больше не развивается.
+> Поверхности хоста, которые потребляет этот плагин (формат сессии V4 и списки first-party-продюсеров `dsh-session-format-v3-to-v4`, экспортируемые декодеры `dsh-session`, контракт каталога архивов `session.jsonl.zstd`/`session.v3.jsonl.zstd` в двух экземплярах + `storages/session_projcache` + два списка id в `workspace.json`), проверены по пунктам: в 0.2.0-rc.1 они **не изменились, нулевые правки кода**; этот релиз — адаптация одних лишь метаданных (смена поколения peer/engines, devDependencies точно закреплены на `0.2.0-rc.1`, дисциплина релизов обновлена вместе с версией).
+
+- **Дом престарелых (файлы истории)**: просмотр официального набора архивов, две **независимые** операции —
+  **снять статус архивации** (меняет только массив, обратимо) и **очистить архивные файлы (purge)** (по-настоящему удаляет сущности с диска, необратимо).
+
+> **Эти две операции не взаимозаменяемы, и объединять их нельзя**:
+>
+> | | Снять статус архивации | Очистить архивные файлы (purge) |
+> |---|---|---|
+> | Маршрут | `session-history-prune` | `session-history-purge` |
+> | Что меняется | только `global.archivedSessionIds` | удаление сущностей с диска + изменение массива архивов + изменение таблицы участников рабочих пространств |
+> | Судьба сессии | возвращается в исходное рабочее пространство боковой панели | исчезает из мира |
+> | Обратимо | ✅ | ❌ |
+>
+> **Очистка с необходимостью влечёт снятие статуса архивации** — иначе останутся id-зомби, «невидимые в боковой панели, которые при снятии архивации превращаются в пустую сессию».
+> Размер показывается **построчно** (на практике: одна запись может занимать от 0 до 23 МБ), кнопка показывает подытог по выбранным.
+>
+> **Два жёстких ограничения** (соблюдайте, иначе операция окажется напрасной):
+> 1. **Список и запись исходят из одного и того же места** — оба признают файл хранилища `~/.dsh/storages/workspace.json`. Находящийся в памяти хоста `workspaceRegistry` — снимок на момент запуска: правка файла не записывается обратно в него; он служит лишь диагностической поверхностью для «уже удалено из файла, но в этом процессе ещё действует» (`pendingRestart`).
+> 2. **Сразу после операции перезапустите DSH** — слой хранилища выполняет полную перезапись, и память имеет приоритет: до завершения работы хоста **любое** изменение архивов или рабочих пространств целиком записывает старое состояние обратно, сводя только что выполненную операцию к нулю.
+- **Диспансеризация (проверка здоровья / сессионный врач)**: осмотр по четырём воротам → рецепт (список команд) → выписка (обратимое вмешательство + сравнение до/после).
+
+> Граница именования: **этот пакет не предоставляет поиск и индексацию**. Поиск/отдельная индексация относятся к другому владению (`dsh-search-index`); ни одна из сторон не употребляет поддоменные термины другой и не интерпретирует поля другой.
+
+## Предпросмотр интерфейса
+
+Внизу боковой панели появляется пункт **«Session Steward»**, рядом с Поиском и Настройками:
+
+![Пункт боковой панели](assets/left-sidebar.png)
+
+**Дом престарелых (файлы истории)** — обзор официального набора архивов; каждая строка показывает свой размер и состояние сущности на диске; отметьте строки, чтобы снять архивацию или очистить:
+
+![Дом престарелых (всё сведено воедино)](assets/archive.png)
+
+**Диспансеризация** — вход в осмотр по четырём воротам, завершающийся обратимым рецептом:
+
+![Диспансеризация](assets/doctor.png)
+
+## Установка
+
+```bash
+dsh plugin --profile web add dsh-manage-session
+# или локальный каталог разработки
+dsh plugin --profile web add "link:E:/test/rewrite-agently/mine-dsh-plugins/dsh-manage-session"
+```
+
+После установки **обязательно перезапустите процесс-хост** (обновления страницы недостаточно).
+
+## Контракт маршрутов
+
+Префикс `/session-steward/api`, имена методов всегда `session-*` (**нельзя** смешивать с `index-*` поискового индекса);
+нераспознанный метод возвращает явную ошибку, никогда не молчит.
+
+| Метод | Поддомен | Назначение |
+|---|---|---|
+| `session-history-list` | history | перечислить набор архивов (приоритет у файла хранилища; с указанием источника, деградации, построчного размера и пометки `pendingRestart`) |
+| `session-history-prune` | history | **снять статус архивации**: массово убрать id из массива архивов (автоматическая резервная копия, требуется перезапуск) |
+| `session-history-purge` | history | **очистить архивные файлы**: по-настоящему удалить каталог транскриптов + кэш проекций + оба списка id (**необратимо**) |
+| `session-health-status` | health | состояние переключателей и таблица методов (для опроса панелью) |
+| `session-health-scan` | health | пакетная проверка (по умолчанию возвращает только сессии не-ok) |
+| `session-health-session` | health | отчёт по четырём воротам одной сессии + рецепт |
+| `session-health-repair` | health | обратимое вмешательство (карантин записи кэша проекций) + до/после |
+
+Пространство имён настроек: `session-steward`; id пункта боковой панели: `dsh-manage-session`.
+
+## Два переключателя (feature gate)
+
+| Переключатель | Поле | Эффект выключения |
+|---|---|---|
+| Файлы истории сессий | `historyFiles` (по умолчанию true) | `session-history-*` не регистрируется, вкладка «Дом престарелых» не рендерится |
+| Проверка здоровья | `healthCheck` (по умолчанию true) | `session-health-*` не регистрируется, вкладка «Диспансеризация» не рендерится |
+
+При выключении соответствующий метод возвращает `{ ok: false, error: '子域已关闭（…=false）：<method> 未注册' }` — **пустых оболочек не остаётся**.
+
+## Осмотр по четырём воротам
+
+| gate | Критерий | level |
+|---|---|---|
+| `log-integrity` | мультифреймовое сканирование zstd → разворачивание provenance → распаковка упакованных строк; seq непрерывны, нет разорванных хвостовых фреймов | `fail` при проблемах чтения; `warn`, если только разорванный хвостовой фрейм |
+| `projection-cache` | отставание `minSeq` файла `~/.dsh/storages/session_projcache/sessions/<id>.json` от последнего seq журнала + незакрытые поля (openStep / activeStep.active / pendingTurnStart / turnBoundary=start) | `fail` при отставании и незакрытости; `warn`, если только одно из двух |
+| `lossless-json` | построчная проверка JSON на потерях через горячее состояние `sessionProjections.checkpoint(session)` (undefined / не конечные числа / -0 / разреженные дыры / необычный прототип / функции·Symbol·BigInt / циклы) | `fail` при обнаружении, с ключом проекции → пакетом-владельцем |
+| `cold-read` | причина последнего `turn/end`, наличие незакрытого open step, есть ли вывод assistant после последнего сообщения user | `fail` при open step; `warn` при interrupted/отсутствии turn/end |
+
+**Рецепт** предлагает только три обратимые вещи: ① поместить повреждённую запись кэша проекций в карантин (сначала резервная копия) ② при наличии незакрытых step напомнить дождаться их закрытия хостом ③ выдать список исполняемых команд.
+**Запрещено**: переписывать журналы сессий, менять исторические данные, молча отбрасывать поля.
+
+## Единственный контракт с `dsh-search-index`
+
+Формат файла архива (`global.archivedSessionIds` из `~/.dsh/storages/workspace.json`):
+**этот плагин пишет, поисковый индекс только читает**. Описание формата в
+`dsh-docs-deliverables/dsh-归档文件格式契约-20260914.md`.
+
+## Разработка
+
+```bash
+pnpm install
+pnpm typecheck     # tsc -b --pretty false
+pnpm test          # vitest run
+pnpm build         # tsc -b && tsdown → lib/index.js + lib/client.js
+```
+
+## Лицензия
+
+MIT

package/cordis.patch.yml

@@ -1,11 +1,11 @@
-# dsh-manage-session bundle patch
-#
-# 通过官方 CLI 安装时 ——
-#
-#   dsh plugin --profile <name> add dsh-manage-session
-#
-# —— 命令会把 `dsh-manage-session` 追加到 bundle 栈，profile 启动时合并本补丁
-# （单个 insert，插入本插件行）。
-- insert:
-    - id: dsh-manage-session
-      name: 'dsh-manage-session'
+# dsh-manage-session bundle patch
+#
+# 通过官方 CLI 安装时 ——
+#
+#   dsh plugin --profile <name> add dsh-manage-session
+#
+# —— 命令会把 `dsh-manage-session` 追加到 bundle 栈，profile 启动时合并本补丁
+# （单个 insert，插入本插件行）。
+- insert:
+    - id: dsh-manage-session
+      name: 'dsh-manage-session'

package/dsh.plugin.json

@@ -1,22 +1,22 @@
-{
-  "id": "dsh-manage-session",
-  "name": "dsh-manage-session",
-  "version": "0.3.3",
-  "description": {
-    "en": "Session Steward (DSH 0.1.5 line): browse and bulk-prune the official session archive set, and run a four-gate session health checkup that ends in a reversible, backup-first prescription. Never rewrites session logs.",
-    "zh": "会话管家（DSH 0.1.5 专线）：浏览并批量清理官方会话归档集合，并对会话做四门体检，最终给出可逆、先备份的处方。不改写会话日志。"
-  },
-  "homepage": "https://github.com/drscrewdriver/dsh-manage-session",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/drscrewdriver/dsh-manage-session.git"
-  },
-  "license": "MIT",
-  "engines": {
-    "dsh": ">=0.1.5-rc.1 <0.1.6-0"
-  },
-  "components": {
-    "host": "lib/index.js",
-    "client": "lib/client.js"
-  }
-}
+{
+  "id": "dsh-manage-session",
+  "name": "dsh-manage-session",
+  "version": "0.5.1",
+  "description": {
+    "en": "Session Steward (DSH 0.2.0 line): browse and bulk-prune the official session archive set, and run a four-gate session health checkup that ends in a reversible, backup-first prescription. Never rewrites session logs.",
+    "zh": "会话管家（DSH 0.2.0 专线）：浏览并批量清理官方会话归档集合，并对会话做四门体检，最终给出可逆、先备份的处方。不改写会话日志。"
+  },
+  "homepage": "https://github.com/drscrewdriver/dsh-manage-session",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/drscrewdriver/dsh-manage-session.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "dsh": ">=0.2.0-rc.1 <0.2.1-0"
+  },
+  "components": {
+    "host": "lib/index.js",
+    "client": "lib/client.js"
+  }
+}