@marktrue/dsh-mobile-remote 3.2.1-alpha.3-app → 3.2.1-alpha.3

package/lib/session-title-cache.js

@@ -0,0 +1,123 @@
+// issue #20 第 2 步（实现要点 1）：**revision 失效的持久化标题缓存**。
+//
+// 背景（见 issue #20 的 note 702 / 793）：
+// - `/sessions` 在响应前同步折叠**全部休眠会话**的标题，而折叠要完整读取每个会话日志
+//   （追加式多帧 zstd）——隔离实测冷缓存 68.2 s、生产 600 s 未返回。
+// - 内核 `sessionQuery.observeSession(id)` 返回的 lease 带 `revision`（来自**不读日志**的
+//   `persistence.stat()`）。revision 未变即意味着日志没变 → **可以零日志读取地复用标题**。
+// - 但 `stat()` 本身也不便宜（实测 61.9 ms/会话 → 全量 354 个 21.9 s），所以本缓存
+//   **必须同时有界**：条目数有界、每次请求的发散量有界（由调用方的时间预算控制）。
+//
+// 本模块只负责"存与取"，不做调度——预算与 single-flight 由调用方掌握。
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** 默认条目上限：约 1000 个会话足够覆盖常见语料，且文件体积可控（~100 KB 量级）。 */
+export const DEFAULT_MAX_ENTRIES = 1000;
+
+/**
+ * @param {object} options
+ * @param {string} options.file 落盘路径（`~/.dsh/mobile-remote/session-titles.json`）
+ * @param {number} [options.maxEntries] 条目上限（超出按最久未更新淘汰）
+ * @param {() => number} [options.now] 时间源（测试可注入）
+ */
+export const createTitleCache = ({ file, maxEntries = DEFAULT_MAX_ENTRIES, now = Date.now }) => {
+	/** sessionId -> { title: string|null, revision: string, at: number } */
+	const entries = new Map();
+	let dirty = false;
+
+	/**
+	 * 读盘并替换当前内存快照。只接受 version 1；缺失/损坏/未知格式一律降级为空缓存，
+	 * 缓存坏了不该让列表挂掉，也不能把不可信字段当成已确认的标题事实。
+	 */
+	const load = () => {
+		entries.clear();
+		dirty = false;
+		try {
+			if (!existsSync(file)) return;
+			const parsed = JSON.parse(readFileSync(file, "utf8"));
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.version !== 1) return;
+			const raw = parsed.entries;
+			if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+			for (const [id, value] of Object.entries(raw)) {
+				if (id === "") continue;
+				if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+				if (typeof value.revision !== "string" || value.revision === "") continue;
+				// 只有显式 null 才代表“确实没有标题”；缺失或其它类型必须回源，不能伪造命中。
+				if (value.title !== null && typeof value.title !== "string") continue;
+				const title = value.title === "" ? null : value.title;
+				entries.set(id, { title, revision: value.revision, at: typeof value.at === "number" ? value.at : 0 });
+			}
+			prune();
+		} catch {
+			entries.clear();
+		}
+	};
+
+	/**
+	 * 取缓存标题。
+	 * @returns `{ hit: true, title }` 表示 **revision 相同、可零日志读取地复用**；
+	 *          `{ hit: false }` 表示需要回源折叠。
+	 */
+	const get = (id, revision) => {
+		if (typeof id !== "string" || id === "" || typeof revision !== "string" || revision === "") {
+			return { hit: false };
+		}
+		const entry = entries.get(id);
+		if (!entry || entry.revision !== revision) return { hit: false };
+		// 命中也要刷新时间戳：淘汰按"最久未更新"，命中说明这个会话仍活跃。
+		entry.at = now();
+		dirty = true;
+		return { hit: true, title: entry.title };
+	};
+
+	/** 写入（title 允许为 null——"确实没有标题"同样是可缓存的事实）。 */
+	const set = (id, revision, title) => {
+		if (typeof id !== "string" || id === "" || typeof revision !== "string" || revision === "") return;
+		entries.set(id, {
+			title: typeof title === "string" && title !== "" ? title : null,
+			revision,
+			at: now(),
+		});
+		dirty = true;
+		prune();
+	};
+
+	/** 按 `at` 淘汰到上限以内。 */
+	const prune = () => {
+		if (entries.size <= maxEntries) return;
+		const sorted = [...entries.entries()].sort((a, b) => a[1].at - b[1].at);
+		const excess = entries.size - maxEntries;
+		for (let i = 0; i < excess; i += 1) {
+			entries.delete(sorted[i][0]);
+			dirty = true;
+		}
+	};
+
+	/** 原子落盘（临时文件 + rename）。没有变更时是空操作。 */
+	const flush = () => {
+		if (!dirty) return false;
+		try {
+			mkdirSync(dirname(file), { recursive: true });
+			const tmp = `${file}.tmp`;
+			writeFileSync(tmp, JSON.stringify({ version: 1, entries: Object.fromEntries(entries) }), "utf8");
+			renameSync(tmp, file);
+			dirty = false;
+			return true;
+		} catch {
+			// 落盘失败不该影响本次响应：内存缓存仍然有效。
+			return false;
+		}
+	};
+
+	return {
+		load,
+		get,
+		set,
+		flush,
+		size: () => entries.size,
+		/** 仅测试用：直接观察某条目。 */
+		peek: (id) => entries.get(id),
+	};
+};

package/lib/session-title-refresh.js

@@ -0,0 +1,261 @@
+export const DEFAULT_TITLE_REFRESH_BUDGET_MS = 1500;
+export const DEFAULT_TITLE_REFRESH_CONCURRENCY = 4;
+
+/**
+ * Coalesce title refreshes for one corpus pass.
+ *
+ * Why a pass folds in **one** host call (issue #20 review, 2026-10-07):
+ * `sessionQuery.readTitleSnapshots(ids)` is not a point read. The installed
+ * `0.2.0-rc.2` chain is
+ *
+ *     readTitleSnapshots → SessionCorpus.projectMany → listPersisted → persistence.list()
+ *
+ * and `persistence.list()` walks the whole corpus (per-file header + stat, plus
+ * a corpus-wide revision hash while a historical generation is present). Batch
+ * size therefore multiplies corpus enumerations: folding four ids at a time
+ * cost ceil(N/4) full enumerations on top of the pass. The pass now hands every
+ * pending id to one call, so the enumeration count stays constant as N grows;
+ * read width inside that call is the host's own `persistedReadConcurrency`
+ * (default 4, `SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY`, bounded by
+ * `projectMany`'s worker pool), and this module adds no per-id fan-out on top of
+ * it. Only the plugin's own revision scan is bounded here — it reads no logs.
+ *
+ * Waiters may leave independently; the shared pass is cancelled only after its
+ * last waiter leaves, unless a timed-out response promoted it to deliberate
+ * background warm-up. A cancelled pass is retired immediately so the next
+ * request starts a live successor instead of feeding the dead queue, while the
+ * fold gate keeps a retired pass and its successor from overlapping — an
+ * overlap would double the host's read width during cancellation cleanup.
+ */
+export const createSessionTitleRefresher = ({
+	readRevision,
+	readTitles,
+	getCachedTitle,
+	setCachedTitle,
+	onCacheChange = () => {},
+	concurrency = DEFAULT_TITLE_REFRESH_CONCURRENCY,
+} = {}) => {
+	if (typeof readTitles !== "function") throw new TypeError("readTitles must be a function");
+	if (!Number.isSafeInteger(concurrency) || concurrency < 1) throw new RangeError("concurrency must be a positive safe integer");
+	let currentRun = null;
+	let disposed = false;
+	// Serializes fold calls across runs: at most one host title call is in flight
+	// per refresher, so cancellation cleanup cannot overlap fresh read work.
+	let foldTail = Promise.resolve();
+
+	const foldAll = (ids, signal) => {
+		const previous = foldTail;
+		let release;
+		foldTail = new Promise((resolve) => { release = resolve; });
+		return (async () => {
+			try {
+				if (signal.aborted) throw signal.reason ?? new Error("session title refresh aborted");
+				await previous.catch(() => {});
+				if (signal.aborted) throw signal.reason ?? new Error("session title refresh aborted");
+				return await readTitles(ids, signal);
+			} finally {
+				release();
+			}
+		})();
+	};
+
+	const finishRun = (run) => {
+		run.done = true;
+		if (run.deadlineTimer) {
+			clearTimeout(run.deadlineTimer);
+			run.deadlineTimer = null;
+		}
+		if (currentRun === run) currentRun = null;
+		run.resolve();
+	};
+
+	// issue #28 复核 2：**run 级**有限寿命（源级政策）。
+	// 调用者级的 `backgroundOnBudget: false` 只约束「谁不提升」——挡不住后来加入的 HTTP 调用者
+	// 在自己的响应预算到点时把 run 提升为**永久后台**；坏源一旦永生，之后健康的请求会一直 join 它
+	// （只拿到短码），失败隔离就没有闭环。故把截止放在 run 上：到点即中止并退休，**不看 background**。
+	const armRunDeadline = (run) => {
+		if (!Number.isFinite(run.deadlineAt) || run.deadlineTimer) return;
+		const remaining = Math.max(0, run.deadlineAt - performance.now());
+		run.deadlineTimer = setTimeout(() => {
+			run.deadlineTimer = null;
+			if (run.done || run.controller.signal.aborted) return;
+			run.controller.abort(new Error("session-title refresh run exceeded its deadline"));
+			if (currentRun === run) currentRun = null;
+		}, remaining);
+		run.deadlineTimer.unref?.();
+	};
+
+	const processRun = async (run) => {
+		const { signal } = run.controller;
+		try {
+			while (!disposed && !signal.aborted && run.queue.length > 0) {
+				// Drain everything queued so far into this round: revisions first
+				// (bounded workers, no log reads), then a single fold call.
+				const pending = run.queue.splice(0, run.queue.length);
+				const misses = [];
+				let cursor = 0;
+				const scanRevisions = async () => {
+					for (;;) {
+						if (disposed || signal.aborted) return;
+						const index = cursor;
+						cursor += 1;
+						if (index >= pending.length) return;
+						const id = pending[index];
+						let revision = null;
+						if (typeof readRevision === "function") {
+							try {
+								const observed = await readRevision(id, signal);
+								revision = typeof observed === "string" && observed !== "" ? observed : null;
+							} catch (error) {
+								if (signal.aborted) throw error;
+							}
+						}
+						if (disposed || signal.aborted) return;
+						const cached = getCachedTitle?.(id, revision);
+						if (cached?.hit) run.results.set(id, cached.title);
+						else misses.push({ index, id, revision });
+					}
+				};
+				await Promise.all(Array.from(
+					{ length: Math.min(concurrency, pending.length) },
+					() => scanRevisions(),
+				));
+				if (disposed || signal.aborted) break;
+				// Worker completion order is not the request order; keep the fold
+				// deterministic (and stable for the host's first-occurrence ordering).
+				misses.sort((a, b) => a.index - b.index);
+
+				if (misses.length > 0) {
+					let folded;
+					try {
+						folded = await foldAll(misses.map(({ id }) => id), signal);
+					} catch (error) {
+						if (signal.aborted) throw error;
+						folded = new Map();
+					}
+					if (disposed || signal.aborted) break;
+					for (const { id, revision } of misses) {
+						const result = folded?.get?.(id);
+						if (!result?.ok) continue;
+						const title = typeof result.title === "string" && result.title !== "" ? result.title : null;
+						setCachedTitle?.(id, revision, title);
+						run.results.set(id, title);
+					}
+				}
+				onCacheChange();
+			}
+		} catch {
+			// An aborted or faulty refresh is a cache miss, never an endpoint failure.
+		} finally {
+			finishRun(run);
+		}
+	};
+
+	const addIds = (run, ids) => {
+		for (const id of ids) {
+			if (typeof id !== "string" || id === "" || run.seen.has(id)) continue;
+			run.seen.add(id);
+			run.queue.push(id);
+		}
+	};
+
+	const createRun = (ids) => {
+		let resolve;
+		const promise = new Promise((done) => { resolve = done; });
+		const run = {
+			controller: new AbortController(),
+			queue: [],
+			seen: new Set(),
+			results: new Map(),
+			waiters: 0,
+			background: false,
+			deadlineAt: Infinity,
+			deadlineTimer: null,
+			done: false,
+			promise,
+			resolve,
+		};
+		addIds(run, ids);
+		currentRun = run;
+		void processRun(run);
+		return run;
+	};
+
+	const refresh = async (ids, { signal, budgetMs = DEFAULT_TITLE_REFRESH_BUDGET_MS, backgroundOnBudget = true, runDeadlineMs } = {}) => {
+		if (disposed || signal?.aborted) return new Map();
+		const uniqueIds = [...new Set(ids)].filter((id) => typeof id === "string" && id !== "");
+		if (uniqueIds.length === 0) return new Map();
+		if (!Number.isFinite(budgetMs) || budgetMs < 0) throw new RangeError("budgetMs must be a non-negative finite number");
+
+		// A run whose upstream was already aborted can no longer consume its queue:
+		// joining it would park this request's ids in a dead queue and hand back a
+		// partial result. Retire it and start a live successor instead; the fold
+		// gate keeps the successor's work behind the retiring pass's cleanup.
+		let run = currentRun;
+		if (!run || run.done || run.controller.signal.aborted) run = createRun(uniqueIds);
+		else addIds(run, uniqueIds);
+		// issue #28 复核 2：run 级截止（取所有声明中**最早**者——只收紧、不放松）。
+		// 它不因后来调用者的 background promotion 而失效：到点由 armRunDeadline 退休该 run。
+		if (Number.isFinite(runDeadlineMs) && runDeadlineMs >= 0) {
+			const nextAt = performance.now() + runDeadlineMs;
+			// 只在**收紧**时重设：后来者更晚的声明不得延长期限（issue #28 复核 3）。
+			if (nextAt < run.deadlineAt) {
+				run.deadlineAt = nextAt;
+				// 旧 timer 必须先清掉再重设——armRunDeadline 见到已有 deadlineTimer 会直接返回，
+				// 那样「收紧」就静默失效（评审实测：先声明 300ms、后声明 20ms，源仍按 300ms 才取消）。
+				if (run.deadlineTimer) {
+					clearTimeout(run.deadlineTimer);
+					run.deadlineTimer = null;
+				}
+				armRunDeadline(run);
+			}
+		}
+		run.waiters += 1;
+		let released = false;
+		const release = () => {
+			if (released) return;
+			released = true;
+			run.waiters -= 1;
+			if (!run.done && !run.background && run.waiters === 0) {
+				run.controller.abort(new Error("all session-title refresh waiters left"));
+			}
+		};
+
+		let timer;
+		let abortHandler;
+		const interrupted = new Promise((resolve) => {
+			if (signal) {
+				abortHandler = () => resolve("aborted");
+				signal.addEventListener("abort", abortHandler, { once: true });
+			}
+			timer = setTimeout(() => resolve("budget"), budgetMs);
+		});
+		const outcome = await Promise.race([
+			run.promise.then(() => "done"),
+			interrupted,
+		]);
+		clearTimeout(timer);
+		if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
+
+		// issue #28 复核 BLOCKING 2：调用方可以要求**有限生命期**。默认（响应路径）预算到点会把
+		// run 提升为「后台预热」并长期存活；但启动预热**不能**这样——否则一次挂住的预热会让之后
+		// 健康的请求一直 join 这个坏 run、只拿到短码。传 `backgroundOnBudget: false` 时不做提升，
+		// 于是下面的 release() 在没有其它等待者时会中止该 run（退休），健康请求随后可重新开始。
+		if (outcome === "budget" && backgroundOnBudget && !signal?.aborted && !run.done) run.background = true;
+		const aborted = signal?.aborted === true;
+		release();
+		return aborted ? new Map() : new Map(run.results);
+	};
+
+	return {
+		refresh,
+		dispose() {
+			disposed = true;
+			currentRun?.controller.abort(new Error("session-title refresher disposed"));
+		},
+		/** Test seam: resolve when the current single-flight pass settles. */
+		whenIdle() {
+			return currentRun?.promise ?? Promise.resolve();
+		},
+	};
+};

package/lib/update-fetch.js

@@ -0,0 +1,24 @@
+// Host credentials are scoped to the explicit loopback origin and update routes, not to arbitrary release URLs.
+export async function fetchUpdateResource(url, {
+  fetchImpl = fetch, token = '', trustedOrigin = '', basePath = '/m', headers = {}, signal, maxRedirects = 5,
+} = {}) {
+  // 精确路径集合：同 origin 的其它处理器（如 /other-plugin/api/update/manifest）不得拿到口令。
+  const mount = basePath === '/' || basePath === '' ? '/m' : basePath.replace(/\/$/, '');
+  const allowedPaths = new Set([`${mount}/api/update/manifest`, `${mount}/api/update/plugin`, `${mount}/api/update/apk`]);
+  let target = new URL(url);
+  for (let hops = 0; hops <= maxRedirects; hops++) {
+    if (target.username || target.password || !(['https:'].includes(target.protocol) ||
+      (target.protocol === 'http:' && ['127.0.0.1','localhost','[::1]'].includes(target.hostname)))) throw new Error('update-url-not-allowed');
+    const authAllowed = Boolean(token) && trustedOrigin !== '' && target.origin === trustedOrigin &&
+      allowedPaths.has(target.pathname);
+    const response = await fetchImpl(target.toString(), {
+      headers: { ...headers, ...(authAllowed ? { 'x-mobile-token': token } : {}) }, redirect: 'manual', signal,
+    });
+    if (![301,302,303,307,308].includes(response.status)) return { response, finalUrl: target.toString() };
+    const location = response.headers.get('location');
+    if (!location) throw new Error('update-redirect-missing');
+    await response.body?.cancel?.();
+    target = new URL(location, target);
+  }
+  throw new Error('update-redirect-limit');
+}

package/lib/update-lock-arbiter.js

@@ -0,0 +1,158 @@
+// Runs only under an OS flock on a persistent inode. No lock-directory unlink/rename races.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync, symlinkSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+function read(file) { try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; } }
+function atomic(file, value) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  try { writeFileSync(tmp, JSON.stringify(value) + '\n', { mode: 0o600 }); renameSync(tmp, file); }
+  finally { if (existsSync(tmp)) rmSync(tmp); }
+}
+function identity(pid) {
+  try { const text = readFileSync(`/proc/${pid}/stat`, 'utf8'); return { pid, start: text.slice(text.lastIndexOf(')') + 2).split(' ')[19] }; }
+  catch { return { pid, start: null }; }
+}
+function alive(person) {
+  if (!person?.pid || !Number.isInteger(person.pid)) return false;
+  try { process.kill(person.pid, 0); } catch(e) { return e.code === 'EPERM'; }
+  return !person.start || identity(person.pid).start === person.start;
+}
+function owns(holder, lease) { return !!lease?.generation && holder?.generation === lease.generation && holder.opId === lease.opId; }
+function fence(holder, lease) { if (!owns(holder, lease)) throw new Error('lease-lost'); }
+function terminal(phase) { return ['settled', 'rolled-back', 'failed'].includes(phase); }
+
+function execute(input) {
+  const { lockPath, operation, lease, stateFile } = input;
+  const holderFile = join(lockPath, 'holder.json');
+  let holder = read(holderFile);
+  const available = !holder || ![holder.worker, holder.supervisor].some(alive);
+  if (operation === 'acquire') {
+    if (holder && owns(holder, lease)) return { ok: true, lease, holder, reentrant: true };
+    // Missing publication is not evidence of owner death. Legacy half-locks require manual repair.
+    if (existsSync(lockPath) && !existsSync(holderFile)) return { ok: false, error: 'lock-unpublished' };
+    if (!available) return { ok: false, error: 'update-busy', holder };
+    if (input.stateFile) {
+      const tx = read(input.stateFile);
+      // 安装/待生效/回滚未完成时，**任何**新操作都不得开始——即使锁已被误释放（holder 为空）。
+      if (tx && ['installing','restart-pending','rolling-back'].includes(tx.phase) &&
+          (!lease || tx.lease?.generation !== lease.generation)) {
+        return { ok: false, error: 'recovery-required', holder, transaction: tx };
+      }
+    }
+    holder = { opId: input.opId, generation: randomUUID(), worker: identity(input.pid), pid: input.pid, at: input.now };
+    mkdirSync(lockPath, { recursive: true }); atomic(holderFile, holder);
+    return { ok: true, holder, lease: { opId: holder.opId, generation: holder.generation } };
+  }
+  if (operation === 'release') {
+    if (!owns(holder, lease)) return { ok: false, error: 'lease-lost' };
+    const tx = input.stateFile ? read(input.stateFile) : null;
+    if (tx && tx.lease?.generation === lease.generation && ['installing','restart-pending','rolling-back'].includes(tx.phase)) {
+      return { ok: false, error: 'recovery-required' };
+    }
+    atomic(holderFile, null); return { ok: true };
+  }
+  if (operation === 'handover') {
+    fence(holder, lease);
+    holder = { ...holder, supervisor: identity(input.toPid), pid: input.toPid };
+    atomic(holderFile, holder); return { ok: true, holder };
+  }
+  if (operation === 'assert') { fence(holder, lease); return { ok: true, holder }; }
+  if (operation === 'state-write') {
+    fence(holder, lease);
+    if (input.tx.opId !== lease.opId) throw new Error('operation-mismatch');
+    const old = read(stateFile);
+    if (old?.lease && old.lease.generation !== lease.generation && !terminal(old.phase)) throw new Error('transaction-generation-mismatch');
+    // 阶段 CAS：旧 worker 不能把"已被别人推进的阶段"改回去（如 failed → installing）。
+    if (old && old.opId === input.tx.opId) {
+      if (input.expectedPhases && !input.expectedPhases.includes(old.phase)) throw new Error('phase-cas-failed');
+      if (terminal(old.phase) && !terminal(input.tx.phase)) throw new Error('terminal-regression');
+    }
+    const next = { ...input.tx, lease, id: lease.generation, updatedAt: new Date().toISOString() };
+    atomic(stateFile, next);
+    if (input.currentFile && input.currentFile !== stateFile) atomic(input.currentFile, next);
+    return { ok: true, transaction: next };
+  }
+  if (operation === 'switch-profile') {
+    fence(holder, lease);
+    const file = join(input.profileDir, 'package.json'), doc = read(file);
+    const key = input.key || 'dsh-mobile-remote';
+    const previous = doc?.dependencies?.[key];
+    if (typeof previous !== 'string') throw new Error('profile-dependency-missing');
+    doc.dependencies[key] = input.specifier; atomic(file, doc);
+    return { ok: true, previous, next: input.specifier };
+  }
+  if (operation === 'restore-profile') {
+    fence(holder, lease);
+    const file = join(input.profileDir, 'package.json');
+    const doc = input.snapshot?.packageJson ? JSON.parse(input.snapshot.packageJson) : read(file);
+    if (!doc?.dependencies) throw new Error('profile-dependencies-missing');
+    const key = input.key || 'dsh-mobile-remote';
+    doc.dependencies[key] = `file:${input.snapshotDir}`; atomic(file, doc);
+    const lockfile = join(input.profileDir, 'pnpm-lock.yaml');
+    if (typeof input.snapshot?.pnpmLock === 'string') writeFileSync(lockfile, input.snapshot.pnpmLock, { mode: 0o600 });
+    else if (input.snapshot?.pnpmLock === null && existsSync(lockfile)) rmSync(lockfile);
+    return { ok: true };
+  }
+  if (operation === 'publish-snapshot-link') {
+    fence(holder, lease);
+    const modules = join(input.profileDir, 'node_modules'); mkdirSync(modules, { recursive: true });
+    // Never traverse an unexpected node_modules symlink into another profile.
+    if (realpathSync(modules) !== join(realpathSync(input.profileDir), 'node_modules')) throw new Error('profile-modules-outside-root');
+    const target = join(modules, 'dsh-mobile-remote');
+    const staged = `${target}.restore-${randomUUID()}`, previous = `${target}.previous-${randomUUID()}`;
+    symlinkSync(realpathSync(input.snapshotDir), staged, 'dir');
+    let moved = false;
+    try {
+      try { renameSync(target, previous); moved = true; } catch(e) { if (e.code !== 'ENOENT') throw e; }
+      renameSync(staged, target);
+    } catch(e) { if (moved && !existsSync(target)) renameSync(previous, target); throw e; }
+    finally { if (existsSync(staged)) rmSync(staged); }
+    // Retain the quarantined old link/tree; never delete active hardlinked module files in place.
+    return { ok: true, installedRoot: target };
+  }
+  if (operation === 'claim-recovery') {
+    fence(holder, lease);
+    const tx = read(stateFile);
+    if (!tx || tx.opId !== lease.opId || tx.lease?.generation !== lease.generation) throw new Error('operation-mismatch');
+    if (tx.phase !== 'rolling-back') throw new Error('not-recovering');
+    // 同代的两个监督器只能有一个执行恢复：先到者写 claim，后到者拿到 claimed。
+    if (tx.recoveryClaim && tx.recoveryClaim.owner !== input.owner) return { ok: false, error: 'recovery-claimed', transaction: tx };
+    const next = { ...tx, recoveryClaim: { owner: input.owner, at: input.now } };
+    atomic(stateFile, next);
+    if (input.currentFile && input.currentFile !== stateFile) atomic(input.currentFile, next);
+    return { ok: true, transaction: next };
+  }
+  if (operation === 'finish-terminal') {
+    fence(holder, lease);
+    const tx = read(stateFile);
+    if (!tx || tx.opId !== lease.opId || tx.lease?.generation !== lease.generation) throw new Error('operation-mismatch');
+    if (input.expectedPhases && !input.expectedPhases.includes(tx.phase)) throw new Error('phase-cas-failed');
+    if (!terminal(input.phase)) throw new Error('not-a-terminal-phase');
+    const next = { ...tx, phase: input.phase, result: input.result, lease, id: lease.generation, updatedAt: new Date().toISOString() };
+    atomic(stateFile, next);
+    if (input.currentFile && input.currentFile !== stateFile) atomic(input.currentFile, next);
+    // 发布终态与释放锁是一次仲裁：中间不存在"已终态但锁仍被旧代持有/已被释放"的空窗。
+    atomic(holderFile, null);
+    return { ok: true, transaction: next };
+  }
+  if (operation === 'converge') {
+    const tx = read(stateFile);
+    if (!tx) return { ok: true, action: 'none', transaction: null };
+    if (terminal(tx.phase)) return { ok: true, action: 'terminal', transaction: tx };
+    if (input.expectedLease && !owns(holder, input.expectedLease)) return { ok: true, action: 'superseded', transaction: tx };
+    if (holder && [holder.worker, holder.supervisor].some(alive)) return { ok: true, action: 'active', transaction: tx };
+    if (existsSync(lockPath) && !existsSync(holderFile)) return { ok: true, action: 'recent', transaction: tx };
+    // Never relabel a possibly damaged install as an ordinary terminal failure.
+    if (['installing','restart-pending','rolling-back'].includes(tx.phase)) return { ok: true, action: 'recovery-required', transaction: tx };
+    if (input.now - Date.parse(tx.startedAt) < input.staleMs) return { ok: true, action: 'recent', transaction: tx };
+    if (tx.lease && holder && !owns(holder, tx.lease)) return { ok: true, action: 'superseded', transaction: tx };
+    const next = { ...tx, phase: 'failed', result: { ok: false, reason: 'holder-gone' } };
+    atomic(stateFile, next); if (holder) atomic(holderFile, null);
+    return { ok: true, action: 'converged', transaction: next };
+  }
+  throw new Error('unknown-arbitration-operation');
+}
+try { console.log(JSON.stringify(execute(JSON.parse(readFileSync(0, 'utf8'))))); }
+catch(e) { console.log(JSON.stringify({ ok: false, error: e.message })); }