@goodandready/dsh-voice 0.9.25 → 0.9.26

package/README.md

@@ -223,6 +223,19 @@ 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 & Operator Recovery Policy
+When updating or installing plugins, DeepSeek Harness profiles coordinate concurrent operations using `<profile-dir>/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
+  ```
 
 ---
 

package/README.ru.md

@@ -220,6 +220,19 @@ 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`.
+* **Канонический принцип претендента**: Процесс-претендент никогда не удаляет существующий lock-файл. Автоматическое удаление чужих блокировок исключено для предотвращения TOCTOU-гонок.
+* **Диагностика**: При наличии lock-файла запрос на обновление возвращает `409 Conflict` с подробной информацией (PID процесса либо код ошибки доступа к файловой системе `EACCES`/`EIO`).
+* **Восстановление оператором**: Если предыдущий процесс установки аварийно завершился (например, OOM или отключение питания) и оставил зависший lock-файл, снятие блокировки выполняет оператор вручную:
+  ```bash
+  rm /home/vadim/.dsh/profiles/web/package.json.lock
+  ```
 
 ---
 

package/README.zh.md

@@ -142,6 +142,17 @@ 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` 协调并发操作。
+* **规范竞争者策略**: 竞争者进程绝不删除现有的锁定文件。禁止竞争者自动清理残留锁，以杜绝 TOCTOU 竞态条件。
+* **诊断信息**: 若存在 lock 文件，更新请求将返回 `409 Conflict` 并附带诊断说明（关联 PID 或文件系统访问错误码 `EACCES`/`EIO`）。
+* **操作员手动恢复**: 若先前安装进程异常终止（如 OOM 或系统断电）留下僵死锁，需由操作员手动清理：
+  ```bash
+  rm /home/vadim/.dsh/profiles/web/package.json.lock
+  ```
 
 ---
 

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}). 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.',
       '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})。若残留请由操作员手动处理：删除 package.json.lock。',
+      'profileLockedExisting': '配置文件已被现有锁定文件锁定。若残留请由操作员手动处理：删除 package.json.lock。',
+      '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}. Operator recovery or filesystem inspection required.`;
+  }
+  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 an existing lockfile. If previous installation crashed, operator recovery is required: remove package.json.lock manually.';
+}
+
 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.26",
   "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",