@goodandready/dsh-voice 0.9.26 → 0.9.27

package/README.md

@@ -226,16 +226,21 @@ Registers `transcribe_audio(file_path, language?)` in `ctx.tools`, allowing agen
 * `POST /api/dsh-voice/update` — Triggers plugin self-update to latest compatible npm version (protected by local caller verification and profile lock check).
 * `GET /api/dsh-voice/update` — Returns update check status (current version, latest version, updateAvailable).
 
-### 🔒 Profile Lock & Operator Recovery Policy
-When updating or installing plugins, DeepSeek Harness profiles coordinate concurrent operations using `<profile-dir>/package.json.lock`.
+### 🔒 Profile Lock & Controlled Operator Recovery Policy
+When updating or installing plugins, DeepSeek Harness profiles coordinate concurrent operations using `<profile-dir>/package.json.lock` (for example, `~/.dsh/profiles/<profile>/package.json.lock`).
 * **Canonical Contender Policy**: The contender process never deletes or unlinks an existing lockfile. Automatic stale lock removal by contenders is prohibited to eliminate TOCTOU (Time-of-Check to Time-of-Use) race conditions and prevent unintended lockfile clobbering.
 * **Diagnostics**: If `<profile-dir>/package.json.lock` is present, update attempts return `409 Conflict` with clear diagnostics:
   - If held by an active process, the PID is reported.
-  - If filesystem inspection encounters access errors (`EACCES`, `EIO`), the operation fails closed with the error code preserved.
-* **Operator Recovery**: If a prior installation process was forcefully killed or terminated unexpectedly (e.g. system OOM or power outage), manual operator recovery is required:
-  ```bash
-  rm /home/vadim/.dsh/profiles/web/package.json.lock
-  ```
+  - If filesystem inspection encounters access errors (`EACCES`, `EIO`), the operation fails closed with the error code preserved. Filesystem errors require inspecting filesystem health, permissions, or mount options — **do not** remove the lockfile in response to `EACCES`/`EIO`.
+* **Controlled Operator Recovery Workflow**:
+  If a previous installation was forcefully interrupted (e.g. system crash, OOM kill) leaving a stale lockfile, recovery is strictly an operator action and must follow this controlled procedure:
+  1. **Establish Exclusive Maintenance**: Ensure no concurrent processes, CLI commands (`dsh plugin add`), web UI operations, or automated updaters are running or scheduled to start for the target profile.
+  2. **Verify Quiescence and Ownership**: Check for active processes (`pgrep`, `ps`, `fuser`, or `lsof`) to confirm that no live process is currently performing package operations in the target profile directory. Lock age alone or observing an unparsed PID is **not** sufficient justification to delete a lock while another installer could start. If quiescence or non-ownership cannot be verified, do not remove the lock.
+  3. **Remove Confirmed Orphan Lock**: Only after confirming the lock is an orphan and exclusive maintenance is established, remove the specific profile lock without recursive or force flags:
+     ```bash
+     rm ~/.dsh/profiles/<profile>/package.json.lock
+     ```
+  4. **Resume Operations**: Re-enable installations and retry the plugin update.
 
 ---
 

package/README.ru.md

@@ -225,14 +225,21 @@ dsh plugin --profile web add @goodandready/dsh-voice
 * `POST /api/dsh-voice/update` — запуск обновления плагина до актуальной версии из npm (с проверкой прав и блокировки профиля).
 * `GET /api/dsh-voice/update` — проверка наличия обновлений.
 
-### 🔒 Политика блокировок профиля и ручное восстановление оператором
-При установке и обновлении плагинов DeepSeek Harness синхронизирует параллельные процессы через `<profile-dir>/package.json.lock`.
-* **Канонический принцип претендента**: Процесс-претендент никогда не удаляет существующий lock-файл. Автоматическое удаление чужих блокировок исключено для предотвращения TOCTOU-гонок.
-* **Диагностика**: При наличии lock-файла запрос на обновление возвращает `409 Conflict` с подробной информацией (PID процесса либо код ошибки доступа к файловой системе `EACCES`/`EIO`).
-* **Восстановление оператором**: Если предыдущий процесс установки аварийно завершился (например, OOM или отключение питания) и оставил зависший lock-файл, снятие блокировки выполняет оператор вручную:
-  ```bash
-  rm /home/vadim/.dsh/profiles/web/package.json.lock
-  ```
+### 🔒 Политика блокировок профиля и контролируемое восстановление оператором
+При установке и обновлении плагинов DeepSeek Harness синхронизирует параллельные процессы через `<profile-dir>/package.json.lock` (например, `~/.dsh/profiles/<profile>/package.json.lock`).
+* **Канонический принцип претендента**: Процесс-претендент никогда не удаляет чужой lock-файл. Автоматическое удаление чужих блокировок претендентом запрещено для исключения TOCTOU-гонок и повреждения состояния профиля.
+* **Диагностика**: При наличии lock-файла запрос на обновление возвращает `409 Conflict` с подробной информацией:
+  - Если блокировка удерживается активным процессом, выводится его PID.
+  - При ошибках файловой системы (`EACCES`, `EIO`) операция завершается безопасно (fail-closed) с сохранением кода ошибки. Ошибки ФС требуют проверки прав доступа, состояния диска или опций монтирования — **не удаляйте** lock-файл при ошибках `EACCES`/`EIO`.
+* **Регламент контролируемого восстановления оператором**:
+  Если предыдущий процесс установки аварийно оборвался (например, OOM или сбой питания) и оставил зависший lock-файл, снятие блокировки выполняет оператор по следующему регламенту:
+  1. **Обеспечение эксклюзивного окна обслуживания**: Убедитесь, что никакие параллельные процессы, команды CLI (`dsh plugin add`), веб-интерфейс или фоновые апдейтеры не выполняют установку и не могут запуститься для данного профиля.
+  2. **Проверка отсутствия живого владельца (quiescence)**: Проверьте с помощью `pgrep`, `ps`, `fuser` или `lsof`, что в каталоге профиля действительно нет активных процессов-установщиков. Сам по себе возраст файла или нераспарсенный PID **не являются** достаточным основанием для удаления lock-файла, пока не исключён параллельный запуск другого процесса. Если состояние покоя не подтверждено, удаление запрещено.
+  3. **Удаление только подтверждённого осиротевшего lock-файла**: Только после подтверждения статуса сироты удалите конкретный файл блокировки без рекурсивных и force-флагов:
+     ```bash
+     rm ~/.dsh/profiles/<profile>/package.json.lock
+     ```
+  4. **Возобновление работы**: Разрешите запуск процессов установки и повторите обновление плагина.
 
 ---
 

package/README.zh.md

@@ -145,14 +145,21 @@ v0.8.18 质量审查后的修复批次（Gitea #79–#87，PR #88）：
 * `POST /api/dsh-voice/update` — 触发插件自动更新至 npm 最新兼容版本（受本地调用与锁校验保护）
 * `GET /api/dsh-voice/update` — 获取更新检查状态与版本信息
 
-### 🔒 配置文件锁与操作员恢复机制
-在安装或更新插件时，DeepSeek Harness 使用 `<profile-dir>/package.json.lock` 协调并发操作。
-* **规范竞争者策略**: 竞争者进程绝不删除现有的锁定文件。禁止竞争者自动清理残留锁，以杜绝 TOCTOU 竞态条件。
-* **诊断信息**: 若存在 lock 文件，更新请求将返回 `409 Conflict` 并附带诊断说明（关联 PID 或文件系统访问错误码 `EACCES`/`EIO`）。
-* **操作员手动恢复**: 若先前安装进程异常终止（如 OOM 或系统断电）留下僵死锁，需由操作员手动清理：
-  ```bash
-  rm /home/vadim/.dsh/profiles/web/package.json.lock
-  ```
+### 🔒 配置文件锁与受控操作员恢复机制
+在安装或更新插件时，DeepSeek Harness 使用 `<profile-dir>/package.json.lock`（例如 `~/.dsh/profiles/<profile>/package.json.lock`）协调并发操作。
+* **规范竞争者策略**: 竞争者进程绝不删除现有的锁定文件。禁止竞争者自动清理残留锁，以杜绝 TOCTOU 竞态条件并避免破坏配置文件状态。
+* **诊断信息**: 若存在 lock 文件，更新请求将返回 `409 Conflict` 并附带诊断说明：
+  - 若由活跃进程持有，则报告其 PID。
+  - 若遭遇文件系统访问错误（`EACCES`、`EIO`），则安全失败（fail-closed）并保留错误码。文件系统错误需要检查磁盘健康度、目录权限或挂载选项——**请勿**因 `EACCES`/`EIO` 错误而删除锁文件。
+* **受控操作员恢复流程**:
+  若先前安装进程异常终止（如 OOM 终止或系统断电）留下僵死锁，必须由操作员按以下受控流程进行清理：
+  1. **建立独占维护窗口**: 确保目标配置文件当前没有正在运行或计划启动的并发安装任务（CLI 命令 `dsh plugin add`、Web UI 交互或自动更新器）。
+  2. **确认静止状态与无活跃属主**: 通过 `pgrep`、`ps`、`fuser` 或 `lsof` 确认目标配置文件目录下确实没有正在执行包操作的活跃进程。仅凭锁文件存在时间较长或 PID 未能解析**不足以**作为删除依据，前提必须是彻底排除其他进程启动的可能。若无法确认静止状态，切勿删除。
+  3. **安全删除已确认的孤立锁**: 只有在完全确认锁文件已孤立且处于维护窗口期时，才允许由操作员手动删除该特定锁文件（严禁使用递归或 force 标志）：
+     ```bash
+     rm ~/.dsh/profiles/<profile>/package.json.lock
+     ```
+  4. **恢复正常运行**: 重新开启安装通道并重试插件更新。
 
 ---
 

package/lib/client.js

@@ -219,9 +219,9 @@ window.__ModuleLoader__.load({
       'updateSuccess': 'Updated successfully! Restart DSH to apply.',
       'updateFailed': 'Update failed. Check logs.',
       'updateCheckFailed': 'Update check failed',
-      'profileLockedPid': 'Profile is locked by process (PID {pid}). Operator recovery is required if stale: remove package.json.lock.',
-      'profileLockedExisting': 'Profile is locked by an existing lockfile. Operator recovery is required if stale: remove package.json.lock.',
-      'profileLockCheckError': 'Profile lock check failed. Filesystem inspection or operator recovery required.',
+      'profileLockedPid': 'Profile is locked by process (PID {pid}). Follow documented controlled operator recovery procedure if stale.',
+      'profileLockedExisting': 'Profile is locked by an existing lockfile. Follow documented controlled operator recovery procedure if stale.',
+      'profileLockCheckError': 'Profile lock check failed. Filesystem inspection required (do not remove lockfile).',
       'checkingUpdates': 'Checking updates…',
       'updateStatusUnknown': 'Version status unknown',
       'sensevoiceTitle': 'SenseVoice Local ASR (1-Click Setup)',
@@ -437,9 +437,9 @@ window.__ModuleLoader__.load({
       'updateSuccess': '更新成功！请重启 DSH 生效。',
       'updateFailed': '更新失败，请查看日志。',
       'updateCheckFailed': '检查更新失败',
-      'profileLockedPid': '配置文件已被进程锁定 (PID {pid})。若残留请由操作员手动处理：删除 package.json.lock。',
-      'profileLockedExisting': '配置文件已被现有锁定文件锁定。若残留请由操作员手动处理：删除 package.json.lock。',
-      'profileLockCheckError': '检查配置文件锁失败。需要排查文件系统或由操作员恢复。',
+      'profileLockedPid': '配置文件已被进程锁定 (PID {pid})。若残留请按受控操作员恢复流程处理。',
+      'profileLockedExisting': '配置文件已被现有锁定文件锁定。若残留请按受控操作员恢复流程处理。',
+      'profileLockCheckError': '检查配置文件锁失败。需排查文件系统，请勿直接删除锁文件。',
       'checkingUpdates': '正在检查更新…',
       'updateStatusUnknown': '版本状态未知',
       'sensevoiceTitle': 'SenseVoice 本地 ASR (一键部署)',

package/lib/updater.js

@@ -211,12 +211,12 @@ export function checkProfileLock(profileDir) {
 export function formatLockDiagnostic(lockStatus) {
   if (!lockStatus?.locked) return null;
   if (lockStatus.error) {
-    return `Profile lock check failed with error ${lockStatus.error}. Operator recovery or filesystem inspection required.`;
+    return `Profile lock check failed with error ${lockStatus.error}. Filesystem inspection required (do not remove lockfile).`;
   }
   if (lockStatus.pid) {
-    return `Profile is locked by process (PID ${lockStatus.pid}). If previous installation crashed, operator recovery is required: remove package.json.lock manually.`;
+    return `Profile is locked by process (PID ${lockStatus.pid}). Follow documented controlled operator recovery procedure if the process terminated abnormally.`;
   }
-  return 'Profile is locked by an existing lockfile. If previous installation crashed, operator recovery is required: remove package.json.lock manually.';
+  return 'Profile is locked by an existing lockfile. Follow documented controlled operator recovery procedure if the process terminated abnormally.';
 }
 
 async function installExact(target, packageSpec, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-voice",
-  "version": "0.9.26",
+  "version": "0.9.27",
   "description": "Voice input for DeepSeek Harness: dictation chunked by pauses and voice messages, each with its own provider fallback chain (Deepgram, Groq, HuggingFace, local whisper.cpp, plus any OpenAI-compatible API of your own).",
   "license": "MIT",
   "type": "module",