@yandy0725/pi-memory 2.4.0 → 2.5.1

package/README.md

@@ -6,6 +6,11 @@ Aligned with Claude Code's auto memory mechanism: **one memory = one file**, a `
 
 > ## ⚠️ Breaking changes
 >
+> **In 2.5.0:**
+>
+> - **Windows directory names changed shape.** `local/<project>` keys now split on `\` as well as `/`, so a Windows project directory is one readable component (`C_3a__Users__you__proj`) instead of a nested tree (`C_3a/Users/you/proj`). Memories stored under the old nested layout are orphaned: run `/memory` inside the project to read the new `Dir:` path, then create that directory if it does not exist and move the old project directory's contents into it (in PowerShell: `New-Item -ItemType Directory -Force "<new dir>"` then `Move-Item "<old project dir>\*" "<new dir>"`); the empty intermediate directories left behind can be ignored. `git/<host>__<owner>__<repo>` names are unchanged on POSIX; on Windows they are unchanged too unless the key's first `.`-delimited label is a reserved device name, or the key contains a backslash, or it ends in a dot or a space — those few names are sanitised now (see [Windows](#windows)). POSIX output is byte-identical to before.
+> - **Entry files whose stem is a Windows reserved device name now get a `_` prefix** (`name: "CON"` → `_CON.md`) on every platform, so the name is safe in a shared `git/` directory. Only newly created files are affected — existing entries keep their file names.
+>
 > **In 2.4.0:**
 >
 > - **The package-level `enabled` switch is gone.** `memory.json` has no top-level `enabled` any more: a leftover key is ignored, and `{"enabled": false}` no longer disables anything — it used to skip model validation too, so a disabled config often had no model configured. Disable the extension the way you disable any pi package — by not loading it — see [Disabling the extension](#disabling-the-extension). `dream` is now a required task in every session.
@@ -161,7 +166,7 @@ Create `memory.json` in the agent directory (`~/.pi/agent/memory.json`) or the p
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `memoryDir` | `~/.pi/memory` | Root directory for all memory data |
+| `memoryDir` | `~/.pi/memory` | Root directory for all memory data. `~`, `~/` and (on Windows) `~\` are expanded; relative values are resolved against the working directory |
 | `memIndexMaxLines` | `200` | Write capacity: max non-empty lines in `MEMORY.md` (the `# Memory Index` header and hand-written headings count too, so this is not exactly the memory count) |
 | `memIndexMaxBytes` | `25600` | Write capacity: max bytes of `MEMORY.md` |
 | `memIndexInjectMaxLines` | `50` | Injection window: max lines of the index put into the `memory_index` section. The window keeps the **newest** lines and drops the **oldest** ones — the index is pure chronological order, so a smaller window never hides the memory you just wrote. **`0` (either key) injects no index at all** — the `memory_index` section stays empty |
@@ -272,7 +277,7 @@ It runs with the five main-agent actions (never `rename` / `rebuild_index`), no
 | Level | Scope | Behaviour |
 |---|---|---|
 | In-process logical lock (per memory dir) | one primitive call; or a whole dream round | Waits up to `lock.timeoutMs`, then throws a readable error naming the directory. `extract` uses the non-waiting form and skips the turn |
-| Cross-process `.lock` | milliseconds, around the physical write | Acquired with `link` (atomic), **never reclaimed automatically**: no TTL, no heartbeat, no takeover |
+| Cross-process `.lock` | milliseconds per retried call around the physical write (a retry storm can hold it for a few seconds) | Acquired with `open(…, "wx")` (`O_CREAT|O_EXCL`) — the **create** is atomic on NTFS, ReFS, exFAT/FAT32 and in a network share's namespace, so the lock excludes processes on every machine using that share; in a sync-client folder it only excludes same-machine processes (see [Windows](#windows)). The holder record is written immediately after the file is created. **Never reclaimed automatically**: no TTL, no heartbeat, no takeover |
 
 A crash inside a write can therefore leave a `.lock` behind, and nothing will ever delete it for you — that is the deliberate price of a hard mutual-exclusion guarantee. The error names the pid, op and start time; `/memory unlock` is the one sanctioned way to clear it.
 
@@ -376,15 +381,26 @@ Directory names are derived as follows:
 - git repos whose remote is http(s), ssh (including scp-style `[user@]host:owner/repo`, where the user is optional) or `git://`, plus the `git+ssh://` / `git+https://` aliases → `git/<host>__<owner>__<repo>`; port, credentials, trailing `/` and `.git` are stripped and the host is lowercased
 - remote URLs are read from the raw git config (`remote.<name>.url`; `origin` first, then alphabetical, first usable URL wins), so `url.*.insteadOf` rewrites do not change the mapping
 - scheme forms apply WHATWG URL normalization (IDN hosts become punycode, percent-encoding and `.`/`..` folding apply, credentials/queries/fragments are dropped), while scp forms keep the path as written — equivalent remotes written differently can map to different directories
-- everything else — non-git directories, git repos without a remote, `file://` or local-path remotes → `local/<absolute-path>` (git repos use the repository root; a Windows-style drive-letter remote such as `C:/repos/foo.git` is treated as scp-style on POSIX, matching git)
+- everything else — non-git directories, git repos without a remote, `file://`, UNC (`\\server\share\repo.git`), relative and local-path remotes → `local/<absolute-path>` (git repos use the repository root). A Windows drive-letter remote (`Z:\repos\foo.git`) counts as a **local path on Windows**, matching how git treats it there; the same string on POSIX is scp syntax (the drive letter is a host) and still maps to a `git/` name, also matching git
 - `/` becomes `__`; characters that are not portable in file names (`<>:"|?*`, control characters) become `_XX` hex escapes
 - names longer than 120 UTF-8 bytes are truncated to 100 bytes on a code-point boundary plus a `__<hash8>` suffix
-- names target POSIX filesystems: a backslash is an ordinary character, and no Windows device-name or trailing-dot handling is applied
+- names are platform-aware: on Windows a backslash is a separator, and names avoid reserved device names and trailing dots/spaces; on POSIX a backslash stays an ordinary character and these Windows-only rules do not apply. The one rule applied everywhere is the `_` prefix for entry file stems that look like a device name (see [Windows](#windows))
 
 The mapping is not injective: underscores are kept as-is, so `/home/a__b` and `/home/a/b` both map to `home__a__b` (and share one memory directory). Changing or renaming a remote, adding a remote that sorts before the one currently in use, or moving a local directory changes the memory directory, orphaning the old one.
 
 **Older legacy layout:** versions before 1.x stored memory under `~/.pi/memory/<12-char-sha256>/`; those directories are no longer read or written. To migrate a project manually, compute the old hash with `printf '%s' "$(git rev-parse --show-toplevel)" | sha256sum | cut -c1-12` (use `$PWD` outside a git repo), then `mv` that directory to the new location (run `/memory` inside the project to see the new path) and split its topic files by hand (see [1.x data](#1x-data)).
 
+## Windows
+
+pi-memory runs natively on Windows — no WSL required.
+
+- **Directory names.** The name derived from a project key is always a single, legal Windows component: `\` counts as a separator (so `C:\Users\you\proj` → `C_3a__Users__you__proj`), a trailing dot or space is hex-escaped (`proj.` → `proj_2e`), and a name whose first `.`-delimited label is a reserved device name gets a `_` prefix (`nul` → `_nul`). Directory names are identical across platforms for an ordinary remote's `git/` key (`github.com__owner__repo`), so a shared `memoryDir` keeps working when the same repository is opened from Linux and Windows. Keys whose first label collides with a reserved device name (`aux.example.com/...`), that contain a backslash, or that end in a dot or a space can still differ between platforms.
+- **Repository root.** The root comes from `git rev-parse --show-toplevel`, so a repository subdirectory maps to the same memory directory as the repository root. Note the root is taken from git's output as-is: it must be a native Windows path, which Git for Windows prints (`C:/...`). A cygwin/MSYS build of `git` prints POSIX-style paths (`/cygdrive/c/...`), which would place the memory directory under a wrong prefix — put Git for Windows' `git.exe` first on `PATH` if you have several git builds installed.
+- **`memoryDir`.** `~`, `~/` and (on Windows) `~\` are expanded; relative values are resolved to absolute paths. Windows paths and UNC shares both work.
+- **Locking.** The cross-process lock is created with `open(…, "wx")` (`CREATE_NEW`). On a network share that primitive is atomic in the share's single namespace, so the lock excludes processes on every machine using that share — a `memoryDir` on a non-NTFS volume is supported. In a **sync-client folder** (OneDrive, Dropbox, …) there is no single namespace: each machine keeps its own copy, so the lock only excludes processes on the same machine — do not share one `memoryDir` between machines that way; use a network share when you need cross-machine exclusion. A transient `EPERM`/`EACCES`/`EBUSY` from an antivirus scanner, an editor or a file indexer is retried with a short backoff; a persistent failure still reports the original error.
+- **Line endings.** Every memory file pi-memory reads tolerates CRLF and lone CR (they are normalised to LF before parsing), and every write emits LF. A `MEMORY.md` or entry file re-saved by Notepad or another Windows editor therefore neither disappears from the index nor inflates the unrecognised-line count.
+- **Known limitation.** A file whose name is a reserved device name (for example `con.md`, created by hand or by an older version on another platform) is skipped on Windows instead of being read, because opening that name reaches the console device rather than the file. Rename it (using a `\\?\` path) or re-create the memory under a new name. While such a file exists, adding a memory whose name derives to it (`CON` now derives `_CON.md`) creates a second file and a second same-named index line; the next `rebuild_index` — which dream runs regularly — drops the stale line.
+
 ## Notifications
 
 | When | Notification |

package/README.zh.md

@@ -6,6 +6,11 @@ pi coding agent 的文件系统持久记忆层。把项目知识（事实、偏
 
 > ## ⚠️ 破坏性变更
 >
+> **2.5.0：**
+>
+> - **Windows 上的目录名形态变了。** `local/<项目>` 的 key 现在按 `\` 与 `/` 一起分段，因此 Windows 项目目录是一个可读的单分量名（`C_3a__Users__you__proj`），而不是嵌套的一棵树（`C_3a/Users/you/proj`）。旧嵌套布局下的记忆会变成孤儿目录：在项目里跑一次 `/memory` 读出新的 `Dir:` 路径，再建好那个目录并把旧项目目录里的内容搬过去（PowerShell 里先 `New-Item -ItemType Directory -Force "<新目录>"`，再 `Move-Item "<旧项目目录>\*" "<新目录>"`）；留下的空中间目录可以不管。`git/<host>__<owner>__<repo>` 在 POSIX 上形态不变；Windows 上同样不变，除非 key 的首段是保留设备名、或 key 含反斜杠、或以点或空格结尾 —— 这类少数名字现在会被收尾（见 [Windows](#windows)）。POSIX 输出与之前逐字节一致。
+> - **stem 是 Windows 保留设备名的 entry 文件现在会加 `_` 前缀**（`name: "CON"` → `_CON.md`），**所有平台**都这样，这样名字在共享的 `git/` 目录里两边都安全。只影响**新建**文件 —— 既有 entry 保留原名。
+>
 > **2.4.0：**
 >
 > - **包级开关 `enabled` 已删除。** `memory.json` 不再有顶层 `enabled`：残留的键会被忽略，`{"enabled": false}` 不再能禁用任何东西 —— 它以前还会跳过模型校验，所以被禁用的配置往往也没配模型。要禁用整个扩展，请像禁用其他 pi package 一样「不加载它」，见[禁用本扩展](#禁用本扩展)。`dream` 现在是每个会话的必需任务。
@@ -161,7 +166,7 @@ staging 的 SSH 用 2222 端口，密钥在 ~/.ssh/staging。
 
 | 键 | 默认值 | 说明 |
 |-----|---------|------|
-| `memoryDir` | `~/.pi/memory` | 所有记忆数据的根目录 |
+| `memoryDir` | `~/.pi/memory` | 所有记忆数据的根目录。`~`、`~/` 与（Windows 上）`~\` 会展开；相对路径按工作目录解析为绝对路径 |
 | `memIndexMaxLines` | `200` | 写入口径：`MEMORY.md` 的最大非空行数（`# Memory Index` 头行与手写标题同样占额度，所以并不等于记忆条数） |
 | `memIndexMaxBytes` | `25600` | 写入口径：`MEMORY.md` 的最大字节数 |
 | `memIndexInjectMaxLines` | `50` | 注入口径：放进 `memory_index` section 的最大行数。窗口保留**最新**的行、丢弃**最旧**的行 —— 索引是纯时间序，窗口再小也不会藏住你刚写完的那条。**任一键写 `0` = 完全不注入索引**（section 保持空值） |
@@ -272,7 +277,7 @@ extract 拿到的是结构化渲染，而不是有损的两条消息摘要：
 | 层级 | 作用域 | 行为 |
 |---|---|---|
 | 进程内逻辑锁（按记忆目录分键） | 单次原语；或 dream 的整轮 | 最多等 `lock.timeoutMs`，超时抛一条写明目录的可读错误。`extract` 用不等待的形态，直接跳过本回合 |
-| 跨进程 `.lock` | 毫秒级，只包住物理写入 | 用 `link` 原子获取，**永不自动回收**：没有 TTL、没有心跳、没有接管 |
+| 跨进程 `.lock` | 每次重试调用毫秒级，只包住物理写入（重试风暴下可持有数秒） | 用 `open(…, "wx")`（`O_CREAT|O_EXCL`）建立 —— **创建**在 NTFS、ReFS、exFAT/FAT32 与网络共享的命名空间里是原子的，因此能排除使用同一共享的所有机器上的进程；在同步客户端目录里只能排除同机进程（见 [Windows](#windows)）。持有者记录在文件建立后立即写入。**永不自动回收**：无 TTL、无心跳、无接管 |
 
 因此写入中途崩溃可能留下一个 `.lock`，而且**没有任何进程会替你删掉它** —— 这是「互斥是硬保证」的刻意代价。错误文案会写明 pid、op、开始时间与路径；`/memory unlock` 是唯一被认可的清除方式。
 
@@ -376,15 +381,26 @@ Lock: free
 - remote 是 http(s)、ssh（含 scp 写法 `[user@]host:owner/repo`，user 可省略）或 `git://`，以及 `git+ssh://` / `git+https://` 别名的 git 仓库 → `git/<host>__<owner>__<repo>`；端口、凭据、结尾的 `/` 与 `.git` 会被剥掉，host 转小写
 - remote URL 从原始 git config 读取（`remote.<name>.url`；先 `origin`，再按字母序，第一个可用的胜出），所以 `url.*.insteadOf` 重写不会影响映射
 - scheme 形式走 WHATWG URL 规范化（IDN host 转 punycode，百分号编码与 `.`/`..` 折叠生效，凭据/query/fragment 被丢弃），scp 形式保留原样路径 —— 等价但写法不同的 remote 可能映射到不同目录
-- 其余情况 —— 非 git 目录、没有 remote 的 git 仓库、`file://` 或本地路径 remote → `local/<absolute-path>`（git 仓库用仓库根；Windows 盘符形式的 remote 如 `C:/repos/foo.git` 在 POSIX 上按 scp 写法处理，与 git 一致）
+- 其余情况 —— 非 git 目录、没有 remote 的 git 仓库、`file://`、UNC（`\\server\share\repo.git`）、相对路径与本地路径 remote → `local/<absolute-path>`（git 仓库用仓库根）。Windows 盘符形式的 remote（`Z:\repos\foo.git`）**在 Windows 上算本地路径**，与 git 在那里的一致；同一串在 POSIX 上是 scp 写法（盘符字母是 host），仍映射到 `git/` 目录名，也与 git 一致
 - `/` 变成 `__`；文件名里不可移植的字符（`<>:"|?*`、控制字符）变成 `_XX` 十六进制转义
 - 超过 120 UTF-8 字节的名字在码点边界截断到 100 字节，再加 `__<hash8>` 后缀
-- 名字面向 POSIX 文件系统：反斜杠是普通字符，不做 Windows 设备名与结尾句点处理
+- 名字是平台感知的：Windows 上反斜杠是分隔符，并避开保留设备名与结尾点/空格；POSIX 上反斜杠仍是普通字符，上述 Windows 规则不适用。唯一在所有平台都生效的规则是「stem 形如设备名的 entry 文件名加 `_` 前缀」（见 [Windows](#windows)）
 
 映射不是单射：下划线原样保留，所以 `/home/a__b` 与 `/home/a/b` 都映射到 `home__a__b`（共享同一个记忆目录）。改动或重命名 remote、新增一个排序更靠前的 remote、移动本地目录，都会改变记忆目录，旧目录会被孤立。
 
 **更老的布局：** 1.x 之前的版本把记忆存在 `~/.pi/memory/<12-char-sha256>/`；这些目录不再被读写。要手工迁移，用 `printf '%s' "$(git rev-parse --show-toplevel)" | sha256sum | cut -c1-12` 算出旧 hash（不在 git 仓库里就用 `$PWD`），把那个目录 `mv` 到新位置（在项目里跑 `/memory` 可以看到新路径），其 topic 文件需要按 [1.x 数据](#1x-数据)手工拆分。
 
+## Windows
+
+pi-memory 在 Windows 上原生可用，不需要 WSL。
+
+- **目录名。** 由项目 key 派生的名字一定是单个、合法的 Windows 分量：`\` 被当作分隔符（`C:\Users\you\proj` → `C_3a__Users__you__proj`），结尾的点或空格被十六进制转义（`proj.` → `proj_2e`），而「第一个 `.` 之前的部分」是保留设备名的名字会加 `_` 前缀（`nul` → `_nul`）。普通 remote 的 `git/` 目录名在所有平台上一致（`github.com__owner__repo`），因此共享 `memoryDir` 时同一仓库从 Linux 与 Windows 打开都会落到同一个目录。首段与保留设备名撞名（如 `aux.example.com/...`）、含反斜杠、或以点或空格结尾的 key，其目录名在两端仍可能不同。
+- **仓库根。** 根路径取自 `git rev-parse --show-toplevel`：从仓库子目录启动与从仓库根启动映射到同一个记忆目录。注意该路径是按 git 的输出原样使用的，必须是原生 Windows 形态 —— Git for Windows 会打印 `C:/...`；若 PATH 上的 `git` 是 cygwin/MSYS 构建，它会打印 `/cygdrive/c/...` 这类 POSIX 形态路径，记忆目录会落到错前缀下。装了多个 git 时，把 Git for Windows 的 `git.exe` 放到 PATH 前面。
+- **`memoryDir`。** `~`、`~/` 与（Windows 上）`~\` 都会展开；相对路径会被解析成绝对路径。Windows 路径与 UNC 共享都可用。
+- **锁。** 跨进程锁用 `open(…, "wx")`（`CREATE_NEW`）建立。在网络共享上这个原语在共享的单一命名空间里是原子的，因此锁能排除使用同一共享的**所有机器**上的进程 —— `memoryDir` 放在非 NTFS 卷上也能用。在**同步客户端目录**（OneDrive、Dropbox 等）里没有单一命名空间：每台机器各留一份副本，锁只能排除同一台机器上的进程 —— 不要用这种方式在多台机器间共享 `memoryDir`；需要跨机互斥时用网络共享。杀软、编辑器或索引器造成的瞬时 `EPERM`/`EACCES`/`EBUSY` 会做短退避重试；持续失败仍按原始错误报出。
+- **换行符。** 读取记忆文件时一律容忍 CRLF 与孤立 CR（解析前归一为 LF），写入一律输出 LF。被记事本等 Windows 编辑器重新保存过的 `MEMORY.md` 或 entry 文件既不会从索引里消失，也不会推高「无法识别的行」计数。
+- **已知限制。** 名字是保留设备名的文件（例如 `con.md`，由手工创建或旧版本在别的平台上创建）在 Windows 上会被**跳过**而不是被读取 —— 按该名字打开会到达控制台设备而不是文件。请改名（需用 `\\?\` 路径）或换名字重新写入这条记忆。在它存在期间，若再添加一条会派生到该名字的记忆（`CON` 现在派生 `_CON.md`），会得到第二个文件与第二条同名索引行；下一次 `rebuild_index`（dream 会定期调用）会清掉那条陈旧索引行。
+
 ## 通知
 
 | 时机 | 通知 |

package/index.ts

@@ -7,6 +7,7 @@ import { runDream } from "./src/dream";
 import { indexCapacity, parseEntryIndex } from "./src/entry-index";
 import { runExtract } from "./src/extract";
 import { readLockStatus, type LockInfo } from "./src/fs-lock";
+import { withFsRetry } from "./src/fs-retry";
 import { readRecordedMemoryIndex } from "./src/index-source";
 import { applyIndexSection, buildIndexSection, buildInjection, indexInjectionCapacity, injectSurfacedContent, runSideQuery, scanEntries } from "./src/inject";
 import {
@@ -127,7 +128,10 @@ async function unlockMemory(memoryDir: string, ui: ExtensionUIContext): Promise<
 	const ok = await ui.confirm("Memory lock", question);
 	if (!ok) return;
 	try {
-		await unlink(lockPath);
+		// 恢复路径也要重试：用户正是因为一把可能被瞬时错误困住的锁才走到这里，而删除本身
+		// 同样会被杀软/索引器/同步客户端打断 —— 这里再报一次 EPERM 就是把用户困在原地。
+		// 幂等（删一个已不存在的文件走下面的 ENOENT 分支），重试无副作用。
+		await withFsRetry(() => unlink(lockPath));
 		ui.notify("Memory lock removed.", "info");
 	} catch (e) {
 		// confirm 到 unlink 之间锁自己消失了：那正是想要的结果

package/package.json

@@ -3,7 +3,7 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"version": "2.4.0",
+	"version": "2.5.1",
 	"description": "File-system driven persistent memory layer for pi coding agent",
 	"license": "MIT",
 	"repository": {

package/src/config.ts

@@ -162,9 +162,12 @@ export function requiredModel(cfg: MemoryConfig, task: ModelTask): string {
 	return value;
 }
 
-function expandTilde(p: string): string {
+function expandTilde(p: string, platform: NodeJS.Platform = process.platform): string {
 	if (p === "~") return homedir();
 	if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+	// `~\` 只在 Windows 上展开：POSIX 上 `~\foo` 是以 `~` 开头的合法文件名，
+	// 改写它会破坏用户真实的路径（spec Ruling 4）。
+	if (platform === "win32" && p.startsWith("~\\")) return join(homedir(), p.slice(2));
 	return p;
 }
 
@@ -200,6 +203,8 @@ export interface LoadConfigContext {
 	isProjectTrusted(): boolean;
 	_globalDir?: string;
 	_configDirName?: string;
+	/** 测试注入缝：命名/展开规则跟随的平台。默认 `process.platform`。 */
+	_platform?: NodeJS.Platform;
 }
 
 export async function loadConfig(ctx: LoadConfigContext): Promise<MemoryConfig> {
@@ -215,6 +220,6 @@ export async function loadConfig(ctx: LoadConfigContext): Promise<MemoryConfig>
 		cfg = deepMerge(cfg, readJsonSafe(projectFile));
 	}
 
-	cfg.memoryDir = expandTilde(cfg.memoryDir);
+	cfg.memoryDir = expandTilde(cfg.memoryDir, ctx._platform ?? process.platform);
 	return cfg;
 }

package/src/dream.ts

@@ -5,6 +5,7 @@ import { runHeadlessAgent } from "./agent-runner";
 import type { SessionPersistenceConfig, ThinkLevel } from "./config";
 import { BACKUP_DIR, type MemoryStore } from "./memory-store";
 import { createSnapshot } from "./snapshot";
+import { isReservedWindowsName } from "./windows-names";
 
 /** Build the dream consolidation task. dream 只有 `memory` 工具的 7 个 action，没有任何文件工具。 */
 export function buildDreamTask(maxLines: number): string {
@@ -72,14 +73,20 @@ export interface RunDreamOpts {
  * - `sessions/`（目录，`sessionPersistence.enabled` 时存在）跳过 —— 同理，而且它可能很大。
  *   `createSnapshot` 的 `cp` 遇到目录会抛 `ERR_FS_EISDIR`（非 ENOENT → fail-closed 上抛 → dream 直接失败）。
  * - `.lock` / `.dream-meta.json` 跳过（都是 dotfile）：锁记录与元数据不属于记忆内容。
+ * - win32：保留设备名文件（`con.md`…）跳过 —— 按名 `cp` 会命中设备（见下）。
  * - 其余全部 `*.md`（entry 文件 + `MEMORY.md`）都会被快照。
  */
-async function snapshotFiles(memoryDir: string): Promise<string[]> {
+async function snapshotFiles(memoryDir: string, platform: NodeJS.Platform = process.platform): Promise<string[]> {
 	const entries = await readdir(memoryDir, { withFileTypes: true }).catch(() => []);
-	return entries
-		.filter((entry) => entry.isFile() && !entry.name.startsWith("."))
-		.map((entry) => entry.name)
-		.sort();
+	return (
+		entries
+			.filter((entry) => entry.isFile() && !entry.name.startsWith("."))
+			// win32：保留设备名文件按名打开会命中设备（CON 等），`createSnapshot` 的 cp 会失败；
+			// dream 是 fail-closed 的，一次 cp 失败就打断整轮（与 `#entryFiles` 同一契约，spec §4.3）。
+			.filter((entry) => !(platform === "win32" && isReservedWindowsName(entry.name)))
+			.map((entry) => entry.name)
+			.sort()
+	);
 }
 
 /**
@@ -101,9 +108,10 @@ export async function runDream(opts: RunDreamOpts): Promise<string> {
 		}
 
 		// 进入时对整目录拍一次快照；这一轮里各原语的逐文件快照被 skipSnapshot 跳过（spec §6）。
-		const files = await snapshotFiles(opts.memoryDir);
+		const files = await snapshotFiles(opts.memoryDir, opts.store.cfg.platform);
 		await createSnapshot(join(opts.memoryDir, BACKUP_DIR), "dream", files, opts.memoryDir, {
 			keep: opts.store.cfg.lock.snapshotKeep,
+			platform: opts.store.cfg.platform,
 		});
 
 		return runHeadlessAgent({

package/src/filename.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { isReservedWindowsName } from "./windows-names";
 
 /** 文件系统不安全字符与控制字符。 */
 // biome-ignore lint/suspicious/noControlCharactersInRegex: 控制字符是故意列入的（Global Constraints 要求剥离 U+0000–U+001F 与 U+007F）
@@ -31,7 +32,12 @@ function truncateBytes(input: string, maxBytes: number): string {
 export function entryFileName(name: string): string {
 	const cleaned = name.replace(UNSAFE, "_").replace(EDGE, "");
 	const stem = cleaned.length === 0 ? "" : truncateBytes(cleaned.replace(WHITESPACE_RUN, "-"), STEM_MAX_BYTES);
-	return `${stem.length === 0 ? `entry-${shortHash(name)}` : stem}${ENTRY_EXT}`;
+	// 保留设备名（`con`、`nul`、`com1`…）在 Windows 上会命中设备而不是文件：`memory add name="CON"`
+	// 的内容会写进控制台，而索引里已经多了一行 —— 静默丢记忆。**全平台**加前缀：git 类记忆目录
+	// 跨机共享，名字必须在两边都安全（spec Ruling 5）。既有文件不受影响：addEntry 按 frontmatter
+	// 的 name 复用已有文件，这里只影响**新建**文件的派生名。
+	const finalStem = stem.length === 0 ? `entry-${shortHash(name)}` : isReservedWindowsName(stem) ? `_${stem}` : stem;
+	return `${finalStem}${ENTRY_EXT}`;
 }
 
 /** 在已占用的文件名集合中为 base 找一个空闲名字（追加 -2、-3……）。 */

package/src/fs-lock.ts

@@ -1,5 +1,6 @@
-import { link, open, readFile, rm, unlink } from "node:fs/promises";
+import { open, readFile, rm } from "node:fs/promises";
 import { hostname } from "node:os";
+import { withFsRetry } from "./fs-retry";
 
 /**
  * **跨进程**锁。只保护「毫秒级的物理写入」这一件事。
@@ -9,8 +10,9 @@ import { hostname } from "node:os";
  * 也就不需要 TTL、续约心跳与存活探测。
  *
  * **永不自动回收**：另一个进程崩溃留下的锁没有任何人能释放它，但**也不会被自动删掉**。
- * 原因是「移走别人的锁」无法用 POSIX 原语做到可证明安全：`link` 这个合法获取原语的条件正是
- * 「锁路径不存在」，所以任何「先移走旧锁、再建立自己的」的接管都会产生一个空窗，其它等待者
+ * 原因是「移走别人的锁」无法用 POSIX 原语做到可证明安全（Windows 同样没有 compare-and-delete
+ * 原语）：锁路径不存在（`open(wx)`）正是
+ * 合法获取条件，所以任何「先移走旧锁、再建立自己的」的接管都会产生一个空窗，其它等待者
  * 可以合法地抢占它；一旦移走的其实是某个**活持有者**刚建立的记录，互斥就无法再恢复（把记录
  * 挪回去又会顶掉抢占者，而路径只能容纳一条记录）。实测：把 `rm` 换成原子 `rename` 仍然会双持有，
  * 加上「比字节 + 放回」则会把空窗拉长，同进程内可稳定复现双持有。
@@ -45,7 +47,9 @@ export class MemoryLockedError extends Error {
 		super(
 			abandoned
 				? `Memory lock at ${lockPath} is abandoned by ${described} — delete the file to clear it`
-				: `Memory is locked by ${described}`,
+				: holder
+					? `Memory is locked by ${described}`
+					: `Memory lock at ${lockPath} is still being written (0 bytes) — if no other process is writing, delete the file or run /memory unlock`,
 		);
 		this.name = "MemoryLockedError";
 	}
@@ -81,13 +85,18 @@ function isLockInfo(value: unknown): value is LockInfo {
 type LockRead =
 	/** 锁路径不存在 —— 这是「空闲」，不是「有问题」。 */
 	| { kind: "absent" }
-	/** 存在但无法解释（非 JSON、空文件、形状不对、读不到）：只有人工能清除它。 */
+	/** 存在且 0 字节：持有者刚建立文件、记录还没写完（或恰好崩溃在这一瞬间）。 */
+	| { kind: "empty" }
+	/** 存在但无法解释（非 JSON、空文件之外的坏内容、形状不对、读不到）：只有人工能清除它。 */
 	| { kind: "unreadable" }
 	| { kind: "held"; holder: LockInfo };
 
 /**
- * 读锁的三种状态。**必须区分「不存在」与「存在但读不懂」** —— 把前者当成后者会让
+ * 读锁的状态。**必须区分「不存在」与「存在但读不懂」** —— 把前者当成后者会让
  * 「持有者刚释放、锁刚被删」被误报成「遗弃的锁」，从而在正常竞争下抛出误导性的错误。
+ *
+ * 自 `open(wx)` 原语起还多一态 `empty`：锁文件建立与记录写入之间有一个极短窗口（spec §4.4），
+ * 它必须与「读不懂」分开 —— 否则等待者会把「别人正在建锁」误报成「遗弃的锁」并立刻失败。
  */
 async function readLockState(lockPath: string): Promise<LockRead> {
 	let raw: string;
@@ -98,6 +107,9 @@ async function readLockState(lockPath: string): Promise<LockRead> {
 		// 权限之类的错误：无法判断内容，按「读不懂」处理（不接管、报可操作错误）
 		return { kind: "unreadable" };
 	}
+	// 0 字节是**正常的中间态**：`open(wx)` 建立文件与写入记录之间有一个极短窗口（spec §4.4）。
+	// 它必须与「读不懂」分开 —— 否则等待者会把「别人正在建锁」误报成「遗弃的锁」并立刻失败。
+	if (raw.length === 0) return { kind: "empty" };
 	try {
 		const parsed: unknown = JSON.parse(raw);
 		return isLockInfo(parsed) ? { kind: "held", holder: parsed } : { kind: "unreadable" };
@@ -109,14 +121,17 @@ async function readLockState(lockPath: string): Promise<LockRead> {
 /**
  * 锁的诊断视图（spec §14 的 `/memory`）。
  *
- * **复用私有的 `readLockState`**，不另写一份读逻辑：三态必须与获取路径同源，
+ * **复用私有的 `readLockState`**，不另写一份读逻辑：状态必须与获取路径同源，
  * 否则会出现「`/memory` 说 free，下一次写入却报 locked」这种无法诊断的矛盾。
+ * 对外只暴露三态：`empty`（建立中的 0 字节记录）归入 `unreadable` —— 对人类观察者而言
+ * 它只可能是崩溃残留，处置方式与「读不懂」相同（`/memory unlock`）。
  * 它**不判断存活、也不删任何东西**（永不自动回收）；持有者是否已死由调用方自己看 pid。
  */
 export async function readLockStatus(
 	lockPath: string,
 ): Promise<{ kind: "absent" } | { kind: "unreadable" } | { kind: "held"; holder: LockInfo }> {
-	return readLockState(lockPath);
+	const state = await readLockState(lockPath);
+	return state.kind === "empty" ? { kind: "unreadable" } : state;
 }
 
 type AcquireOutcome =
@@ -124,49 +139,68 @@ type AcquireOutcome =
 	| { acquired: false; holder: LockInfo | null; abandoned: boolean };
 
 /**
- * 尝试一次获取。路径为空时不当作失败 —— 那是「刚好被释放」，直接再试一次 link（CAS 会自然地
+ * 尝试一次获取。路径为空时不当作失败 —— 那是「刚好被释放」，直接再试一次 `open(wx)`（CAS 会自然地
  * 决出唯一赢家）；两次都撞上「刚好被释放」才交回给调用方重试。
  */
 async function acquireOnce(lockPath: string, info: LockInfo): Promise<AcquireOutcome> {
 	for (let round = 0; round < 2; round++) {
-		if (await writeExclusive(lockPath, info)) return { acquired: true };
+		if (await createExclusive(lockPath, info)) return { acquired: true };
 		const state = await readLockState(lockPath);
 		if (state.kind === "absent") continue;
+		// 建立中：有人在写记录，等它写完（或超时）。**不是**遗弃。
+		if (state.kind === "empty") return { acquired: false, holder: null, abandoned: false };
 		if (state.kind === "unreadable") return { acquired: false, holder: null, abandoned: true };
 		return { acquired: false, holder: state.holder, abandoned: isAbandoned(state.holder) };
 	}
 	return { acquired: false, holder: null, abandoned: false };
 }
 
-let tempCounter = 0;
-
 /**
- * 原子获取：先把持有者信息写进同目录的唯一临时文件，再 `link` 到锁路径。
+ * 原子获取：`open(lockPath, "wx")`（POSIX 的 `O_CREAT|O_EXCL`、Windows 的 `CREATE_NEW`、
+ * SMB2 的 `FILE_CREATE`）保证只有一个进程能建立锁文件，建立后**立即**写入完整的持有者记录。
  *
- * 不能用 `open(lockPath, "wx")` 后紧接着单独写内容 —— 那会让锁路径出现「存在但 0 字节」的
- * 中间态，等待者读到空文件会把它判为「无法解释」并据为己有。link 是原子的：锁路径要么不存在，
- * 要么内容是完整的 JSON。
+ * 与旧实现的差别：旧实现先把记录写进同目录的临时文件、再 `link` 到锁路径，因而内容原子出现；
+ * 但 `link` **只支持 NTFS**（ReFS、部分网络共享与云盘目录都不支持），在那些卷上整把锁取不到
+ * → 记忆完全不可写（spec §1.2 P4）。`open(wx)` 的**建立**在任意卷上都原子 —— 原子的只是
+ * 「谁建了这个文件」，**不是记录内容**：内容随后才写，于是有「文件已建立、内容未写入」的极短
+ * 窗口，由读取侧的 `empty` 态与 `/memory unlock` 兜底（spec §4.4）。
  */
-async function writeExclusive(lockPath: string, info: LockInfo): Promise<boolean> {
-	tempCounter += 1;
-	const tempPath = `${lockPath}.${process.pid}.${tempCounter}.tmp`;
+async function createExclusive(lockPath: string, info: LockInfo): Promise<boolean> {
+	let handle: Awaited<ReturnType<typeof open>>;
 	try {
-		const handle = await open(tempPath, "wx");
-		try {
-			await handle.writeFile(JSON.stringify(info), "utf8");
-		} finally {
-			await handle.close();
-		}
-		try {
-			await link(tempPath, lockPath);
-			return true;
-		} catch (e) {
-			if ((e as NodeJS.ErrnoException).code === "EEXIST") return false;
-			throw e;
-		}
-	} finally {
-		await unlink(tempPath).catch(() => {});
+		handle = await withFsRetry(() => open(lockPath, "wx"));
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "EEXIST") return false;
+		throw e;
+	}
+	try {
+		const record = Buffer.from(JSON.stringify(info), "utf8");
+		await withFsRetry(async () => {
+			// 定长位置写 + 完整性校验：写入用显式偏移，重试不会续写（`writeFile` 会把第二次写入
+			// 追加到当前位置 → 两个 JSON 拼接 → 读者判 unreadable → 持有者自己也释放不掉这把锁）。
+			let written = 0;
+			while (written < record.length) {
+				const { bytesWritten } = await handle.write(record, written, record.length - written, written);
+				if (bytesWritten <= 0) {
+					throw Object.assign(new Error("lock record write made no progress"), { code: "EIO" });
+				}
+				written += bytesWritten;
+			}
+		});
+		// `close` 也可能失败（SMB/网络盘的延迟刷写错误、EIO），而它在记录**已落盘**之后发生：
+		// 若直接上抛，`withLock` 的 finally 不会执行（acquire 从未返回 true），锁会留在原地并指向
+		// 本进程 → 本进程此后每次获取都读到「活持有者」并自锁到 timeout。故与写入失败同一处置。
+		await handle.close();
+	} catch (e) {
+		// 走到这里说明这把锁没有可用的持有者（记录没写进去，或 close 失败）：先关句柄再删文件
+		// （Windows 上删除打开中的文件需要 share-delete，且删除会延迟到关闭之后），否则会留下
+		// 0 字节/自指的锁挡住后来的写入者。`rm` 走重试：win32 上杀软/索引器造成的瞬时 EPERM
+		// 正是本任务要消掉的那类残留（spec §1.2 P5）。
+		await handle.close().catch(() => {});
+		await withFsRetry(() => rm(lockPath, { force: true })).catch(() => {});
+		throw e;
 	}
+	return true;
 }
 
 function holderInfo(op: string, now: number): LockInfo {
@@ -186,13 +220,14 @@ function isAbandoned(holder: LockInfo | null): boolean {
 
 /**
  * 只在锁仍是自己持有的情况下删除；否则留给真正的持有者。
- * 记录读不懂时也**不删** —— 那是别人的状态（或需要人工处理的状态），不该由我们清理。
+ * 记录读不懂或仍是 0 字节（建立中）时也**不删** —— 那是别人的状态（或需要人工处理的状态），
+ * 不该由我们清理 —— 我们无法证明它属于自己（spec §4.4）。`force: true` 让「刚好被释放」不是错误。
  */
 async function releaseLock(lockPath: string): Promise<void> {
 	const state = await readLockState(lockPath);
-	if (state.kind === "unreadable") return;
+	if (state.kind === "unreadable" || state.kind === "empty") return;
 	if (state.kind === "held" && !isOwnRecord(state.holder)) return;
-	await rm(lockPath, { force: true });
+	await withFsRetry(() => rm(lockPath, { force: true }));
 }
 
 function isOwnRecord(holder: LockInfo): boolean {

package/src/fs-retry.ts

@@ -0,0 +1,51 @@
+import { setTimeout as sleep } from "node:timers/promises";
+
+/**
+ * 物理文件系统调用的短退避重试。存在理由（spec §1.2 P5）：Windows 上杀软扫描、索引器、
+ * 编辑器会用瞬时 `EPERM`/`EBUSY` 打断正常写入；而 pi-memory 是 fail-closed 且锁永不自动回收 ——
+ * 一次瞬时错误若落在释放锁的 `rm(.lock)` 上，就会留下一个只能人工 `/memory unlock` 的锁，
+ * 之后该项目**所有**记忆写入被堵死。
+ */
+
+/** 全平台都算瞬时：这些 errno 在 POSIX 上同样是可恢复的争用（对齐 Node `fs.rm` 的重试集合）。 */
+const TRANSIENT_CODES = new Set(["EBUSY", "EMFILE", "ENFILE", "ENOTEMPTY"]);
+/** 只在 win32 追加：POSIX 上 EPERM/EACCES 是永久性权限错误，重试只会拖慢 fail-closed。 */
+const WINDOWS_ONLY_CODES = new Set(["EPERM", "EACCES"]);
+
+export function isTransientFsError(err: unknown, platform: NodeJS.Platform = process.platform): boolean {
+	const code = (err as NodeJS.ErrnoException | null | undefined)?.code;
+	if (typeof code !== "string") return false;
+	if (TRANSIENT_CODES.has(code)) return true;
+	return platform === "win32" && WINDOWS_ONLY_CODES.has(code);
+}
+
+export interface FsRetryOptions {
+	retries?: number;
+	baseDelayMs?: number;
+	maxDelayMs?: number;
+	platform?: NodeJS.Platform;
+	/** 测试注入缝：替换真实等待。 */
+	sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * 重试 `fn` 直到成功、遇到非瞬时错误、或耗尽预算。
+ * **错过的错误原样上抛**（含耗尽后的最后一次）—— 调用方的 fail-closed 语义与错误文案都不变
+ * （spec Ruling 8），这里不包装新错误类型。
+ */
+export async function withFsRetry<T>(fn: () => Promise<T>, options: FsRetryOptions = {}): Promise<T> {
+	const retries = options.retries ?? 6;
+	const baseDelayMs = options.baseDelayMs ?? 20;
+	const maxDelayMs = options.maxDelayMs ?? 300;
+	const platform = options.platform ?? process.platform;
+	const wait = options.sleep ?? ((ms: number) => sleep(ms));
+
+	for (let attempt = 0; ; attempt++) {
+		try {
+			return await fn();
+		} catch (e) {
+			if (attempt >= retries || !isTransientFsError(e, platform)) throw e;
+			await wait(Math.min(maxDelayMs, baseDelayMs * 2 ** attempt));
+		}
+	}
+}

package/src/memory-store.ts

@@ -5,8 +5,10 @@ import { deriveDescription, type EntryType, parseEntryFile, serializeEntryFile }
 import { formatIndexLine, indexCapacity, parseEntryIndex, removeIndexLine, upsertIndexLine } from "./entry-index";
 import { entryFileName, resolveUniqueFileName } from "./filename";
 import { withLock } from "./fs-lock";
+import { withFsRetry } from "./fs-retry";
 import { isProcessLockActive, tryWithProcessLock, withProcessLock } from "./process-lock";
 import { createSnapshot } from "./snapshot";
+import { isReservedWindowsName } from "./windows-names";
 
 export const INDEX_FILE = "MEMORY.md";
 export const LOCK_FILE = ".lock";
@@ -63,6 +65,8 @@ export interface StoreConfig {
 	/** 跨进程 `.lock` 的等待上限。注意这里**没有 ttl** —— 锁只在毫秒级的物理写入期间持有，
 	 *  且永不自动回收（见 fs-lock.ts）；dream 的整轮互斥由 process-lock.ts 的进程内队列承担。 */
 	lock: { timeoutMs: number; snapshotKeep: number };
+	/** 命名/读取规则跟随的平台（默认 `process.platform`）。测试注入缝，生产不传。 */
+	platform?: NodeJS.Platform;
 }
 
 export interface EntrySummary {
@@ -109,11 +113,30 @@ function compareSummaries(a: EntrySummary, b: EntrySummary): number {
 export class MemoryStore {
 	readonly #cache = new Map<string, CacheRow>();
 
+	get #platform(): NodeJS.Platform {
+		return this.cfg.platform ?? process.platform;
+	}
+
+	/** 物理写入路径的统一重试入口（spec §4.5）：只包物理调用，不包逻辑。 */
+	#retry<T>(fn: () => Promise<T>): Promise<T> {
+		return withFsRetry(fn, { platform: this.#platform });
+	}
+
 	constructor(readonly cfg: StoreConfig) {}
 
+	/** 读取路径与 `#savingQueue` 的 `mkdir` **刻意不重试**（spec §4.5）：读失败不改变磁盘状态，
+	 *  目录创建失败会在获取锁阶段就干净地报错（无残留）；重试只会拖慢 fail-closed。 */
 	async #entryFiles(): Promise<string[]> {
 		const names = await readdir(this.cfg.memoryDir).catch(() => []);
-		return names.filter((n) => n.endsWith(".md") && n !== INDEX_FILE && !n.startsWith(".")).sort();
+		return (
+			names
+				.filter((n) => n.endsWith(".md") && n !== INDEX_FILE && !n.startsWith("."))
+				// win32：按名打开保留设备名文件会命中设备（CON 等），`readFile` 会阻塞在控制台而不是
+				// 返回内容。修复前的版本或外部工具可能留下过这种文件，这里把它从清单里剔除 ——
+				// 最坏表现是「该条记忆在本机不可见」，而不是卡住整个扫描（spec Ruling 5）。
+				.filter((n) => !(this.#platform === "win32" && isReservedWindowsName(n)))
+				.sort()
+		);
 	}
 
 	/** 已被占用的文件名：磁盘上的条目文件 + 索引文件本身。
@@ -214,6 +237,7 @@ export class MemoryStore {
 	async #snapshot(label: string, files: string[]): Promise<void> {
 		await createSnapshot(join(this.cfg.memoryDir, BACKUP_DIR), label, files, this.cfg.memoryDir, {
 			keep: this.cfg.lock.snapshotKeep,
+			platform: this.#platform,
 		});
 	}
 
@@ -298,12 +322,6 @@ export class MemoryStore {
 		return out;
 	}
 
-	/** 清空并重建缓存（手工编辑过目录后用）。 */
-	async refreshCache(): Promise<void> {
-		this.#cache.clear();
-		await this.listEntries();
-	}
-
 	/** name 校验：非空、单行、不含 `](`。add 与 replace 共用，否则改名就成了绕过入口。 */
 	#validateName(name: string): void {
 		if (!name) throw new Error("name is required");
@@ -353,23 +371,25 @@ export class MemoryStore {
 				const now = new Date();
 
 				await this.#maybeSnapshot(options, "write", [INDEX_FILE, file]);
-				await writeFile(
-					join(this.cfg.memoryDir, file),
-					serializeEntryFile(
-						{
-							name,
-							description,
-							type: input.type ?? existing?.type ?? "feedback",
-							created,
-							modified: now.toISOString(),
-						},
-						body,
+				await this.#retry(() =>
+					writeFile(
+						join(this.cfg.memoryDir, file),
+						serializeEntryFile(
+							{
+								name,
+								description,
+								type: input.type ?? existing?.type ?? "feedback",
+								created,
+								modified: now.toISOString(),
+							},
+							body,
+						),
+						"utf8",
 					),
-					"utf8",
 				);
 
 				const next = upsertIndexLine(await this.readIndex(), { name, file, description });
-				await writeFile(this.#indexPath(), next, "utf8");
+				await this.#retry(() => writeFile(this.#indexPath(), next, "utf8"));
 				this.#cache.delete(file);
 
 				return { file, capacityWarning: this.#capacityWarning(next) };
@@ -407,26 +427,28 @@ export class MemoryStore {
 				const file = name === current.name ? current.file : await this.#resolveTargetFile(name, current.file);
 
 				await this.#maybeSnapshot(options, "write", [INDEX_FILE, current.file, file]);
-				await writeFile(
-					join(this.cfg.memoryDir, file),
-					serializeEntryFile(
-						{
-							name,
-							description,
-							type: patch.type ?? current.type,
-							created: current.created,
-							modified: new Date().toISOString(),
-						},
-						body,
+				await this.#retry(() =>
+					writeFile(
+						join(this.cfg.memoryDir, file),
+						serializeEntryFile(
+							{
+								name,
+								description,
+								type: patch.type ?? current.type,
+								created: current.created,
+								modified: new Date().toISOString(),
+							},
+							body,
+						),
+						"utf8",
 					),
-					"utf8",
 				);
 				if (file !== current.file) {
 					// 大小写不敏感 / 做 Unicode 规范化的文件系统上，两个不同的字符串可能指向同一 inode；
 					// 那种情况下上面的 writeFile 已经写穿了原文件，再 unlink 会把刚写入的文件删掉。
 					const target = join(this.cfg.memoryDir, file);
 					const source = join(this.cfg.memoryDir, current.file);
-					if (!(await sameFile(target, source))) await unlinkStrict(source);
+					if (!(await sameFile(target, source))) await this.#retry(() => unlinkStrict(source));
 				}
 
 				const raw = await this.readIndex();
@@ -442,7 +464,7 @@ export class MemoryStore {
 					{ name, file, description },
 					line ? { atLineNo: line.lineNo } : undefined,
 				);
-				await writeFile(this.#indexPath(), next, "utf8");
+				await this.#retry(() => writeFile(this.#indexPath(), next, "utf8"));
 				this.#cache.delete(current.file);
 				this.#cache.delete(file);
 
@@ -456,8 +478,9 @@ export class MemoryStore {
 				if (!current) throw new Error(`Entry "${ref}" not found`);
 
 				await this.#maybeSnapshot(options, "write", [INDEX_FILE, current.file]);
-				await unlinkStrict(join(this.cfg.memoryDir, current.file));
-				await writeFile(this.#indexPath(), removeIndexLine(await this.readIndex(), current.file), "utf8");
+				await this.#retry(() => unlinkStrict(join(this.cfg.memoryDir, current.file)));
+				const next = removeIndexLine(await this.readIndex(), current.file);
+				await this.#retry(() => writeFile(this.#indexPath(), next, "utf8"));
 				this.#cache.delete(current.file);
 		});
 	}
@@ -483,7 +506,9 @@ export class MemoryStore {
 					...effectiveHeader,
 					...summaries.map((s) => formatIndexLine(s.name, s.file, s.description)),
 				];
-				await writeFile(this.#indexPath(), rebuilt.length === 0 ? "" : `${rebuilt.join("\n")}\n`, "utf8");
+				await this.#retry(() =>
+					writeFile(this.#indexPath(), rebuilt.length === 0 ? "" : `${rebuilt.join("\n")}\n`, "utf8"),
+				);
 				this.#cache.clear();
 
 				return { entries: summaries.length, headerLines: effectiveHeader.length };

package/src/paths.ts

@@ -1,11 +1,25 @@
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
-import { join, resolve } from "node:path";
+import { join, posix, resolve, win32 } from "node:path";
 import { promisify } from "node:util";
+import { windowsSafeName } from "./windows-names";
 
 const execFileP = promisify(execFile);
 const GIT_TIMEOUT_MS = 3000;
 
+/**
+ * 仓库根：`git rev-parse --show-toplevel`（绝对路径）。
+ *
+ * 2026-10-04 用户决定回到这个实现（spec Ruling 12，**撤销 Ruling 3**）：Windows 上只用
+ * PowerShell、Git Bash 不在支持面内，所以「MSYS 形态输出会让 `resolve()` 得到 `C:\c\…`」这条
+ * 动机消失。随之删除了 `--is-inside-work-tree` 判据与 MSYS 仿真用例：裸仓库、cwd 在 `.git`
+ * 内部（含 `.git/objects`）时 git 以 `fatal: this operation must be run in a work tree` 退出，
+ * 这里天然返回 `null`，调用方落回 `local/<绝对路径>`；非仓库同样由 catch 返回 `null`。
+ *
+ * 已知限制（spec §7）：若 PATH 上的 `git` 是 cygwin/MSYS 构建（对任何调用者都打印
+ * `/cygdrive/c/…` 这类 POSIX 形态路径），`resolve()` 会得到错误前缀 —— 同一项目会出现第二个
+ * 记忆目录。Git for Windows 的 `git.exe` 打印原生路径，不受影响。
+ */
 async function gitToplevel(cwd: string): Promise<string | null> {
 	try {
 		const { stdout } = await execFileP("git", ["rev-parse", "--show-toplevel"], { cwd, timeout: GIT_TIMEOUT_MS });
@@ -38,24 +52,41 @@ function truncateToBytes(input: string, maxBytes: number): string {
 	return kept;
 }
 
+export interface NamingOptions {
+	/** 命名规则跟随的平台（默认 `process.platform`）。win32 上 `\` 作为分隔符参与分段。 */
+	platform?: NodeJS.Platform;
+}
+
+// win32 上 `\` 也是分隔符 —— 它必须参与分段，而不是被转义成字面量：转义会让整个名字在
+// `join(memoryDir, …)` 时仍被拆成多级目录（`local/C_3a/Users/...`），而畸形 key
+// （`host/a\..\..\..\etc`）里的 `..` 段还能让目录逃出 memoryDir（spec §1.2 P1/P7）。
+const PATH_SEPARATORS = /[/\\]/;
+const POSIX_SEPARATORS = /\//;
+
 /**
  * Encode a project key into a single, human-readable directory name.
- * `host/repo/path` → `host__repo__path`; `/abs/path` → `abs__path`.
- * Naming targets POSIX filesystems: `\` is an ordinary character, without
- * Windows device-name or trailing-dot handling.
+ * `host/repo/path` → `host__repo__path`; `/abs/path` → `abs__path`。
+ *
+ * 平台差异（spec Ruling 1/D2）：win32 上按 `/` 与 `\` 双分隔符分段，并保证输出满足三条
+ * 不变量 —— 不含分隔符、不以 `.`/空格结尾、不是保留设备名；POSIX 上 `\` 仍是普通字符，
+ * 输出与 win32 支持引入前逐字节一致。
  */
-export function projectDirName(key: string): string {
+export function projectDirName(key: string, options?: NamingOptions): string {
+	const platform = options?.platform ?? process.platform;
+	const separator = platform === "win32" ? PATH_SEPARATORS : POSIX_SEPARATORS;
 	const segments = key
-		.split("/")
+		.split(separator)
 		.filter((segment) => segment !== "" && segment !== "." && segment !== "..")
 		.map(escapeSegment);
 	if (segments.length === 0) return "root";
 	const joined = segments.join("__");
 	// Filesystems cap one name at 255 bytes: count bytes so multi-byte names
 	// (CJK, emoji) cannot exceed the limit, and cut on code point boundaries.
-	if (Buffer.byteLength(joined, "utf8") <= DIR_NAME_MAX_BYTES) return joined;
-	const suffix = createHash("sha256").update(key).digest("hex").slice(0, HASH_LENGTH);
-	return `${truncateToBytes(joined, DIR_NAME_KEEP_BYTES)}__${suffix}`;
+	const name =
+		Buffer.byteLength(joined, "utf8") <= DIR_NAME_MAX_BYTES
+			? joined
+			: `${truncateToBytes(joined, DIR_NAME_KEEP_BYTES)}__${createHash("sha256").update(key).digest("hex").slice(0, HASH_LENGTH)}`;
+	return platform === "win32" ? windowsSafeName(name) : name;
 }
 
 export type ProjectKind = "git" | "local";
@@ -68,6 +99,12 @@ export interface ProjectIdentity {
 
 const GIT_PROTOCOLS = new Set(["http", "https", "ssh", "git"]);
 const SCHEME_URL = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+/**
+ * Windows 盘符路径（`Z:\…` / `Z:/…`）。在 win32 上这是**本地路径**，不是 scp 的 `host:path`：
+ * Git for Windows 就这么解释（用户可以 `git clone Z:\some.git`）；而 `resolve()` 会把它当成
+ * host `z`（spec Ruling 13）。POSIX 上同一串是合法的 scp 写法（host `C`），与 git 一致，不改判。
+ */
+const WINDOWS_DRIVE_PATH = /^[a-zA-Z]:[\\/]/;
 
 /** Lowercase and IDN-normalize a host the way the URL API does for https. */
 function normalizeHost(host: string): string {
@@ -81,11 +118,14 @@ function normalizeHost(host: string): string {
 /**
  * Normalize an http(s)/ssh/git remote URL to `host/path`.
  * Accepts `[user@]host:path` scp syntax and `git+ssh` / `git+https` aliases.
- * Returns null for file:// URLs, local paths and URLs without a repository path.
+ * Returns null for file:// URLs, local paths and URLs without a repository path
+ * （因此盘符本地 remote 在 win32 上也返回 null → 落回 `local/<绝对路径>`）。
  */
-export function normalizeRemoteUrl(url: string): string | null {
+export function normalizeRemoteUrl(url: string, platform: NodeJS.Platform = process.platform): string | null {
 	const raw = url.trim();
 	if (!raw) return null;
+	// win32 上「盘符 + 分隔符」开头的是本地路径，不是 scp 的 host（见 `WINDOWS_DRIVE_PATH`）。
+	if (platform === "win32" && WINDOWS_DRIVE_PATH.test(raw)) return null;
 
 	let host: string;
 	let path: string;
@@ -160,18 +200,46 @@ async function gitRemoteUrls(cwd: string): Promise<RemoteEntry[]> {
 	}
 }
 
-/** Resolve the project identity: normalized git remote, or the project root path. */
-export async function projectIdentity(cwd: string): Promise<ProjectIdentity> {
+/** Resolve the project identity: normalized git remote, or the project root path.
+ *
+ * `platform` 决定盘符远程的归类（win32 上当本地路径，见 `normalizeRemoteUrl`）；其余平台行为不变。
+ */
+export async function projectIdentity(cwd: string, platform: NodeJS.Platform = process.platform): Promise<ProjectIdentity> {
 	const toplevel = await gitToplevel(cwd);
 	if (!toplevel) return { kind: "local", key: resolve(cwd) };
 	for (const { url } of await gitRemoteUrls(cwd)) {
-		const key = normalizeRemoteUrl(url);
+		const key = normalizeRemoteUrl(url, platform);
 		if (key) return { kind: "git", key };
 	}
 	return { kind: "local", key: resolve(toplevel) };
 }
 
+type PathApi = typeof import("node:path");
+
+/**
+ * 断言 `dir` 确实是 `base` 之内的一层（spec §4.2 / D4）。
+ *
+ * 派生名一旦含有分隔符，`join` 就会把它拆成多级路径 —— 畸形 remote（key 里带 `\..\..`）
+ * 能让目录逃出 `memoryDir`。fail-closed：越界即抛错，由 session_start 转成配置错误态，
+ * 而不是悄悄写到别的地方。
+ *
+ * 导出仅为直接单测：POSIX 命名下 `projectDirName` 不可能产出分隔符，公开 API 走不到这条分支。
+ * `platform` 决定用哪套 `path` 语义（win32 的 `relative` 大小写不敏感、认 `\` 与盘符）。
+ */
+export function assertInsideRoot(base: string, dir: string, platform: NodeJS.Platform = process.platform): void {
+	const api: PathApi = platform === "win32" ? win32 : posix;
+	const rel = api.relative(base, dir);
+	if (rel === "" || rel.startsWith("..") || api.isAbsolute(rel)) {
+		throw new Error(`Refusing to use memory directory ${dir}: it escapes ${base}`);
+	}
+}
+
 export async function resolveMemoryDir(config: { memoryDir: string }, cwd: string): Promise<string> {
 	const { kind, key } = await projectIdentity(cwd);
-	return join(config.memoryDir, kind, projectDirName(key));
+	// 相对路径配置（如 `"./memory"`）固化成绝对路径：逻辑锁的 key 用这个字符串，
+	// 同一目录的不同写法不该得到两把锁（见 `memory-store.ts` 的 `#logicalKey`）。
+	const base = resolve(config.memoryDir);
+	const dir = join(base, kind, projectDirName(key));
+	assertInsideRoot(base, dir);
+	return dir;
 }

package/src/snapshot.ts

@@ -1,9 +1,22 @@
 import { cp, mkdir, readdir, rm, stat } from "node:fs/promises";
 import { basename, join } from "node:path";
+import { withFsRetry } from "./fs-retry";
 
 export interface SnapshotOptions {
 	keep: number;
 	now?: () => Date;
+	/** 重试判定跟随的平台（默认 `process.platform`）：win32 才把 EPERM/EACCES 当瞬时错误。 */
+	platform?: NodeJS.Platform;
+}
+
+/**
+ * 只包住**幂等**的物理调用（`mkdir` 是 `recursive` 的、`cp` 会覆盖），因此重试不会产生副作用。
+ * 快照跑在**每一次**写入原语里（memory-store 的 `#maybeSnapshot`，已在跨进程锁之内），而
+ * Windows 上杀软扫描与同步客户端打断的正是 `mkdir`/`cp` 这类调用：不重试的话，一次瞬时
+ * EPERM 就会让 `memory add` 直接失败（spec §1.2 P5）。
+ */
+function withSnapshotRetry<T>(fn: () => Promise<T>, platform?: NodeJS.Platform): Promise<T> {
+	return withFsRetry(fn, { platform });
 }
 
 /** 可字典序排序的快照时间戳（ISO 8601，`:` 与 `.` 换为 `-`）。 */
@@ -11,14 +24,16 @@ export function snapshotStamp(now: () => Date): string {
 	return now().toISOString().replace(/[:.]/g, "-");
 }
 
-async function uniqueDir(backupRoot: string, base: string): Promise<string> {
-	await mkdir(backupRoot, { recursive: true });
+async function uniqueDir(backupRoot: string, base: string, platform?: NodeJS.Platform): Promise<string> {
+	await withSnapshotRetry(() => mkdir(backupRoot, { recursive: true }), platform);
 	for (let n = 1; ; n++) {
 		const candidate = n === 1 ? join(backupRoot, base) : join(backupRoot, `${base}-${n}`);
 		try {
-			await mkdir(candidate);
+			await withSnapshotRetry(() => mkdir(candidate), platform);
 			return candidate;
 		} catch (e) {
+			// EEXIST 仍然是「换下一个名字」的信号：它不在 `withFsRetry` 的瞬时错误集合里，
+			// 重试不会吞掉它（重名快照的用例靠这一行）。
 			if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
 		}
 	}
@@ -32,11 +47,16 @@ export async function createSnapshot(
 	memoryDir: string,
 	options: SnapshotOptions,
 ): Promise<string> {
-	const dir = await uniqueDir(backupRoot, `${snapshotStamp(options.now ?? (() => new Date()))}-${label}`);
+	const dir = await uniqueDir(
+		backupRoot,
+		`${snapshotStamp(options.now ?? (() => new Date()))}-${label}`,
+		options.platform,
+	);
 	for (const file of files) {
 		try {
-			await cp(join(memoryDir, file), join(dir, basename(file)));
+			await withSnapshotRetry(() => cp(join(memoryDir, file), join(dir, basename(file))), options.platform);
 		} catch (e) {
+			// ENOENT（条目文件还不存在）同样不在重试集合里：跳过行为不变。
 			if ((e as NodeJS.ErrnoException).code === "ENOENT") continue;
 			throw e;
 		}
@@ -63,6 +83,9 @@ export async function pruneSnapshots(backupRoot: string, keep: number): Promise<
 
 	dirs.sort();
 	for (const name of dirs.slice(0, Math.max(0, dirs.length - Math.max(0, keep)))) {
-		await rm(join(backupRoot, name), { recursive: true, force: true });
+		// 删目录会被杀软/索引器打成瞬时 EPERM/EBUSY：用 Node 自带的退避重试。
+		// 这两个参数**不是 Windows 专属**（Linux 上实测：`maxRetries: 3, retryDelay: 300`
+		// 会把一个 EMFILE 重试三次），因此全平台都生效。
+		await rm(join(backupRoot, name), { recursive: true, force: true, maxRetries: 6, retryDelay: 50 });
 	}
 }

package/src/windows-names.ts

@@ -0,0 +1,39 @@
+/**
+ * Windows 名字的两条硬规则。目录名（`paths.ts`）与 entry 文件名（`filename.ts`）共用。
+ *
+ * 为什么需要（spec §1.2 P2/P6）：
+ * - Windows 把一组「保留设备名」当设备：`NUL`、`CON`、`COM1`…；**带扩展名也一样**
+ *   （`NUL.txt`、`NUL.tar.gz` 都等价于 `NUL`），判定基准是「第一个 `.` 之前的部分」。
+ *   用这些名字创建文件得不到文件：写入落到设备上（`con.md` 写进控制台），而索引里
+ *   已经多了一行 —— 表现为静默丢记忆。
+ * - Windows 静默剥掉结尾的 `.` 与空格：`proj.` 与 `proj ` 都是 `proj`，
+ *   于是两个不同的 key 会撞进同一个目录。
+ *
+ * 两条规则**全平台生效**：git 类记忆目录跨机共享，名字必须在两边都安全（spec Ruling 5）。
+ */
+
+/** 保留设备名（大小写不敏感）。MS 文档的经典集合 + 控制台别名。 */
+const RESERVED_BASE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9]|conin\$|conout\$)$/i;
+
+/** 判定基准是**第一个 `.` 之前的部分**：`NUL.tar.gz` 等价于 `NUL`。 */
+export function isReservedWindowsName(name: string): boolean {
+	const dot = name.indexOf(".");
+	return RESERVED_BASE.test(dot === -1 ? name : name.slice(0, dot));
+}
+
+/** 结尾的 `.` / 空格 → `_2e` / `_20`（沿用 `escapeSegment` 的 `_XX` 十六进制词汇表）。 */
+export function escapeWindowsTrailing(name: string): string {
+	const last = name[name.length - 1];
+	if (last === ".") return `${name.slice(0, -1)}_2e`;
+	if (last === " ") return `${name.slice(0, -1)}_20`;
+	return name;
+}
+
+/**
+ * 把名字收尾成 Windows 可安全使用的形态。
+ * 顺序固定：先转义结尾点/空格、再判保留名（固定只为确定性；两种顺序都安全）。
+ */
+export function windowsSafeName(name: string): string {
+	const escaped = escapeWindowsTrailing(name);
+	return isReservedWindowsName(escaped) ? `_${escaped}` : escaped;
+}