[MicroGery]

Summary

Rust checkpoint publication retains history, but callers need a way to inspect an exact checkpoint and explicitly restore its workspace. This adds isolated checkpoint loading and same-Root workspace restoration: an idle ordinary Session can publish history and files, restore files into a new directory, accept an explicit next message, and publish a successor using the existing checkpoint Head as its CAS expectation.

Refs #2370. This is a bounded Rust consumer increment; it does not close the issue or establish full TypeScript/cloud parity.

• Use one publishCheckpoint / checkpointReceipt contract. workspaceConsistency: null publishes history only; either explicit Workspace mode includes immutable file objects and an inventory. Both modes share one manifest and the checkpoint stream header.
• Retain durable exact-load claims, startup reconciliation, isolated inspection databases and original-operation receipts. Loading verifies Workspace objects without copying them into an unused inspection directory. History reads use shared read admission and immutable SQLite connections; Artifact subscriptions stream bounded chunks through one connection.
• Restore only an idle Session whose event-history cut still matches the checkpoint. Read markers, titles, pinning and binding changes no longer invalidate unchanged history; the current metadata revision is used only for the restore commit's CAS. Recheck history and idle state inside that commit, and commit the new binding and receipt atomically.
• Fence the target Session and overlapping Workspaces during capture/restore, including pending messages and admitted Goal producers. Unrelated Sessions can execute, edit metadata and publish checkpoints during the copy. Title changes wait behind per-Session admission; project relocation respects active reservations.
• Accept an absolute restore parent path, then obtain and validate its physical directory identity inside the Host. Restore into a new unique child directory with explicit backend/permission selection; loading and restoration never submit a message automatically.

Consistency and supported scope

Workspace capture requires caller_confirmed_quiescent or unverified and always returns external_writers_not_fenced. Caller confirmation means external writers remain stopped throughout capture; it is not an OS snapshot proof. Detected changes abort either mode, and hashes establish byte integrity only. This supports ordinary macOS project directories without Apple entitlements, with no unconditional point-in-time consistency claim. The consistency mode survives publication, loading and restoration.

Capture follows project .gitignore, nested ignore rules and .git/info/exclude, excludes Git metadata/dependencies/cache directories and known credential paths, and permits ordinary test certificate/key fixtures. Symlinks, special files and unsupported paths still fail. The former arbitrary entry/byte/depth/time caps are removed. File metadata/content checks remain, but they cannot fence external writers.

Restoration preserves the Session ID and checkpoint Head in the same Root. It does not rewind advanced event history, rebuild a lost Root or transfer authority across Hosts. WorkHub, child Sessions, Goal state and executor backends remain outside restoration scope. Failed or occupied destinations are retained for inspection and never adopted automatically. No UI, automatic execution, auxiliary-state migration or object GC is added. Workspace durability currently uses Unix facilities.

The simplified private checkpoint format intentionally has no compatibility shim for earlier development snapshots. Those need recreation or a separately designed offline migration; this PR does not silently reinterpret them.

Verification

The packaged-contract fix was rebased onto rust-preview@aee0d6f87. In the frozen-history method, the generated schema now carries the same display order and tool-call origin as live history. The exact-load test compares the frozen chunks with what the live Host returned before publication. Restore uses the merged path-based Workspace API and retains the observed physical parent identity. Upstream migration 18 is unchanged. This PR uses version 19 for its new checkpoint tables.

On the final PR head 78447d92a:

• The SDK check reproduced stale declarations before regeneration, then verified all five generated files. The Linux product job also passed declaration, type and packaging checks. The packaged public-client test passed against a real Host. All six hosted CLI shards and all four hosted Desktop shards passed.
• On macOS arm64, 33 checkpoint-storage tests, 11 Agent API tests and 13 Host checkpoint tests passed. One manual performance benchmark was skipped. Both public CLI clients passed, including the publish → exact load → history read path.
• On the same Mac, all 19 Desktop integration tests passed with the CI nextest filter, one test process at a time and zero retries. A plain single-process cargo test run timed out waiting for UI controls in 18 cases. Both CLI and Desktop used the upstream nsh-platform-gpui/runtime-shaders feature because the builder lacks the offline Metal compiler. The SDK TypeScript check and workspace-member formatting check also passed.
• Hosted CI reports an external-executor cancellation test failure in native shard 6. The same named test expected before_instructions_ack and observed opened on the unmodified merge base branch as well as on the earlier rebase base.

The Workspace performance benchmark remains outstanding.

Review notes

This update addresses all seven review topics: event-history eligibility, project ignore/file policy, admission scope, read costs, unnecessary serde compatibility, private inventory versioning, and duplicated publication APIs. It also adapts restore input to the path-based direction discussed in #6632 while preserving Host-owned directory identity checks.

The existing Linux directory-sync fix remains: reopen . relative to the capability directory before fsync, preserving authority and error propagation. The branch includes upstream #6628's CLI backend fixture correction, #6640's terminal test stabilization, and #6639's native executor replacement. During the earlier executor rebase, obsolete OAR lint edits were dropped and the upstream executor implementation was retained; only the still-relevant parent-authority assertion simplification remains in the first commit. A structural comparison against aee0d6f87 shows changes to 12 checkpoint methods and no changes to other services. No CI configuration, test timeout or assertion was weakened.

AI use

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

OpenAI Codex assisted with implementation, review, tests, documentation and this description. Material AI-authored commits include Generated-by: Codex.

Checklist

• Tests cover the changed behavior and failure boundaries
• Format, types and core affected Rust suites pass
• Verified the packaged public CLI checkpoint path on macOS and in hosted Linux CI
• Full hosted matrix green (see the upstream executor failure above)

Does this PR entail a change in behavior?

• Yes — described above
• No

[Astro-Han]

Automated review notice: This comment was posted by an automated review agent. It is not an independent human review and does not replace one.

This is a focused review of the directory-sync repair at bfd1c9aa095013e559d4fa5e82336a588609323f, not a complete review of the 45-file checkpoint feature or its database migration.

The range comparison shows the two original feature commits are patch-equivalent after rebasing onto #6628; the new author change replaces two directory fsync calls. Both now open . relative to the already-owned directory before syncing. The recursive materializer still syncs file content and directory entries before reporting readiness; restoration still syncs the parent and verifies the destination before recording its physical identity. Sync errors continue to propagate.

A controlled Linux syscall check reproduces EBADF when syncing an O_PATH directory descriptor, while opening . relative to it produces a syncable descriptor for the same device/inode. This checks the operating-system premise, not the full Rust Host implementation.

I read the actual logs from current-head CI 41833908251. All seven previously failing workspace cases now pass: native restore/next turn/CAS (8.177 seconds), in-flight Goal exclusion (6.297), atomic restore receipt (6.148), occupied-destination retry (5.586), immutable material/conditional guarantee (13.725), durable completion record (3.916), and Head/destination race rejection (25.427). This clears the previously observed failures for those exact cases. The run still fails the external-agent original-install-receipt UI wait at external_agents.rs:91, also observed on the shared branch; I have not established it as a checkpoint regression.

I found no new confirmed P0–P2 in these two sync changes. The actual Git merge against current rust-preview at 89e7dcdaf070566f511f4b8d99239b9a944d2993 succeeds. I have not independently completed the broader migration, load/restore authorization, directory ownership and crash-recovery review, nor run the complete native application locally. The author-reported macOS suites remain the author's evidence.

---

Automated review notice: This comment was posted by an automated review agent operated by Astro-Han. It is not an independent human review and does not replace one.

[UncertaintyDeterminesYou4ndMe]

Heads-up on an overlap with #6632. In #6632 (comment) @M4n5ter set the direction that callers name directories by path and AgentDirectorySelection (rootId / segments / directoryIdentity) goes away as an input contract; #6632 now removes the type and takes path across create, selectWorkspace, projects, imports and WorkHub, with maka-workspace-support resolving ~, ./.. and the most specific root, and capturing the identity itself.

SessionCheckpointRestore.parent here is a DirectorySelection, so whichever PR lands second has to adapt: if this one goes first, we will switch parent to a path in #6632 (one call into the same resolver); if #6632 goes first, this one needs that change on rebase. Happy to do either, or to send a patch here.

[M4n5ter]

English

Reviewed bfd1c9aa0. The durable restore journal, isolated inspection SQLite database, and destination directory identity checks are well structured, and the existing external_agents.rs CI failure on this run is an unrelated rust-preview baseline issue.

Before merging, several behavioral, concurrency, cost, and no-compatibility-shim issues need to be addressed:

1. restoreSessionCheckpoint checks session_control.revision instead of the conversation history cut (platform/event-log/src/root_store/checkpoints/restore.rs:168-170, 240-262)
   prepare_workspace_restore rejects restoration whenever current.revision != inventory.sessions[0].revision ("live Session advanced beyond checkpoint"). However, current.revision (session_control.revision + workspace binding metadata_epoch) advances on ordinary non-history operations:

   • Viewing a conversation after a completed turn clears has_unread via markRead (set_session_read_marker increments session_control.revision);
   • Automatic title generation or user metadata updates (renaming, pinning, labels) increment session_control.revision;
   • Project relocation advances metadata_epoch;
   • Restoring a checkpoint once increments session_control.revision while leaving the checkpoint Head unchanged, so the same checkpoint can never be restored a second time even with zero new messages.
     Restoration should verify that the session is idle (reusing export_bundle's require_idle checks) and that its event_log history cut still matches the checkpoint bundle, using the live current.revision only as the mutate_session_metadata CAS precondition.

2. Workspace capture ignores .gitignore, aborts the entire checkpoint on .env / *.pem / *.key, and enforces arbitrary hardcoded caps (platform/event-log/src/root_store/checkpoints/workspace.rs:35-38, 61-83, 140-155, 194-197, 223-234)

   • excluded() only skips a fixed list (.git, node_modules, .DS_Store, __pycache__, .cache, .maka-workspace.json), ignoring .gitignore / .git/info/exclude as well as common build/venv directories (target, .venv, etc., where symlinks like .venv/bin/python also abort capture).
   • secret() aborts the entire publication on any .env, .env.*, *.pem, *.key, etc. Running this against maka itself fails both with target/ (287,915 entries / 173.72 GiB) and on a clean tree due to test fixtures (platform/network/tests/integration/fixtures/*.{pem,key}); any normal project with a local gitignored .env also cannot create a checkpoint.
   • Please also remove arbitrary hardcoded caps (MAX_ENTRIES = 20_000, MAX_BYTES = 2 GiB, and the 120s wall-clock deadline) unless grounded in a real invariant with generous headroom—workspace capture should respect ignore rules rather than rejecting normal repositories.

3. Global Owner::runs lock rejects unrelated active sessions and holds Mutex<Runs> across the entire disk copy & fsync (plugins/agent/native/src/owner/checkpoints/session.rs:82-93, 125-130, plugins/agent/native/src/owner/checkpoints/restore.rs:85-103, 193-195)

   • Both publishSessionCheckpoint and restoreSessionCheckpoint return agent_checkpoint_busy whenever Owner::runs has any active controls, preparing, or retained_cleanup entry. Because Owner spans all sessions of the Agent, an active turn, scheduled task, Goal, or Bot run in Session B causes checkpoint publish/restore on a completely idle Session A to fail.
   • Holding OwnedMutexGuard<Runs> (plus Agent-wide goals.gate on restore) across the entire filesystem walk/hash/copy/fsync stalls markRead, metadata, send, and other runs.lock().await callers on unrelated sessions. Admission should fence at session/shared-workspace granularity inside a short critical section without holding Mutex<Runs> across disk I/O.

4. Unused full workspace materialization in loadHistoryCheckpoint and per-32 KiB writer EventLog open/migrate/fsync/close in with_loaded (platform/event-log/src/root_store/checkpoints/load.rs:146-200, 418-421, objects.rs:46-47, 183-255)

   • loadHistoryCheckpoint calls objects.inspection_workspace(...), copying and fsyncing the entire workspace into inspections/{key}.workspace, which no product code reads or cleans up. Isolated history/artifact inspection only needs workspace::verify.
   • Every loadedHistoryCheckpointHistory / Artifacts / Artifact (32 KiB chunk) query enters with_loaded, spawning an OS thread + Tokio runtime, calling Objects::open (2 directory fsyncs), taking an exclusive CheckpointLoad write gate and .writer.lock, opening EventLog in Execution mode (running all 18 migrations), re-hashing the manifest, reading 32 KiB, and shutting down. Reading a multi-MB attachment repeats that full writer open/fsync/close cycle hundreds of times. Please stream inspection artifacts via a Subscription (matching readHistoryCheckpoint) or keep read access lightweight and read-only without directory fsyncs, migrations, or exclusive write gates.

5. Remove #[serde(default, skip_serializing_if = "Option::is_none")] backward-compatibility shims on internal storage structs (platform/event-log/src/checkpoints.rs:56-57, platform/event-log/src/checkpoints/load.rs:39)
   We do not maintain runtime compatibility branches for pre-existing local SQLite JSON rows from #6498 / #6581 (and 0018's history_checkpoint_loads is a brand-new table anyway). Evolve the persisted struct directly; if existing local dev databases need updating, provide a standalone one-off migration script Gist in the PR description instead of keeping serde fallback attributes in code.

6. Drop speculative internal format version fields (platform/event-log/src/root_store/checkpoints/workspace.rs:41-44, 270, 295)
   Internal storage formats are updated directly without pre-allocating Inventory.version: u32 (version: 1 / != 1 checks) for hypothetical future versions.

7. Unify the parallel publishHistoryCheckpoint / publishSessionCheckpoint surface instead of preserving #6581 untouched (plugins/agent/api/src/contract/checkpoints.rs, plugins/agent/native/src/owner/checkpoints*, platform/event-log/src/checkpoints.rs)
   Nothing in product/UI/CLI code calls publishHistoryCheckpoint yet (only #6581 tests). Rather than carrying two parallel publish/receipt RPC pairs (publishHistoryCheckpoint + historyCheckpointReceipt and publishSessionCheckpoint + sessionCheckpointReceipt), dual Manifest variants, and dual stream header frames, please collapse onto a single checkpoint contract (with optional workspace capture where applicable) and migrate the existing callers/tests directly—unless there is a concrete requirement that forces two separate RPC families.

简体中文

看过 bfd1c9aa0 了。恢复操作的持久化日志、隔离的只读检视 SQLite 库以及目标目录物理身份校验整体结构是清晰的；另外这次 CI 里的 external_agents.rs 失败属于 rust-preview 基线问题，与本 PR 无关。

合入前需要先处理以下行为正确性、并发锁粒度、读写成本以及去兼容层问题：

1. restoreSessionCheckpoint 用 session_control.revision 判断会话是否推进，导致常规查看/改名/二次恢复全部失效（platform/event-log/src/root_store/checkpoints/restore.rs:168-170, 240-262）
   prepare_workspace_restore 只要发现 current.revision != inventory.sessions[0].revision 就报 "live Session advanced beyond checkpoint" 拒绝恢复。但 current.revision（session_control.revision + 工作区绑定 metadata_epoch）并不是对话历史游标：

   • 一轮对话结束后（has_unread = 1）发布检查点，随后用户只要点开会话触发 markRead（set_session_read_marker 会递增 session_control.revision）；
   • 后台自动生成标题，或用户改标题/置顶/改标签（metadata）；
   • 项目目录迁移递增 metadata_epoch；
   • 对同一检查点恢复过一次后想再次恢复（首次恢复自身会递增 session_control.revision，而检查点 Head 不变）；
     以上常规操作在零新消息的情况下都会让 restoreSessionCheckpoint 永久失败。恢复前置检查应改为校验会话空闲（复用 export_bundle 的 require_idle）且 event_log 历史切面仍与检查点 bundle 一致；实时 current.revision 仅作为 mutate_session_metadata 当次提交的 CAS 版本号。

2. 工作区扫描忽略 .gitignore、命中 .env/*.pem/*.key 直接整次报错中止，并带有无依据的硬编码上限（platform/event-log/src/root_store/checkpoints/workspace.rs:35-38, 61-83, 140-155, 194-197, 223-234）

   • excluded() 仅跳过了固定白名单（.git、node_modules、.DS_Store、__pycache__、.cache、.maka-workspace.json），未遵循 .gitignore / .git/info/exclude，也未处理 target、.venv 等构建与虚拟环境目录（例如 .venv/bin/python 软链接会直接中止捕获）。
   • secret() 命中 .env、.env.*、*.pem、*.key 等文件名即整次 Err 失败。用 maka 仓库自身实测：保留 target/ 时（287,915 条目 / 173.72 GiB）直接超限失败，即使排除 target/ 后也会因测试证书夹具 platform/network/tests/integration/fixtures/*.{pem,key} 100% 失败；任何本地带 gitignored .env 的常规项目同样无法创建检查点。
   • 同时请去掉无真实资源依据的硬编码上限（MAX_ENTRIES = 20_000、MAX_BYTES = 2 GiB、120s 固定超时），应通过遵循忽略规则处理工作区内容，而不是拒绝正常规模的开发仓库。

3. 全局 Owner::runs 互斥误拒其他无关活跃会话，且跨整次磁盘拷贝与 fsync 长持 Mutex<Runs>（plugins/agent/native/src/owner/checkpoints/session.rs:82-93, 125-130、plugins/agent/native/src/owner/checkpoints/restore.rs:85-103, 193-195）

   • publishSessionCheckpoint 和 restoreSessionCheckpoint 只要看到 Owner::runs 中存在任意 controls / preparing / retained_cleanup 就直接返回 agent_checkpoint_busy。由于 Owner 管辖整个 Agent 下的全部会话，只要会话 B（或定时任务 / Goal / Bot）正在运行，完全空闲的会话 A 就无法发布或恢复检查点。
   • 两者还通过 OwnedMutexGuard<Runs>（恢复路径另持有全局 goals.gate）在整个目录遍历、哈希、拷贝和 fsync 期间长持锁，大仓库拷贝期间会阻塞其他会话的 markRead、metadata、send 等所有需要 runs.lock().await 的常规操作。请改为按目标会话/共享工作区粒度在短临界区内完成准入互斥，不要跨磁盘 I/O 持有 Mutex<Runs>。

4. loadHistoryCheckpoint 无意义复制整份工作区副本，且 with_loaded 每读取 32 KiB 块都完整启停一次写模式 EventLog（platform/event-log/src/root_store/checkpoints/load.rs:146-200, 418-421、objects.rs:46-47, 183-255）

   • loadHistoryCheckpoint 调用 objects.inspection_workspace(...) 将完整工作区复制并 fsync 到 inspections/{key}.workspace，但没有任何产品接口读取或清理该目录，白白放大一倍磁盘占用；只读检视只需执行 workspace::verify。
   • loadedHistoryCheckpointHistory / Artifacts / Artifact（每块 32 KiB）每次查询都经由 with_loaded 新建 OS 线程与 Tokio runtime -> Objects::open（含 2 次目录 fsync）-> 独占 CheckpointLoad 写门控与 .writer.lock -> 以 Execution 写模式打开 EventLog（跑全部 18 个 migration）-> 重算 manifest SHA-256 -> 读 32 KiB -> shutdown()。读取几 MB 的附件就会重复上百次写库启停与目录 fsync。建议将检视附件读取改为流式 Subscription（对齐 readHistoryCheckpoint），或使用不触发目录 fsync/migration/独占写门控的轻量只读访问。

5. 移除内部持久化结构上的旧数据反序列化兼容属性（platform/event-log/src/checkpoints.rs:56-57、platform/event-log/src/checkpoints/load.rs:39）
   当前不提供本地旧格式运行时兼容保证，不需要在 PublicationRequest.workspace（以及全新表 0018 对应的 LoadState::Ready.workspace）上添加 #[serde(default, skip_serializing_if = "Option::is_none")] 来兼容 #6498 / #6581 的旧 JSON 行。请直接修改数据结构；如本地开发库有旧数据需要处理，在 PR body 中附上独立的一次性迁移脚本 Gist 即可。

6. 移除内部清单预留的 version 字段（platform/event-log/src/root_store/checkpoints/workspace.rs:41-44, 270, 295）
   内部存储格式后续如需调整直接修改即可，不为假设的未来升级预留 Inventory.version: u32（version: 1）及版本号分支检查。

7. 收口平行的 publishHistoryCheckpoint / publishSessionCheckpoint 双轨接口（plugins/agent/api/src/contract/checkpoints.rs、plugins/agent/native/src/owner/checkpoints*、platform/event-log/src/checkpoints.rs）
   目前全仓产品侧/UI/CLI 尚未接入 #6581 的 publishHistoryCheckpoint（仅测试调用）。不必为保留 #6581 原签名不动而并行维护两套同构的 publish/receipt RPC、Manifest 变体与流首帧类型；除非有明确的产品场景必须区分两套独立 RPC，否则请直接合并为统一的检查点接口（通过可选参数控制是否捕获工作区）并同步迁移现有测试调用方。

_{Automated review generated by Antigravity.}

[Astro-Han]

Automated review notice: This comment was posted by an automated review agent operated by Astro-Han. It is not an independent human review and does not replace one.

Scoped follow-up at 4638cc8a31f6ed8bdabd1a3d21b539cd7a19b275: I checked the checkpoint API/service changes, generated-contract packaging and export validation, and the new hosted failures. This is not a complete review of the 52-file checkpoint implementation.

[P2] Synchronize the generated Agent contract before packaging. The checked-in packages/plugin-sdk/src/contracts.ts does not match the Rust ABI used by this commit. The product job fails packages/plugin-sdk/scripts/generate.mjs check with Runtime declarations are stale: .../packages/plugin-sdk/src/contracts.ts (generate.mjs:262). This also has a user-facing integration failure: the CLI job cannot activate the Agent and reports plugin agent: capability contract mismatch: undeclared or changed export: agent; even the newly added public checkpoint-client test fails before activation. All four desktop CLI shards fail their 19 tests at this same Agent activation boundary.

The packaging path uses nativeImplementations.agent → contracts.agent (plugins/agent/agent/package.ts:33, packages/plugin-sdk/src/native.ts:306), and platform/plugin-core/src/package.rs:245–255 rejects the mismatched exported contract. Please regenerate the SDK declarations from the final Rust sources, then rerun the declaration check and real product/Host startup tests.

The failing CI checked out merge 2f5131987d56979fb01c21ba41e2ec3b994de210 into bfe92124; I fetched it and verified its source tree is identical to this PR head. The baseline product job verifies all five declaration files, and that baseline run passes its CLI/desktop shards. This failure is distinct from the previously unattributed UI/lifecycle timeouts.

Against current rust-preview 8822a2a7, a fresh static merge has content conflicts in platform/event-log/README.md and plugins/agent/native/src/service.rs. The full migration, restore/concurrency, filesystem identity and crash-recovery behavior remain unverified by me. I did not run Rust or native tests locally; the test results above are from the linked hosted jobs.

[Astro-Han]

This is a scoped follow-up to my earlier packaged-contract P2, rather than a complete review of the 52-file checkpoint implementation. I read the complete 202-line follow-up diff after the rebased review-fix commit, the non-schema range-diff, and the relevant path/identity and generated-schema code.

The stale generated-declaration finding is resolved in the current integrated build. I read the successful product job 127694650012 from run 42156127335: it verifies all five generated declaration files, passes SDK/bundle/UI type checks, and builds the 24 ordinary plugin packages. Its actual checkout is 57abee1aefa92bc641f2ec49e9566a2213d38299, with parents 72162299 and this PR head; my local merge-tree produces that same tree. I have not independently rerun real Host activation or the CLI public-client tests. Those tests remain separate from the generator result.

The follow-up also carries HistoryChunk.order and tool-call origin into the frozen-history contract and updates the exact-load assertion. A key-order-independent comparison of the SDK contracts against current Rust confines semantic differences to checkpoint-related methods/definitions; other services remain unchanged. The restore adaptation reads parent.identity from workspace::observed and passes it into the durable restore operation instead of dropping physical identity.

The new checkpoint migration is now version 19, while upstream version 18 is byte-identical to current rust-preview; the renamed checkpoint SQL itself is unchanged. I executed those two migration scripts and basic new-table inserts against a minimal synthetic SQLite predecessor. This does not test SQLx checksums, real user data, or an upgrade from an earlier unpublished checkpoint snapshot. My attempted whole-history SQLite run stops at migration 13 because it lacks Maka's custom SQL function; that harness limitation is not a product failure.

No new confirmed P0–P2 issue in this bounded follow-up. The current merge is clean, and the earlier two-conflict state is obsolete. The full 52-file review, crash/restart recovery, permissions, CAS, concurrent-client restoration and native cross-platform validation are still incomplete. The whole CI run is not yet complete; the author's Mac test counts are not my test results.

---

Automated review notice: This comment was posted by an automated review agent operated by Astro-Han. It is not an independent human review and does not replace one.