dsh-lcx-codex 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+本项目遵循语义化版本。未通过真实验收的能力只记录在Unreleased，不作为已发布功能。
+
+## Unreleased
+
+### Fixed
+
+- Hosted Search 与 Alpha Search 现在和 Native V2 Compact 一样，复用 DSH 已添加的 `openai-responses` provider 路由、凭据引用、headers 与 retry policy；不再要求用户为插件重复配置 `LCX_API_KEY`。
+- README 将插件运行时凭据与运行在 DSH 外的 Alpha 探针/E2E 测试凭据明确分开。
+- README 改为简短的用户手册，以 npm 安装为主；Alpha 提示前置，并按 NewAPI 当前源码区分 4 种中转渠道类型与 Sub2API 直连，共 5 种部署路径。
+
+## 0.3.0 - 2026-08-20
+
+### Changed
+
+- 收紧 npm/DSH 安装包，只保留运行时代码、Alpha 运维探针、许可证和用户文档；开发测试与 schema 校验脚本继续保留在源码仓库。
+- README 和包元数据明确 `LCX` 只是插件名称；支持 Sub2API 反代或 NewAPI 中转的 GPT 模型，不隶属于 OpenAI；Alpha 能力继续按部署 fingerprint 与可信 provenance 分类，不作全局 native 承诺。
+- 明确 Alpha 经过 NewAPI 时渠道类型必须为 `Sub2API`，不能使用普通 `OpenAI` 渠道。
+- README 改为面向用户的中文文档，提供经 DSH/pnpm 帮助核对的 GitHub URL、Release 包、更新和卸载命令；本地 `link:` 安装明确归入源码开发流程。
+
+### Added
+
+- Hosted Search 完整结构化参数与 citation/source/image 输出。
+- 独立 `websearch_alpha`，支持 search、image、open/find/click、PDF screenshot、finance、weather、sports 和 time；capability/ref sidecar 按 route 与 session 隔离。
+- Native V2 checkpoint v3、同路由 replay、Sol/Luna portable migration、fork/tree/restart generation lease 与 durable-image migration。
+
+### Fixed
+
+- Native replay and portable migration no longer depend on the nonexistent `GenerateOptions.branchId`; fork safety uses public session ancestry and derived marker history while preserving existing v3 fingerprint compatibility.
+- README 的本地 link 安装示例不再包含开发机绝对路径。
+- Alpha 从 rc.8 公共 `session.requestContext()` 读取 active route，避免模型切换后的 capability 误判。
+- Alpha 对 HTTP 200 内的函数调用语义错误 fail closed，并修正 sports action 的 wire 字段。
+- Responses SSE 去重、usage、工具配对、并发 sidecar、Windows ACL、图片 offload/hydrate 和 remote/local summary 边界。
+
+## 0.2.0
+
+- Hosted Responses query-only Web Search。
+- Native Remote Compaction V2，拒绝legacy transport。
+- checkpoint v3、同route replay和第一批portable model migration。
+- 图片同route attachment hydrate，portable image migration保持fail closed。
+- 协议、大小、超时、重试、redirect和日志脱敏基础测试。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-lcx-codex contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# dsh-lcx-codex
+
+社区维护的 DSH 插件，为兼容 OpenAI Responses/Codex 协议的 GPT 模型增加 Hosted Web Search、Alpha Search 和 Native V2 远程压缩。
+
+> [!IMPORTANT]
+> Alpha Search 有 5 种可用部署路径：Sub2API 直连，以及经 NewAPI 的 4 种渠道类型：`Sub2API`、`New API`、`ChatGPT Subscription (Codex)`、`Advanced Custom`。普通 `OpenAI` 渠道不支持 `/v1/alpha/search`，会在 NewAPI 内被拒绝。
+
+这份名单来自 NewAPI 当前主分支的 [`AlphaSearchHelper`](https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/relay/alpha_search_handler.go)。不同版本的 NewAPI 可能有差异，最终以实际 capability probe 为准。
+
+`LCX` 只是插件名称，不是服务商或协议。本插件支持：
+
+- 直接使用 Sub2API 反代的 GPT 模型。
+- 使用 NewAPI 中转的 GPT 模型（也就是第三方中转）；NewAPI 的上游渠道连接 Sub2API。
+
+```text
+DSH -> Sub2API -> OpenAI Responses/Codex-compatible upstream
+DSH -> NewAPI -> Sub2API/compatible channel -> OpenAI Responses/Codex-compatible upstream
+```
+
+本项目不隶属于 OpenAI，也不是 OpenAI 官方发布的插件或 OAuth 客户端。
+
+## 功能
+
+| 功能 | 工具或协议 | 说明 |
+|---|---|---|
+| Hosted Web Search | `websearch_gpt` | `/responses` + `web_search`，返回正文、来源和 citations |
+| Alpha Search | `websearch_alpha` | `/alpha/search`，支持 search、open/find/click、PDF screenshot、image、finance、weather、sports 和 time |
+| Native V2 Compact | `/responses` + `compaction_trigger` | 保存 checkpoint v3，支持同路由回放、模型迁移、fork/tree、重启和图片 attachment |
+
+Alpha 只有在 capability 记录与当前 endpoint、provider、model 和 schema 匹配时才会启用。Hosted 与 Alpha 是两条独立协议，不会互相静默降级。
+
+## 安装
+
+发布到 npm 后，推荐直接安装包名：
+
+```powershell
+dsh plugin --profile web add dsh-lcx-codex
+```
+
+也可以下载 GitHub Release 中的 `.tgz` 安装指定版本：
+
+```powershell
+dsh plugin --profile web add .\dsh-lcx-codex-0.3.0.tgz
+```
+
+安装后启动 DSH：
+
+```powershell
+dsh web
+```
+
+打开 `设置 -> 插件 -> LCX / Codex 能力`，按需启用 Hosted、Alpha 或 Native Compact。插件默认关闭。
+
+## 要求
+
+- Node.js 20 或更高版本
+- DSH `0.1.0-rc.8` 或兼容版本
+- 已在 DSH 中添加并能正常对话的 GPT 模型
+- 模型使用 `llm-pi-ai` 的 `openai-responses` provider
+
+插件复用当前 DSH 模型的 provider、model、Responses 地址、凭据引用、headers 和 retry policy，并通过 DSH credentials service 取凭据。正常运行不需要再给插件配置一份 `LCX_API_KEY`。
+
+界面中的 endpoint 和 model 字段用于没有活动会话路由时的默认选择，以及旧版直连配置兼容；同名 DSH provider 已存在时，以 DSH provider 配置为准。
+
+## Alpha probe
+
+Alpha 能力按部署记录为 `native`、`command-capable`、`emulated-search-only`、`unsupported` 或 `unknown`。HTTP 200 本身不能证明 action 是原生能力。
+
+探针是 DSH runtime 外的独立 Node.js 脚本，不能调用 DSH credentials service，因此探针需要本机 key 文件；插件运行时不需要重复配置。
+
+```powershell
+$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME } else { Join-Path $env:USERPROFILE '.dsh' }
+$env:LCX_API_KEY_FILE = 'C:\path\to\local-key.txt'
+$env:LCX_MODEL = '实际模型名'
+node (Join-Path $dshHome 'profiles\web\node_modules\dsh-lcx-codex\scripts\probe-alpha.mjs')
+```
+
+要同时探测 image、finance、weather、sports 和 time：
+
+```powershell
+$env:LCX_ALPHA_PROBE_STRUCTURED = '1'
+node (Join-Path $dshHome 'profiles\web\node_modules\dsh-lcx-codex\scripts\probe-alpha.mjs')
+```
+
+探针不会输出 key 或完整响应正文。完成后重启 DSH，或关闭再开启 Alpha 设置。
+
+## 数据与限制
+
+- Checkpoint：`$DSH_HOME/storages/lcx-codex/checkpoints-v3.json`
+- Alpha capability：`$DSH_HOME/storages/lcx-codex/web-alpha-capabilities.json`
+- Alpha refs：`$DSH_HOME/storages/lcx-codex/web-alpha-refs.json`
+- 只支持 Native remote-compaction V2，不调用 `/responses/compact`
+- Checkpoint 不保存图片原始字节或 data URL
+- Opaque checkpoint 不跨不兼容 provider、model、base URL、session 或 lineage 回放
+- 不包含图片生成功能
+
+不要把 API key、OAuth token、Authorization header、账户 ID、session cookie 或运行时 sidecar 提交到 GitHub。
+
+## 更新与卸载
+
+```powershell
+dsh plugin --profile web update dsh-lcx-codex
+dsh plugin --profile web remove dsh-lcx-codex
+```
+
+卸载不会删除 `$DSH_HOME/storages/lcx-codex/`。如果会话仍引用 checkpoint marker，不要单独删除对应 sidecar。
+
+## 开发
+
+```powershell
+npm install
+npm test
+npm run test:schema
+```
+
+真实 E2E 和 Alpha probe 只应读取本机忽略文件或环境变量中的测试凭据。
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# Adds optional search and compaction for Sub2API-proxied or NewAPI-relayed GPT
+# models without touching existing profiles or presets.
+- insert:
+    - id: lcx-codex
+      name: dsh-lcx-codex
+      config:
+        provider: lcx
+        baseURL: https://api.lcxbot.com/v1
+        apiKeyEnv: LCX_API_KEY
+        model: gpt-5.6-sol
+        compactTransport: native-v2
+        checkpointPath: !!js dshHomePath('storages/lcx-codex/checkpoints-v3.json')
+        alphaCapabilityPath: !!js dshHomePath('storages/lcx-codex/web-alpha-capabilities.json')
+        alphaRefPath: !!js dshHomePath('storages/lcx-codex/web-alpha-refs.json')
+        webSearchProvider: lcx-responses
+        webMaxResults: 8
+        timeoutMs: 300000
+        maxAttempts: 3

package/lib/checkpoint-store-v3.js

@@ -0,0 +1,459 @@
+import {
+  chmodSync,
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, join, basename } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { PORTABLE_HISTORY_BYTE_BUDGET } from './compact.js'
+import { ensurePrivateFileAcl } from './private-file.js'
+
+export const CHECKPOINT_V3_VERSION = 3
+export const CHECKPOINT_V3_MAX_RECORDS = 256
+export const CHECKPOINT_V3_MAX_BYTES = 16 * 1024 * 1024
+
+const LOCK_STALE_MS = 30 * 1000
+const LOCK_WAIT_MS = 5 * 1000
+const TEMP_STALE_MS = 60 * 60 * 1000
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu
+
+export class CheckpointV3Error extends Error {
+  constructor(message, code, cause) {
+    super(message, cause === undefined ? undefined : { cause })
+    this.name = 'CheckpointV3Error'
+    this.code = code
+  }
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function bytes(value, pretty = false) {
+  return Buffer.byteLength(JSON.stringify(value, null, pretty ? 2 : undefined), 'utf8')
+}
+
+function validImageAttachmentRef(ref) {
+  return isObject(ref) && /^sha256:[a-f0-9]{64}$/iu.test(String(ref.attachmentId ?? '')) &&
+    ['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(ref.mediaType) &&
+    Number.isSafeInteger(ref.bytes) && ref.bytes > 0 && Number.isSafeInteger(ref.width) && ref.width > 0 &&
+    Number.isSafeInteger(ref.height) && ref.height > 0 && (ref.name === undefined || typeof ref.name === 'string')
+}
+
+function validContentPart(part) {
+  if (!isObject(part) || typeof part.type !== 'string' || part.type.length === 0 || part.type === 'input_image') return false
+  if (part.type === 'dsh_image_attachment') return validImageAttachmentRef(part.attachment)
+  if ((part.type === 'input_text' || part.type === 'output_text' || part.type === 'summary_text' || part.type === 'refusal') && typeof part.text !== 'string') return false
+  return true
+}
+
+function validMessageItem(item) {
+  return typeof item.role === 'string' && item.role.length > 0 && Array.isArray(item.content) && item.content.every(validContentPart)
+}
+
+function validPortableMessageItem(item) {
+  return typeof item.role === 'string' && item.role.length > 0 && Array.isArray(item.content) &&
+    item.content.every(validContentPart)
+}
+
+function validNativeOutputItem(item) {
+  if (!isObject(item) || typeof item.type !== 'string' || item.type.length === 0) return false
+  if (item.id !== undefined && (typeof item.id !== 'string' || item.id.length === 0)) return false
+  if (item.type === 'message') return validMessageItem(item)
+  if (item.type === 'compaction') return validNativeCompaction(item)
+  if (item.type === 'function_call') {
+    return typeof item.call_id === 'string' && item.call_id.length > 0 &&
+      typeof item.name === 'string' && item.name.length > 0 &&
+      typeof item.arguments === 'string'
+  }
+  if (item.type === 'function_call_output') {
+    return typeof item.call_id === 'string' && item.call_id.length > 0 &&
+      (typeof item.output === 'string' || (Array.isArray(item.output) && item.output.every(validContentPart)))
+  }
+  if (item.type === 'reasoning') {
+    return (item.encrypted_content === undefined || typeof item.encrypted_content === 'string') &&
+      (item.content === undefined || (Array.isArray(item.content) && item.content.every(validContentPart))) &&
+      (item.summary === undefined || (Array.isArray(item.summary) && item.summary.every(validContentPart)))
+  }
+  return true
+}
+
+function validPortableItem(item) {
+  if (!isObject(item) || typeof item.type !== 'string' || item.type.length === 0) return false
+  if (item.type === 'compaction' || item.type === 'context_compaction' || item.type === 'compaction_trigger') return false
+  if (item.type.startsWith('response.')) return false
+  if (Object.prototype.hasOwnProperty.call(item, 'encrypted_content')) return false
+  if (item.id !== undefined && (typeof item.id !== 'string' || item.id.length === 0)) return false
+  if (item.type === 'message') return validPortableMessageItem(item)
+  if (item.type === 'function_call') {
+    return typeof item.call_id === 'string' && item.call_id.length > 0 &&
+      typeof item.name === 'string' && item.name.length > 0 &&
+      typeof item.arguments === 'string'
+  }
+  if (item.type === 'function_call_output') {
+    return typeof item.call_id === 'string' && item.call_id.length > 0 &&
+      (typeof item.output === 'string' || (Array.isArray(item.output) && item.output.every(validContentPart)))
+  }
+  return true
+}
+
+function validNativeCompaction(item) {
+  return isObject(item) && item.type === 'compaction' &&
+    typeof item.encrypted_content === 'string' && item.encrypted_content.length > 0
+}
+
+function validateItemCollection(items, validator, strictPairing) {
+  const ids = new Set()
+  const callIndexes = new Map()
+  const outputIndexes = new Map()
+  for (let index = 0; index < items.length; index += 1) {
+    const item = items[index]
+    if (!validator(item)) return false
+    if (item.id !== undefined) {
+      if (ids.has(item.id)) return false
+      ids.add(item.id)
+    }
+    if (item.type === 'function_call') {
+      if (callIndexes.has(item.call_id)) return false
+      callIndexes.set(item.call_id, index)
+    }
+    if (item.type === 'function_call_output') {
+      if (outputIndexes.has(item.call_id)) return false
+      outputIndexes.set(item.call_id, index)
+    }
+  }
+  if (strictPairing) {
+    if (callIndexes.size !== outputIndexes.size) return false
+    for (const [callId, callIndex] of callIndexes) {
+      if (!outputIndexes.has(callId) || callIndex >= outputIndexes.get(callId)) return false
+    }
+  }
+  return true
+}
+
+function validRecord(record, { strictPortablePairing = false } = {}) {
+  if (!isObject(record) || record.version !== CHECKPOINT_V3_VERSION ||
+    typeof record.checkpointId !== 'string' || record.checkpointId.length < 8 ||
+    typeof record.lineageId !== 'string' || record.lineageId.length === 0 ||
+    typeof record.sourceSessionId !== 'string' || record.sourceSessionId.length === 0 ||
+    record.sourceSessionId !== record.lineageId ||
+    (record.sourceBranchId !== undefined && (typeof record.sourceBranchId !== 'string' || record.sourceBranchId.length === 0)) ||
+    (record.parentCheckpointId !== undefined && (typeof record.parentCheckpointId !== 'string' || !UUID_PATTERN.test(record.parentCheckpointId))) ||
+    (record.transport !== undefined && typeof record.transport !== 'string') ||
+    typeof record.provider !== 'string' || record.provider.length === 0 ||
+    typeof record.model !== 'string' || record.model.length === 0 ||
+    typeof record.modelKey !== 'string' || record.modelKey !== `${record.provider}:${record.model}` ||
+    typeof record.baseURLFingerprint !== 'string' || record.baseURLFingerprint.length === 0 ||
+    typeof record.routeFingerprint !== 'string' || record.routeFingerprint.length === 0 ||
+    !Array.isArray(record.nativeOutput) || record.nativeOutput.length === 0 ||
+    !validNativeCompaction(record.nativeCompaction) ||
+    !Array.isArray(record.portableHistory) ||
+    typeof record.portableSummary !== 'string' ||
+    (record.portableImageCount !== undefined && (!Number.isSafeInteger(record.portableImageCount) || record.portableImageCount < 0)) ||
+    !Number.isFinite(record.createdAt)) return false
+
+  const nativeCompactions = record.nativeOutput.filter((item) => isObject(item) && item.type === 'compaction')
+  if (nativeCompactions.length !== 1 ||
+    nativeCompactions[0].encrypted_content !== record.nativeCompaction.encrypted_content) return false
+  if (!validateItemCollection(record.nativeOutput, validNativeOutputItem, true)) return false
+  if (!validateItemCollection(record.portableHistory, validPortableItem, strictPortablePairing)) return false
+  return bytes(record.nativeOutput) <= PORTABLE_HISTORY_BYTE_BUDGET &&
+    bytes(record.portableHistory) <= PORTABLE_HISTORY_BYTE_BUDGET &&
+    bytes(record.portableSummary) <= 16 * 1024
+}
+
+function emptyData() {
+  return { version: CHECKPOINT_V3_VERSION, checkpoints: {} }
+}
+
+function normalizedLimits(options = {}) {
+  const maxRecords = options.maxRecords ?? options.maxRecordCount ?? CHECKPOINT_V3_MAX_RECORDS
+  const maxBytes = options.maxBytes ?? options.maxTotalBytes ?? CHECKPOINT_V3_MAX_BYTES
+  if (!Number.isSafeInteger(maxRecords) || maxRecords < 1 || !Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+    throw new CheckpointV3Error('Invalid checkpoint v3 store limits', 'LCX_CHECKPOINT_V3_LIMIT_INVALID')
+  }
+  return { maxRecords, maxBytes }
+}
+
+function validateData(parsed, file, limits, { strict = false, strictIds = new Set() } = {}) {
+  if (parsed?.version !== CHECKPOINT_V3_VERSION) {
+    throw new CheckpointV3Error(`Unsupported checkpoint v3 store in ${file}`, 'LCX_CHECKPOINT_V3_VERSION_UNSUPPORTED')
+  }
+  if (!isObject(parsed.checkpoints)) {
+    throw new CheckpointV3Error(`Invalid checkpoint v3 store in ${file}`, 'LCX_CHECKPOINT_V3_CORRUPT')
+  }
+  const entries = Object.entries(parsed.checkpoints)
+  if (entries.length > limits.maxRecords) {
+    throw new CheckpointV3Error(`Checkpoint v3 store exceeds record limit (${entries.length}/${limits.maxRecords})`, 'LCX_CHECKPOINT_V3_LIMIT_EXCEEDED')
+  }
+  for (const [id, record] of entries) {
+    if (id !== record?.checkpointId) {
+      throw new CheckpointV3Error(`Checkpoint v3 map key does not match record checkpointId (${id})`, 'LCX_CHECKPOINT_V3_KEY_MISMATCH')
+    }
+    if (!validRecord(record, { strictPortablePairing: strict || strictIds.has(id) })) {
+      throw new CheckpointV3Error(`Invalid checkpoint v3 record ${id} in ${file}`, 'LCX_CHECKPOINT_V3_CORRUPT')
+    }
+  }
+  for (const [id, record] of entries) {
+    if (record.parentCheckpointId !== undefined) {
+      const parent = parsed.checkpoints[record.parentCheckpointId]
+      if (!parent) throw new CheckpointV3Error(`Checkpoint v3 parent ${record.parentCheckpointId} for ${id} is missing`, 'LCX_CHECKPOINT_V3_PARENT_MISSING')
+      if (parent.lineageId !== record.lineageId) throw new CheckpointV3Error(`Checkpoint v3 parent ${record.parentCheckpointId} for ${id} has a different lineage`, 'LCX_CHECKPOINT_V3_PARENT_MISMATCH')
+    }
+  }
+  const data = { version: CHECKPOINT_V3_VERSION, checkpoints: parsed.checkpoints }
+  if (bytes(data, true) > limits.maxBytes) {
+    throw new CheckpointV3Error(`Checkpoint v3 store exceeds byte limit (${bytes(data, true)}/${limits.maxBytes})`, 'LCX_CHECKPOINT_V3_LIMIT_EXCEEDED')
+  }
+  return data
+}
+
+function sleepSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds)
+}
+
+function fileSignature(file) {
+  try {
+    const info = statSync(file)
+    return { mtimeMs: info.mtimeMs, ctimeMs: info.ctimeMs, size: info.size, ino: info.ino }
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+function sameFileSignature(left, right) {
+  return left?.mtimeMs === right?.mtimeMs && left?.ctimeMs === right?.ctimeMs &&
+    left?.size === right?.size && left?.ino === right?.ino
+}
+
+function lockMetadata(text) {
+  const lines = String(text ?? '').split(/\r?\n/u)
+  const pid = Number(lines[0])
+  const startedAt = Number(lines[1])
+  const token = typeof lines[2] === 'string' && lines[2].length > 0 ? lines[2] : undefined
+  return {
+    pid: Number.isSafeInteger(pid) && pid > 0 ? pid : undefined,
+    startedAt: Number.isFinite(startedAt) && startedAt > 0 ? startedAt : undefined,
+    token,
+  }
+}
+
+function processAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error?.code === 'EPERM'
+  }
+}
+
+function staleLockSnapshot(file) {
+  try {
+    const info = statSync(file)
+    const text = readFileSync(file, 'utf8')
+    const metadata = lockMetadata(text)
+    const age = Date.now() - Math.max(info.mtimeMs, metadata.startedAt ?? 0)
+    if (age <= LOCK_STALE_MS || processAlive(metadata.pid)) return undefined
+    return { text, mtimeMs: info.mtimeMs, size: info.size }
+  } catch {
+    return undefined
+  }
+}
+
+function unlinkLockIfUnchanged(file, snapshot) {
+  if (!snapshot) return false
+  try {
+    const info = statSync(file)
+    if (info.mtimeMs !== snapshot.mtimeMs || info.size !== snapshot.size || readFileSync(file, 'utf8') !== snapshot.text) return false
+    unlinkSync(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function cleanupStaleTemps(file) {
+  const directory = dirname(file)
+  const prefix = `.${basename(file)}.`
+  let names
+  try {
+    names = readdirSync(directory)
+  } catch {
+    return
+  }
+  const now = Date.now()
+  for (const name of names) {
+    if (!name.startsWith(prefix) || !name.endsWith('.tmp')) continue
+    const temporary = join(directory, name)
+    try {
+      const info = statSync(temporary)
+      if (info.isFile() && now - info.mtimeMs > TEMP_STALE_MS) unlinkSync(temporary)
+    } catch {
+      // A concurrent writer may have removed or replaced the candidate.
+    }
+  }
+}
+
+export class CheckpointV3Store {
+  constructor(file, options = {}) {
+    this.file = file
+    this.lockFile = `${file}.lock`
+    this.limits = normalizedLimits(options)
+    this.fileSignature = undefined
+    this.data = this.load()
+  }
+
+  load(options = {}) {
+    cleanupStaleTemps(this.file)
+    try {
+      const data = validateData(JSON.parse(readFileSync(this.file, 'utf8')), this.file, this.limits, options)
+      this.fileSignature = fileSignature(this.file)
+      return data
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        this.fileSignature = undefined
+        return emptyData()
+      }
+      if (error instanceof CheckpointV3Error) throw error
+      throw new CheckpointV3Error(`Unable to load checkpoint v3 store ${this.file}`, 'LCX_CHECKPOINT_V3_CORRUPT', error)
+    }
+  }
+
+  refreshIfChanged() {
+    const currentSignature = fileSignature(this.file)
+    if (!sameFileSignature(currentSignature, this.fileSignature)) this.data = this.load()
+  }
+
+  get(id) {
+    this.refreshIfChanged()
+    return Object.prototype.hasOwnProperty.call(this.data.checkpoints, id) ? this.data.checkpoints[id] : undefined
+  }
+
+  has(id) {
+    return this.get(id) !== undefined
+  }
+
+  put(id, record) {
+    if (typeof id !== 'string' || id !== record?.checkpointId) {
+      throw new CheckpointV3Error(`Checkpoint v3 map key does not match record checkpointId (${id})`, 'LCX_CHECKPOINT_V3_KEY_MISMATCH')
+    }
+    if (!validRecord(record, { strictPortablePairing: true })) {
+      throw new CheckpointV3Error(`Invalid checkpoint v3 record ${id}`, 'LCX_CHECKPOINT_V3_CORRUPT')
+    }
+    mkdirSync(dirname(this.file), { recursive: true })
+    if (fileSignature(this.file)) ensurePrivateFileAcl(this.file)
+    ensurePrivateFileAcl(dirname(this.file))
+    const release = this.acquireLock()
+    try {
+      const latest = this.load()
+      const candidate = {
+        version: CHECKPOINT_V3_VERSION,
+        checkpoints: { ...latest.checkpoints, [id]: structuredClone(record) },
+      }
+      this.data = validateData(candidate, this.file, this.limits, { strictIds: new Set([id]) })
+      this.saveAtomicUnlocked()
+    } finally {
+      release()
+    }
+  }
+
+  acquireLock() {
+    const started = Date.now()
+    while (Date.now() - started <= LOCK_WAIT_MS) {
+      let fd
+      const token = randomUUID()
+      const lockText = `${process.pid}\n${Date.now()}\n${token}\n`
+      try {
+        fd = openSync(this.lockFile, 'wx', 0o600)
+        try {
+          writeFileSync(fd, lockText, { encoding: 'utf8' })
+          fsyncSync(fd)
+        } finally {
+          closeSync(fd)
+          fd = undefined
+        }
+        ensurePrivateFileAcl(this.lockFile)
+        return () => {
+          try {
+            const current = readFileSync(this.lockFile, 'utf8')
+            if (current === lockText) unlinkSync(this.lockFile)
+          } catch {
+            // The lock may have been removed by stale recovery after a crash.
+          }
+        }
+      } catch (error) {
+        if (fd !== undefined) {
+          try { closeSync(fd) } catch {}
+        }
+        if (error?.code !== 'EEXIST') {
+          throw new CheckpointV3Error(`Unable to acquire checkpoint v3 lock ${this.lockFile}`, 'LCX_CHECKPOINT_V3_LOCK_FAILED', error)
+        }
+        if (unlinkLockIfUnchanged(this.lockFile, staleLockSnapshot(this.lockFile))) continue
+        sleepSync(10)
+      }
+    }
+    throw new CheckpointV3Error(`Timed out acquiring checkpoint v3 lock`, 'LCX_CHECKPOINT_V3_LOCK_TIMEOUT')
+  }
+
+  saveAtomic(options = {}) {
+    mkdirSync(dirname(this.file), { recursive: true })
+    if (fileSignature(this.file)) ensurePrivateFileAcl(this.file)
+    ensurePrivateFileAcl(dirname(this.file))
+    const release = this.acquireLock()
+    try {
+      const latest = this.load()
+      const merged = {
+        version: CHECKPOINT_V3_VERSION,
+        checkpoints: { ...latest.checkpoints, ...this.data.checkpoints },
+      }
+      this.data = validateData(merged, this.file, this.limits, { strict: options.strict === true })
+      this.saveAtomicUnlocked()
+    } finally {
+      release()
+    }
+  }
+
+  saveAtomicUnlocked() {
+    cleanupStaleTemps(this.file)
+    const directory = dirname(this.file)
+    mkdirSync(directory, { recursive: true })
+    const temporary = join(directory, `.${basename(this.file)}.${randomUUID()}.tmp`)
+    const serialized = JSON.stringify(this.data, null, 2)
+    let fd
+    try {
+      fd = openSync(temporary, 'wx', 0o600)
+      // Harden the empty temporary file before it receives checkpoint content.
+      if (!ensurePrivateFileAcl(temporary)) {
+        throw new Error(`Unable to apply private ACL to checkpoint temporary file ${temporary}`)
+      }
+      writeFileSync(fd, serialized, { encoding: 'utf8' })
+      fsyncSync(fd)
+      closeSync(fd)
+      fd = undefined
+      try { chmodSync(temporary, 0o600) } catch {
+        // Windows may not expose POSIX mode bits; the ACL was applied before writing.
+      }
+      renameSync(temporary, this.file)
+      ensurePrivateFileAcl(this.file)
+      this.fileSignature = fileSignature(this.file)
+    } catch (error) {
+      if (fd !== undefined) {
+        try { closeSync(fd) } catch {}
+      }
+      try { unlinkSync(temporary) } catch {
+        // Preserve the original write failure.
+      }
+      throw new CheckpointV3Error(`Unable to atomically write checkpoint v3 store ${this.file}`, 'LCX_CHECKPOINT_V3_WRITE_FAILED', error)
+    }
+  }
+}