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

package/src/fs-core-recovery-lock.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Guards `start()`'s writer-lock arbitration in fs-core-recovery.ts: the
+ * worker queues for the `navigator.locks` writer lease, serves readonly
+ * after a 3s deadline if the lease has not landed yet, and upgrades once a
+ * deferred grant arrives. A rejected lock request (the lease will never
+ * come — e.g. the browser aborts the request) must not be treated the same
+ * as "still queued": before the deadline it must fail startup outright;
+ * after the deadline it must kill the worker (FATAL) instead of serving
+ * readonly forever with no path back to writer.
+ *
+ * `navigator`/`BroadcastChannel` are OPFS/Web-Locks browser globals absent
+ * from the Node vitest environment, so both are stubbed via `vi.stubGlobal`.
+ * `core` is a structural fake — only the fields `start()` actually touches —
+ * narrowed through `as unknown as FsCore` (see client.test.ts's
+ * `ClientInternals` for the same pattern; no `as any`/`@ts-expect-error`).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import * as recovery from './fs-core-recovery.js'
+import type { FsCore } from './fs-core.worker.js'
+import type { FsCoreMode } from './worker-lib/protocol.js'
+
+type LockRequestFn = (name: string, opts: unknown, cb: (lock: unknown) => Promise<void>) => Promise<unknown>
+
+interface FakeCore {
+  projectId: string
+  root: unknown
+  bc: unknown
+  mode: FsCoreMode
+  releaseLock: (() => void) | null
+  writerLockQueued: boolean
+  sbHandle: { close: () => void } | null
+  walHandle: { close: () => void } | null
+  recover: () => Promise<void>
+  becomeWriter: () => Promise<void>
+  pushFullToQuery: () => void
+  welcome: () => void
+  event: (e: unknown) => void
+  enqueue: (fn: () => unknown) => Promise<unknown>
+  onBroadcast: (msg: { type?: string }) => Promise<void>
+}
+
+function makeCore(overrides: Partial<FakeCore> = {}): FakeCore {
+  return {
+    projectId: '',
+    root: undefined,
+    bc: undefined,
+    mode: 'starting',
+    releaseLock: null,
+    writerLockQueued: false,
+    sbHandle: null,
+    walHandle: null,
+    recover: vi.fn(async () => {}),
+    becomeWriter: vi.fn(async () => {}),
+    pushFullToQuery: vi.fn(),
+    welcome: vi.fn(),
+    event: vi.fn(),
+    enqueue: vi.fn((fn: () => unknown) => Promise.resolve(fn())),
+    onBroadcast: vi.fn(async () => {}),
+    ...overrides,
+  }
+}
+
+/** Stand-in for the global `BroadcastChannel` ctor `start()` calls directly
+ * (`new BroadcastChannel('dwc:' + projectId)`) — not reachable through the
+ * fake `core` object since `start()` overwrites `core.bc` itself. */
+class FakeBroadcastChannel {
+  name: string
+  onmessage: ((e: MessageEvent) => void) | null = null
+  posted: unknown[] = []
+  constructor(name: string) { this.name = name }
+  postMessage(msg: unknown): void { this.posted.push(msg) }
+  close(): void {}
+}
+
+function stubBrowserGlobals(request: LockRequestFn): void {
+  vi.stubGlobal('BroadcastChannel', FakeBroadcastChannel)
+  vi.stubGlobal('navigator', {
+    storage: { getDirectory: async () => ({ getDirectoryHandle: async () => ({}) }) },
+    locks: { request },
+  })
+}
+
+describe('fs-core-recovery start() — writer-lock arbitration', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  it('promotes to writer immediately when the lease is granted before the 3s deadline', async () => {
+    vi.useFakeTimers()
+    const request: LockRequestFn = vi.fn((_name, _opts, cb) => cb({}))
+    stubBrowserGlobals(request)
+    const core = makeCore()
+
+    await recovery.start(core as unknown as FsCore, 'proj-a')
+
+    expect(core.becomeWriter).toHaveBeenCalledTimes(1)
+    expect(core.welcome).toHaveBeenCalledTimes(1)
+    // recover()/pushFullToQuery() are only called directly on the readonly
+    // (timeout) branch — their absence here is evidence the happy path, not
+    // the deadline fallback, was taken.
+    expect(core.recover).not.toHaveBeenCalled()
+    expect(core.pushFullToQuery).not.toHaveBeenCalled()
+  })
+
+  it('a lock request that rejects before the 3s deadline must reject start(), not silently become the writer', async () => {
+    vi.useFakeTimers()
+    const request: LockRequestFn = vi.fn(() => Promise.reject(new Error('writer lock request aborted')))
+    stubBrowserGlobals(request)
+    const core = makeCore()
+
+    await expect(recovery.start(core as unknown as FsCore, 'proj-b')).rejects.toThrow()
+
+    expect(core.becomeWriter).not.toHaveBeenCalled()
+    expect(core.mode).not.toBe('writer')
+  })
+
+  it('falls back to readonly at the 3s deadline, then upgrades once the deferred lock is granted', async () => {
+    vi.useFakeTimers()
+    let grantCb!: (lock: unknown) => Promise<void>
+    const request: LockRequestFn = vi.fn((_name, _opts, cb) => {
+      grantCb = cb
+      return new Promise(() => {}) // only settles through cb's own held-lock promise, unused here
+    })
+    stubBrowserGlobals(request)
+    const core = makeCore()
+
+    const startPromise = recovery.start(core as unknown as FsCore, 'proj-c')
+    await vi.advanceTimersByTimeAsync(3000)
+    await startPromise
+
+    expect(core.recover).toHaveBeenCalledTimes(1)
+    expect(core.mode).toBe('readonly')
+    expect(core.welcome).toHaveBeenCalledTimes(1)
+    expect(core.becomeWriter).not.toHaveBeenCalled()
+
+    grantCb({})
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(core.enqueue).toHaveBeenCalledTimes(1)
+    expect(core.becomeWriter).toHaveBeenCalledTimes(1)
+  })
+
+  it('a lock request that rejects only after the 3s deadline must kill the worker (FATAL), not stay readonly forever', async () => {
+    vi.useFakeTimers()
+    let rejectLock!: (e: unknown) => void
+    const request: LockRequestFn = vi.fn(() => new Promise((_resolve, reject) => { rejectLock = reject }))
+    stubBrowserGlobals(request)
+    const core = makeCore()
+
+    const startPromise = recovery.start(core as unknown as FsCore, 'proj-d')
+    await vi.advanceTimersByTimeAsync(3000)
+    await startPromise
+
+    expect(core.mode).toBe('readonly')
+    expect(core.becomeWriter).not.toHaveBeenCalled()
+
+    rejectLock(new Error('writer lock request aborted'))
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(core.becomeWriter).not.toHaveBeenCalled()
+    expect(core.mode).toBe('dead')
+    expect(core.event).toHaveBeenCalledWith(expect.objectContaining({ type: 'FATAL' }))
+  })
+
+  it('releases the writer lock, closes handles, and dies when becomeWriter fails after a timely grant', async () => {
+    // The lock callback's held-lock promise settles only through
+    // core.releaseLock(); a becomeWriter failure that skips the release keeps
+    // every other tab queued behind a dead writer forever.
+    vi.useFakeTimers()
+    let held!: Promise<unknown>
+    const request: LockRequestFn = vi.fn((_name, _opts, cb) => { held = cb({}); return held })
+    stubBrowserGlobals(request)
+    const core = makeCore({
+      becomeWriter: vi.fn(() => Promise.reject(new Error('superblock open failed'))),
+      // Simulates handles becomeWriter opened before it threw — failure
+      // cleanup must not leave them dangling.
+      sbHandle: { close: vi.fn() },
+      walHandle: { close: vi.fn() },
+    })
+
+    await expect(recovery.start(core as unknown as FsCore, 'proj-e')).rejects.toThrow()
+
+    let released = false
+    held.then(() => { released = true })
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(released).toBe(true)
+    expect(core.releaseLock).toBeNull()
+    expect(core.mode).toBe('dead')
+    expect(core.sbHandle).toBeNull()
+    expect(core.walHandle).toBeNull()
+  })
+
+  it('a deferred upgrade whose becomeWriter fails releases the lock and reports FATAL instead of staying readonly', async () => {
+    vi.useFakeTimers()
+    let grantCb!: (lock: unknown) => Promise<void>
+    const request: LockRequestFn = vi.fn((_name, _opts, cb) => {
+      grantCb = cb
+      return new Promise(() => {})
+    })
+    stubBrowserGlobals(request)
+    const core = makeCore({
+      becomeWriter: vi.fn(() => Promise.reject(new Error('wal segment open failed'))),
+      sbHandle: { close: vi.fn() },
+      walHandle: { close: vi.fn() },
+    })
+
+    const startPromise = recovery.start(core as unknown as FsCore, 'proj-f')
+    await vi.advanceTimersByTimeAsync(3000)
+    await startPromise
+    expect(core.mode).toBe('readonly')
+
+    const held = grantCb({})
+    let released = false
+    held.then(() => { released = true })
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(core.becomeWriter).toHaveBeenCalledTimes(1)
+    expect(core.mode).toBe('dead')
+    expect(core.event).toHaveBeenCalledWith(expect.objectContaining({ type: 'FATAL' }))
+    expect(released).toBe(true)
+    expect(core.releaseLock).toBeNull()
+  })
+})

package/src/fs-core-recovery.ts

@@ -12,11 +12,75 @@ import {
   type SlotInfo, type WalRecord,
 } from './worker-lib/wal-codec.js'
 import { normalizePath } from './worker-lib/paths.js'
+import type { CoreWireMessage, FsCoreMode } from './worker-lib/protocol.js'
 import { epochFloor, OP, OPID_WINDOW, rpcErr, SEGMENT_ROTATE_BYTES, type MirrorEntry } from './worker-lib/engine-shared.js'
 
 export { epochFloor }
 
 // ── 启动：锁 → 恢复 → 打开写句柄 → 全量同步 query ──
+
+/**
+ * 发起（或重新发起）写者锁排队。resolve = granted（回调持锁直到
+ * core.releaseLock 被调用）；reject = 锁仲裁本身失败（不是"被别人占着"——
+ * 排队会一直等，reject 只发生在 Web Locks 层异常，如上下文销毁中）。
+ * 能跑 fs-core（OPFS SyncAccessHandle）的环境必有 Web Locks，因此 reject
+ * 一律按致命处理，绝不允许无锁当写者（互斥基座坏了 ≠ 无人竞争）。
+ */
+function queueWriterLock(core: FsCore): Promise<Lock | null> {
+  core.writerLockQueued = true
+  return new Promise<Lock | null>((resolve, reject) => {
+    navigator.locks.request('dwc:writer:' + core.projectId, { mode: 'exclusive' }, (lock) => {
+      core.writerLockQueued = false
+      core.writerLockHeld = true
+      resolve(lock)
+      return new Promise<void>((release) => { core.releaseLock = release })
+    }).catch((err) => {
+      core.writerLockQueued = false
+      reject(err instanceof Error ? err : new Error(String(err)))
+    })
+  })
+}
+
+/**
+ * 拿到锁之后的升级（becomeWriter）失败时的收尾：升级失败的 worker 既当不了
+ * 写者也不该再占着锁——关掉可能已打开的句柄、释放写者锁（后面排队的 tab 才
+ * 有机会接手）、置 dead。FATAL 的发出留给调用方（启动路径由 HELLO catch 发，
+ * 延迟路径由 wireDeferredWriterUpgrade 发），避免双发。
+ */
+function failWriterUpgrade(core: FsCore): void {
+  try { core.sbHandle?.close() } catch { /* 尽力关闭；句柄可能没开成 */ }
+  try { core.walHandle?.close() } catch { /* 同上 */ }
+  core.sbHandle = null
+  core.walHandle = null
+  if (core.releaseLock) { core.releaseLock(); core.releaseLock = null }
+  core.writerLockHeld = false
+  core.mode = 'dead'
+}
+
+/**
+ * 只读服务期间的延迟升级路径：granted → 排队任务里 becomeWriter，失败则
+ * 释放锁 + FATAL + dead（不能让后续排队的 tab 堵在一个死写者后面）；
+ * rejected → 该 worker 永远无法升级写者，同样诚实死掉——绝不静默滞留
+ * readonly 让宿主误以为还在正常排队。
+ */
+function wireDeferredWriterUpgrade(core: FsCore, granted: Promise<Lock | null>): void {
+  granted.then(
+    async (lock) => {
+      if (!lock || core.mode === 'dead') return
+      try {
+        await core.enqueue(async () => { await core.becomeWriter() })
+      } catch (err) {
+        failWriterUpgrade(core)
+        core.event({ type: 'FATAL', error: 'writer upgrade failed: ' + String(err) })
+      }
+    },
+    (err) => {
+      core.mode = 'dead'
+      core.event({ type: 'FATAL', error: 'writer lock arbitration failed: ' + String(err) })
+    },
+  )
+}
+
 export async function start(core: FsCore, projectId: string): Promise<void> {
   core.projectId = projectId
   core.root = await (await navigator.storage.getDirectory()).getDirectoryHandle(projectId, { create: true })
@@ -24,29 +88,58 @@ export async function start(core: FsCore, projectId: string): Promise<void> {
   core.bc.onmessage = (e: MessageEvent) => core.onBroadcast(e.data)
 
   // 排队等锁；3s 拿不到先以只读服务，granted 后升级。禁止 steal。
-  const granted = new Promise<Lock | null>((resolve) => {
-    navigator.locks.request('dwc:writer:' + projectId, { mode: 'exclusive' }, (lock) => {
-      resolve(lock)
-      return new Promise<void>((release) => { core.releaseLock = release })
-    }).catch(() => resolve(null))
-  })
+  // 超时前锁仲裁失败 → 这里直接抛出 → HELLO catch 发 FATAL（client 侧 connect
+  // 拒绝）——绝不落入 becomeWriter。
+  const granted = queueWriterLock(core)
   const winner = await Promise.race([granted, new Promise<'timeout'>((r) => setTimeout(() => r('timeout'), 3000))])
   if (winner === 'timeout') {
     await core.recover()
     core.mode = 'readonly'
     core.pushFullToQuery()
     core.welcome()
-    granted.then(async (lock) => {
-      if (!lock || core.mode === 'dead') return
-      await core.enqueue(async () => { await core.becomeWriter() })
-    })
+    wireDeferredWriterUpgrade(core, granted)
     return
   }
-  await core.becomeWriter()
+  try {
+    await core.becomeWriter()
+  } catch (err) {
+    // 拿到锁但升级失败：释放锁再上抛（HELLO catch 发 FATAL）——否则后面排队
+    // 的 tab 永远堵在一个死写者后面。
+    failWriterUpgrade(core)
+    throw err
+  }
   core.welcome()
 }
 
+/**
+ * readonly 端主动请求写权交接（协作交接协议的发起半边；接收半边见
+ * {@link onBroadcast}）：广播 handover-request 让现任写者排干释放，自己的
+ * 排队锁请求随之 granted → 升级。何时调用是宿主的策略（如用户在"另一个
+ * 标签页持有写权"提示上点"在此接管"）——本函数只提供机制，绝不自动重发。
+ * 同一 pending 周期内重复调用被合并（不追加锁请求、不重复广播）；收到
+ * handover-done 广播即周期结束（见 onBroadcast），可再次发起。
+ */
+export function requestHandover(core: FsCore): { requested?: true; mode?: FsCoreMode } {
+  if (core.mode === 'writer') return { mode: 'writer' }
+  if (core.mode === 'draining') throw rpcErr('draining', 'writer is handing over')
+  // 只有 readonly 端有交接可言：dead 自己永远升级不了（让健康写者排干是纯伤害），
+  // starting 尚未仲裁出身份——都如实回报状态、不广播、不动锁队列。
+  if (core.mode !== 'readonly') return { mode: core.mode }
+  if (core.handoverRequested) return { requested: true }
+  // 锁已到手、becomeWriter 在途（granted 与 mode='writer' 之间的异步窗口）：
+  // 升级马上完成，再排队/广播只会留下一个日后可能抢锁的陈旧请求。
+  if (core.writerLockHeld) return { requested: true }
+  core.handoverRequested = true
+  if (!core.writerLockQueued) {
+    // 曾排干交出写权的 worker：原锁请求已了结，重新排队并接回升级路径。
+    wireDeferredWriterUpgrade(core, queueWriterLock(core))
+  }
+  core.bc.postMessage({ type: 'handover-request' })
+  return { requested: true }
+}
+
 export async function becomeWriter(core: FsCore): Promise<void> {
+  core.handoverRequested = false // 升级即周期终结：此前发起的交接请求已达成
   await core.recover() // 旧写者可能刚交出——以盘上状态为准重建
   // epoch 递增写入候选槽（防御性护栏：记录归属可判别）
   core.sbHandle = await (await core.root.getFileHandle('superblock', { create: true })).createSyncAccessHandle()
@@ -175,6 +268,8 @@ export async function recover(core: FsCore): Promise<void> {
   core.appendedGen = core.walGen = core.memGen = core.ackGen = gen
   core.trimCheckpoints() // 回放会重新加回历史 checkpoint 记录 → 恢复后同样裁剪
   for (const r of replayed.slice(-OPID_WINDOW)) {
+    // 只有 {gen}：WAL 不记录内存态 extras（cpId/turnId/expiresAt/restored），
+    // 这些条目服务跨会话去重，同会话超时重试永远命中 live 缓存的完整形状。
     if (r.meta.opId) core.rememberOpId(r.meta.opId, { gen: r.gen })
   }
   if (!segs.length) {
@@ -230,7 +325,7 @@ export function opRead(core: FsCore, { path }: { path: string }): { content: str
   const norm = normalizePath(path)
   const e = norm && core.mirror.get(norm)
   if (!e) throw rpcErr('not-found', String(path))
-  return { content: e.content, rev: e.rev, gen: core.memGen } // P0：镜像在内存，64KB 路由约束成为空转（见 §2.1）
+  return { content: e.content, rev: e.rev, gen: core.memGen } // 镜像常驻内存，读直接命中权威状态，无需按内容大小分流
 }
 export function opLs(core: FsCore): { paths: string[]; gen: number } { return { paths: [...core.mirror.keys()].sort(), gen: core.memGen } }
 export function opStatus(core: FsCore): {
@@ -258,13 +353,19 @@ export function pushFullToQuery(core: FsCore): void {
   for (const [p, ent] of core.mirror) files[p] = { content: ent.content, rev: ent.rev }
   core.queryPort.postMessage({ gen: core.memGen, full: true, files })
 }
-export function event(core: FsCore, e: Record<string, unknown>): void { if (core.clientPort) core.clientPort.postMessage(e) }
+export function event(core: FsCore, e: CoreWireMessage): void { if (core.clientPort) core.clientPort.postMessage(e) }
 export function welcome(core: FsCore): void {
   core.event({ type: 'WELCOME', epoch: core.epoch, memGen: core.memGen, readonly: core.mode !== 'writer', mode: core.mode })
 }
 
 // ── 协作交接（禁 steal）──
 export async function onBroadcast(core: FsCore, msg: { type?: string }): Promise<void> {
+  if (msg.type === 'handover-done' && core.mode !== 'writer') {
+    // 一个交接周期已完成（某个写者排干释放）。无论本 worker 是否是赢家，
+    // 合并标志都复位：没抢到锁的 readonly 端可以再次向新写者发起请求。
+    core.handoverRequested = false
+    return
+  }
   if (msg.type === 'handover-request' && core.mode === 'writer') {
     core.mode = 'draining'
     await core.enqueue(async () => {
@@ -273,6 +374,7 @@ export async function onBroadcast(core: FsCore, msg: { type?: string }): Promise
       core.sbHandle!.close(); core.sbHandle = null
       core.mode = 'readonly'
       if (core.releaseLock) { core.releaseLock(); core.releaseLock = null }
+      core.writerLockHeld = false
       core.bc.postMessage({ type: 'handover-done', gen: core.memGen })
       core.event({ evt: 'writer-lost', gen: core.memGen })
     })

package/src/fs-core-write-ops.ts

@@ -11,7 +11,7 @@ import { DERIVED_PREFIXES, normalizePath } from './worker-lib/paths.js'
 import {
   AUDIT_CAP, CHECKPOINT_KEEP, GROUP_WINDOW_MS, OP, OP_NAME, OPID_WINDOW, rpcErr, SEGMENT_ROTATE_BYTES,
   TURN_DEFAULT_TTL_MS, TURN_MAX_OPS, WRITE_OPCODES,
-  type AuditEntry, type MirrorEntry, type Respond,
+  type AuditEntry, type MirrorEntry, type OpIdResult, type Respond,
 } from './worker-lib/engine-shared.js'
 import type {
   CheckpointArgs, EditArgs, MvArgs, RestoreArgs, RmArgs, TurnBeginArgs, TurnEndArgs, WriteArgs,
@@ -46,13 +46,13 @@ export function audit(core: FsCore, entry: AuditEntry): void {
 
 /** turn 执法（agent 专属）：在 append 前的同一同步块内调用，无让出点，
  * 撤销（turnEnd/过期）与写入之间不存在竞态窗口。human 写不受限。
- * W4 纵深加固（第二道锁，docs/k3-terminal-split-plan.md §6 替代方案 A / §8.3）：门已
+ * 纵深加固（第二道锁）：门已
  * arm（core.agentToken !== null）时，即使 turnId 猜对/偷到、turn 仍活跃，也必须携带匹配
  * 的 agentToken，否则拒绝 —— 威胁模型是"B realm 内代码拿到裸 window.__FS_CLIENT 后伪造
  * {actor:'agent', turnId} 直写"，令牌只有内核持有（kernel.js 闭包，从不落 window）。
  * 校验顺序刻意放在 turn 有效性判定之后：turnId 完全不匹配/已过期的旧行为（'turn-closed'）
  * 保持不变（fs 域既有 e2e 的等价断言不回归），令牌门只在"turn 确实活跃且 turnId 匹配"这一步
- * 追加第二道拒绝，精确对应 blocker #6 的伪造场景。 */
+ * 追加第二道拒绝，精确对应上述伪造场景。 */
 export function checkTurn(core: FsCore, actor: string | undefined, turnId: string | undefined, agentToken: string | undefined): void {
   if (actor !== 'agent') return
   const t = core.turn
@@ -73,7 +73,7 @@ export function armAgentToken(core: FsCore, token: unknown): { armed: boolean; i
   throw rpcErr('agent-token-gate-armed', 'agent token gate already armed with a different token')
 }
 
-/** §4.7 restore 冲突执法：非 force 时在 appendSync 同步块内调用，无让出点。
+/** restore 冲突执法：非 force 时在 appendSync 同步块内调用，无让出点。
  * auditLog 是容量 AUDIT_CAP 的环——若其最老条目已晚于 baseGen+1，说明 (baseGen, 最老审计]
  * 区间的历史已被丢弃（compaction 或环覆盖），无法证明期间没有人类写，一律保守拒绝。 */
 export function checkRestoreConflict(core: FsCore, baseGen: number): void {
@@ -107,7 +107,7 @@ export function checkWrite(core: FsCore, path: unknown, ifMatch: unknown, _actor
 }
 
 /** 段超阈值 → 影子 compaction（物化 manifest + 新段 + superblock 翻转），
- * 而不是裸换段：WAL 长度被真正回收，重放成本有上界（P1 compaction 上线）。 */
+ * 而不是裸换段：WAL 长度被真正回收，重放成本有上界。 */
 export async function rotateIfNeeded(core: FsCore): Promise<void> {
   if (core.walOffset <= SEGMENT_ROTATE_BYTES) return
   await core.compactNow()
@@ -143,7 +143,9 @@ export function flushWindow(core: FsCore): void {
   let actor = 'human'
   for (const w of core.windowOps) {
     core.ackGen = Math.max(core.ackGen, w.gen)
-    if (w.opId) core.rememberOpId(w.opId, { gen: w.gen })
+    // 缓存与 respond 同形（含 extra）——超时重试的重放必须携带首个响应的全部
+    // 字段（cpId/turnId/expiresAt），见 engine-shared.ts 的 OpIdResult。
+    if (w.opId) core.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'
@@ -153,7 +155,7 @@ export function flushWindow(core: FsCore): void {
   core.bc.postMessage({ type: 'fs-change', gen: core.memGen })
 }
 
-export function rememberOpId(core: FsCore, opId: string, v: { gen: number }): void {
+export function rememberOpId(core: FsCore, opId: string, v: OpIdResult): void {
   core.opIds.set(opId, v)
   if (core.opIds.size > OPID_WINDOW) core.opIds.delete(core.opIds.keys().next().value!)
 }
@@ -233,7 +235,7 @@ export async function makeCheckpoint(core: FsCore, { opId, actor, turnId }: { op
   return { cpId, gen }
 }
 
-/** P5 LRU：Map 按插入序，裁掉最老的（活跃 turn 的锚点必然在最近 N 个内）。 */
+/** checkpoint LRU：Map 按插入序，裁掉最老的（活跃 turn 的锚点必然在最近 N 个内）。 */
 export function trimCheckpoints(core: FsCore): void {
   while (core.checkpoints.size > CHECKPOINT_KEEP) {
     core.checkpoints.delete(core.checkpoints.keys().next().value!)
@@ -249,7 +251,7 @@ export async function opCheckpoint(core: FsCore, { actor = 'human', turnId, agen
   core.scheduleFlush(true)
 }
 
-// ── P4 turn 能力：铸造（checkpoint 锚 + 激活）→ 执法（checkTurn）→ 撤销 ──
+// ── turn 能力：铸造（checkpoint 锚 + 激活）→ 执法（checkTurn）→ 撤销 ──
 export async function opTurnBegin(core: FsCore, { turnId, ttlMs, opId }: TurnBeginArgs, respond: Respond): Promise<void> {
   if (!turnId || typeof turnId !== 'string') throw rpcErr('bad-args', 'turnId required')
   if (core.turn && Date.now() <= core.turn.expiresAt) {
@@ -280,7 +282,7 @@ export function opDiff(core: FsCore, { turnId }: { turnId?: string }): { turnId:
   return { turnId, changes, cpId, auditWindow: { cap: AUDIT_CAP, sinceGen: core.auditLog.length ? core.auditLog[0]!.gen : core.memGen } }
 }
 
-/** §4.7 restore 冲突策略：payload 支持 {cpId, baseGen?, force?}。baseGen 缺省时
+/** restore 冲突策略：payload 支持 {cpId, baseGen?, force?}。baseGen 缺省时
  * 从 checkpoint 自身记录的 gen 推导（checkpoint 创建时已存 {h, gen}）。非 force 时在
  * appendSync 同步块内做冲突检查（见 checkRestoreConflict）；force:true 全部跳过。
  * turn 执法（checkTurn）不受 force 影响——agent 场景仍必须在活跃 turn 内。 */
@@ -305,7 +307,8 @@ export async function opRestore(core: FsCore, { cpId, baseGen, force = false, ac
   core.mirror = next
   core.memGen = core.walGen
   core.ackGen = gen
-  if (opId) core.rememberOpId(opId, { gen })
+  // 缓存与 respond 同形（restore 无 rev、带 restored）——见 OpIdResult。
+  if (opId) core.rememberOpId(opId, { gen, restored: Object.keys(files).length })
   core.pushFullToQuery()
   respond({ ok: true, result: { gen, restored: Object.keys(files).length } })
   core.event({ evt: 'fs-change', gen, actor, count: Object.keys(files).length, restore: cpId })

package/src/fs-core.worker.ts

@@ -1,5 +1,5 @@
 /**
- * fs-core worker — ProjectFS 单写者权威（P0，同 origin 形态）。
+ * fs-core worker — ProjectFS 单写者权威（同 origin 形态）。
  *
  * 持久层（OPFS，无物化文件树）：
  *   <projectId>/blobs/<h2>/<sha256>   内容寻址、不可变、写后 flush
@@ -19,10 +19,11 @@
 import * as recovery from './fs-core-recovery.js'
 import * as writeOps from './fs-core-write-ops.js'
 import type { WalRecord } from './worker-lib/wal-codec.js'
-import { rpcErr, type MirrorEntry, type Respond, type TurnState, type WindowOp, type WorkerError } from './worker-lib/engine-shared.js'
+import { rpcErr, type MirrorEntry, type OpIdResult, type Respond, type TurnState, type WindowOp, type WorkerError } from './worker-lib/engine-shared.js'
 import type {
   CheckpointArgs, DiffArgs, EditArgs, MvArgs, ReadArgs, RestoreArgs, RmArgs, TurnBeginArgs, TurnEndArgs, WriteArgs,
 } from './worker-lib/rpc-types.js'
+import type { CoreWireMessage, FsCoreMode } from './worker-lib/protocol.js'
 
 /** FileSystemFileHandle.move() postdates this TS lib version's ambient types
  * (feature-detected at the call site via `if (fh.move) …`, matching the
@@ -35,10 +36,10 @@ declare global {
 
 // ───────────────────────── core 主体 ─────────────────────────
 export class FsCore {
-  mode: 'starting' | 'writer' | 'readonly' | 'draining' | 'dead' = 'starting'
+  mode: FsCoreMode = 'starting'
   mirror = new Map<string, MirrorEntry>()
   checkpoints = new Map<string, { h: string; gen: number }>()
-  opIds = new Map<string, { gen: number }>()
+  opIds = new Map<string, OpIdResult>()
   appendedGen = 0
   walGen = 0
   memGen = 0
@@ -59,7 +60,7 @@ export class FsCore {
   currentSlot = 0
   turn: TurnState | null = null // {turnId, cpId, expiresAt, ops} —— 内存态：worker 重启即失效（安全默认）
   auditLog: Array<{ gen: number; opcode: number; actor?: string; turnId?: string; path?: string; from?: string; to?: string; cpId?: string }> = [] // 环形
-  // 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 同一安全默认。
@@ -71,6 +72,15 @@ export class FsCore {
   lastSegStart!: number
   lastSegValidEnd!: number
   manifestCrc!: number
+  // 写者锁排队中（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: string): Promise<void> { return recovery.start(this, projectId) }
@@ -86,9 +96,10 @@ export class FsCore {
   opStatus() { return recovery.opStatus(this) }
   pushDiff(diff: Record<string, MirrorEntry | null>, gen: number): void { recovery.pushDiff(this, diff, gen) }
   pushFullToQuery(): void { recovery.pushFullToQuery(this) }
-  event(e: Record<string, unknown>): void { recovery.event(this, e) }
+  event(e: CoreWireMessage): void { recovery.event(this, e) }
   welcome(): void { recovery.welcome(this) }
   onBroadcast(msg: { type?: string }): Promise<void> { return recovery.onBroadcast(this, msg) }
+  requestHandover(): { requested?: true; mode?: FsCoreMode } { return recovery.requestHandover(this) }
 
   // ── 写路径/compaction（fs-core-write-ops.ts） ──
   enqueue<T>(fn: () => T | Promise<T>): Promise<T> { return writeOps.enqueue(this, fn) }
@@ -102,7 +113,7 @@ export class FsCore {
   rotateIfNeeded(): Promise<void> { return writeOps.rotateIfNeeded(this) }
   newSegment(startGen: number): Promise<void> { return writeOps.newSegment(this, startGen) }
   flushWindow(): void { writeOps.flushWindow(this) }
-  rememberOpId(opId: string, v: { gen: number }): void { writeOps.rememberOpId(this, opId, v) }
+  rememberOpId(opId: string, v: OpIdResult): void { writeOps.rememberOpId(this, opId, v) }
   scheduleFlush(immediate?: boolean): void { writeOps.scheduleFlush(this, immediate) }
   opWrite(args: WriteArgs, respond: Respond): Promise<void> { return writeOps.opWrite(this, args, respond) }
   opEdit(args: EditArgs, respond: Respond): Promise<void> { return writeOps.opEdit(this, args, respond) }
@@ -121,10 +132,11 @@ export class FsCore {
   handleRpc(msg: { id: number; opId?: string; args?: Record<string, unknown>; op: string }): void {
     const respond: Respond = (r) => this.clientPort!.postMessage({ id: msg.id, ...r })
     const fail = (e: WorkerError) => respond({ ok: false, code: e.code || 'internal', error: e.message || String(e), ...(e.extra || {}) })
-    // opId 幂等：已知 opId 直接返回既有结果
+    // opId 幂等：已知 opId 原样重放缓存的完整结果（见 OpIdResult）。rev 只在
+    // 缓存没有时兜底为 gen（WAL 回放重建的跨会话条目只有 {gen}）。
     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: Record<string, unknown> = { ...msg.args, opId: msg.opId }
@@ -148,9 +160,12 @@ export class FsCore {
       read: () => respond({ ok: true, result: this.opRead(a as unknown as ReadArgs) }),
       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) }),
+      // 协作交接发起（readonly 端）：广播 + 必要时重新排队锁，纯内存/信道操作，
+      // 不碰 WAL——同步分支（升级本身走 becomeWriter 的 enqueue 路径）。
+      requestHandover: () => respond({ ok: true, result: this.requestHandover() }),
     }
     const fn = table[msg.op]
     if (!fn) { fail(rpcErr('bad-op', String(msg.op))); return }
@@ -167,7 +182,7 @@ const core = new FsCore()
 self.onmessage = async (e: MessageEvent) => {
   const msg = e.data
   if (msg.type === 'HELLO') {
-    core.clientPort = self // 单客户端 P0：直接用 worker 主端口
+    core.clientPort = self // 单客户端形态：直接用 worker 主端口
     core.queryPort = msg.queryPort || null
     try {
       await core.start(msg.projectId)

package/src/worker-files.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Guards the worker-artifact distribution contract helper: the file-name
+ * list matches what build-workers.js actually emits, and path resolution
+ * follows the "literal siblings of client.js" rule on both separators.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { FS_CORE_WORKER_FILES, resolveWorkerFiles } from './worker-files.js'
+
+describe('FS_CORE_WORKER_FILES', () => {
+  it('matches the outfiles build-workers.js emits', () => {
+    const buildScript = readFileSync(join(__dirname, '..', 'build-workers.js'), 'utf8')
+    for (const name of FS_CORE_WORKER_FILES) {
+      expect(buildScript).toContain(`dist/${name}`)
+    }
+  })
+})
+
+describe('resolveWorkerFiles', () => {
+  it('resolves worker paths as siblings of client.js (POSIX)', () => {
+    const r = resolveWorkerFiles('/repo/node_modules/@dimina-kit/fs-core/dist/client.js')
+    expect(r.dir).toBe('/repo/node_modules/@dimina-kit/fs-core/dist')
+    expect(r.files).toEqual([
+      '/repo/node_modules/@dimina-kit/fs-core/dist/fs-core.worker.js',
+      '/repo/node_modules/@dimina-kit/fs-core/dist/fs-query.worker.js',
+    ])
+  })
+
+  it('preserves Windows separators', () => {
+    const r = resolveWorkerFiles('C:\\proj\\node_modules\\@dimina-kit\\fs-core\\dist\\client.js')
+    expect(r.dir).toBe('C:\\proj\\node_modules\\@dimina-kit\\fs-core\\dist')
+    expect(r.files[0]).toBe('C:\\proj\\node_modules\\@dimina-kit\\fs-core\\dist\\fs-core.worker.js')
+  })
+
+  it('rejects a separator-less input', () => {
+    expect(() => resolveWorkerFiles('client.js')).toThrow(/not a path/)
+  })
+})