@goodandready/dsh-voice 0.9.25 → 0.9.27

package/README.md

@@ -223,6 +223,24 @@ Registers `transcribe_audio(file_path, language?)` in `ctx.tools`, allowing agen
 * `GET /dsh-voice/config` — Returns live plugin configuration snapshot.
 * `PUT /dsh-voice/config` — Updates and persists plugin configuration across network.
 * `GET/POST /dsh-voice/sensevoice-installer` — SenseVoice 1-click model installation status and trigger (protected by `isTrustedCaller`, model paths redacted).
+* `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 & 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. 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

@@ -220,6 +220,26 @@ dsh plugin --profile web add @goodandready/dsh-voice
 * `POST /dsh-voice/transcribe` — `{ dataBase64, mimeType, mode }` → `{ ok, text, provider, tookMs }`
 * `POST /dsh-voice/polish` — `{ text }` → `{ ok, text }`
 * `GET /dsh-voice/status` — состояние демонов, цепочки, конфигурация SenseVoice и реалтайма.
+* `GET/PUT /dsh-voice/config` — получение и сохранение конфигурации плагина.
+* `GET/POST /dsh-voice/sensevoice-installer` — статус и установка модели SenseVoice в 1 клик.
+* `POST /api/dsh-voice/update` — запуск обновления плагина до актуальной версии из npm (с проверкой прав и блокировки профиля).
+* `GET /api/dsh-voice/update` — проверка наличия обновлений.
+
+### 🔒 Политика блокировок профиля и контролируемое восстановление оператором
+При установке и обновлении плагинов 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

@@ -142,6 +142,24 @@ v0.8.18 质量审查后的修复批次（Gitea #79–#87，PR #88）：
 * `GET /dsh-voice/config` — 获取插件运行时配置快照
 * `PUT /dsh-voice/config` — 跨网络安全持久化更新插件配置
 * `GET/POST /dsh-voice/sensevoice-installer` — SenseVoice 一键模型安装状态与触发接口（受 `isTrustedCaller` 保护，绝对路径脱敏）
+* `POST /api/dsh-voice/update` — 触发插件自动更新至 npm 最新兼容版本（受本地调用与锁校验保护）
+* `GET /api/dsh-voice/update` — 获取更新检查状态与版本信息
+
+### 🔒 配置文件锁与受控操作员恢复机制
+在安装或更新插件时，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,6 +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}). 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)',
@@ -434,6 +437,9 @@ window.__ModuleLoader__.load({
       'updateSuccess': '更新成功！请重启 DSH 生效。',
       'updateFailed': '更新失败，请查看日志。',
       'updateCheckFailed': '检查更新失败',
+      'profileLockedPid': '配置文件已被进程锁定 (PID {pid})。若残留请按受控操作员恢复流程处理。',
+      'profileLockedExisting': '配置文件已被现有锁定文件锁定。若残留请按受控操作员恢复流程处理。',
+      'profileLockCheckError': '检查配置文件锁失败。需排查文件系统，请勿直接删除锁文件。',
       'checkingUpdates': '正在检查更新…',
       'updateStatusUnknown': '版本状态未知',
       'sensevoiceTitle': 'SenseVoice 本地 ASR (一键部署)',
@@ -3084,6 +3090,17 @@ voice._chainsPromise = null
           })
           const data = await res.json().catch(() => ({}))
           if (!res.ok || data.ok === false) {
+            if (data.code) {
+              const base = t('profileLockCheckError')
+              throw new Error(base ? `${base} (${data.code})` : (data.error || `HTTP ${res.status}`))
+            }
+            if (data.locked) {
+              const key = data.pid ? 'profileLockedPid' : 'profileLockedExisting'
+              const translated = t(key)
+              if (translated && translated !== key) {
+                throw new Error(data.pid ? translated.replace('{pid}', String(data.pid)) : translated)
+              }
+            }
             throw new Error(data.error || `HTTP ${res.status}`)
           }
           setUpdaterMsg(data.message || t('updateSuccess'))

package/lib/updater.js

@@ -208,11 +208,24 @@ export function checkProfileLock(profileDir) {
   return { locked: true, pid };
 }
 
+export function formatLockDiagnostic(lockStatus) {
+  if (!lockStatus?.locked) return null;
+  if (lockStatus.error) {
+    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}). Follow documented controlled operator recovery procedure if the process terminated abnormally.`;
+  }
+  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) {
   if (target.cliEntry === undefined) throw new Error('Automatic update is unavailable in this runtime.');
   const lockCheck = checkProfileLock(target.profileDir);
   if (lockCheck.locked) {
-    throw new Error(`Another package installation is currently in progress${lockCheck.pid ? ` (PID ${lockCheck.pid})` : ''}.`);
+    const err = new Error(formatLockDiagnostic(lockCheck));
+    if (lockCheck.error) err.code = lockCheck.error;
+    throw err;
   }
   await new Promise((resolvePromise, reject) => {
     const child = spawn(process.execPath, [
@@ -295,8 +308,11 @@ export function registerPluginUpdater(ctx, options) {
         if (installing || lockStatus.locked) {
           json(response, 409, {
             error: lockStatus.locked
-              ? `Another package installation is currently in progress${lockStatus.pid ? ` (PID ${lockStatus.pid})` : ''}.`
+              ? formatLockDiagnostic(lockStatus)
               : 'This plugin is already updating.',
+            code: lockStatus.error,
+            locked: Boolean(lockStatus.locked),
+            pid: lockStatus.pid ?? null,
           });
           return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-voice",
-  "version": "0.9.25",
+  "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",