[jiangkoumo]

关联 #534（macOS native 上的三个问题），基于 layerfs_v2_0_0（d43047413），按 docs/architecture 与 #533 的 2.0 意图修，只改 2.0 保留的入口。

改了什么

1. 并发打开（A）：macOS 的写入准入改为与 Linux 相同的 flock 排队；StoreService::open_direct 遇到锁占用时返回 Busy，不再统一包成 Failed。
2. Store 目录权限（B）：store create（identity::make_empty）、install_local、backup restore 在用户检查之后以 0700 创建 Store 目录；kernel_guard::check 保持纯检查、无副作用（只读打开不留空目录），统一取 Store 文件的 parent。已有目录为 0755 时，project init 提前报 Unsupported，信息含路径、当前/期望权限与 chmod 700 <path>。校验失败只清理本次新建的目录。
3. macOS native 命令环境（C）：host_process 在 macOS 上透传 RUSTUP_HOME、CARGO_HOME、GIT_CONFIG_GLOBAL（存在时），HOME 仍为 <sandbox>/tmp；用 cfg(target_os = "macos") 门控，Linux 行为与基线一致。
4. 同步更新 docs/architecture 与 SDK 方法文档。

验证

• macOS（M2，macOS 27.2）：cargo fmt --check、tools/check_product_boundary.py、工具测试、7 个 crate clippy -D warnings、受影响测试全部通过；store_open_cache 的运行中写锁测试在 macOS 上启用并通过。
• Linux（x86_64，Rust 1.85.1）：fmt、边界检查、5 个 crate clippy --all-targets -D warnings 通过；layerfs-store-service 136、layerfs-store-backup 19、layerfs-sandbox 101、layerfs-control 12、layerfs-api 83 通过。
• 失败 3 个，在基线 d430474 上同样失败（环境相关，非本 PR 引入）：layerfs-control --test kernel_application、layerfs-api --test workspace_names 两个。
• 未运行：Docker/VM 沙箱路径、PostgreSQL、全工作区测试。

已知未改

• layerfs doctor 对 Store 目录权限用 0o076 判定（允许 0701），比 kernel_guard 的 0o077 略宽，未在本 PR 修改。
• LayerFS 2.0: one home, machines and Stores, one SDK #533 落地后可能需要再 merge 一次解冲突。

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[ImmuneFOMO]

Retested 6be2f6c on my M3 Max (macOS 26.6.2), release build, native machine, with my #534 scripts ported to the 2.0 API. I ran the same scripts on the base d430474 to compare. Your writer_admission, kernel_guard and local_search_path tests pass here too.

                                   base d430474               6be2f6c
agents failing at a shared start   2 of 3 in 2 of 3 runs      0 in 15 runs of 3-10 agents
cold cargo build, no exports       28.6 s toolchain install   13.1 s
                                   + 17.9 s build

1. Concurrent start: on the base the two agents fail at sandbox.create with Store open: Store busy before effect in the daemon log. With the fix most runs started all agents at the same moment and some were staggered. In one run I killed an agent's node process with kill -9 in the middle of its commits, and in three I killed the daemon that does an agent's writes. The other agents kept committing every time. Over all 17 runs: 1716 commits, no errors outside the killed agents, nothing hung, and PRAGMA integrity_check on store.sqlite is ok.

2. Store folder: with 0755, store.create, project.init, branch.fork and sandbox.create all stop with Unsupported, the path and chmod 700. On the doctor gap you listed: for that folder doctor suggests chmod g-rwx,o-rw, which gives 0701. Doctor then reports ok, but project.init still refuses:

   Unsupported: the Store's directory .../home/store/p has mode 0701 (group/other bits 0001 are set); the daemon requires a private directory (mode 0700, no group/other access); fix with: chmod 700 .../home/store/p
   

   Should doctor's Store folder check (scan.rs:81) use 0o077 and suggest chmod 700 like kernel_guard? The other home folders can keep 0701 for traversable.

3. Without any exports, commands now get RUSTUP_HOME, CARGO_HOME and GIT_CONFIG_GLOBAL while HOME stays tmp. git config user.email works and rustup no longer installs the toolchain into the sandbox tmp

The full flow passes too: init, fork, mount, edits from the host, commit, cargo build, commit with target/, fork, warm build (0.54 s), merge, close. Nothing is left mounted or running after close.

Also on the base, so it was there before the flock: with 5 or more agents some commits wait 1 to 4.3 s while the other agents' commits keep overtaking them (up to 58 during one wait), sometimes until every agent that wasn't stuck has finished. Is that known, or should I open an issue for it?

[jiangkoumo]

Retested 6be2f6c on my M3 Max (macOS 26.6.2), release build, native machine, with my #534 scripts ported to the 2.0 API. I ran the same scripts on the base d430474 to compare. Your writer_admission, kernel_guard and local_search_path tests pass here too.

                                   base d430474               6be2f6c

agents failing at a shared start   2 of 3 in 2 of 3 runs      0 in 15 runs of 3-10 agents

cold cargo build, no exports       28.6 s toolchain install   13.1 s

                                   + 17.9 s build

1. Concurrent start: on the base the two agents fail at sandbox.create with Store open: Store busy before effect in the daemon log. With the fix most runs started all agents at the same moment and some were staggered. In one run I killed an agent's node process with kill -9 in the middle of its commits, and in three I killed the daemon that does an agent's writes. The other agents kept committing every time. Over all 17 runs: 1716 commits, no errors outside the killed agents, nothing hung, and PRAGMA integrity_check on store.sqlite is ok.

2. Store folder: with 0755, store.create, project.init, branch.fork and sandbox.create all stop with Unsupported, the path and chmod 700. On the doctor gap you listed: for that folder doctor suggests chmod g-rwx,o-rw, which gives 0701. Doctor then reports ok, but project.init still refuses:

   
   Unsupported: the Store's directory .../home/store/p has mode 0701 (group/other bits 0001 are set); the daemon requires a private directory (mode 0700, no group/other access); fix with: chmod 700 .../home/store/p
   
   

   Should doctor's Store folder check (scan.rs:81) use 0o077 and suggest chmod 700 like kernel_guard? The other home folders can keep 0701 for traversable.

3. Without any exports, commands now get RUSTUP_HOME, CARGO_HOME and GIT_CONFIG_GLOBAL while HOME stays tmp. git config user.email works and rustup no longer installs the toolchain into the sandbox tmp

The full flow passes too: init, fork, mount, edits from the host, commit, cargo build, commit with target/, fork, warm build (0.54 s), merge, close. Nothing is left mounted or running after close.

Also on the base, so it was there before the flock: with 5 or more agents some commits wait 1 to 4.3 s while the other agents' commits keep overtaking them (up to 58 during one wait), sometimes until every agent that wasn't stuck has finished. Is that known, or should I open an issue for it?

@ImmuneFOMO 非常感谢这么细的复测，17 轮、1716 次 commit 加上 kill -9 和杀 daemon 的场景，比我们自己测得还全。

1. doctor 的 Store 目录检查：你说得对，这是我们这次加 0700 要求时漏掉的。已在 8a85fa4 修复：store/ 目录改用 0o077 检查，提示 chmod 700，和 kernel_guard 一致；其他 home 目录仍保留 0701（traversable）。新增测试 a_store_folder_others_may_pass_through_is_an_error_naming_chmod_700，doctor 测试 5 项和 layerfs-control clippy 在 Linux 上通过。

2. 5 个以上 agent 时 commit 被插队等待 1–4.3 秒：这在基线上就有，和本 PR 无关。麻烦你单独开一个 issue，附上复现脚本和数据，我们后面会针对它来修。

再次感谢！

[ImmuneFOMO]

Checked 8a85fa4 on my Mac. The doctor tests pass (5 of 5), and for the 0701 Store folder doctor now says has mode 0701; a Store's folder is 0700 with chmod 700 as the fix. After that project.init goes through. The commit stalls are in #578, with the scripts and data, and they come from the sync(2) before each commit

[Mola-maker]

Hey @jiangkoumo, PR #570 is currently conflicting with recent layerfs_v2_0_0 updates. Since this touches macOS native concurrent open & permissions, could you rebase onto the latest base when convenient? Thanks!

[jiangkoumo]

本 PR 的写入准入（并发打开返回 Busy）已移植进 #647，并补了 digest 拒绝报确定 Busy 与 #540 的占槽修复，统一在 #647 推进和验证。这里先关闭，后续讨论请移步 #647。感谢 @ImmuneFOMO 之前的复测。