farming-code 2.2.8 → 2.2.12

package/README.md

@@ -9,9 +9,21 @@
 ![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)
 ![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-555)
 
-Farming is a browser workspace for supervising AI coding agents on a development machine. It keeps several live agents, structured conversations, real terminals, project files, review, history, and runtime controls in one place—without moving the repository or agent processes into the browser.
+Farming is an open-source, customizable browser workspace for supervising AI coding agents on a development machine. It keeps several live agents, structured conversations, real terminals, project files, review, history, and runtime controls in one place—without moving the repository or agent processes into the browser.
 
-Run Farming beside the coding CLIs you already use, then return to the same work from a desktop or phone. Closing the browser does not stop the agents; the native PTY host can also preserve live terminal sessions while the Farming server restarts.
+Run Farming on the development machine where your coding CLIs already work, then return to the same tasks from a desktop or phone. Closing the browser does not stop the agents; the native PTY host can also preserve live terminal sessions while the Farming server restarts.
+
+## Quick Start
+
+With Node.js 22 or newer and at least one supported coding CLI installed and signed in, install and start Farming in one command:
+
+```bash
+npm install --global farming-code@latest && farming daemon
+```
+
+Open the authenticated URL printed by the command, choose **New Agent**, select an Agent and workspace, and start in Chat or Terminal.
+
+![Farming Code workspace](./docs/products/code/assets/01-code-workspace.png)
 
 ## Two Interfaces, One Runtime
 
@@ -19,7 +31,7 @@ Farming 2 provides two complete browser interfaces over the same agents and sess
 
 ### Farming Code
 
-The default workbench for reading conversations, intervening in tasks, editing files, and reviewing an evolving change.
+The default workbench for reading conversations, intervening in tasks, editing files, and reviewing workspace changes.
 
 ![Farming Code structured Chat](./docs/products/code/assets/11-code-agent-process.png)
 
@@ -39,24 +51,36 @@ A keyboard-first control room for watching many agents, opening structured Chat
 
 Switching interfaces does not restart or duplicate an Agent. If Farming Code cannot start or render, its bounded diagnostic view leaves the live CRT surface available rather than hiding the running sessions.
 
+To switch without editing the URL:
+
+- **Farming Code → CRT:** click the gear at the bottom-left, open **Interface**, then choose **Farming CRT**.
+- **Farming CRT → Code:** press `S` (or choose **[S] SETTINGS**), then choose **Farming Code** under **UI Theme**.
+
+Farming carries the focused Agent into the other interface when possible. Both views keep using the same live Agent and provider session; this is an interface switch, not a restart.
+
 The complete current capability map and screenshot tour are in the [Farming 2 product overview](./docs/products/README.md). See the focused [Farming Code guide](./docs/products/code/README.md) and [Farming CRT guide](./docs/products/crt/README.md) for the full workflows.
 
+## Farming Net: One Portal For Deployments
+
+Farming Net is a separate, token-protected directory for the Farming instances you already run. Its cards can point to a Farming on the current device, a remote development host, an intranet address, or a tunnel. Enrolled targets accept short-lived signed passes, so users keep one portal login instead of a list of deployment URLs and target tokens.
+
+```bash
+FARMING_NET_PORT=6693 FARMING_NET_BASE_PATH=/farming-net npm run start:net
+```
+
+The portal keeps its token, signing identity, and private `instances.json` registry under `~/.farming-net/`. It does not proxy target traffic or store target tokens; each destination remains an independent Farming service and explicitly chooses whether to trust the portal. See the [Farming Net guide](./docs/products/net/README.md) for enrollment and the security boundary.
+
 ## What You Can Do
 
-- Group live agents by project, pin important work, rename sessions, track unread activity, and archive or resume work.
+- Group live agents by project, pin or rename important work, track unread activity, search live and historical sessions, and archive or resume tasks.
 - Use structured ACP Chat for Codex, Claude Code, OpenCode, and Qoder. Plans, reasoning, tools, permission requests, embedded terminals, child sessions, attachments, queued follow-ups, and exact change summaries remain available without overwhelming the final answer.
-- Open a real PTY Terminal when exact CLI behavior matters. Chat / Terminal changes the actual runtime and safely resumes the same provider session when its identity is available.
-- Change supported live Codex model, reasoning, Fast, Ultra, and permission settings. Terminal changes are applied to the running workflow before the next message rather than being limited to a future launch profile.
-- Browse Project Files, Open Editors, search with ripgrep, edit with Monaco, preview Markdown and images, follow `path:line` links, inspect git changes, diffs, and blame.
-- Review one evolving change across revisions, keep findings tied to the compared revision, mark files reviewed, and inspect meaningful deltas instead of treating every Agent turn as a separate review.
-- Search live Agents and the supported provider-session archive, then open, continue, restore, or resume the matching work.
+- Switch the same provider session between structured Chat and a real PTY Terminal. Supported Codex model, reasoning, Fast, Ultra, and permission changes reach the live workflow; a compatible Terminal applies model changes immediately and confirms the CLI state before accepting the next Composer message.
+- Browse, search, and lightly edit Project Files; inspect a VS Code-derived Git history graph, changed files, Git changes, Diff, and Blame; then open commits or working-copy changes in Review with captured revisions, inline comments, and Reviewed state.
 - Observe CPU/MEM, token-rate, context, quota, provider usage, and CRT daily/live token telemetry when the provider exposes the required data.
-- Use the same service from desktop and mobile browsers, with layouts designed for the amount of attention available on each device.
+- Continue the same Farming Code task from desktop or phone without moving the Agent process away from the development host.
 
 ![Farming Code project files and blame](./docs/products/code/assets/04-files-editor-blame.png)
 
-![Farming Review](./docs/products/code/assets/10-review-workflow.png)
-
 ## Supported Agent Paths
 
 Farming discovers installed CLIs on the host. The richer structured runtime currently applies to providers with ACP support; other detected coding agents remain first-class terminal sessions.
@@ -75,14 +99,7 @@ Farming discovers installed CLIs on the host. The richer structured runtime curr
 
 Farming hosts CLIs that already work on the same machine. It does not replace provider installation, login, or account configuration.
 
-## Quick Start
-
-Install Node.js 22 or newer, install and sign in to at least one supported coding CLI, then run:
-
-```bash
-npm install --global farming-code
-farming daemon
-```
+## Runtime Defaults And Daemon Commands
 
 Farming defaults to port `6694`, base path `/farming`, config directory `~/.farming`, and token authentication. The startup log prints a URL similar to:
 
@@ -90,7 +107,7 @@ Farming defaults to port `6694`, base path `/farming`, config directory `~/.farm
 http://development-host:6694/farming?token=<startup-token>
 ```
 
-Open it, choose **New Agent**, select an Agent and workspace, and start in Chat or Terminal. Useful daemon commands are:
+Useful daemon commands are:
 
 ```bash
 farming status
@@ -107,11 +124,7 @@ The first authenticated start stores a readable random token in `~/.farming/.ses
 
 Desktop keeps the project, conversation, files, and review close together. Mobile focuses one conversation, terminal, or file at a time and moves navigation into a drawer, making it useful for checking progress and sending a short intervention.
 
-<p align="center">
-  <img src="./docs/products/code/assets/05-mobile-agent-chat.jpg" alt="Farming Code on mobile" width="320">
-  &nbsp;&nbsp;
-  <img src="./docs/products/crt/assets/09-crt-mobile-dashboard.jpg" alt="Farming CRT on mobile" width="320">
-</p>
+Farming CRT is currently a desktop interface. Use Farming Code from a phone; CRT mobile concepts are not part of the supported product yet.
 
 ## Installation And Updates
 
@@ -143,9 +156,9 @@ Development host
   repositories, shells, Codex, Claude Code, OpenCode, Qoder, ...
 ```
 
-The backend owns lifecycle, authentication, session routing, workspace boundaries, history, and configuration. Interactive terminal sessions use a separate native PTY host by default, allowing browser and server reconnection without replacing the live process. The browser terminal renderer defaults to xterm.js; the Ghostty web adapter remains an explicit debug path.
+The backend owns lifecycle, authentication, session routing, workspace boundaries, history, and configuration. Interactive terminal sessions use a separate native PTY host by default, allowing browser and server reconnection without replacing the live process. The browser terminal renderer defaults to xterm.js WebGL as its single supported product path; the Ghostty web adapter remains an explicit debug path, not a runtime fallback.
 
-Runtime settings live in `~/.farming/settings.json`. Farming session metadata, the project membership index, archived runs, theme settings, update state, logs, and the startup token use separate files under `~/.farming/`. External provider histories remain read-only integrations.
+Runtime settings live in `~/.farming/settings.json`. Farming session metadata, the project membership index, archived runs, theme settings, update state, logs, and the startup token use separate files under `~/.farming/`. External provider histories remain read-only integrations except for explicit Codex archive and unarchive lifecycle actions.
 
 ## Security
 
@@ -158,6 +171,7 @@ Token authentication protects HTTP and WebSocket traffic. `FARMING_DISABLE_AUTH=
 - [Farming 2 product overview and capability map](./docs/products/README.md)
 - [Farming Code guide](./docs/products/code/README.md)
 - [Farming CRT guide](./docs/products/crt/README.md)
+- [Farming Net deployment portal](./docs/products/net/README.md)
 - [Mobile guide](./docs/products/code/mobile-guide.md)
 - [ACP runtime](./docs/products/code/acp-runtime.md)
 - [Review foundation](./docs/products/code/review-foundation.md)

package/README.zh_cn.md

@@ -9,9 +9,21 @@
 ![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)
 ![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-555)
 
-Farming 是一个运行在开发机上的浏览器 AI Coding Agent 工作台。它把多个实时 Agent、结构化对话、真实终端、项目文件、Review、历史记录和运行时控制放在一起，同时代码仓库和 Agent 进程仍然留在开发机上。
+Farming 是一个开源、可自定义、运行在开发机上的浏览器 AI Coding Agent 工作台。它把多个实时 Agent、结构化对话、真实终端、项目文件、Review、历史记录和运行时控制放在一起，同时代码仓库和 Agent 进程仍然留在开发机上。
 
-把 Farming 运行在你平时使用 Coding CLI 的机器旁边，就可以从电脑或手机回到同一批工作。关闭浏览器不会停止 Agent；Farming Server 重启时，独立的原生 PTY Host 也可以保留正在运行的终端会话。
+在 Coding CLI 已经能正常工作的开发机上运行 Farming，就可以从电脑或手机回到同一批任务。关闭浏览器不会停止 Agent；Farming Server 重启时，独立的原生 PTY Host 也可以保留正在运行的终端会话。
+
+## 快速开始
+
+准备好 Node.js 22 或更新版本，以及至少一个已安装、已登录的受支持 Coding CLI，然后用一行命令安装并启动 Farming：
+
+```bash
+npm install --global farming-code@latest && farming daemon
+```
+
+打开命令输出的带鉴权 URL，选择 **New Agent**、Agent 类型和 Workspace，然后从 Chat 或 Terminal 开始工作。
+
+![Farming Code 工作台](./docs/products/code/assets/01-code-workspace.png)
 
 ## 两套界面，同一套运行时
 
@@ -19,7 +31,7 @@ Farming 2 在同一批 Agent 和 Session 上提供两套完整的浏览器界面
 
 ### Farming Code
 
-默认工作台，适合阅读对话、介入任务、编辑文件，以及持续 Review 同一个演进中的修改。
+默认工作台，适合阅读对话、介入任务、编辑文件和检查工作区修改。
 
 ![Farming Code 结构化 Chat](./docs/products/code/assets/11-code-agent-process.png)
 
@@ -39,24 +51,36 @@ Farming 2 在同一批 Agent 和 Session 上提供两套完整的浏览器界面
 
 切换界面不会重启或复制 Agent。如果 Farming Code 启动或渲染失败，有限范围的诊断层仍会保留后面的实时 CRT 界面，而不是把正在运行的 Session 一起遮掉。
 
+不修改地址也可以直接切换：
+
+- **Farming Code → CRT：**点击左下角齿轮，打开**界面**，再选择 **Farming CRT**。
+- **Farming CRT → Code：**按 `S`（或点击 **[S] SETTINGS**），在 **UI Theme** 中选择 **Farming Code**。
+
+条件允许时，Farming 会把当前聚焦的 Agent 一起带到另一套界面。两边继续使用同一个实时 Agent 和 Provider Session；这里只切换界面，不会重启会话。
+
 完整能力矩阵和截图导览见 [Farming 2 产品总览](./docs/products/README.zh_cn.md)。两套界面的完整流程分别见 [Farming Code 指南](./docs/products/code/README.zh_cn.md) 和 [Farming CRT 指南](./docs/products/crt/README.zh_cn.md)。
 
+## Farming Net：部署门户
+
+Farming Net 是一套独立、带 Token 鉴权的 Farming 环境目录。卡片可以指向当前设备、远程开发机、内网地址或隧道中的 Farming；已登记的目标接受短时签名通行证，让用户只保留一个门户登录，不再分别记录每个部署地址和目标 Token。
+
+```bash
+FARMING_NET_PORT=6693 FARMING_NET_BASE_PATH=/farming-net npm run start:net
+```
+
+门户自己的 Token、签名身份和私有 `instances.json` 注册表放在 `~/.farming-net/`。它不代理目标流量，也不保存目标 Token；每个目标仍是独立 Farming 服务，并且主动决定是否信任门户。登记方式和安全边界见 [Farming Net 指南](./docs/products/net/README.zh_cn.md)。
+
 ## 现在可以做什么
 
-- 按项目组织实时 Agent，置顶重点工作、重命名、查看未读状态，并归档或恢复任务。
+- 按项目组织实时 Agent，置顶或重命名重点工作、查看未读状态、搜索实时与历史 Session，并归档或恢复任务。
 - Codex、Claude Code、OpenCode 和 Qoder 使用结构化 ACP Chat。计划、推理、工具调用、权限请求、内嵌终端、子 Session、附件、排队追问和精确修改摘要都可以保留，但不会淹没最终答案。
-- 需要原汁原味 CLI 行为时打开真实 PTY Terminal。Chat / Terminal 切换会改变实际运行时，并在身份可用时安全地恢复同一个 Provider Session。
-- 修改运行中 Codex 所支持的模型、思考强度、Fast、Ultra 和权限设置。Terminal 的修改会在下一条消息前作用到当前工作流，而不是只改未来的启动 Profile。
-- 浏览 Project Files 和 Open Editors，用 ripgrep 搜索、Monaco 轻量编辑、预览 Markdown/图片、跟随 `path:line` 链接，并检查 Git Changes、Diff 和 Blame。
-- 围绕同一个演进中的 Change 跨 Revision Review，让 Finding 与对比版本绑定，标记文件已审阅，并关注多轮之间真正有意义的变化。
-- 搜索实时 Agent 和受支持 Provider 的完整 Session 归档，然后打开、继续、恢复或 Resume 对应工作。
+- 在结构化 Chat 与真实 PTY Terminal 之间切换同一个 Provider Session。支持的 Codex 模型、思考强度、Fast、Ultra 和权限修改会作用到实时工作流；兼容 Terminal 会立即应用模型修改，并在接受下一条 Composer 消息前确认 CLI 的真实状态。
+- 浏览、搜索并轻量编辑 Project Files，通过复用 VS Code 图算法的 Git History 查看提交树与变更文件，检查 Git Changes、Diff 和 Blame，再把 Commit 或 Working Copy 修改送入带 Revision、行内评论和 Reviewed 状态的 Review。
 - 在 Provider 提供所需数据时查看 CPU/MEM、Token Rate、Context、Quota、Provider 用量，以及 CRT 的按日/实时 Token 遥测。
-- 在电脑和手机浏览器中使用同一个服务；不同布局围绕不同设备上可用的注意力设计。
+- 从电脑或手机继续同一个 Farming Code 任务，Agent 进程始终留在开发机上。
 
 ![Farming Code 项目文件与 Blame](./docs/products/code/assets/04-files-editor-blame.png)
 
-![Farming Review](./docs/products/code/assets/10-review-workflow.png)
-
 ## 支持的 Agent 路径
 
 Farming 会发现开发机上已经安装的 CLI。有 ACP 支持的 Provider 使用更完整的结构化运行时，其他检测到的 Coding Agent 仍然可以作为一等 Terminal Session 使用。
@@ -75,14 +99,7 @@ Farming 会发现开发机上已经安装的 CLI。有 ACP 支持的 Provider
 
 Farming 承载的是已经能在同一台机器正常工作的 CLI，不替代 Provider 的安装、登录和账户配置。
 
-## 快速开始
-
-安装 Node.js 22 或更新版本，并先安装、登录至少一个受支持的 Coding CLI：
-
-```bash
-npm install --global farming-code
-farming daemon
-```
+## 运行默认值与 Daemon 命令
 
 默认端口是 `6694`，Base Path 是 `/farming`，配置目录是 `~/.farming`，Token 鉴权默认开启。启动日志会打印类似下面的 URL：
 
@@ -90,7 +107,7 @@ farming daemon
 http://development-host:6694/farming?token=<startup-token>
 ```
 
-打开 URL，选择 **New Agent**、Agent 类型和 Workspace，然后从 Chat 或 Terminal 开始工作。常用守护进程命令：
+常用守护进程命令：
 
 ```bash
 farming status
@@ -107,11 +124,7 @@ farming stop
 
 桌面端把项目、对话、文件和 Review 放在彼此靠近的位置。移动端一次聚焦一段对话、一个终端或一个文件，并把导航移入抽屉，更适合查看进度和发送短介入。
 
-<p align="center">
-  <img src="./docs/products/code/assets/05-mobile-agent-chat.jpg" alt="Farming Code 手机界面" width="320">
-  &nbsp;&nbsp;
-  <img src="./docs/products/crt/assets/09-crt-mobile-dashboard.jpg" alt="Farming CRT 手机界面" width="320">
-</p>
+Farming CRT 当前只作为桌面界面使用。手机请使用 Farming Code；CRT 手机方案目前仍是概念设计，不属于已支持的产品能力。
 
 ## 安装与更新
 
@@ -143,9 +156,9 @@ Development host
   repositories, shells, Codex, Claude Code, OpenCode, Qoder, ...
 ```
 
-后端负责生命周期、鉴权、Session 路由、Workspace 边界、History 和配置。交互式 Terminal 默认由独立的原生 PTY Host 持有，因此浏览器和 Server 可以重新连接，而不需要替换实际进程。xterm.js 是产品默认终端渲染器；Ghostty Web Adapter 只保留为显式调试路径。
+后端负责生命周期、鉴权、Session 路由、Workspace 边界、History 和配置。交互式 Terminal 默认由独立的原生 PTY Host 持有，因此浏览器和 Server 可以重新连接，而不需要替换实际进程。xterm.js WebGL 是唯一受支持的产品 Terminal Renderer；Ghostty Web Adapter 只保留为显式调试路径，不作为运行时 Fallback。
 
-运行时设置存放在 `~/.farming/settings.json`。Farming Session 元数据、项目成员索引、归档运行、主题设置、更新状态、日志和启动 Token 使用 `~/.farming/` 下彼此独立的文件。外部 Provider History 仍然只读。
+运行时设置存放在 `~/.farming/settings.json`。Farming Session 元数据、项目成员索引、归档运行、主题设置、更新状态、日志和启动 Token 使用 `~/.farming/` 下彼此独立的文件。外部 Provider History 保持只读，但明确的 Codex archive / unarchive 生命周期操作除外。
 
 ## 安全
 
@@ -158,6 +171,7 @@ Token 鉴权同时保护 HTTP 和 WebSocket。`FARMING_DISABLE_AUTH=1` 只适合
 - [Farming 2 产品总览与能力矩阵](./docs/products/README.zh_cn.md)
 - [Farming Code 指南](./docs/products/code/README.zh_cn.md)
 - [Farming CRT 指南](./docs/products/crt/README.zh_cn.md)
+- [Farming Net 部署门户](./docs/products/net/README.zh_cn.md)
 - [移动端指南](./docs/products/code/mobile-guide.zh_cn.md)
 - [ACP 运行时](./docs/products/code/acp-runtime.zh_cn.md)
 - [Review 基础](./docs/products/code/review-foundation.zh_cn.md)

package/THIRD_PARTY_NOTICES.md

@@ -15,8 +15,8 @@ preserved in bundled `node_modules` when bundled dependencies are enabled.
 | Package | Version | License | Purpose |
 | --- | --- | --- | --- |
 | `@agentclientprotocol/sdk` | 1.2.1 | Apache-2.0 | ACP JSON-RPC client and protocol types |
-| `@agentclientprotocol/codex-acp` | 1.1.2 | Apache-2.0 | Codex ACP adapter |
-| `@agentclientprotocol/claude-agent-acp` | 0.58.1 | Apache-2.0 | Claude Code ACP adapter |
+| `@agentclientprotocol/codex-acp` | 1.1.4 | Apache-2.0 | Codex ACP adapter |
+| `@agentclientprotocol/claude-agent-acp` | 0.59.0 | Apache-2.0 | Claude Code ACP adapter |
 | `@xterm/addon-clipboard` | 0.2.0 | MIT | Browser terminal clipboard integration |
 | `@xterm/addon-fit` | 0.11.0 | MIT | Browser terminal sizing |
 | `@xterm/addon-search` | 0.16.0 | MIT | Browser terminal search |
@@ -65,6 +65,15 @@ The CRT skin bundles one font file under `frontend/skins/crt/fonts/`:
 
 The corresponding license texts are stored beside the font files.
 
+## Adapted Source Code
+
+Farming's Git history swimlane transform and graph-row renderer adapt the
+Visual Studio Code SCM history graph from Microsoft Visual Studio Code commit
+`0217c2f1a0defc7fdbfb4feba74e71e366de6822`. The adapted files retain the
+Microsoft copyright and MIT license header. Visual Studio Code is licensed
+under the MIT License:
+https://github.com/microsoft/vscode/blob/0217c2f1a0defc7fdbfb4feba74e71e366de6822/LICENSE.txt
+
 ## Bundled Data
 
 Farming includes a generated Chinese poetic token word list at

package/backend/acp-checkpoint-store.js

@@ -0,0 +1,198 @@
+const crypto = require('crypto');
+const fs = require('fs/promises');
+const path = require('path');
+const { promisify } = require('util');
+const zlib = require('zlib');
+const storageLayout = require('./storage-layout');
+
+const gzip = promisify(zlib.gzip);
+const gunzip = promisify(zlib.gunzip);
+const CHECKPOINT_VERSION = 1;
+const DEFAULT_WRITE_DELAY_MS = 250;
+
+async function durableWrite(file, data) {
+  const handle = await fs.open(file, 'w');
+  try {
+    await handle.writeFile(data);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function syncDirectory(directory) {
+  const handle = await fs.open(directory, 'r');
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+function normalizeIdentity(value = {}) {
+  return {
+    provider: String(value.provider || '').trim().toLowerCase(),
+    providerHomeId: String(value.providerHomeId || 'default').trim() || 'default',
+    sessionId: String(value.sessionId || '').trim(),
+    cwd: path.resolve(String(value.cwd || process.cwd())),
+  };
+}
+
+function checkpointKey(identity) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify(normalizeIdentity(identity)))
+    .digest('hex');
+}
+
+function sameIdentity(left, right) {
+  return JSON.stringify(normalizeIdentity(left)) === JSON.stringify(normalizeIdentity(right));
+}
+
+class AcpCheckpointStore {
+  constructor(configDir, options = {}) {
+    this.dir = storageLayout.acpCheckpointsDir(configDir);
+    this.writeDelayMs = Number.isFinite(Number(options.writeDelayMs))
+      ? Math.max(0, Math.floor(Number(options.writeDelayMs)))
+      : DEFAULT_WRITE_DELAY_MS;
+    this.pending = new Map();
+    this.writeChains = new Map();
+  }
+
+  paths(identity) {
+    const key = checkpointKey(identity);
+    return {
+      key,
+      checkpoint: path.join(this.dir, `${key}.json.gz`),
+      dirty: path.join(this.dir, `${key}.dirty`),
+    };
+  }
+
+  enqueue(key, operation) {
+    const previous = this.writeChains.get(key) || Promise.resolve();
+    const next = previous.catch(() => {}).then(operation);
+    this.writeChains.set(key, next);
+    void next.then(() => {
+      if (this.writeChains.get(key) === next) this.writeChains.delete(key);
+    }, () => {
+      if (this.writeChains.get(key) === next) this.writeChains.delete(key);
+    });
+    return next;
+  }
+
+  async load(identity, options = {}) {
+    const normalized = normalizeIdentity(identity);
+    if (!normalized.provider || !normalized.sessionId) return null;
+    const files = this.paths(normalized);
+    const inFlight = this.writeChains.get(files.key);
+    if (inFlight) await inFlight.catch(() => {});
+    try {
+      const [compressed, dirty] = await Promise.all([
+        fs.readFile(files.checkpoint),
+        fs.access(files.dirty).then(() => true).catch(() => false),
+      ]);
+      const payload = JSON.parse((await gunzip(compressed)).toString('utf8'));
+      if (
+        payload?.version !== CHECKPOINT_VERSION
+        || !sameIdentity(payload.identity, normalized)
+        || !payload.state
+      ) return null;
+      if (dirty && options.allowDirty !== true) return null;
+      return { state: payload.state, exact: !dirty, savedAt: Number(payload.savedAt || 0) };
+    } catch (error) {
+      if (error?.code !== 'ENOENT') {
+        console.warn('Failed to read ACP checkpoint:', error && (error.message || error));
+      }
+      return null;
+    }
+  }
+
+  async markDirty(identity) {
+    const normalized = normalizeIdentity(identity);
+    if (!normalized.provider || !normalized.sessionId) return;
+    const files = this.paths(normalized);
+    const pending = this.pending.get(files.key);
+    if (pending?.timer) clearTimeout(pending.timer);
+    this.pending.delete(files.key);
+    return this.enqueue(files.key, async () => {
+      await fs.mkdir(this.dir, { recursive: true });
+      await durableWrite(files.dirty, `${Date.now()}\n`);
+      await syncDirectory(this.dir);
+    });
+  }
+
+  schedule(identity, state, options = {}) {
+    const normalized = normalizeIdentity(identity);
+    if (!normalized.provider || !normalized.sessionId || !state) return;
+    const files = this.paths(normalized);
+    const previous = this.pending.get(files.key);
+    if (previous?.timer) clearTimeout(previous.timer);
+    const pending = {
+      identity: normalized,
+      state,
+      exact: options.exact === true,
+      timer: null,
+    };
+    pending.timer = setTimeout(() => {
+      this.pending.delete(files.key);
+      void this.write(pending.identity, pending.state, { exact: pending.exact });
+    }, this.writeDelayMs);
+    pending.timer.unref?.();
+    this.pending.set(files.key, pending);
+  }
+
+  async write(identity, state, options = {}) {
+    const normalized = normalizeIdentity(identity);
+    if (!normalized.provider || !normalized.sessionId || !state) return;
+    const files = this.paths(normalized);
+    const pending = this.pending.get(files.key);
+    if (pending?.timer) clearTimeout(pending.timer);
+    this.pending.delete(files.key);
+    return this.enqueue(files.key, async () => {
+      const payload = {
+        version: CHECKPOINT_VERSION,
+        savedAt: Date.now(),
+        identity: normalized,
+        state: state.exportCheckpoint(),
+      };
+      const compressed = await gzip(Buffer.from(JSON.stringify(payload)), { level: zlib.constants.Z_BEST_SPEED });
+      await fs.mkdir(this.dir, { recursive: true });
+      if (options.exact !== true) {
+        await durableWrite(files.dirty, `${Date.now()}\n`);
+        await syncDirectory(this.dir);
+      }
+      const temporary = `${files.checkpoint}.${process.pid}.${Date.now()}.tmp`;
+      try {
+        await durableWrite(temporary, compressed);
+        await fs.rename(temporary, files.checkpoint);
+        await syncDirectory(this.dir);
+      } finally {
+        await fs.rm(temporary, { force: true }).catch(() => {});
+      }
+      if (options.exact === true) {
+        await fs.rm(files.dirty, { force: true });
+        await syncDirectory(this.dir);
+      }
+    });
+  }
+
+  async flush() {
+    const pending = [...this.pending.values()];
+    this.pending.clear();
+    pending.forEach(item => {
+      if (item.timer) clearTimeout(item.timer);
+    });
+    await Promise.all(pending.map(item => this.write(item.identity, item.state, { exact: item.exact })));
+    await Promise.all([...this.writeChains.values()].map(write => write.catch(() => {})));
+  }
+
+  async dispose() {
+    await this.flush();
+  }
+}
+
+module.exports = {
+  AcpCheckpointStore,
+  CHECKPOINT_VERSION,
+  checkpointKey,
+  normalizeIdentity,
+};