@dimina-kit/fs-core 0.2.0-dev.20260710085051 → 0.3.0-dev.6-dev.20260711133419

package/README.md

@@ -1,6 +1,11 @@
 # @dimina-kit/fs-core
 
-浏览器端 OPFS WAL 文件系统内核：单写者权威（Web Locks 选主）、WAL-first 写序、checkpoint/restore 回滚、agent 写权 turn 门控，零运行时依赖。
+浏览器端 OPFS WAL 文件系统内核：单写者权威（Web Locks 选主 + 协作交接）、WAL-first 写序、checkpoint/restore 回滚、agent 写权 turn 门控，零运行时依赖。
+
+给两类宿主用：
+
+- **fs-core 即真相源**的宿主（如 qdmp-web-workbench）：项目文件直接活在 OPFS 账本里，导出/落盘是下游动作（`/disk-mirror`、`/zip`）。
+- **磁盘才是真相源**的宿主（如 dimina-kit workbench/devtools）：fs-core 只做记账与 agent 写权执法，`/sync` 引擎负责磁盘↔账本双向对账。
 
 ## 安装
 
@@ -8,38 +13,220 @@
 npm i @dimina-kit/fs-core
 ```
 
-## 入口
-
-| 子路径 | 用途 |
-| --- | --- |
-| `@dimina-kit/fs-core/client` | `ProjectFsClient.connect({ projectId })`：读写/快照/grep/glob、`mode`/`onModeChange`（多标签页单写者可见性）、turn API |
-| `@dimina-kit/fs-core/agent-tools` | fs_read/fs_write/fs_restore 等 agent 工具面（fs-core 侧 turn 执法） |
-| `@dimina-kit/fs-core/disk-mirror` | File System Access 目录镜像（防抖增量写盘，`pick(handle)` 可注入已授权句柄） |
-| `@dimina-kit/fs-core/sync` | 磁盘↔账本同步引擎（TruthPort 适配外部真相源） |
-| `@dimina-kit/fs-core/zip` | 快照打包为 ZIP |
-
-## 使用
+## 快速上手
 
 ```js
 import { ProjectFsClient } from '@dimina-kit/fs-core/client'
 
-// 宿主需把 dist/fs-core.worker.js 与 dist/fs-query.worker.js 部署到可访问 URL
-// （默认约定 /ide/fs/ 下），client 以 module worker 加载它们。
+// 宿主需把 dist/fs-core.worker.js 与 dist/fs-query.worker.js 部署到可访问 URL，
+// client 以 module worker 加载它们。coreUrl/queryUrl 的缺省值 /ide/fs/ 是最初
+// dwc 宿主的部署形状；其它宿主都应显式传入自己的 URL。文件名/位置的单一权威
+// 见 `@dimina-kit/fs-core/worker-files` 的 resolveWorkerFiles()。
 const fs = await ProjectFsClient.connect({
   projectId: 'my-project',
   coreUrl: '/ide/fs/fs-core.worker.js',
   queryUrl: '/ide/fs/fs-query.worker.js',
 })
-await fs.write('app.json', '{}')
-const { content } = await fs.read('app.json')
+const { gen, rev } = await fs.write('app.json', '{}') // 写 API 的 opts 与返回值全部类型化
+const { content } = await fs.read('app.json')         //（FsWriteCallOpts / FsWriteResult 等随 /client 导出）
+
+// 错误处理按符号匹配（错误码契约见 `/protocol`）：
+import { isFsCoreErrorCode } from '@dimina-kit/fs-core/protocol'
+try {
+  await fs.write('app.json', '{}')
+} catch (e) {
+  if (isFsCoreErrorCode(e, 'readonly')) {
+    /* 另一个标签页持有写权 —— 见下文「多标签页单写者」 */
+  }
+}
 ```
 
-## Worker 产物约束
+### Worker 产物部署
 
-`dist/fs-core.worker.js` 与 `dist/fs-query.worker.js` 是单文件自包含 ESM（无 import 语句、零依赖），宿主按字面文件名从 `dist/` 拷贝/托管即可；以 module worker（`{ type: 'module' }`）加载。
+`dist/fs-core.worker.js` 与 `dist/fs-query.worker.js` 是单文件自包含 ESM（无 import 语句、零依赖），宿主按**字面文件名**从 `dist/` 拷贝/托管即可，以 module worker（`{ type: 'module' }`）加载。构建脚本请消费 `@dimina-kit/fs-core/worker-files` 的 `resolveWorkerFiles()`（ESM/CJS 双形态）拿文件名与路径，不要手拼。
 
 需要 OPFS（`navigator.storage.getDirectory`）与 `createSyncAccessHandle`（worker 内），即 Chromium ≥ 102 一类环境；不依赖 COI。
 
+## 架构总览
+
+三个执行体，一条权威链：
+
+```mermaid
+flowchart LR
+  subgraph 主线程
+    C["ProjectFsClient<br/>（RPC 封装 + opId 幂等重试 + mode 状态机）"]
+  end
+  subgraph "fs-core worker（单写者权威）"
+    W["FsCore<br/>WAL append / 内存镜像 / turn 执法 / compaction"]
+  end
+  subgraph "fs-query worker（只读副本）"
+    Q["快照 / grep / glob<br/>（不占写路径）"]
+  end
+  C -- "写类 op（write/rm/mv/restore/turn*）" --> W
+  C -- "查询类 op（snapshot/grep/glob）" --> Q
+  W -- "diff 端口（增量推送镜像）" --> Q
+  W -- "事件（fs-change / writer-granted / writer-lost / FATAL）" --> C
+```
+
+- **fs-core worker** 是唯一权威：持有 OPFS 写句柄，所有写序列化在一条 `enqueue` 链上。
+- **fs-query worker** 是它的只读投影：core 经专用 MessagePort 推增量 diff，重查询（全量快照、grep、glob）在这里跑，不打扰写路径。
+- **client** 只是主线程的便利面：Promise API、写超时后按同 `opId` 幂等重试恰一次、把 worker 事件翻译成 `mode`/`onChange`。
+
+### 持久层布局（OPFS，无物化文件树）
+
+```
+<projectId>/blobs/<h2>/<sha256>   内容寻址、不可变、写后 flush
+<projectId>/manifests/<gen>.json  compaction 产物（CRC 记录在 superblock）
+<projectId>/wal.<startGen>        分段 append-only 日志，禁止原地重写/truncate
+<projectId>/superblock            双槽定长 64B×2；只写非当前槽，flush 后翻转
+```
+
+### WAL-first 写序
+
+每个写类 op 严格按 **blob flush → WAL append（组提交 flush）→ 应用内存镜像 → ack(opId) → 广播** 的顺序执行。ack 语义：**已 ack 必恢复；未 ack 可能恢复**——超时重试用同 `opId` 消歧（fs-core 对已知 opId 直接返回既有结果，不重放副作用）。
+
+```mermaid
+sequenceDiagram
+  participant C as client
+  participant W as fs-core worker
+  participant O as OPFS
+  C->>W: write(path, content, opId)
+  W->>O: blob flush（内容寻址，>4KB 才落 blob，小 payload 内联进 WAL）
+  W->>O: WAL append + 组提交 flush（50ms 窗口）
+  W->>W: 应用内存镜像（gen++）
+  W-->>C: ack {gen, rev}（同 opId 重放 → 直接返回该结果）
+  W-->>C: 广播 fs-change 事件
+  W-->>W: 段超 4MB → 影子 compaction（manifest 物化 + 新段 + superblock 翻转）
+```
+
+崩溃恢复（worker 启动时）：superblock 双槽选优 → 加载 manifest（CRC 校验）→ 按段升序回放 WAL 有效前缀（帧级 CRC，坏尾截断）→ 重建内存镜像与 opId 窗口。
+
+## 多标签页单写者与协作交接
+
+同一 `projectId` 只有一个写者：Web Locks `'dwc:writer:<projectId>'` 排队互斥，**禁 steal**。
+
+- 后开的标签页 3s 拿不到锁即以 **readonly** 服务（`fs.mode === 'readonly'`，经 `onModeChange` 订阅变化），排队请求保留，锁 granted 后自动升级为写者。
+- readonly 端可调 `fs.requestHandover()` **主动请求交接**：现任写者排干（flush + 关句柄）后释放锁，本端排队请求随之 granted。何时发起是宿主的 UI 策略（典型：在"另一个标签页持有写权"提示上放"在此接管"动作），fs-core 只提供机制、绝不自动重发；同一 pending 周期内重复调用被合并。只有 readonly 会真正行动：writer/dead/starting 上调用是 no-op（如实返回 `{mode}`），draining 以错误码 `'draining'` 拒绝。
+- **锁仲裁本身失败**（Web Locks 层异常，非"被人占着"）一律 FATAL——绝不无锁当写者，也绝不静默滞留 readonly。能跑 fs-core（OPFS SyncAccessHandle）的环境必有 Web Locks，仲裁失败只可能是异常环境，诚实死掉比装活好。
+- **拿到锁但升级失败**（恢复/开句柄抛错）同样 FATAL，且**必定释放锁**——失败的 worker 绝不占着锁当死写者，后面排队的标签页正常接手。
+
+```mermaid
+sequenceDiagram
+  participant A as Tab A（写者）
+  participant L as Web Locks
+  participant B as Tab B（readonly，排队中）
+  Note over B: 用户点"在此接管写权"
+  B->>B: requestHandover()（无排队请求则先重新排队）
+  B-->>A: BroadcastChannel: handover-request
+  A->>A: 排干：flushWindow → 关 WAL/superblock 句柄 → mode=readonly
+  A->>L: 释放写者锁
+  A-->>B: BroadcastChannel: handover-done（各 readonly 端复位合并标志）
+  A->>A: 发 writer-lost 事件（宿主提示"已交出写权"）
+  L->>B: 锁 granted
+  B->>B: becomeWriter：recover（以盘上状态为准重建）→ epoch++ → mode=writer
+  B->>B: 发 writer-granted 事件（宿主撤 readonly 提示）
+```
+
+交出写权的一端**不会**自动重新排队（否则两个 tab 会互相抢）；它再次调用 `requestHandover()` 时才重新排队并广播。
+
+## Agent 写权：turn 门控与回滚
+
+agent（`actor: 'agent'`）的写必须发生在一个活跃 turn 内，执法在 fs-core worker 侧（`checkTurn` 与 WAL append 同一同步块，无竞态窗口）——调用方伪造不了：
+
+1. `turnBegin(turnId)`：铸造 turn，同时自动打一个 checkpoint 锚（回滚点）；有 TTL 与 per-turn op 限额（跑飞的 agent 刹车）。
+2. turn 内的 `write/edit/rm/mv`：携带 `{actor:'agent', turnId}`；宿主可另经 `armAgentTokenGate(token)` 上第二道令牌门（令牌只有内核持有，防同 realm 内伪造）。
+3. `diff(turnId)`：该 turn 的全部改动清单（WAL 审计标注免费提供）。
+4. `restore(cpId)`：回滚到锚点；非 force 时做冲突执法——锚点之后存在人类写则拒绝（附 `humanPaths`），审计环覆盖不到的历史一律保守拒绝。
+5. `turnEnd(turnId)`：撤销 turn（同步置位，立即生效）。
+
+`@dimina-kit/fs-core/agent-tools` 提供 MCP 形状的工具表包装（`fs_read`/`fs_write`/`fs_restore`/…，execute 自动注入 turnId，模型伪造不了别的 turn）。
+
+## 两套磁盘机制的划界（永不合流）
+
+- **`/disk-mirror`**：OPFS 真相源 → 本地目录的**单向导出**（File System Access，防抖全量比对写盘）。适用于"fs-core 即真相源"的宿主（如 qdmp-web-workbench）想把内容落到本地磁盘。
+- **`/sync`**：**外部真相源 ↔ fs-core 账本的双向对账引擎**（TruthPort 抽象外部真相源；echo 判据、FIFO 序列化、二进制侧车）。适用于"磁盘才是真相源、fs-core 只记账"的宿主（如 dimina-kit workbench 经 `/__fs` 桥 + SSE watch）。
+- 一个宿主真需要双向时，正确姿势是给 `/sync` 写一个 poll 形态的 TruthPort 适配器，而不是把 `/disk-mirror` 养成第二个同步引擎。
+- **未来 poll 适配器须自持的不变量**（引擎只服务 push 形态宿主，不内置 poll 侧机制）：poll 宿主自己驱动出站扫描（读账本→写真相源），因此必须自己防"刚从真相源灌入的变更被自己的出站扫描原样回写"——抑制记录须**一次性消费**（命中即清除，不是常驻内容缓存）、匹配须区分文本/字节/删除三种形态、且**绝不能把真相源"读不到"（瞬时 I/O 失败）推断为删除**。
+
+## `/sync` 同步引擎
+
+宿主注入两件东西，拿回一个引擎：
+
+```ts
+import { createSyncEngine } from '@dimina-kit/fs-core/sync'
+
+const engine = createSyncEngine(client /* fs-core 账本 */, truthPort /* 外部真相源 */, {
+  applyToEditor: async (rel, bytes) => { /* 入站变更灌进编辑器 buffer；bytes===null 是删除 */ },
+  onDegraded: (d) => { /* 降级上抛：watcher-dead / path-sync-failed（见下） */ },
+})
+await engine.populateLedger() // 全量播种 + 对账残留
+engine.start()                // 订阅 truthPort.changes，开始入站对账
+```
+
+核心机制：
+
+- **ledgerTurn FIFO**：入站批与 `onHumanSave` 记账走同一条 FIFO，二者永不交错——飞行中保存的同路径入站通知总能看到保存完成后的账本记录。
+- **echo 判据**（双向都是内容比较）：入站字节 == 账本记录 → 是自己上次写的回声，丢弃；出站保存 == 账本记录 → 冗余，跳过。
+- **二进制分层**：NUL 嗅探分类，二进制永不进字符串账本，由 `binary-sidecar` 的 `{size, sha256}` 索引承接（echo 判据 = 尺寸+哈希相等）。二进制无 WAL 审计/回滚（审计面是字符串契约）。
+- **降级必须 loud**（`onDegraded`）：
+  - `{kind:'watcher-dead'}`——变更订阅死了，此后账本只反映打开时镜像 + 已处理的批；
+  - `{kind:'path-sync-failed', rel, stage:'truth-read'|'reconcile', error}`——单路径对账失败被跳过（真相源读失败 / 账本写失败）。
+  静默跳过会让账本漂移而无人知晓，所以事件与 console 告警**同时**发。
+
+```mermaid
+sequenceDiagram
+  participant T as TruthPort（磁盘/桥）
+  participant E as sync 引擎
+  participant F as fs-core 账本
+  participant Ed as 编辑器 buffer
+  T-->>E: changes 批 [a.js, b.png]
+  E->>T: read(a.js)
+  alt 内容 == 账本记录
+    E->>E: 自己写的回声 → 丢弃
+  else 新内容
+    E->>F: client.write(a.js, text, {actor:'human'})
+    E->>Ed: applyToEditor(a.js, bytes)
+  end
+  E->>T: read(b.png)（NUL 嗅探 → 二进制）
+  E->>E: binary-sidecar.put()（尺寸+哈希判 echo）
+  E->>Ed: applyToEditor(b.png, bytes)
+  Note over E: read 瞬时失败 → 跳过该路径 + onDegraded(path-sync-failed)
+```
+
+watch 事件是 coalesced/有损的（macOS FSEvents 会合并突发、丢递归删除的子项）——TruthPort 适配器在喂给引擎**之前**先经 `watch-expander` 做 stat 级核对展开，引擎信任到手的批。
+
+## 宿主接入清单
+
+**形态一：fs-core 即真相源**（qdmp 形状）
+
+1. `ProjectFsClient.connect()`，项目加载时播种（注意换项目要"rm 旧 + 覆盖写新"的重置语义，`seed()` 是"非空即跳过"）。
+2. 订阅 `onModeChange` 呈现多标签页写权状态；readonly 提示上挂 `requestHandover()` 动作。
+3. 二进制资产自建 `binary-sidecar`（`retainBytes: true`），导出/编译经 `overlay()` 与账本文本合并。
+4. 需要落盘 → `/disk-mirror`；需要打包 → `/zip`。
+
+**形态二：磁盘即真相源**（workbench 形状）
+
+1. 实现 `TruthPort`（read/write/delete/walk/changes），watch 批先过 `watch-expander`。
+2. `createSyncEngine()` + `populateLedger()` + `start()`；人类保存落盘**之后**调 `onHumanSave`（记账是 best-effort，绝不阻塞保存本身）。
+3. 接 `onDegraded` 到宿主可见的通道（状态条/诊断面板），不要只留 console。
+4. agent 写走 turn 门控面（`turnBegin`/`agentWrite`/`diff`/`restore`），磁盘与账本一致后再回灌编辑器。
+
+两种形态都请从 `/protocol` 导入错误码/事件名做符号匹配，不要抄 worker 源码里的字符串字面量。
+
+## 入口一览
+
+| 子路径 | 用途 |
+| --- | --- |
+| `@dimina-kit/fs-core/client` | `ProjectFsClient.connect({ projectId })`：读写/快照/grep/glob、`mode`/`onModeChange`/`requestHandover`（多标签页单写者）、turn API |
+| `@dimina-kit/fs-core/agent-tools` | fs_read/fs_write/fs_restore 等 agent 工具面（fs-core 侧 turn 执法） |
+| `@dimina-kit/fs-core/disk-mirror` | File System Access 目录镜像（防抖增量写盘，`pick(handle)` 可注入已授权句柄） |
+| `@dimina-kit/fs-core/sync` | 磁盘↔账本同步引擎（TruthPort 适配外部真相源；`onDegraded` 降级上抛） |
+| `@dimina-kit/fs-core/sync/binary-sidecar` | 二进制侧车：分类（NUL 嗅探）、`{size, sha256}` 索引、echo 判据、可选 bytes 保留 + `overlay()` 合并 |
+| `@dimina-kit/fs-core/sync/watch-expander` | watch 批扩展 helper（stat 级核对，供 TruthPort 适配器组装 `changes`） |
+| `@dimina-kit/fs-core/protocol` | 线上契约：错误码/事件名/消息形状（消费方按符号匹配，不抄 worker 源码字符串；`/client` 亦有 re-export） |
+| `@dimina-kit/fs-core/worker-files` | Node 侧 worker 产物清单：`FS_CORE_WORKER_FILES` + `resolveWorkerFiles()`（ESM/CJS 双形态） |
+| `@dimina-kit/fs-core/zip` | 快照打包为 ZIP |
+
 ## License
 
 MIT

package/dist/client.js

@@ -1,8 +1,8 @@
-/**
- * ProjectFsClient — 主线程侧 ProjectFS 封装（P0，同 origin）。
- * 起 fs-core / fs-query 两个 worker，牵好 core→query 的 diff 端口，
- * 暴露 Promise API；写请求自动带 opId，超时重试幂等（同 opId 重发）。
- */
+// The wire contract (error codes, event names, message shapes) lives in
+// worker-lib/protocol.ts — shared verbatim with the worker's own emit sites —
+// and is re-exported here so consumers can match on symbols instead of
+// quoting string literals from worker source.
+export { FS_CORE_ERROR_CODES, getFsCoreErrorCode, isFsCoreErrorCode } from './worker-lib/protocol.js';
 const WRITE_TIMEOUT_MS = 8000;
 export class ProjectFsClient {
     projectId;
@@ -18,7 +18,6 @@ export class ProjectFsClient {
     welcome = null;
     pingTimer;
     lastPong;
-    _retried;
     /** 测试用：抹掉一个项目的全部持久层（只能在无 core 运行时调用）。 */
     static async wipe(projectId) {
         const root = await navigator.storage.getDirectory();
@@ -27,6 +26,11 @@ export class ProjectFsClient {
         }
         catch { }
     }
+    /** `coreUrl`/`queryUrl` default to the `/ide/fs/` deployment convention of
+     * the original dwc host (documented in this package's README「使用」节);
+     * every other real host serves the worker files elsewhere and passes both
+     * URLs explicitly — see `resolveWorkerFiles` (`./worker-files`) for the
+     * authoritative file-name/sibling contract. */
     static async connect({ projectId, coreUrl = '/ide/fs/fs-core.worker.js', queryUrl = '/ide/fs/fs-query.worker.js', clientId = 'c-' + Math.random().toString(36).slice(2, 10), }) {
         const c = new ProjectFsClient();
         c.projectId = projectId;
@@ -132,8 +136,10 @@ export class ProjectFsClient {
             const entryResolve = resolve;
             const timer = timeout
                 ? setTimeout(() => {
-                    // 超时重试一次：同 opId 幂等（fs-core 对已知 opId 返回既有结果）
-                    if (opId && !this._retried) {
+                    // 超时重试一次：同 opId 幂等（fs-core 对已知 opId 返回既有结果）；
+                    // 重试自己的 timer 只会终止性 reject，不会再进这个分支，所以每次
+                    // 调用恰好一次重试。
+                    if (opId) {
                         const retryId = ++this.seq;
                         this.pending.set(retryId, { resolve: entryResolve, reject, timer: setTimeout(() => { this.pending.delete(retryId); reject(new Error(op + ' timeout (after retry)')); }, timeout) });
                         this.pending.delete(id);
@@ -166,22 +172,28 @@ export class ProjectFsClient {
     mv(from, to, opts = {}) { return this._writeOp('mv', { from, to, ...opts }); }
     mkdir(path, opts = {}) { return this._writeOp('mkdir', { path, ...opts }); }
     checkpoint(opts = {}) { return this._writeOp('checkpoint', { ...opts }); }
-    /** opts: {baseGen?, force?} 透传给 fs-core（§4.7 restore 冲突策略）；baseGen 缺省时
+    /** opts.baseGen/force 透传给 fs-core（restore 冲突策略）；baseGen 缺省时
      * fs-core 从 checkpoint 自身记录的 gen 推导。 */
     restore(cpId, opts = {}) { return this._writeOp('restore', { cpId, ...opts }); }
     compact() { return this._rpc('compact', {}, { timeout: 30000 }); }
-    // ── P4 turn 能力：铸造（附带 checkpoint 锚）→ agent 写执法 → 撤销 ──
+    // ── turn 能力：铸造（附带 checkpoint 锚）→ agent 写执法 → 撤销 ──
     turnBegin(turnId, opts = {}) { return this._writeOp('turnBegin', { turnId, ...opts }); }
     turnEnd(turnId) { return this._writeOp('turnEnd', { turnId }); }
     /** 该 turn 的改动清单（WAL actor/turnId 审计标注免费提供）。 */
     diff(turnId) { return this._rpc('diff', { turnId }); }
-    /** W4 纵深加固令牌门（docs/k3-terminal-split-plan.md §6 替代方案 A / §8.3）：特权方法，只应
+    /** 纵深加固令牌门：特权方法，只应
      * 由内核（kernel.js createKernel）在 boot 早期调用一次，把只有内核持有的随机令牌交给 fs-core；
      * 此后 actor:'agent' 的写类 op 必须在 opts 里携带匹配的 agentToken（fs-core 侧强制，见
      * fs-core.worker.js checkTurn/armAgentToken）。无 opId/超时重试——一次性 admin 调用，非写路径
      * 幂等本就由 fs-core 的 armAgentToken 自身保证（同令牌重放 ok，不同令牌拒绝）。 */
     armAgentTokenGate(token) { return this._rpc('armAgentTokenGate', { token }); }
     // ── 读 API：小读走 core（权威），查询/快照走 query（不占写路径）──
+    /** readonly 端主动请求写权交接（协作交接协议，禁 steal）：现任写者排干释放后，
+     * 本 client 的排队锁请求 granted → mode 经 writer-granted 事件翻转（订阅
+     * onModeChange 观察结果）。只有 readonly 会真正行动：writer/dead/starting 上
+     * 调用是 no-op（如实返回 {mode}），draining 以错误码 'draining' 拒绝。
+     * 何时调用是宿主策略——典型是用户在"另一个标签页持有写权"提示上点"在此接管"。 */
+    requestHandover() { return this._rpc('requestHandover', {}); }
     read(path) { return this._rpc('read', { path }); }
     ls() { return this._rpc('ls', {}); }
     status() { return this._rpc('status', {}); }

package/dist/disk-mirror.js

@@ -1,7 +1,7 @@
 /**
- * 本地磁盘镜像（P5，Chromium only）—— showDirectoryPicker() 授权一个真实磁盘目录，
+ * 本地磁盘镜像（Chromium only）—— showDirectoryPicker() 授权一个真实磁盘目录，
  * 把项目树 write-through 镜像过去：用户在访达/资源管理器里能看到自己的项目。
- * 这是"持久化到磁盘"的字面回答（架构文档 §4 出口 1）。
+ * 这是"持久化到磁盘"的字面回答。
  *
  * 策略：fs-change 防抖 2s 全量比对同步（内容不变的文件跳过 —— 内容比对在内存，
  * 磁盘只写变更）；删除按上次镜像记录清理。授权需要用户手势，无授权时静默不动。

package/dist/fs-core.worker.js

@@ -120,37 +120,97 @@ function epochFloor(replayed) {
 }
 
 // src/fs-core-recovery.ts
-async function start(core2, projectId) {
-  core2.projectId = projectId;
-  core2.root = await (await navigator.storage.getDirectory()).getDirectoryHandle(projectId, { create: true });
-  core2.bc = new BroadcastChannel("dwc:" + projectId);
-  core2.bc.onmessage = (e) => core2.onBroadcast(e.data);
-  const granted = new Promise((resolve) => {
-    navigator.locks.request("dwc:writer:" + projectId, { mode: "exclusive" }, (lock) => {
+function queueWriterLock(core2) {
+  core2.writerLockQueued = true;
+  return new Promise((resolve, reject) => {
+    navigator.locks.request("dwc:writer:" + core2.projectId, { mode: "exclusive" }, (lock) => {
+      core2.writerLockQueued = false;
+      core2.writerLockHeld = true;
       resolve(lock);
       return new Promise((release) => {
         core2.releaseLock = release;
       });
-    }).catch(() => resolve(null));
+    }).catch((err) => {
+      core2.writerLockQueued = false;
+      reject(err instanceof Error ? err : new Error(String(err)));
+    });
   });
+}
+function failWriterUpgrade(core2) {
+  try {
+    core2.sbHandle?.close();
+  } catch {
+  }
+  try {
+    core2.walHandle?.close();
+  } catch {
+  }
+  core2.sbHandle = null;
+  core2.walHandle = null;
+  if (core2.releaseLock) {
+    core2.releaseLock();
+    core2.releaseLock = null;
+  }
+  core2.writerLockHeld = false;
+  core2.mode = "dead";
+}
+function wireDeferredWriterUpgrade(core2, granted) {
+  granted.then(
+    async (lock) => {
+      if (!lock || core2.mode === "dead") return;
+      try {
+        await core2.enqueue(async () => {
+          await core2.becomeWriter();
+        });
+      } catch (err) {
+        failWriterUpgrade(core2);
+        core2.event({ type: "FATAL", error: "writer upgrade failed: " + String(err) });
+      }
+    },
+    (err) => {
+      core2.mode = "dead";
+      core2.event({ type: "FATAL", error: "writer lock arbitration failed: " + String(err) });
+    }
+  );
+}
+async function start(core2, projectId) {
+  core2.projectId = projectId;
+  core2.root = await (await navigator.storage.getDirectory()).getDirectoryHandle(projectId, { create: true });
+  core2.bc = new BroadcastChannel("dwc:" + projectId);
+  core2.bc.onmessage = (e) => core2.onBroadcast(e.data);
+  const granted = queueWriterLock(core2);
   const winner = await Promise.race([granted, new Promise((r) => setTimeout(() => r("timeout"), 3e3))]);
   if (winner === "timeout") {
     await core2.recover();
     core2.mode = "readonly";
     core2.pushFullToQuery();
     core2.welcome();
-    granted.then(async (lock) => {
-      if (!lock || core2.mode === "dead") return;
-      await core2.enqueue(async () => {
-        await core2.becomeWriter();
-      });
-    });
+    wireDeferredWriterUpgrade(core2, granted);
     return;
   }
-  await core2.becomeWriter();
+  try {
+    await core2.becomeWriter();
+  } catch (err) {
+    failWriterUpgrade(core2);
+    throw err;
+  }
   core2.welcome();
 }
+function requestHandover(core2) {
+  if (core2.mode === "writer") return { mode: "writer" };
+  if (core2.mode === "draining") throw rpcErr("draining", "writer is handing over");
+  if (core2.mode !== "readonly") return { mode: core2.mode };
+  if (core2.handoverRequested) return { requested: true };
+  if (core2.writerLockHeld) return { requested: true };
+  core2.handoverRequested = true;
+  if (!core2.writerLockQueued) {
+    wireDeferredWriterUpgrade(core2, queueWriterLock(core2));
+  }
+  core2.bc.postMessage({ type: "handover-request" });
+  return { requested: true };
+}
 async function becomeWriter(core2) {
+  core2.handoverRequested = false;
   await core2.recover();
   core2.sbHandle = await (await core2.root.getFileHandle("superblock", { create: true })).createSyncAccessHandle();
   core2.epoch += 1;
@@ -373,6 +433,10 @@ function welcome(core2) {
   core2.event({ type: "WELCOME", epoch: core2.epoch, memGen: core2.memGen, readonly: core2.mode !== "writer", mode: core2.mode });
 }
 async function onBroadcast(core2, msg) {
+  if (msg.type === "handover-done" && core2.mode !== "writer") {
+    core2.handoverRequested = false;
+    return;
+  }
   if (msg.type === "handover-request" && core2.mode === "writer") {
     core2.mode = "draining";
     await core2.enqueue(async () => {
@@ -386,6 +450,7 @@ async function onBroadcast(core2, msg) {
         core2.releaseLock();
         core2.releaseLock = null;
       }
+      core2.writerLockHeld = false;
       core2.bc.postMessage({ type: "handover-done", gen: core2.memGen });
       core2.event({ evt: "writer-lost", gen: core2.memGen });
     });
@@ -512,7 +577,7 @@ function flushWindow(core2) {
   let actor = "human";
   for (const w of core2.windowOps) {
     core2.ackGen = Math.max(core2.ackGen, w.gen);
-    if (w.opId) core2.rememberOpId(w.opId, { gen: w.gen });
+    if (w.opId) core2.rememberOpId(w.opId, { gen: w.gen, rev: w.gen, ...w.extra });
     w.respond({ ok: true, result: { gen: w.gen, rev: w.gen, ...w.extra } });
     if (w.path) paths.push(w.path);
     if (w.actor === "agent") actor = "agent";
@@ -652,7 +717,7 @@ async function opRestore(core2, { cpId, baseGen, force = false, actor = "human",
   core2.mirror = next;
   core2.memGen = core2.walGen;
   core2.ackGen = gen;
-  if (opId) core2.rememberOpId(opId, { gen });
+  if (opId) core2.rememberOpId(opId, { gen, restored: Object.keys(files).length });
   core2.pushFullToQuery();
   respond({ ok: true, result: { gen, restored: Object.keys(files).length } });
   core2.event({ evt: "fs-change", gen, actor, count: Object.keys(files).length, restore: cpId });
@@ -784,7 +849,7 @@ var FsCore = class {
   // {turnId, cpId, expiresAt, ops} —— 内存态：worker 重启即失效（安全默认）
   auditLog = [];
   // 环形
-  // W4 纵深加固令牌门（docs/k3-terminal-split-plan.md §6 替代方案 A / §8.3）：只有内核持有的
+  // 纵深加固令牌门：只有内核持有的
   // 随机令牌，一次性置位（armAgentToken）。null = 未 arm（门不生效，checkTurn 不额外校验）——
   // 保证不起内核的裸 fs 场景（fs 域单测/工具，如 test:fs-smoke/test:fs-wal 直连 client）零回归。
   // 同 worker 重启即失效（内存态，不落 WAL/持久层），与 this.turn 同一安全默认。
@@ -795,6 +860,15 @@ var FsCore = class {
   lastSegStart;
   lastSegValidEnd;
   manifestCrc;
+  // 写者锁排队中（granted/仲裁失败时复位）——requestHandover 据此判断是否需要重新排队
+  writerLockQueued = false;
+  // 写者锁已持有（granted 一刻置位；排干释放/升级失败清理时复位）。granted 与
+  // mode='writer' 之间有异步窗口（recover/开句柄）——requestHandover 据此避免
+  // 在升级在途时再排一个陈旧锁请求
+  writerLockHeld = false;
+  // 交接请求合并标志：一个 pending 周期内重复 requestHandover 不追加锁请求/不重复广播；
+  // becomeWriter（自己赢了）或 handover-done 广播（别人赢了）复位
+  handoverRequested = false;
   // ── 启动/恢复/只读查询（fs-core-recovery.ts） ──
   start(projectId) {
     return start(this, projectId);
@@ -844,6 +918,9 @@ var FsCore = class {
   onBroadcast(msg) {
     return onBroadcast(this, msg);
   }
+  requestHandover() {
+    return requestHandover(this);
+  }
   // ── 写路径/compaction（fs-core-write-ops.ts） ──
   enqueue(fn) {
     return enqueue(this, fn);
@@ -928,7 +1005,7 @@ var FsCore = class {
     const fail = (e) => respond({ ok: false, code: e.code || "internal", error: e.message || String(e), ...e.extra || {} });
     if (msg.opId && this.opIds.has(msg.opId)) {
       const known = this.opIds.get(msg.opId);
-      respond({ ok: true, result: { ...known, rev: known.gen, idempotent: true } });
+      respond({ ok: true, result: { rev: known.gen, ...known, idempotent: true } });
       return;
     }
     const a = { ...msg.args, opId: msg.opId };
@@ -950,9 +1027,12 @@ var FsCore = class {
       read: () => respond({ ok: true, result: this.opRead(a) }),
       ls: () => respond({ ok: true, result: this.opLs() }),
       status: () => respond({ ok: true, result: this.opStatus() }),
-      // W4 令牌门铸造（§6 替代方案 A / §8.3）：纯内存状态置位，无 I/O、不让出，
+      // 令牌门铸造：纯内存状态置位，无 I/O、不让出，
       // 不入 WAL 序列化链——同步分支即可（同 read/ls/status），不打扰组提交/恢复逻辑。
-      armAgentTokenGate: () => respond({ ok: true, result: this.armAgentToken(a.token) })
+      armAgentTokenGate: () => respond({ ok: true, result: this.armAgentToken(a.token) }),
+      // 协作交接发起（readonly 端）：广播 + 必要时重新排队锁，纯内存/信道操作，
+      // 不碰 WAL——同步分支（升级本身走 becomeWriter 的 enqueue 路径）。
+      requestHandover: () => respond({ ok: true, result: this.requestHandover() })
     };
     const fn = table[msg.op];
     if (!fn) {