@lark-codem/codem-cli 0.1.238-fornax-codem-ca.100102809488.0.g450a419 → 0.1.239

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@lark-codem/codem-cli",
-  "version": "0.1.238-fornax-codem-ca.100102809488.0.g450a419",
+  "version": "0.1.239",
   "codemServiceManagementProtocol": 3,
+  "codemProfileProtocol": 1,
   "type": "module",
   "description": "CodeM local CLI for Feishu-driven coding sessions",
   "license": "SEE LICENSE IN LICENSE",
   "files": [
     "bin",
+    "profile",
     "LICENSE"
   ],
   "os": [
@@ -27,10 +29,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@lark-codem/codem-core": "0.8.70-fornax-codem-ca.100102809488.0.g4bf6451"
+    "@lark-codem/codem-core": "0.8.71",
+    "zod": "3.25.76"
   },
   "optionalDependencies": {
-    "@lark-codem/codem-cli-linux-x64": "0.1.238-fornax-codem-ca.100102809488.0.g450a419"
+    "@lark-codem/codem-cli-darwin-arm64": "0.1.239",
+    "@lark-codem/codem-cli-darwin-x64": "0.1.239",
+    "@lark-codem/codem-cli-linux-arm64": "0.1.239",
+    "@lark-codem/codem-cli-linux-x64": "0.1.239",
+    "@lark-codem/codem-cli-win32-arm64": "0.1.239",
+    "@lark-codem/codem-cli-win32-x64": "0.1.239"
   },
   "engines": {
     "node": ">=18"

package/profile/config-lock.js

@@ -0,0 +1,512 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, openSync, rmSync, writeSync } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { debugLog } from "./debug.js";
+
+// 跨进程 config 互斥锁（zero-dep：原子 create-with-content + owner PID liveness）。
+//
+// 背景：本机 daemon 轮询、daemon 启动、交互式 CLI、linco-runner、host-channel 各持
+// 一个 OAuthTokenManager，共享 `~/.codem/config.json` 里同一个飞书 refresh token(RT)。
+// 飞书 RT 单次使用、每次刷新即轮换：两个进程若并发刷新，一个赢家轮到新 RT 并落盘，
+// 另一个拿着旧内存快照整文件写回就会把新 RT 覆盖成死 RT，下次刷新必 invalid_grant →
+// OAuth 会话被清、被迫 `codem login --force`。ConfigStore 的 `#withWriteLock` 只是进程内
+// promise 链，跨进程仍是 last-writer-wins。此锁把所有 refresh / auth 写盘收敛到一个
+// 跨进程临界区，消除该竞态。
+//
+// 核心不变量：**存活进程持有的锁绝不会被回收**。破坏互斥的代价（死 RT → 强制重登）
+// 远大于「等待者超时报一个瞬时错误」，所以任何「看起来像孤儿」都不足以触发回收——
+// 只有**可证明无主**才回收。
+//
+// ── 为什么用 tmp + link 而不是 writeFile(flag:"wx") ──────────────────────────
+//
+// 锁文件必须「一出现就是完整的」。`writeFile(flag:"wx")` = open(O_CREAT|O_EXCL) +
+// write + close 是**两步**：open 成功后锁文件已在盘上、大小为 0，body 要等下一个
+// event-loop turn 的 write 才落盘。这中间的窗口不是纳秒级、而是**无界**的（线程池
+// 饥饿 / 慢同步盘 iCloud·NFS / 进程被 SIGTSTP 停在两步之间）。于是「活着的持有者持有
+// 一个 0 字节锁」是可达状态——曾据此写过一版「回收 0 字节锁」的自愈，被对抗式 PoC 测出
+// maxActive=2（回收者删掉了活持有者正在写的锁），是一次真实的互斥破坏。
+//
+// 正解是从**源头**消灭 0 字节窗口，而不是事后回收它：
+//   1. 把完整 body 写进临时文件 `<lock>.tmp-<token>`（tmp 不在锁路径上，谁也不看它）。
+//   2. `fs.link(tmp, lockFile)` 原子上位——link 要么让 lockFile 指向那个**已写满**的
+//      inode，要么 EEXIST（已被持有）。lockFile 因此**不可能**以 0 字节 / 半截 body 的
+//      形态存在，哪怕一瞬。write 失败也只弄脏 tmp，锁路径始终干净，绝不留死锁残骸。
+// 这样锁文件恒为完整，回收判定不必再去猜「0 字节是死是活」——那条分支整条不存在。
+//
+// ── 不支持 hardlink 的文件系统（降级路径） ──────────────────────────────────
+//
+// 有些文件系统压根不实现 link(2)：veFaaS 容器的 /home、部分 FUSE / 网络盘，link 直接返回
+// ENOTSUP / EPERM / ENOSYS。这类错误不是「锁被占」而是「这台机器上锁机制不可用」，硬抛出去
+// 会让**每一次** config 写盘（login / token 刷新 / 切空间）无条件失败——线上就是这么炸的。
+//
+// 降级到 O_CREAT|O_EXCL 独占创建（`open(lockFile, "wx")`）：
+//   - 互斥性不变：O_EXCL 本身即独占，两个进程不可能同时创建成功。
+//   - 代价是重新出现 create→write 之间的 0 字节窗口。用**同步** open/write/close 把它压进
+//     一条同步代码路径：没有 event-loop turn、不受线程池饥饿或慢盘 await 影响，只有
+//     SIGKILL / 断电能命中（上面那版被 PoC 打穿的旧实现是异步两步，窗口无界）。
+//   - 即便命中，回收器对读不出 owner 的锁一律判 owner_unreadable → 不回收，所以最坏结果是
+//     留一具需人工 rm 的 0 字节残骸（超时错误里已带提示），**绝不会误删活持有者的锁**——
+//     「存活进程持有的锁绝不被回收」这条不变量在降级路径上同样成立。
+// update-service.js 的 acquireUpdateLock 早有同一降级（ENOTSUP/EPERM/ENOSYS → wx）。
+//
+// ── release 与回收 ────────────────────────────────────────────────────────
+//
+// - release：读锁文件 token，匹配自己的才 unlink；不匹配（锁已易主）→ no-op，绝不移动
+//   或删除别人的锁。锁文件要么在锁路径上、要么不存在，等待者的原子 link 语义始终成立。
+// - 回收（orphan reaping）只认**可证明无主**：owner `host` 为本机 **且** kill(pid,0) 抛
+//   ESRCH（PID 明确不存在）。EPERM / 未知错误 / 元数据不可读 / 异机 host 一律按存活处理
+//   ——PID 复用等边界最多让锁延迟释放，绝不以破坏互斥换可用性。回收者通过
+//   `<lock>.reap/` 下的唯一候选做 Bakery 选举，把 token 复核与 unlink 串成单回收者
+//   临界区；候选绑定 PID，进程崩溃后可被后续回收者安全清理。
+// - tmp 清扫：获取时顺带扫描同目录的 `<lock>.tmp-*` 兄弟，仅回收「可证明无主」
+//   （body 可读 + 本机 host + kill(pid,0) ESRCH）的残留——等待窗口内被 SIGKILL/Ctrl+C/
+//   断电终止的进程留下的 tmp 由此收敛，body 读不出的一律不动（见 sweepAbandonedTmpFiles）。
+//
+//   ⚠️ 明确不做「回收 0 字节锁」的自愈：新代码永不产生 0 字节锁，但 rolling upgrade 期间
+//   旧版进程仍可能瞬时留下 0 字节锁，且无法与旧版崩溃残骸区分——回收它就会误删活持有者。
+//   一个升级前遗留的 0 字节残骸会走 owner_unreadable 分支超时（诊断会报 size=0，运维照提示
+//   rm 即可）。这是可控的一次性过渡代价，换取的是绝不破坏互斥。
+
+const DEFAULT_STALE_MS = 10_000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_RETRY_MS = 75;
+const REAPER_CHOOSING_PREFIX = "choosing-";
+const REAPER_TICKET_PREFIX = "ticket-";
+const REAPER_TICKET_WIDTH = 16;
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// 重试间隔加抖动，避免多个等待者被唤醒后同频撞锁（thundering herd）。
+function jitter(baseMs) {
+  return baseMs + Math.floor(Math.random() * baseMs);
+}
+
+// kill(pid, 0) 不发信号只探测：ESRCH = 确认不存在（唯一算「死」的判定）；
+// EPERM（存在但无权限）与任何未知错误一律按存活处理。
+function defaultIsPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== "ESRCH";
+  }
+}
+
+// 文件刚好在 stat 前被释放/回收：返回 null → 调用方按「重试」处理。
+async function statLock(filePath) {
+  try {
+    const stats = await fs.stat(filePath);
+    return { mtimeMs: stats.mtimeMs, size: stats.size };
+  } catch {
+    return null;
+  }
+}
+
+// link(2) 在「文件系统不支持硬链接」时的错误码。EPERM 也算：受限容器 / 开了
+// fs.protected_hardlinks 的内核会用它拒绝 link，语义同样是「这条路走不通」，而不是「锁被占」。
+const NO_HARDLINK_CODES = new Set(["ENOTSUP", "EOPNOTSUPP", "EPERM", "ENOSYS"]);
+
+// 把锁推上锁路径。true = 独占拿到；false = EEXIST（别人持有 → 走争抢/回收判定）。
+// 主路径 link(2)（锁文件恒完整）；FS 不支持 hardlink 时降级到同步 O_EXCL 创建（见头注）。
+async function publishLock({ tmpFile, lockFile, body }) {
+  try {
+    await fs.link(tmpFile, lockFile);
+    return true;
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      return false;
+    }
+    if (!NO_HARDLINK_CODES.has(error?.code)) {
+      throw error;
+    }
+    debugLog("config-lock.hardlink_unsupported", { lockFile, code: error.code });
+  }
+
+  let fd;
+  try {
+    fd = openSync(lockFile, "wx");
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    writeSync(fd, body);
+  } catch (error) {
+    // body 没写成 → 锁路径上只剩一个我们自己刚创建的 0 字节文件。它归我们所有（O_EXCL 保证
+    // 没有第二个持有者），就地删掉，别把残骸留给下一个进程去超时。
+    rmSync(lockFile, { force: true });
+    throw error;
+  } finally {
+    closeSync(fd);
+  }
+  return true;
+}
+
+async function readOwner(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    // 不可读/解析失败（含 0 字节、半截读）→ null。
+    return null;
+  }
+}
+
+// 机会性清扫残留 tmp（Bug 7384601509）：tmp 的生命周期原本只挂在「获取进程走完所有
+// 出口」上——等待窗口内被 SIGINT/SIGTERM/SIGKILL/崩溃/断电终止的进程，其 tmp 因文件名
+// 内嵌 randomUUID 永不复用而永久残留。这里在每次获取时顺带回收同目录的 `<lock>.tmp-*`
+// 兄弟文件，判定与锁文件回收完全同一不变量：**可证明无主才删**（body 可读 + host 为
+// 本机 + isPidAlive 判定 PID 不存在）。body 读不出的 tmp 一律不动（可能是正在写的活
+// 等待者，误删会让其 fs.link 失败于 ENOENT 而不是 EEXIST，错误直接抛给调用方）；异机
+// host 不动（共享 HOME 场景不替别机做主）。清扫 best-effort：任何失败只留 debugLog，
+// 绝不影响获取主流程。
+async function sweepAbandonedTmpFiles(lockFile, { isPidAlive, ownTmp }) {
+  const dir = path.dirname(lockFile);
+  const prefix = `${path.basename(lockFile)}.tmp-`;
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      debugLog("config-lock.tmp_sweep_failed", { lockFile, code: error?.code, message: error?.message });
+    }
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const name = entry.name;
+    // ownTmp 显式跳过：调用方可能注入「一律判死」的 isPidAlive 测试桩，靠探活区分
+    // 不了自己的 tmp；误删自己的 tmp 会让 fs.link 失败于 ENOENT。
+    if (!name.startsWith(prefix) || name === ownTmp) continue;
+    const sibling = path.join(dir, name);
+    const owner = await readOwner(sibling);
+    if (!owner) continue; // body 读不出：无法证明无主，不动
+    if (owner.host !== os.hostname()) continue; // 异机无法探活，不动
+    // process.kill 接受正的 int32 PID；范围外的元数据不能作为死亡证明。
+    if (!Number.isInteger(owner.pid) || owner.pid <= 0 || owner.pid > 0x7fff_ffff) continue;
+    try {
+      if (isPidAlive(owner.pid)) continue; // 存活（含僵尸/PID 复用）一律不删
+    } catch (error) {
+      debugLog("config-lock.tmp_sweep_failed", { tmpFile: sibling, code: error?.code, message: error?.message });
+      continue;
+    }
+    try {
+      await fs.rm(sibling, { force: true });
+    } catch (error) {
+      debugLog("config-lock.tmp_remove_failed", { tmpFile: sibling, code: error?.code, message: error?.message });
+      continue;
+    }
+    debugLog("config-lock.tmp_swept", { tmpFile: sibling, pid: owner.pid });
+  }
+}
+
+/**
+ * 获取 `<targetPath>.lock` 跨进程锁。返回一个幂等的、ownership-checked 的 `release()`。
+ *
+ * 协议：body 先写进 `<lock>.tmp-<token>`，再 `fs.link(tmp, lockFile)` 原子上位（FS 不支持
+ * hardlink 时降级为同步 O_EXCL 创建，见头注）。上位
+ * 成功 = 独占持有；EEXIST = 别人持有 → 若锁 age 超过 staleMs 则判定 owner 是否可证明
+ * 无主（本机 host + kill(0) ESRCH），可证明才回收、回到原子 link 重新竞争；否则
+ * sleep(retry+jitter) 直到拿到或超时。超时抛 `CONFIG_LOCK_TIMEOUT`（调用方应把它当成
+ * 瞬时错误：不清盘、下轮重试），绝不静默降级成无锁写，以免重新引入覆盖竞态。
+ *
+ * @returns {Promise<() => Promise<void>>} release 函数
+ */
+export async function acquireConfigLock(targetPath, {
+  staleMs = DEFAULT_STALE_MS,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  retryMs = DEFAULT_RETRY_MS,
+  now = Date.now,
+  sleep = defaultSleep,
+  isPidAlive = defaultIsPidAlive
+} = {}) {
+  const lockFile = `${targetPath}.lock`;
+  const token = `${randomUUID()}.${process.pid}`;
+  const tmpFile = `${lockFile}.tmp-${token}`;
+  const body = JSON.stringify({ token, pid: process.pid, host: os.hostname(), acquiredAt: now() });
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  const deadline = now() + timeoutMs;
+  // 最后一次「探活后仍决定不回收」的观察。事后唯一能区分「慢临界区」和「真死锁」的证据。
+  let contention = null;
+
+  // 先把完整 body 落进 tmp（O_EXCL 的唯一 tmp 名，绝不撞车）。写失败只弄脏 tmp，
+  // 锁路径始终干净——绝不像旧实现那样在锁路径上留下 0 字节死锁残骸。
+  try {
+    await fs.writeFile(tmpFile, body, { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    await fs.rm(tmpFile, { force: true }).catch(() => {});
+    throw error;
+  }
+
+  try {
+    // 清扫处于自己的 tmp 清理保护区内，且失败不阻断锁获取。
+    await sweepAbandonedTmpFiles(lockFile, { isPidAlive, ownTmp: path.basename(tmpFile) }).catch((error) => {
+      debugLog("config-lock.tmp_sweep_failed", { lockFile, code: error?.code, message: error?.message });
+    });
+    for (;;) {
+      // 原子上位：lockFile 要么指向这个已写满的 inode，要么 EEXIST。link 之后
+      // lockFile 与 tmpFile 是同一 inode 的两个名字，删 tmp 不影响 lockFile。
+      if (!(await publishLock({ tmpFile, lockFile, body }))) {
+        // 已被持有。age 超过 staleMs 才做回收判定（阈值只是省 kill(0) 的触发器，
+        // 不是死亡判定）。
+        const stats = await statLock(lockFile);
+        if (stats !== null && now() - stats.mtimeMs > staleMs) {
+          const ageMs = now() - stats.mtimeMs;
+          const outcome = await reapIfOrphaned(lockFile, { isPidAlive });
+          if (outcome.reaped) {
+            // 回收成功不直接授予锁：回到原子上位与其他等待者公平竞争。
+            debugLog("config-lock.reaped", { lockFile, reason: outcome.reason, ageMs });
+            continue;
+          }
+          contention = { reason: outcome.reason, owner: outcome.owner, ageMs, size: stats.size };
+          // 只在 CODEM_DEBUG 下留痕。绝不能裸 console.warn：bridge 与交互式 linco TUI
+          // 共享 fd 2（linco-runner 用 stdio:"inherit" 起 TUI），TUI 运行期间父进程仍会
+          // 走这条路径写 config（如切空间）——一行诊断会直接刷进 ratatui 的 alternate
+          // screen 且用户无法消除。诊断信息不丢：同样的文本在超时错误的 message 里。
+          debugLog("config-lock.contended", { lockFile, ...contention });
+        }
+        if (now() >= deadline) {
+          // 超时时刻重读一次当前 owner：`contention` 可能是几秒前的观察（锁在期间已易主，
+          // 新持有者一直 fresh 就不再触发探活），直接拿它当「当前持有者」会指认一个早已退出
+          // 的 pid，把运维带去追错的进程。
+          const current = await readOwner(lockFile);
+          const timeout = new Error(
+            `config lock busy after ${timeoutMs}ms: ${lockFile} (${describeContention(contention, current)})`
+          );
+          timeout.code = "CONFIG_LOCK_TIMEOUT";
+          timeout.lockFile = lockFile;
+          timeout.lockOwner = current;
+          timeout.notReclaimedReason = contention?.reason ?? null;
+          throw timeout;
+        }
+        await sleep(jitter(retryMs));
+        continue;
+      }
+
+      // 上位成功 → 我们独占持有。
+      let released = false;
+      return async () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        // Ownership-checked release：token 匹配才删；不匹配/读不到 → no-op，
+        // 绝不移动或删除别人的锁。存活 holder 的锁只有自己会删（见头注不变量），
+        // 所以这里的 read→unlink 无竞态。
+        const owner = await readOwner(lockFile);
+        if (owner?.token === token) {
+          await fs.rm(lockFile, { force: true }).catch(() => {});
+        }
+      };
+    }
+  } finally {
+    // tmp 在所有出口（成功 return / 超时 throw / 其它 error）都不再需要：成功时
+    // lockFile 已是独立的第二个名字，删 tmp 只是丢一个多余的 link，inode 由 lockFile 存续。
+    // 删失败不再静默吞掉（残留 tmp 正是 Bug 7384601509 的累积源之一），与
+    // config-lock.hardlink_unsupported 同风格留痕，便于事后定位。
+    await fs.rm(tmpFile, { force: true }).catch((error) => {
+      debugLog("config-lock.tmp_remove_failed", { tmpFile, code: error?.code, message: error?.message });
+    });
+  }
+}
+
+// orphan 回收：仅当 owner host 为本机且 PID 明确不存在（ESRCH）时 unlink——这是原始的、
+// 唯一可证明无主的回收路径，未作任何放松。unlink 前复核 token 未变（两个回收者竞争同一
+// 具尸体时，输家看到新 holder 的 token 即中止）。
+//
+// 返回 { reaped, reason, owner }。**每条「不回收」的分支都必须带上 reason** —— 这些分支
+// 合起来就是「锁永不回收」的全部入口，一旦命中就是人工 rm 才能解的死锁，而过去它们只
+// 返回一个哑 boolean：超时错误里没有 owner、没有 age、没有判定理由，事后除了猜没有任何
+// 可查的东西（线上曾出现 411 次同一行零信息量的 `config lock busy`，现场被 rm 掉后根因
+// 永久不可判定）。reason 会进超时错误。
+async function reapIfOrphaned(lockFile, { isPidAlive }) {
+  const owner = await readOwner(lockFile);
+  if (!owner) {
+    // 元数据不可读：0 字节（升级前旧版残骸）/ 半截 / 外部工具写的别的格式。无法证明
+    // 无主——尤其 rolling upgrade 期间旧版进程可能瞬时留下 0 字节锁——一律按存活处理。
+    return { reaped: false, reason: "owner_unreadable", owner: null };
+  }
+  if (owner.host !== os.hostname()) {
+    return { reaped: false, reason: "foreign_host", owner }; // 异机无法探活
+  }
+  if (!Number.isInteger(owner.pid) || owner.pid <= 0) {
+    return { reaped: false, reason: "invalid_pid", owner };
+  }
+  if (isPidAlive(owner.pid)) {
+    // 核心不变量：存活进程持有的锁绝不回收。注意 kill(pid,0) 对「僵尸进程」和
+    // 「PID 已被复用」同样返回存活 —— 那类边界宁可延迟释放，也不误回收。
+    return { reaped: false, reason: "owner_alive", owner };
+  }
+  const releaseReaper = await tryAcquireReaperElection(lockFile, { isPidAlive });
+  if (!releaseReaper) {
+    return { reaped: false, reason: "reap_in_progress", owner };
+  }
+  try {
+    // 与 App 共享该选举协议；没有它，另一个 waiter 可在复核后误删新 holder。
+    const recheck = await readOwner(lockFile);
+    if (!recheck || recheck.token !== owner.token) {
+      return { reaped: false, reason: "owner_changed", owner };
+    }
+    await fs.rm(lockFile, { force: true }).catch(() => {});
+    return { reaped: true, reason: "dead_owner", owner };
+  } finally {
+    await releaseReaper();
+  }
+}
+
+// 单次 Bakery 选举：choosing 先声明进入取号门区，ticket 决定全序；失败者退出后由外层
+// 带抖动重试。每个目录名包含唯一 token，所以清理死亡 PID 的候选不会命中新候选。
+async function tryAcquireReaperElection(lockFile, { isPidAlive }) {
+  const reaperDir = `${lockFile}.reap`;
+  const candidateId = `${reaperHostDigest()}.${process.pid}.${randomUUID()}`;
+  const choosingPath = path.join(reaperDir, `${REAPER_CHOOSING_PREFIX}${candidateId}`);
+  let ticketPath = null;
+  let acquired = false;
+
+  await fs.mkdir(reaperDir, { recursive: true });
+  await fs.mkdir(choosingPath);
+  try {
+    try {
+      const observed = await scanReaperCandidates(reaperDir, REAPER_TICKET_PREFIX, { isPidAlive });
+      if (observed.blocked) {
+        return null;
+      }
+      const ticket = observed.candidates.reduce((maximum, entry) => Math.max(maximum, entry.ticket), 0) + 1;
+      if (!Number.isSafeInteger(ticket)) return null;
+      ticketPath = path.join(
+        reaperDir,
+        `${REAPER_TICKET_PREFIX}${String(ticket).padStart(REAPER_TICKET_WIDTH, "0")}-${candidateId}`
+      );
+      await fs.mkdir(ticketPath);
+    } finally {
+      await fs.rm(choosingPath, { recursive: true, force: true });
+    }
+    const choosing = await scanReaperCandidates(reaperDir, REAPER_CHOOSING_PREFIX, { isPidAlive });
+    if (choosing.blocked || choosing.candidates.length > 0) {
+      return null;
+    }
+    const tickets = await scanReaperCandidates(reaperDir, REAPER_TICKET_PREFIX, { isPidAlive });
+    const own = tickets.candidates.find((entry) => entry.candidateId === candidateId);
+    if (tickets.blocked || !own) {
+      return null;
+    }
+    const hasPredecessor = tickets.candidates.some((entry) =>
+      entry.ticket < own.ticket ||
+      (entry.ticket === own.ticket && entry.candidateId < candidateId)
+    );
+    if (hasPredecessor) {
+      return null;
+    }
+    acquired = true;
+    let released = false;
+    return async () => {
+      if (released) return;
+      released = true;
+      await fs.rm(ticketPath, { recursive: true, force: true });
+    };
+  } finally {
+    if (!acquired) {
+      try {
+        await fs.rm(choosingPath, { recursive: true, force: true });
+      } finally {
+        if (ticketPath) await fs.rm(ticketPath, { recursive: true, force: true });
+      }
+    }
+  }
+}
+
+async function scanReaperCandidates(reaperDir, prefix, { isPidAlive }) {
+  let entries;
+  try {
+    entries = await fs.readdir(reaperDir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { blocked: false, candidates: [] };
+    }
+    throw error;
+  }
+
+  const candidates = [];
+  let blocked = false;
+  for (const entry of entries) {
+    if (!entry.name.startsWith(prefix)) continue;
+    // A reserved candidate name with an unexpected file type is not proof of
+    // an absent contender. Preserve it and refuse to reclaim the lock.
+    if (!entry.isDirectory()) {
+      blocked = true;
+      continue;
+    }
+    const parsed = parseReaperCandidate(entry.name, prefix);
+    if (!parsed) {
+      blocked = true;
+      continue;
+    }
+    if (parsed.hostDigest === reaperHostDigest() && parsed.pid !== process.pid && !isPidAlive(parsed.pid)) {
+      await fs.rm(path.join(reaperDir, entry.name), { recursive: true, force: true });
+      continue;
+    }
+    candidates.push(parsed);
+  }
+  return { blocked, candidates };
+}
+
+function reaperHostDigest() {
+  return createHash("sha256").update(os.hostname(), "utf8").digest("hex");
+}
+
+function parseReaperCandidate(name, prefix) {
+  let ticket = 0;
+  let candidateId;
+  if (prefix === REAPER_CHOOSING_PREFIX) {
+    candidateId = name.slice(prefix.length);
+  } else {
+    const match = /^ticket-(\d+)-(.+)$/.exec(name);
+    if (!match) return null;
+    ticket = Number(match[1]);
+    candidateId = match[2];
+    if (!Number.isSafeInteger(ticket) || ticket <= 0) return null;
+  }
+  const identity = /^([a-f0-9]{64})\.([1-9]\d*)\.([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/.exec(candidateId);
+  if (!identity) return null;
+  const pid = Number(identity[2]);
+  if (!Number.isSafeInteger(pid)) return null;
+  return { candidateId, hostDigest: identity[1], pid, ticket };
+}
+
+const NOT_RECLAIMED_REASONS = {
+  owner_unreadable: "lock metadata is empty or unparseable, so it cannot be proven ownerless (a 0-byte lock is left behind by a pre-upgrade crash and must be removed by hand)",
+  foreign_host: "lock was taken on another host, so liveness cannot be probed",
+  invalid_pid: "lock metadata carries no usable pid",
+  owner_alive: "owner process is still alive (note: kill(pid,0) also reports alive for a zombie or a recycled pid)",
+  reap_in_progress: "another process is already rechecking and reclaiming this dead owner's lock",
+  owner_changed: "lock changed hands while probing the owner"
+};
+
+// 渲染一行可诊断的文本。`observation` 是最后一次「判定不回收」的观察（可能已过期），
+// `current` 是超时时刻重读到的持有者 —— 两者分开报，别把陈旧观察当成当前持有者。
+function describeContention(observation, current) {
+  const holder = current
+    ? `held by pid=${current.pid ?? "?"} host=${current.host ?? "?"}`
+    : "holder unreadable or already gone at timeout";
+
+  if (!observation) {
+    // 从未过龄 → 从未探活：短临界区的正常争抢，别报成卡死锁。
+    return `${holder}; lock stayed fresh throughout (never aged past staleMs) — likely normal contention, not a stuck lock`;
+  }
+
+  const { owner, reason, ageMs, size } = observation;
+  const probed = owner
+    ? `pid=${owner.pid ?? "?"} host=${owner.host ?? "?"}`
+    : `owner=<unparseable> size=${size ?? "?"}B`;
+  const age = Number.isFinite(ageMs) ? ` age=${(ageMs / 1000).toFixed(1)}s` : "";
+  const why = NOT_RECLAIMED_REASONS[reason] ?? reason ?? "unknown";
+  return `${holder}; last probe saw ${probed}${age} and did not reclaim because ${why}`;
+}

package/profile/credential-errors.js

@@ -0,0 +1,27 @@
+export function credentialStorageRecovery(errorCode) {
+  const code = String(errorCode).replace(/^credential_storage_/, "");
+  if (code === "backend_load_failed") return {
+    message: "本机凭据模块无法加载",
+    hint: "请重新安装与当前操作系统和架构匹配的完整 CodeM 包；保留现有凭据文件，不要删除或重新生成主密钥。"
+  };
+  if (code !== "corrupt" && code !== "key_missing") return null;
+  return {
+    message: code === "corrupt" ? "本机加密凭据损坏" : "本机凭据主密钥缺失",
+    hint: "请运行 codem report --dry-run --no-session 生成本地诊断包；如有备份，请恢复配套的凭据和主密钥。不要单独删除或重新生成主密钥。"
+  };
+}
+
+export class CredentialStorageError extends Error {
+  constructor(code, kind = null) {
+    const recovery = credentialStorageRecovery(code);
+    super(`Credential storage ${code}${kind ? ` (${kind})` : ""}${recovery ? `。${recovery.message}。${recovery.hint}` : ""}`);
+    this.name = "CredentialStorageError";
+    this.code = `credential_storage_${code}`;
+    this.kind = kind;
+  }
+}
+
+export function isRecoverableCredentialState(error) {
+  return error?.code === "credential_storage_rotation_pending"
+    || error?.code === "credential_storage_rotation_unknown";
+}

package/profile/credential-metadata.js

@@ -0,0 +1,29 @@
+import fs from "node:fs/promises";
+import { CredentialStorageError } from "./credential-errors.js";
+
+export const CREDENTIAL_SCHEMA = 1;
+const KINDS = new Set(["oauth", "router-ak"]);
+const STATES = new Set(["legacy", "preparing", "secure"]);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+function fail(code, kind) { throw new CredentialStorageError(code, kind); }
+
+export async function readCredentialMetadata(metadataPath, marker = null, expectedKind = null) {
+  if (expectedKind && marker && marker.kind !== expectedKind) fail("scope_mismatch", expectedKind);
+  let metadata;
+  try {
+    metadata = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT" && !marker) return null;
+    fail(error.code === "ENOENT" ? "metadata_missing" : "metadata_unreadable");
+  }
+  if (metadata?.schemaVersion !== CREDENTIAL_SCHEMA) fail("incompatible");
+  if (!UUID.test(metadata.scopeId) || !UUID.test(metadata.loginEpoch)
+    || typeof metadata.loggedOut !== "boolean" || !metadata.slots || typeof metadata.slots !== "object") fail("corrupt");
+  for (const [kind, slot] of Object.entries(metadata.slots)) {
+    if (!KINDS.has(kind) || !STATES.has(slot?.state)) fail("corrupt", kind);
+    if (slot.state !== "legacy" && typeof slot.backend !== "string") fail("corrupt", kind);
+    if (slot.rotation && !UUID.test(slot.rotation.operationId)) fail("corrupt", kind);
+  }
+  if (marker && (marker.schemaVersion !== CREDENTIAL_SCHEMA || marker.scopeId !== metadata.scopeId)) fail("scope_mismatch");
+  return metadata;
+}