@ellieyujin/pi-reopen 0.0.0-stage → 0.2.0-dev.0

package/extensions/open-all.ts

@@ -0,0 +1,232 @@
+/**
+ * pi-workspace 扩展：登记存活 Pi、区分主动退出与被动死亡、提供 Pi 内恢复入口。
+ * 核心逻辑在项目 src/*.js（CLI 共用）；本文件只做 Pi 侧适配。
+ */
+import { realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+
+function resolveSrcDir(): string {
+	const candidates: string[] = [];
+	if (process.env.PI_WORKSPACE_SRC) candidates.push(process.env.PI_WORKSPACE_SRC);
+	try {
+		candidates.push(join(dirname(realpathSync(fileURLToPath(import.meta.url))), "..", "src"));
+	} catch {
+		/* import.meta.url 不可用时忽略 */
+	}
+	for (const dir of candidates) {
+		try {
+			realpathSync(join(dir, "restore.js"));
+			return dir;
+		} catch {
+			/* 尝试下一个候选 */
+		}
+	}
+	throw new Error("无法定位 pi-workspace 源码目录；可设置 PI_WORKSPACE_SRC");
+}
+
+const ENTRY_WINDOW_MS = 24 * 3_600_000;
+
+export default async function (pi: ExtensionAPI) {
+	const srcDir = resolveSrcDir();
+	const load = async (name: string) => await import(pathToFileURL(join(srcDir, name)).href);
+	const { workspacePaths } = await load("paths.js");
+	const members = await load("members.js");
+	const liveness = await load("liveness.js");
+	const claims = await load("claims.js");
+	const restore = await load("restore.js");
+	const spawn = await load("spawn.js");
+	const preflightMod = await load("preflight.js");
+	const fs = await import("node:fs");
+	const paths = workspacePaths();
+
+	let currentSessionId: string | undefined;
+	let signalExit = false;
+	const signals = process.platform === "win32" ? ["SIGTERM"] as const : ["SIGHUP", "SIGTERM"] as const;
+	const markSignalExit = () => { signalExit = true; };
+	function detachSignals(): void {
+		for (const signal of signals) process.off(signal, markSignalExit);
+	}
+
+	// 测试钩子：仅在设置 PI_WORKSPACE_HOOKS 时生效，返回 runRestore 的注入参数
+	async function loadHooks(): Promise<any> {
+		const file = process.env.PI_WORKSPACE_HOOKS;
+		if (!file) return {};
+		try {
+			const mod = await import(pathToFileURL(file).href);
+			return typeof mod.default === "function" ? await mod.default() : mod;
+		} catch {
+			return {};
+		}
+	}
+
+	pi.on("session_start", (_event: unknown, ctx: any) => {
+		detachSignals();
+		signalExit = false;
+		if (ctx.mode === "tui") {
+			for (const signal of signals) process.on(signal, markSignalExit);
+		}
+		register(ctx);
+	});
+
+	// 全新会话启动时文件尚未落盘；首条用户消息后补登记，此后每次发消息刷新时间戳
+	pi.on("message_end", (event: any, ctx: any) => {
+		if (event?.message?.role === "user") register(ctx);
+	});
+
+	function register(ctx: any): void {
+		if (ctx.mode !== "tui") return;
+		const sessionFile = ctx.sessionManager.getSessionFile();
+		if (!sessionFile) return; // 仍未落盘的空窗口，不登记（恢复时跳过）
+		currentSessionId = ctx.sessionManager.getSessionId();
+		members.writeMember({
+			sessionId: currentSessionId,
+			cwd: ctx.cwd,
+			sessionFile,
+			name: ctx.sessionManager.getSessionName(),
+			ts: Date.now(),
+			pid: process.pid,
+			processStart: liveness.processStart(process.pid),
+			bootId: liveness.currentBootId(),
+		});
+		claims.releaseClaim(currentSessionId, paths);
+	}
+
+	pi.on("session_shutdown", async (event: any) => {
+		// Pi also emits quit for SIGHUP/SIGTERM. Let all signal listeners run first.
+		if (event.reason === "quit") await new Promise<void>((resolve) => setImmediate(resolve));
+		try {
+			if (!currentSessionId || event.reason === "reload") return;
+			if (event.reason === "quit" && signalExit) return;
+			if (["quit", "new", "resume", "fork"].includes(event.reason)) {
+				members.deleteMember(currentSessionId, paths);
+			}
+		} finally {
+			detachSignals();
+			currentSessionId = undefined;
+		}
+	});
+
+	async function restoreAndReport(ctx: any, dryRun = false): Promise<void> {
+		const result = await restore.runRestore({ dryRun, ...(await loadHooks()) });
+		for (const line of restore.summarize(result)) ctx.ui.notify(line, result.ok ? "info" : "warning");
+	}
+
+	async function openRecent(ctx: any): Promise<void> {
+		const now = Date.now();
+		const candidates: any[] = [];
+		try {
+			for (const dir of fs.readdirSync(paths.sessions)) {
+				const p = join(paths.sessions, dir);
+				let files: string[];
+				try {
+					files = fs.readdirSync(p).filter((f: string) => f.endsWith(".jsonl"));
+				} catch {
+					continue;
+				}
+				for (const file of files) {
+					const full = join(p, file);
+					try {
+						const mtime = fs.statSync(full).mtimeMs;
+						if (now - mtime > ENTRY_WINDOW_MS) continue;
+						// 只读首行取会话头，避免加载整个会话文件（可达数 MB）
+						const fd = fs.openSync(full, "r");
+						let firstLine: string;
+						try {
+							const buf = Buffer.alloc(65536);
+							const bytes = fs.readSync(fd, buf, 0, buf.length, 0);
+							const chunk = buf.subarray(0, bytes).toString("utf8");
+							const nl = chunk.indexOf("\n");
+							firstLine = nl === -1 ? chunk : chunk.slice(0, nl);
+						} finally {
+							fs.closeSync(fd);
+						}
+						const header = JSON.parse(firstLine);
+						if (header.id && header.cwd) {
+							candidates.push({ sessionId: header.id, cwd: header.cwd, sessionFile: full, ts: mtime });
+						}
+					} catch {
+						/* 跳过损坏文件 */
+					}
+				}
+			}
+		} catch {
+			/* 无会话目录 */
+		}
+		const live = new Set(members.listMembers(paths).filter((m: any) => liveness.isLive(m)).map((m: any) => m.sessionId));
+		const own = currentSessionId;
+		const todo = candidates
+			.filter((c) => c.sessionId !== own && !live.has(c.sessionId))
+			.sort((a, b) => b.ts - a.ts);
+		if (!todo.length) {
+			ctx.ui.notify("近 24 小时没有可补选的对话", "info");
+			return;
+		}
+		const list = todo
+			.map((e, i) => `${i + 1}. ${new Date(e.ts).toLocaleString()} | ${e.cwd} | ${e.name ?? e.sessionId}`)
+			.join("\n");
+		const input = await ctx.ui.input(`近期候选（不代表原先打开的窗口）\n${list}\n输入序号，多个用逗号分隔；取消则不打开`);
+		if (!input?.trim()) return;
+		const parts = input.trim().split(/[\s,，]+/);
+		if (parts.some((p: string) => !/^\d+$/.test(p) || Number(p) < 1 || Number(p) > todo.length)) {
+			ctx.ui.notify("序号无效，未打开标签页", "warning");
+			return;
+		}
+		const selected = [...new Set(parts.map(Number))].map((n: number) => todo[n - 1]);
+		if (!(await ctx.ui.confirm("恢复选中的 Pi 对话？", selected.map((e: any) => `${e.cwd} | ${e.name ?? e.sessionId}`).join("\n")))) return;
+		const pre = preflightMod.preflight();
+		if (!pre.ok) {
+			for (const line of restore.summarize({ ok: false, stage: "preflight", checks: pre.checks })) {
+				ctx.ui.notify(line, "warning");
+			}
+			return;
+		}
+		let opened = 0;
+		for (const entry of selected) {
+			const claim = claims.claimSession(entry.sessionId, process.pid, paths);
+			if (!claim.claimed) continue;
+			const result = await spawn.openTab({
+				wezterm: pre.wezterm,
+				distro: pre.distro,
+				piBin: pre.piBin,
+				cwd: entry.cwd,
+				sessionFile: entry.sessionFile,
+			});
+			if (result.ok) {
+				members.writeMember({ ...entry, pid: undefined, processStart: undefined, bootId: undefined, ts: Date.now() });
+				opened++;
+			} else {
+				claims.releaseClaim(entry.sessionId, paths);
+				ctx.ui.notify(`${entry.cwd}：WezTerm 请求失败 — ${result.error}`, "warning");
+			}
+		}
+		ctx.ui.notify(opened ? `已请求打开 ${opened} 个 pi 终端` : "没有打开任何标签页", opened ? "info" : "warning");
+	}
+
+	pi.registerCommand("all", {
+		description: "恢复已登记的 pi 终端（/all recent 补选历史；/all clear 清空登记）",
+		handler: async (args: string, ctx: any) => {
+			const arg = (args ?? "").trim();
+			if (arg === "clear") {
+				const removed = members.clearWorkspace(paths);
+				ctx.ui.notify(`已清空 ${removed} 条登记；对话文件未删除`, "info");
+				return;
+			}
+			if (arg === "recent") return openRecent(ctx);
+			if (arg) {
+				ctx.ui.notify("用法：/all | /all recent | /all clear", "warning");
+				return;
+			}
+			await restoreAndReport(ctx);
+		},
+	});
+
+	pi.registerShortcut(Key.ctrlShift("o"), {
+		description: "一键恢复上次所有 pi 终端",
+		handler: async (ctx: any) => {
+			await restoreAndReport(ctx);
+		},
+	});
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@ellieyujin/pi-reopen",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "license": "MIT",
+  "version": "0.2.0-dev.0",
+  "description": "Restore recorded Pi sessions in Windows WezTerm tabs from WSL; includes a Pi extension and standalone CLI.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bridge-01/pi-workspace.git"
+  },
+  "homepage": "https://github.com/bridge-01/pi-workspace#readme",
+  "bugs": {
+    "url": "https://github.com/bridge-01/pi-workspace/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "next"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "workspace",
+    "wezterm",
+    "wsl"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "bin",
+    "README.md",
+    "docs"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/open-all.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "bin": {
+    "pi-workspace": "bin/pi-workspace.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  }
+}

package/src/binfmt.js

@@ -0,0 +1,51 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+
+const BINFMT_ENTRY = "/proc/sys/fs/binfmt_misc/WSLInterop";
+const CONF_DIRS = ["/etc/binfmt.d", "/usr/lib/binfmt.d", "/run/binfmt.d", "/lib/binfmt.d"];
+export const BINFMT_CONF_CONTENT = ":WSLInterop:M::MZ::/init:PF";
+
+export const PERSIST_HINT =
+	"WSLInterop 注册可能在 WSL 重启后再次丢失（未发现 binfmt.d 持久化配置）。\n" +
+	"一次性持久化（需 sudo 密码，工具不会自动执行）：\n" +
+	`printf '%s\\n' '${BINFMT_CONF_CONTENT}' | sudo tee /usr/lib/binfmt.d/WSLInterop.conf >/dev/null\n` +
+	"echo -1 | sudo tee /proc/sys/fs/binfmt_misc/WSLInterop >/dev/null\n" +
+	"sudo systemctl restart systemd-binfmt";
+
+/**
+ * WSLInterop 注册状态与持久化状态：
+ * - registered：当前内核是否已注册（恢复可用性的前提）
+ * - persistent：是否存在 binfmt.d 配置，使 systemd-binfmt 在启动时自动补注册
+ */
+export function binfmtStatus(deps = {}) {
+	const exists = deps.exists ?? existsSync;
+	const readFile = deps.readFile ?? ((p) => readFileSync(p, "utf8"));
+	const readdir = deps.readdir ?? readdirSync;
+	const registered = exists(BINFMT_ENTRY);
+	let persistent = false;
+	for (const dir of CONF_DIRS) {
+		if (!exists(dir)) continue;
+		let files;
+		try {
+			files = readdir(dir);
+		} catch {
+			continue;
+		}
+		for (const file of files) {
+			const path = `${dir}/${file}`;
+			if (file.toLowerCase().includes("wslinterop")) {
+				persistent = true;
+				break;
+			}
+			try {
+				if (readFile(path).includes(":WSLInterop:")) {
+					persistent = true;
+					break;
+				}
+			} catch {
+				/* 不可读文件（目录等）忽略 */
+			}
+		}
+		if (persistent) break;
+	}
+	return { registered, persistent };
+}

package/src/claims.js

@@ -0,0 +1,67 @@
+import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { processStart } from "./liveness.js";
+import { workspacePaths } from "./paths.js";
+
+export const CLAIM_TTL_MS = 60_000;
+
+function writeAtomic(file, data) {
+	const temp = `${file}.${process.pid}.tmp`;
+	writeFileSync(temp, data, { mode: 0o600 });
+	renameSync(temp, file);
+}
+
+export function readClaim(sessionId, paths = workspacePaths()) {
+	try {
+		return JSON.parse(readFileSync(join(paths.claims, `${sessionId}.json`), "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * 声明“本会话正在被启动”，防止并发/连续恢复重复开标签页。
+ * 已有声明在 TTL 内且持有者进程存活时视为占用；过期或持有者已死则接管。
+ */
+export function claimSession(sessionId, ownerPid, paths = workspacePaths(), now = Date.now()) {
+	mkdirSync(paths.claims, { recursive: true });
+	const existing = readClaim(sessionId, paths);
+	if (
+		existing &&
+		existing.pid !== ownerPid &&
+		now - existing.ts < CLAIM_TTL_MS &&
+		processStart(existing.pid) !== undefined
+	) {
+		return { claimed: false, holder: existing };
+	}
+	writeAtomic(join(paths.claims, `${sessionId}.json`), JSON.stringify({ pid: ownerPid, ts: now }));
+	return { claimed: true };
+}
+
+/** 新 Pi 完成登记时清除自己的启动声明。 */
+export function releaseClaim(sessionId, paths = workspacePaths()) {
+	try {
+		unlinkSync(join(paths.claims, `${sessionId}.json`));
+	} catch {
+		/* 不存在即目标状态 */
+	}
+}
+
+/** 清理过期或持有者已死的声明（恢复前调用）。 */
+export function sweepClaims(paths = workspacePaths(), now = Date.now()) {
+	let files;
+	try {
+		files = readdirSync(paths.claims);
+	} catch {
+		return;
+	}
+	for (const file of files.filter((f) => f.endsWith(".json"))) {
+		try {
+			const claim = JSON.parse(readFileSync(join(paths.claims, file), "utf8"));
+			const dead = now - claim.ts >= CLAIM_TTL_MS || processStart(claim.pid) === undefined;
+			if (dead) unlinkSync(join(paths.claims, file));
+		} catch {
+			/* 损坏声明留待 TTL 后接管 */
+		}
+	}
+}

package/src/cli.js

@@ -0,0 +1,69 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { binfmtStatus, PERSIST_HINT } from "./binfmt.js";
+import { workspacePaths } from "./paths.js";
+import { currentBootId, isLive } from "./liveness.js";
+import { clearWorkspace } from "./members.js";
+import { inspect, label, runRestore, summarize } from "./restore.js";
+import { preflight } from "./preflight.js";
+
+const USAGE = `pi-workspace — 恢复上次的 Pi 终端组合
+
+用法：
+  pi-workspace restore [--dry-run] [--no-wait]   恢复关闭终端时仍打开的 Pi（补开缺失的）
+  pi-workspace list                              查看登记成员与状态
+  pi-workspace doctor                            环境检查
+  pi-workspace clear                             清空登记（不删除对话文件）
+`;
+
+function listLines({ plan }) {
+	if (!plan.items.length) return ["没有登记成员。关闭 WezTerm 时仍打开的 Pi 会在下次启动后自动登记。"];
+	const lines = [];
+	for (const item of plan.items) {
+		const title = item.entry.name || item.entry.sessionId;
+		const when = new Date(item.entry.ts).toLocaleString();
+		lines.push(`${label(item.state).padEnd(8)} ${title} | ${item.entry.cwd} | ${when}`);
+	}
+	return lines;
+}
+
+export async function run(argv = [], { stdout = process.stdout, env = process.env } = {}) {
+	const [command, ...flags] = argv;
+	const hasFlag = (name) => flags.includes(name);
+	const write = (line) => stdout.write(`${line}\n`);
+
+	switch (command) {
+		case "restore": {
+			const result = await runRestore({ env, dryRun: hasFlag("--dry-run"), noWait: hasFlag("--no-wait") });
+			for (const line of summarize(result)) write(line);
+			if (!result.ok) return result.stage === "preflight" ? 2 : 1;
+			return 0;
+		}
+		case "list": {
+			for (const line of listLines(inspect({ paths: workspacePaths(env) }))) write(line);
+			return 0;
+		}
+		case "doctor": {
+			const pre = preflight({ env });
+			for (const check of pre.checks) {
+				write(`${check.ok ? "✔" : "✖"} ${check.name}：${check.detail}`);
+				if (check.hint) write(`  → ${check.hint}`);
+			}
+			const binfmt = binfmtStatus();
+			if (binfmt.registered && !binfmt.persistent) {
+				write("⚠ WSLInterop 已注册但未持久化：");
+				for (const line of PERSIST_HINT.split("\n")) write(`  ${line}`);
+			}
+			write(pre.ok ? "环境就绪。" : "存在未通过项，恢复前需先解决。");
+			return pre.ok ? 0 : 2;
+		}
+		case "clear": {
+			const removed = clearWorkspace(workspacePaths(env));
+			write(`已清空 ${removed} 条登记与启动占用；对话文件与旧格式记录未删除。`);
+			return 0;
+		}
+		default:
+			write(USAGE);
+			return command ? 1 : 0;
+	}
+}

package/src/discover.js

@@ -0,0 +1,65 @@
+import { execFileSync } from "node:child_process";
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** WezTerm 发现：显式路径 → PATH → 常见安装位置 → where.exe + wslpath。 */
+export function discoverWezterm(env = process.env, deps = {}) {
+	const fileExists = deps.isFile ?? isFile;
+	const readdir = deps.readdir ?? readdirSync;
+	const execFile = deps.execFile ?? execFileSync;
+	if (env.PI_WORKSPACE_WEZTERM) {
+		return fileExists(env.PI_WORKSPACE_WEZTERM) ? env.PI_WORKSPACE_WEZTERM : undefined;
+	}
+	const candidates = (env.PATH ?? "").split(":").filter((p) => p.startsWith("/"))
+		.map((dir) => join(dir, "wezterm.exe"));
+	candidates.push("/mnt/c/Program Files/WezTerm/wezterm.exe");
+	try {
+		for (const drive of readdir("/mnt")) {
+			candidates.push(join("/mnt", drive, "Program Files", "WezTerm", "wezterm.exe"));
+			const users = join("/mnt", drive, "Users");
+			let names;
+			try {
+				names = readdir(users);
+			} catch {
+				continue;
+			}
+			for (const user of names) {
+				candidates.push(
+					join(users, user, "AppData", "Local", "Programs", "WezTerm", "wezterm.exe"),
+					join(users, user, "scoop", "shims", "wezterm.exe"),
+				);
+			}
+		}
+	} catch {
+		/* /mnt 不可枚举时忽略 */
+	}
+	for (const candidate of candidates) {
+		if (fileExists(candidate)) return candidate;
+	}
+	try {
+		const options = { env, encoding: "utf8", timeout: 5000 };
+		const where = (env.PATH ?? "").split(":").filter((p) => p.startsWith("/"))
+			.map((dir) => join(dir, "where.exe")).find(fileExists)
+			?? "/mnt/c/Windows/System32/where.exe";
+		const out = execFile(where, ["wezterm.exe"], options);
+		for (const line of out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean)) {
+			try {
+				const path = execFile("wslpath", ["-u", line], options).trim();
+				if (fileExists(path)) return path;
+			} catch {
+				/* 某个 Windows 路径不可转换时继续下一项 */
+			}
+		}
+	} catch {
+		/* interop 不可用时静默 */
+	}
+	return undefined;
+}
+
+function isFile(path) {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}

package/src/launch.js

@@ -0,0 +1,15 @@
+import { dirname } from "node:path";
+import { agentDir } from "./paths.js";
+
+export function shellQuote(value) {
+	return "'" + value.replaceAll("'", "'\\''") + "'";
+}
+
+/** 仅传递启动所需配置，不把认证等整个环境写进命令行。 */
+export function launchSetup(env = process.env, piBin) {
+	const path = [piBin?.startsWith("/") ? dirname(piBin) : undefined, env.PATH].filter(Boolean).join(":");
+	return [
+		...(path ? [`export PATH=${shellQuote(path)}:"$PATH"`] : []),
+		`export PI_CODING_AGENT_DIR=${shellQuote(agentDir(env))}`,
+	].join("; ");
+}

package/src/liveness.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+
+/** 当前 Linux/WSL 启动 ID；重启后变化。 */
+export function currentBootId(readFile = (p) => readFileSync(p, "utf8")) {
+	try {
+		return readFile("/proc/sys/kernel/random/boot_id").trim();
+	} catch {
+		return undefined;
+	}
+}
+
+/** 进程启动时刻（/proc stat 字段 22）；进程不存在或为僵尸时 undefined。 */
+export function processStart(pid, readFile = (p) => readFileSync(p, "utf8")) {
+	try {
+		const stat = readFile(`/proc/${pid}/stat`);
+		const after = stat.slice(stat.lastIndexOf(")") + 2).trim().split(/\s+/);
+		if (after[0] === "Z") return undefined;
+		return after[19];
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * 记录所指向的 Pi 进程是否仍在同一启动周期内存活。
+ * bootId 不一致（重启过）一律视为不存活——满足“重启后失效 PID 不误判”。
+ */
+export function isLive(entry, deps = {}) {
+	if (!entry?.pid || !entry?.processStart || !entry?.bootId) return false;
+	// bootId 允许传值或函数，便于调用方复用已读取的值
+	const boot = typeof deps.bootId === "function" ? deps.bootId() : (deps.bootId ?? currentBootId());
+	if (boot !== entry.bootId) return false;
+	const start = deps.processStart
+		? deps.processStart(entry.pid)
+		: processStart(entry.pid);
+	return start === entry.processStart;
+}

package/src/members.js

@@ -0,0 +1,84 @@
+import {
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { workspacePaths } from "./paths.js";
+
+/**
+ * 成员记录语义（已确认规则）：
+ * - Pi 打开（session_start）→ 写入/刷新记录（含 pid、processStart、bootId）
+ * - Pi 内主动退出 / 切换会话（session_shutdown: quit|new|resume|fork）→ 删除记录（不恢复）
+ * - 被动死亡（关窗、崩溃、WSL 关机）→ 无清理，记录自然残留 → 恢复
+ */
+function writeAtomic(file, data) {
+	const temp = `${file}.${process.pid}.tmp`;
+	writeFileSync(temp, data, { mode: 0o600 });
+	renameSync(temp, file);
+}
+
+export function writeMember(entry, paths = workspacePaths()) {
+	mkdirSync(paths.members, { recursive: true });
+	writeAtomic(join(paths.members, `${entry.sessionId}.json`), JSON.stringify(entry, null, 2));
+}
+
+export function readMember(sessionId, paths = workspacePaths()) {
+	try {
+		return JSON.parse(readFileSync(join(paths.members, `${sessionId}.json`), "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+export function deleteMember(sessionId, paths = workspacePaths()) {
+	try {
+		unlinkSync(join(paths.members, `${sessionId}.json`));
+	} catch {
+		/* 不存在即目标状态 */
+	}
+}
+
+export function listMembers(paths = workspacePaths()) {
+	const out = [];
+	let files;
+	try {
+		files = readdirSync(paths.members);
+	} catch {
+		return out;
+	}
+	for (const file of files.filter((f) => f.endsWith(".json"))) {
+		try {
+			const entry = JSON.parse(readFileSync(join(paths.members, file), "utf8"));
+			if (entry?.sessionId) out.push(entry);
+		} catch {
+			/* 跳过损坏记录，恢复时宁可少报不可错报 */
+		}
+	}
+	return out.sort((a, b) => a.ts - b.ts);
+}
+
+/** 清空登记与启动占用；不触碰旧格式文件与对话文件。 */
+export function clearWorkspace(paths = workspacePaths()) {
+	let removed = 0;
+	for (const dir of [paths.members, paths.claims]) {
+		let files;
+		try {
+			files = readdirSync(dir);
+		} catch {
+			continue;
+		}
+		for (const file of files.filter((f) => f.endsWith(".json"))) {
+			try {
+				unlinkSync(join(dir, file));
+				removed++;
+			} catch {
+				/* 忽略 */
+			}
+		}
+	}
+	return removed;
+}