dsh-config-manager 0.1.85 → 0.1.86

package/lib/index.d.ts

@@ -77,7 +77,7 @@ export declare const name = "config-manager";
 /** Services required before the engine can mount (present in every profile). */
 export declare const inject: string[];
 /** Plugin version, kept in sync with package.json ("version"). */
-export declare const PLUGIN_VERSION = "0.1.85";
+export declare const PLUGIN_VERSION = "0.1.86";
 /**
  * Star 引导弹窗指向的 GitHub 仓库（用户引导点 Star 的目标）。
  * 与 package.json 的 repository 字段保持一致；界面不可改（硬编码，参照

package/lib/index.js

@@ -136,7 +136,7 @@ export const name = 'config-manager';
 /** Services required before the engine can mount (present in every profile). */
 export const inject = ['settings', 'credentials'];
 /** Plugin version, kept in sync with package.json ("version"). */
-export const PLUGIN_VERSION = '0.1.85';
+export const PLUGIN_VERSION = '0.1.86';
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager';
 /**

package/lib/sync/git/git-transport.js

@@ -53,6 +53,15 @@ const execFileAsync = promisify(execFile);
  */
 const INSPECT_FACTS_TTL_MS = 10_000;
 const inspectFactsCache = new Map();
+/**
+ * 只读自检等锁的上限（2026-10-27）。
+ *
+ * 为什么和写路径不同：写操作本来就该等（一次 push 十几秒是正常的），但自检挂在
+ * `GET /sync/status` 上，同步任务持锁期间它等待是**纯损失** —— 界面要的只是「工作副本有没有跟随
+ * 当前地址」，拿不到锁就如实报忙，让请求有界返回（再退一步还有 10 s 的接口预算兜底）。此前它沿用
+ * 缺省的 300 s：一次自动同步持锁就能让同步页每次打开都白等 10 s（真机 2026-10-27）。
+ */
+const INSPECT_WORKDIR_LOCK_TIMEOUT_MS = 1_500;
 function inspectFactsCacheKey(workDir, repoUrl) {
     return workDir + '\u0000' + repoUrl;
 }
@@ -423,6 +432,8 @@ export class GitTransport {
                 }
             }
             try {
+                // 只读自检传短上限：它挂在状态接口上，等不起一次同步（见 INSPECT_WORKDIR_LOCK_TIMEOUT_MS）；
+                // 写路径不传，沿用缺省的 300 s。
                 return await withWorkdirLock(this.o.workDir, async () => {
                     this.workdirLockDepth += 1;
                     try {
@@ -431,7 +442,7 @@ export class GitTransport {
                     finally {
                         this.workdirLockDepth -= 1;
                     }
-                });
+                }, opts.lockTimeoutMs === undefined ? {} : { timeoutMs: opts.lockTimeoutMs });
             }
             catch (err) {
                 // 等锁超时 = 别人正在同步（另一个 DSH 实例 / 另一个同步任务），不是通道故障：
@@ -543,8 +554,12 @@ export class GitTransport {
         if (hit !== undefined && Date.now() - hit.at < INSPECT_FACTS_TTL_MS && (hit.detail || !detail)) {
             return { ...hit.facts };
         }
-        // 只读命令也要排队：与并发的 fetch/checkout 交错会让 status/rev-list 读到半更新状态
-        const facts = await this.withWorkdir(() => this.inspectWorkDirLocked(opts), { readonly: true });
+        // 只读命令也要排队：与并发的 fetch/checkout 交错会让 status/rev-list 读到半更新状态。
+        // 但排队必须有界（短上限）：拿不到锁就报「工作副本忙」，绝不把状态接口拖进 300 s 的等待。
+        const facts = await this.withWorkdir(() => this.inspectWorkDirLocked(opts), {
+            readonly: true,
+            lockTimeoutMs: INSPECT_WORKDIR_LOCK_TIMEOUT_MS,
+        });
         const prev = inspectFactsCache.get(key);
         if (detail || prev === undefined || !prev.detail) {
             inspectFactsCache.set(key, { at: Date.now(), detail, facts });

package/lib/utils/workdir-lock.d.ts

@@ -19,7 +19,10 @@
  *  - 锁文件放 `os.tmpdir()`（按工作目录绝对路径哈希命名），**不写进工作副本**：
  *    工作副本还没 clone 出来也能先锁住，且绝不让 `git status` 看到脏文件；
  *  - 跨进程独占用 `open(path,'wx')`（O_EXCL，原子）；等待方轮询，超时抛 WorkdirLockError；
- *  - holder 崩溃留下的陈旧锁按 mtime 回收（超过 staleMs 才回收，避免误抢仍在跑的长时间任务）；
+ *  - holder 崩溃留下的陈旧锁：先问 holder pid 是否还存在（ESRCH ⇒ 已被杀，立即回收），
+ *    读不出 pid 或进程仍存活时才按 mtime 超过 staleMs 回收（避免误抢仍在跑的长时间任务）；
+ *  - 等待方是**有界**的：等文件锁与进程内链上排队共用同一个 timeoutMs 上限，超时即抛，
+ *    绝不在界面早已放弃之后仍去驱动工作副本；
  *  - 进程内再串一条 Promise 链：同进程两个 GitTransport 实例（autosync / 路由）共用同一条链，
  *    不依赖文件锁的轮询延迟。
  */
@@ -47,6 +50,27 @@ export interface WorkdirLockOptions {
 export declare function workdirLockKey(workDir: string): string;
 /** 锁文件路径（导出仅为测试与诊断；不要手工删一把可能被人持有的锁） */
 export declare function workdirLockPath(workDir: string): string;
+/**
+ * holder 进程是否还活着（三态：true = 存活、false = 确定已死、null = 判不了）。
+ *
+ * 为什么必须问：holder 被强杀时（DSH 重启 / 崩溃 / 任务管理器结束进程）`finally` 不会执行，
+ * 锁文件就留在 tmpdir 里；只按 mtime 判定要等满 staleMs（15 分钟）才接管。这段窗口里**所有**
+ * 同步与只读自检都排在锁上 —— 真机 2026-10-27：DSH 重启踩在一次 push 中间，pid 28888 的锁留在
+ * %TEMP%，之后每次打开同步页 `GET /sync/status` 都要等满 10 s 预算再 503。
+ *
+ * 误差方向：只有 `ESRCH`（pid 完全不存在）才判死；`EPERM`（进程存在但无权发信号，如 Linux 跨用户）
+ * 判活；pid 复用也会把「别人的锁」判成活 —— 两种误判都偏向保守（最多退化成 mtime 规则），
+ * 绝不会把仍在跑的 holder 的锁抢走。
+ */
+export declare function workdirLockHolderAlive(pid: unknown): boolean | null;
+/**
+ * 一次性清扫本机所有「holder 已死」的工作副本锁（每进程只跑一次）。
+ *
+ * 为什么需要：pid 回收只在**自己被这把锁挡住时**生效，而残留锁可能属于早已不再使用的工作目录
+ * （换过仓库、换过数据目录、临时实例）—— 它们永远不会再被查询，却一直躺在 %TEMP%（真机 2026-10-27
+ * 见到 8 个，最久 3.4 天）。只删 pid 确定不存在的锁：读不出 holder 的不动（保守，宁可留下）。
+ */
+export declare function pruneDeadWorkdirLocksOnce(): Promise<void>;
 /**
  * 在指定工作副本上串行执行 fn（同一目录的调用排队，跨进程同理）。
  *
@@ -54,5 +78,5 @@ export declare function workdirLockPath(workDir: string): string;
  * 不要在里面再调用会等这把锁的其他工作副本操作 —— 可重入请由调用方用自己的 depth 计数处理。
  */
 export declare function withWorkdirLock<T>(workDir: string, fn: () => Promise<T>, options?: WorkdirLockOptions): Promise<T>;
-/** 仅供测试：清空进程内串行链（不影响磁盘上的锁文件） */
+/** 仅供测试：清空进程内串行链与一次性清扫标记（不影响磁盘上的锁文件） */
 export declare function resetWorkdirLockChainsForTest(): void;

package/lib/utils/workdir-lock.js

@@ -19,7 +19,10 @@
  *  - 锁文件放 `os.tmpdir()`（按工作目录绝对路径哈希命名），**不写进工作副本**：
  *    工作副本还没 clone 出来也能先锁住，且绝不让 `git status` 看到脏文件；
  *  - 跨进程独占用 `open(path,'wx')`（O_EXCL，原子）；等待方轮询，超时抛 WorkdirLockError；
- *  - holder 崩溃留下的陈旧锁按 mtime 回收（超过 staleMs 才回收，避免误抢仍在跑的长时间任务）；
+ *  - holder 崩溃留下的陈旧锁：先问 holder pid 是否还存在（ESRCH ⇒ 已被杀，立即回收），
+ *    读不出 pid 或进程仍存活时才按 mtime 超过 staleMs 回收（避免误抢仍在跑的长时间任务）；
+ *  - 等待方是**有界**的：等文件锁与进程内链上排队共用同一个 timeoutMs 上限，超时即抛，
+ *    绝不在界面早已放弃之后仍去驱动工作副本；
  *  - 进程内再串一条 Promise 链：同进程两个 GitTransport 实例（autosync / 路由）共用同一条链，
  *    不依赖文件锁的轮询延迟。
  */
@@ -56,6 +59,102 @@ export function workdirLockKey(workDir) {
 export function workdirLockPath(workDir) {
     return path.join(os.tmpdir(), `dshcm-workdir-${workdirLockKey(workDir)}.lock`);
 }
+/**
+ * holder 进程是否还活着（三态：true = 存活、false = 确定已死、null = 判不了）。
+ *
+ * 为什么必须问：holder 被强杀时（DSH 重启 / 崩溃 / 任务管理器结束进程）`finally` 不会执行，
+ * 锁文件就留在 tmpdir 里；只按 mtime 判定要等满 staleMs（15 分钟）才接管。这段窗口里**所有**
+ * 同步与只读自检都排在锁上 —— 真机 2026-10-27：DSH 重启踩在一次 push 中间，pid 28888 的锁留在
+ * %TEMP%，之后每次打开同步页 `GET /sync/status` 都要等满 10 s 预算再 503。
+ *
+ * 误差方向：只有 `ESRCH`（pid 完全不存在）才判死；`EPERM`（进程存在但无权发信号，如 Linux 跨用户）
+ * 判活；pid 复用也会把「别人的锁」判成活 —— 两种误判都偏向保守（最多退化成 mtime 规则），
+ * 绝不会把仍在跑的 holder 的锁抢走。
+ */
+export function workdirLockHolderAlive(pid) {
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ESRCH')
+            return false;
+        if (code === 'EPERM')
+            return true;
+        return null;
+    }
+}
+/** 读锁文件里记录的 holder（读不出 / 半写入 / 不是对象 ⇒ null，一律退回 mtime 规则） */
+async function readLockHolder(lockPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(lockPath, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object')
+            return null;
+        const holder = parsed;
+        return { pid: holder.pid, workDir: holder.workDir };
+    }
+    catch {
+        return null;
+    }
+}
+const LOCK_FILE_PREFIX = 'dshcm-workdir-';
+let pruneScheduled = false;
+/**
+ * 一次性清扫本机所有「holder 已死」的工作副本锁（每进程只跑一次）。
+ *
+ * 为什么需要：pid 回收只在**自己被这把锁挡住时**生效，而残留锁可能属于早已不再使用的工作目录
+ * （换过仓库、换过数据目录、临时实例）—— 它们永远不会再被查询，却一直躺在 %TEMP%（真机 2026-10-27
+ * 见到 8 个，最久 3.4 天）。只删 pid 确定不存在的锁：读不出 holder 的不动（保守，宁可留下）。
+ */
+export async function pruneDeadWorkdirLocksOnce() {
+    if (pruneScheduled)
+        return;
+    pruneScheduled = true;
+    const dir = os.tmpdir();
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    const remove = async (lockPath) => {
+        try {
+            await fs.unlink(lockPath);
+        }
+        catch {
+            // 别人同时也在清扫 / 已被释放：无事可做
+        }
+    };
+    await Promise.all(names
+        .filter((name) => name.startsWith(LOCK_FILE_PREFIX) && name.endsWith('.lock'))
+        .map(async (name) => {
+        const lockPath = path.join(dir, name);
+        const holder = await readLockHolder(lockPath);
+        if (holder === null)
+            return; // 读不出 holder：保守留下
+        const alive = workdirLockHolderAlive(holder.pid);
+        if (alive === false)
+            return await remove(lockPath); // holder 确定已死
+        if (alive !== true)
+            return; // 判不了：留下
+        // pid 复用陷阱：holder pid 此刻可能属于一个毫不相干的进程（本机实测 2026-10-27：一条测试残留锁的
+        // pid 9704 已被 `NoiseCancelingEngine.exe` 复用）。只有「它声明的工作目录确实不存在 + 锁已过
+        // staleMs」才清 —— 那说明 holder 早就不在这把锁上了，而不是正在干活。
+        const st = await fs.stat(lockPath).catch(() => null);
+        if (st === null || Date.now() - st.mtimeMs <= DEFAULT_WORKDIR_LOCK_STALE_MS)
+            return;
+        const workDir = typeof holder.workDir === 'string' ? holder.workDir : '';
+        if (workDir === '')
+            return;
+        if (await fs.stat(workDir).then(() => true, () => false))
+            return;
+        await remove(lockPath);
+    }));
+}
 async function tryAcquire(lockPath, workDir, staleMs, now) {
     const token = randomUUID();
     try {
@@ -84,7 +183,18 @@ async function tryAcquire(lockPath, workDir, staleMs, now) {
         const code = err.code;
         if (code !== 'EEXIST')
             throw err;
-        // 陈旧锁回收：holder 崩溃/被杀后留下的文件不能让同步永久卡死
+        // ① holder pid 已经不存在 ⇒ 这把锁必然陈旧，立即回收，不等 staleMs（重启/崩溃后的现场）
+        const holder = await readLockHolder(lockPath);
+        if (workdirLockHolderAlive(holder?.pid) === false) {
+            try {
+                await fs.unlink(lockPath);
+            }
+            catch {
+                // 别人刚好也判定并回收、或 holder 的 finally 刚好跑到：下一轮重试即可
+            }
+            return null;
+        }
+        // ② 读不出 holder / holder 仍存活 ⇒ 只有超过 staleMs 才视为崩溃残留（绝不抢正在跑的长任务）
         try {
             const st = await fs.stat(lockPath);
             if (now() - st.mtimeMs > staleMs)
@@ -109,8 +219,15 @@ export async function withWorkdirLock(workDir, fn, options = {}) {
     const now = options.now ?? Date.now;
     const key = workdirLockKey(workDir);
     const lockPath = workdirLockPath(workDir);
+    // 顺带清扫本机别的死 holder 残留（每进程一次，失败不影响本次取锁）
+    void pruneDeadWorkdirLocksOnce().catch(() => undefined);
+    // 计时必须在进入串行链**之前**取：链上排队同样属于「在等这把锁」。否则一个只读调用排在
+    // 上一个 300 s 的同步后面时，计时从轮到它那一刻才清零，超时上限形同失效（2026-10-27 现场）。
+    const started = now();
     const run = async () => {
-        const started = now();
+        // 排队期间调用方已超时放弃：轮到它时直接失败，**不执行 fn**，免得被遗弃的请求稍后仍去驱动工作副本
+        if (now() - started >= timeoutMs)
+            throw new WorkdirLockError(workDir, now() - started);
         // 先同步做一次尝试，再进入轮询：无竞争的常见情形零额外延迟
         let release = await tryAcquire(lockPath, workDir, staleMs, now);
         while (release === null) {
@@ -132,16 +249,27 @@ export async function withWorkdirLock(workDir, fn, options = {}) {
     // 链里只保留「尾巴」的完成状态，异常不向下游传染
     const tail = current.then(() => undefined, () => undefined);
     chains.set(key, tail);
+    // 硬上界：timeoutMs 是「拿到锁」的上限，不是「开始计时后」的上限。只用 run 内的计时不够 ——
+    // 排在长任务后面的调用永远轮不到自己计时，界面就被历史任务拖着走。这里直接对链头 race，
+    // 超时 reject；被放弃的 run 之后还会被链唤醒，但入口的过期检查让它立刻抛（不碰工作副本）。
+    let rejectDeadline;
+    const deadline = new Promise((_, reject) => { rejectDeadline = reject; });
+    const timer = setTimeout(() => { rejectDeadline?.(new WorkdirLockError(workDir, timeoutMs)); }, timeoutMs);
+    // unref：这个计时器不该拖住进程退出（缺省 300 s）
+    if (typeof timer.unref === 'function')
+        timer.unref();
     try {
-        return await current;
+        return await Promise.race([current, deadline]);
     }
     finally {
+        clearTimeout(timer);
         if (chains.get(key) === tail)
             chains.delete(key);
     }
 }
-/** 仅供测试：清空进程内串行链（不影响磁盘上的锁文件） */
+/** 仅供测试：清空进程内串行链与一次性清扫标记（不影响磁盘上的锁文件） */
 export function resetWorkdirLockChainsForTest() {
     chains.clear();
+    pruneScheduled = false;
 }
 //# sourceMappingURL=workdir-lock.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-config-manager",
-  "version": "0.1.85",
+  "version": "0.1.86",
   "license": "MIT",
   "description": "Backup, restore, export, import, migrate and sync your DeepSeek Harness (DSH) configuration: settings, plugins, MCP servers, skills, agent presets and workspaces. One-click migration to another machine. DSH 配置一键备份、恢复、导出、导入、迁移与同步插件。",
   "icon": "./icon.svg",

package/src/index.ts

@@ -180,7 +180,7 @@ export const name = 'config-manager'
 export const inject = ['settings', 'credentials']
 
 /** Plugin version, kept in sync with package.json ("version"). */
-export const PLUGIN_VERSION = '0.1.85'
+export const PLUGIN_VERSION = '0.1.86'
 
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager'

package/src/sync/git/git-transport.test.ts

@@ -18,6 +18,7 @@ import { computeSnapshotMeta, DEFAULT_SYNC_TIMEOUT_MS, isEncryptedSections, Sync
 import type { SyncSnapshot } from '../transport.ts';
 import type { FilesSection, SectionData, SectionId } from '../../schema/types.ts';
 import { sha256Hex } from '../../utils/hashing.ts';
+import { resetWorkdirLockChainsForTest, workdirLockPath } from '../../utils/workdir-lock.ts';
 
 /* ---------------- helpers ---------------- */
 
@@ -1411,4 +1412,35 @@ test('自检缓存：TTL 过期后重新自检', async (t) => {
   assert.ok(calls.length > warm, 'TTL 过期后必须重新自检，绝不无限期返回旧事实');
 });
 
+/**
+ * 为什么有这条用例（真机 2026-10-27）：自检挂在 `GET /sync/status` 上，而同步任务持锁是常态
+ * （autosync 每 1~2 分钟一次 push）。此前它沿用工作副本锁缺省的 300 s 等待 ⇒ 同步页每次打开都白等
+ * 满 10 s 接口预算再报超时。只读自检必须**有界**：拿不到锁立刻如实报「忙」，让调用方按可操作文案提示。
+ */
+test('只读自检有界：锁被活进程持有时报「工作副本忙」，绝不等满锁的缺省上限', async (t) => {
+  clearInspectFactsCache();
+  const dir = await makeGitWorkDir(t);
+  const lockPath = workdirLockPath(dir);
+  // 模拟另一个存活实例正在同步：pid 存活 ⇒ 不会被当作陈旧锁回收，只能等
+  await fs.writeFile(lockPath, JSON.stringify({ pid: process.pid, token: 'other-instance' }));
+  t.after(async () => {
+    await fs.rm(lockPath, { force: true });
+    resetWorkdirLockChainsForTest();
+  });
+  const calls: CallRecord[] = [];
+  const transport = new GitTransport(makeOptions({ workDir: dir, exec: mockExec(calls) }));
+
+  const t0 = Date.now();
+  await assert.rejects(transport.inspectWorkDir(), (err: unknown) => {
+    assert.ok(err instanceof GitTransportError, '必须是 GitTransportError');
+    assert.equal(err.kind, 'conflict', '等锁超时是「通道忙」，不是协议/网络故障');
+    assert.equal(err.retryable, true);
+    assert.match(err.message, /正被另一个同步任务占用/);
+    return true;
+  });
+  const elapsed = Date.now() - t0;
+  assert.ok(elapsed < 3_000, '自检必须在短上限内失败（实测 ' + String(elapsed) + 'ms），绝不能等缺省的 300 s');
+  assert.equal(calls.length, 0, '拿不到锁就不得 spawn 任何 git 命令');
+});
+
 

package/src/sync/git/git-transport.ts

@@ -108,6 +108,16 @@ export interface GitWorkDirFacts {
 const INSPECT_FACTS_TTL_MS = 10_000;
 const inspectFactsCache = new Map<string, { at: number; detail: boolean; facts: GitWorkDirFacts }>();
 
+/**
+ * 只读自检等锁的上限（2026-10-27）。
+ *
+ * 为什么和写路径不同：写操作本来就该等（一次 push 十几秒是正常的），但自检挂在
+ * `GET /sync/status` 上，同步任务持锁期间它等待是**纯损失** —— 界面要的只是「工作副本有没有跟随
+ * 当前地址」，拿不到锁就如实报忙，让请求有界返回（再退一步还有 10 s 的接口预算兜底）。此前它沿用
+ * 缺省的 300 s：一次自动同步持锁就能让同步页每次打开都白等 10 s（真机 2026-10-27）。
+ */
+const INSPECT_WORKDIR_LOCK_TIMEOUT_MS = 1_500;
+
 function inspectFactsCacheKey(workDir: string, repoUrl: string): string {
   return workDir + '\u0000' + repoUrl;
 }
@@ -508,7 +518,7 @@ export class GitTransport implements SyncTransport {
    *
    * 可重入：内层（ensureRepo/pullFromRemote/adoptRemoteHistory 等）不重复取锁。
    */
-  private async withWorkdir<T>(fn: () => Promise<T>, opts: { readonly?: boolean } = {}): Promise<T> {
+  private async withWorkdir<T>(fn: () => Promise<T>, opts: { readonly?: boolean; lockTimeoutMs?: number } = {}): Promise<T> {
     try {
       if (this.workdirLockDepth > 0) {
         this.workdirLockDepth += 1;
@@ -519,6 +529,8 @@ export class GitTransport implements SyncTransport {
         }
       }
       try {
+        // 只读自检传短上限：它挂在状态接口上，等不起一次同步（见 INSPECT_WORKDIR_LOCK_TIMEOUT_MS）；
+        // 写路径不传，沿用缺省的 300 s。
         return await withWorkdirLock(this.o.workDir, async () => {
           this.workdirLockDepth += 1;
           try {
@@ -526,7 +538,7 @@ export class GitTransport implements SyncTransport {
           } finally {
             this.workdirLockDepth -= 1;
           }
-        });
+        }, opts.lockTimeoutMs === undefined ? {} : { timeoutMs: opts.lockTimeoutMs });
       } catch (err) {
         // 等锁超时 = 别人正在同步（另一个 DSH 实例 / 另一个同步任务），不是通道故障：
         // 给可操作文案并标记 retryable，别让它伪装成「git 命令失败」。
@@ -637,8 +649,12 @@ export class GitTransport implements SyncTransport {
     if (hit !== undefined && Date.now() - hit.at < INSPECT_FACTS_TTL_MS && (hit.detail || !detail)) {
       return { ...hit.facts };
     }
-    // 只读命令也要排队：与并发的 fetch/checkout 交错会让 status/rev-list 读到半更新状态
-    const facts = await this.withWorkdir(() => this.inspectWorkDirLocked(opts), { readonly: true });
+    // 只读命令也要排队：与并发的 fetch/checkout 交错会让 status/rev-list 读到半更新状态。
+    // 但排队必须有界（短上限）：拿不到锁就报「工作副本忙」，绝不把状态接口拖进 300 s 的等待。
+    const facts = await this.withWorkdir(() => this.inspectWorkDirLocked(opts), {
+      readonly: true,
+      lockTimeoutMs: INSPECT_WORKDIR_LOCK_TIMEOUT_MS,
+    });
     const prev = inspectFactsCache.get(key);
     if (detail || prev === undefined || !prev.detail) {
       inspectFactsCache.set(key, { at: Date.now(), detail, facts });

package/src/utils/workdir-lock.test.ts

@@ -15,8 +15,10 @@ import path from 'node:path';
 import {
   DEFAULT_WORKDIR_LOCK_STALE_MS,
   WorkdirLockError,
+  pruneDeadWorkdirLocksOnce,
   resetWorkdirLockChainsForTest,
   withWorkdirLock,
+  workdirLockHolderAlive,
   workdirLockPath,
 } from './workdir-lock.ts';
 
@@ -65,8 +67,9 @@ test('不同工作副本：互不阻塞（锁按目录隔离）', async (t) => {
 
 test('等锁超时：别人持有锁且未过期 → 抛 WorkdirLockError（而不是无限等待）', async (t) => {
   const dir = await makeDir(t);
-  // 模拟另一个进程正在持有锁（文件已存在、mtime 新鲜 → 不会被当成陈旧锁回收）
-  await fs.writeFile(workdirLockPath(dir), JSON.stringify({ pid: 999999, token: 'other-process' }));
+  // 模拟另一个**仍然存活**的进程持有锁（mtime 新鲜、pid 存在 ⇒ 两条回收路径都不该触发）。
+  // 必须用真实存活 pid：死 pid 的锁现在会立即回收（见下一条用例），不再进入等待。
+  await fs.writeFile(workdirLockPath(dir), JSON.stringify({ pid: process.pid, token: 'other-process' }));
   await assert.rejects(
     withWorkdirLock(dir, async () => 'never', { timeoutMs: 30, sleep: fastSleep }),
     (err: unknown) => {
@@ -79,22 +82,92 @@ test('等锁超时：别人持有锁且未过期 → 抛 WorkdirLockError（而
   await fs.access(workdirLockPath(dir));
 });
 
-test('陈旧锁回收：holder 崩溃留下的锁（超过 stale 阈值）→ 自动接管', async (t) => {
+test('holder pid 已死：立即回收锁，不等 staleMs（DSH 重启/崩溃现场，2026-10-27）', async (t) => {
   const dir = await makeDir(t);
   const lockPath = workdirLockPath(dir);
-  await fs.writeFile(lockPath, JSON.stringify({ pid: 999999, token: 'dead' }));
+  // 取一个必然不存在的 pid，并先证明判定本身是对的，免得把环境差异伪装成通过
+  const deadPid = 4_000_000;
+  assert.equal(workdirLockHolderAlive(deadPid), false, '前提：该 pid 必须不存在（否则本用例无意义）');
+  await fs.writeFile(lockPath, JSON.stringify({ pid: deadPid, token: 'dead-holder' }));
+  const t0 = Date.now();
+  assert.equal(await withWorkdirLock(dir, async () => 'ok'), 'ok');
+  assert.ok(Date.now() - t0 < 500, '死 holder 的锁必须立即回收，绝不能等到 staleMs（15 分钟）');
+  await assert.rejects(fs.access(lockPath), '释放后锁文件必须消失');
+});
+
+test('陈旧锁回收：holder 仍存活但锁文件超过 stale 阈值 → 自动接管', async (t) => {
+  const dir = await makeDir(t);
+  const lockPath = workdirLockPath(dir);
+  // pid 存活 ⇒ pid 路径不回收，只能走 mtime 兜底（覆盖 holder 卡死、永远不释放 finally 的情形）
+  await fs.writeFile(lockPath, JSON.stringify({ pid: process.pid, token: 'hung-holder' }));
   const stale = new Date(Date.now() - DEFAULT_WORKDIR_LOCK_STALE_MS - 60_000);
   await fs.utimes(lockPath, stale, stale);
   assert.equal(await withWorkdirLock(dir, async () => 'ok'), 'ok');
   await assert.rejects(fs.access(lockPath), '释放后锁文件必须消失');
 });
 
+test('读不出的 holder 一律退回 mtime 规则：新鲜锁仍须等待，不得盲抢', async (t) => {
+  const dir = await makeDir(t);
+  const lockPath = workdirLockPath(dir);
+  await fs.writeFile(lockPath, 'not-json'); // 半写入/旧格式：判不了 holder 是否存活
+  await assert.rejects(
+    withWorkdirLock(dir, async () => 'never', { timeoutMs: 30, sleep: fastSleep }),
+    (err: unknown) => err instanceof WorkdirLockError,
+  );
+  await fs.access(lockPath);
+});
+
+test('链上排队也计入超时：排在长任务后面的调用按时失败，且绝不执行 fn', async (t) => {
+  const dir = await makeDir(t);
+  const slow = withWorkdirLock(dir, async () => {
+    await new Promise((r) => setTimeout(r, 400));
+    return 'slow';
+  });
+  let quickRan = false;
+  const t0 = Date.now();
+  await assert.rejects(
+    withWorkdirLock(dir, async () => { quickRan = true; return 'quick'; }, { timeoutMs: 60 }),
+    (err: unknown) => err instanceof WorkdirLockError,
+  );
+  const elapsed = Date.now() - t0;
+  assert.ok(elapsed < 350, '排队到上限就必须失败，不能等前一个长任务跑完（实测 ' + String(elapsed) + 'ms）');
+  assert.equal(quickRan, false, '已超时放弃的调用绝不允许随后仍去驱动工作副本');
+  assert.equal(await slow, 'slow');
+});
+
 test('异常也释放锁：fn 抛错后下一次仍能拿到锁（不会把后续同步永久卡死）', async (t) => {
   const dir = await makeDir(t);
   await assert.rejects(withWorkdirLock(dir, async () => { throw new Error('boom'); }), /boom/);
   assert.equal(await withWorkdirLock(dir, async () => 'ok'), 'ok');
 });
 
+test('一次性清扫：holder 已死的残留锁被删，活锁与读不出的锁一律保留', async (t) => {
+  const dir = await makeDir(t); // 顺便重置一次性清扫标记
+  const suffix = String(Date.now()) + String(Math.random()).slice(2, 8);
+  const deadPath = path.join(os.tmpdir(), 'dshcm-workdir-' + suffix + 'a.lock');
+  const alivePath = path.join(os.tmpdir(), 'dshcm-workdir-' + suffix + 'b.lock');
+  const opaquePath = path.join(os.tmpdir(), 'dshcm-workdir-' + suffix + 'c.lock');
+  // pid 复用陷阱：pid 现在还活着，但它声明的工作目录早已不存在、锁也过了 staleMs
+  const reusedPath = path.join(os.tmpdir(), 'dshcm-workdir-' + suffix + 'd.lock');
+  const goneDir = path.join(os.tmpdir(), 'dshcm-gone-' + suffix);
+  await fs.writeFile(deadPath, JSON.stringify({ pid: 4_000_000, token: 'dead', workDir: dir }));
+  await fs.writeFile(alivePath, JSON.stringify({ pid: process.pid, token: 'alive', workDir: dir }));
+  await fs.writeFile(opaquePath, 'not-json');
+  await fs.writeFile(reusedPath, JSON.stringify({ pid: process.pid, token: 'reused', workDir: goneDir }));
+  const old = new Date(Date.now() - DEFAULT_WORKDIR_LOCK_STALE_MS - 60_000);
+  await fs.utimes(reusedPath, old, old);
+  t.after(async () => {
+    await Promise.all([deadPath, alivePath, opaquePath, reusedPath].map((f) => fs.rm(f, { force: true })));
+  });
+
+  await pruneDeadWorkdirLocksOnce();
+
+  await assert.rejects(fs.access(deadPath), 'holder 已死的残留锁必须被清掉');
+  await fs.access(alivePath); // 活锁 + 工作目录还在 ⇒ 动不得
+  await fs.access(opaquePath); // 读不出 holder ⇒ 保守保留
+  await assert.rejects(fs.access(reusedPath), '工作目录已消失且过了 staleMs ⇒ pid 复用造成的僵尸锁应清掉');
+});
+
 test('锁按绝对路径归一：同一目录的不同写法共享一把锁', async (t) => {
   const dir = await makeDir(t);
   let active = 0;