feat(runtime): provision verified dependencies for managed workspaces

[zhiiw]

Summary

This PR adds a verified dependency-environment boundary for managed workspaces.

Its primary invariant is:

Managed execution may consume dependency files only from a Maka-owned, identity-verifiable environment derived from the admitted Git baseline. If producer, artifact, workspace, or identity proof is missing or changes, admission fails closed before an execution scope is issued.

The implementation never copies or reuses ignored node_modules content from the source checkout.

What changed

• Adds a durable managed dependency artifact owner with staging, receipt persistence, atomic publication, reopen verification, active leases, and bounded LRU cleanup.
• Derives environment identity from the admitted manifest and lockfile, package-manager identity, actual Node version and ABI, platform/architecture, and policy version.
• Verifies the complete dependency tree and rejects escaping symlinks, producer drift, receipt drift, workspace drift, and artifact tampering.
• Binds dependency environments to managed execution scopes and exposes node_modules/** as a read-only logical projection for Read, Glob, and Grep.
• Revalidates Git head, workspace authority, and dependency identity after provisioning and before issuing the final scope.
• Ships and verifies a bundled npm 12.0.2 producer for supported Node runtimes.
• Materializes the bundled producer with tar 7.5.22 in place of npm 12.0.2's bundled 7.5.19, and records patch provenance plus final-tree hashes in the manifest.
• Runs npm with hermetic configuration, the official registry, lifecycle scripts disabled, and audit/funding network activity disabled.
• Adds Electron resource packaging, third-party notices, packaged-resource verification, and a real bundled-runtime smoke test.

Safety and behavior boundaries

• The source checkout remains outside the dependency authority boundary; source node_modules is never admitted.
• Provisioning mode is fixed before execution admission and cannot silently fall back after durable selection.
• Only exact npm 12.0.2 and non-workspace package-lock v3 inputs are currently accepted.
• Lockfiles containing links, lifecycle scripts, non-registry resolved URLs, missing integrity, or oversized inputs are rejected.
• This PR enables read-only dependency consumption only. It does not enable Shell/Build execution, dependency mutation, secrets, scratch directories, or automatic managed mode for existing users.
• The existing attached-checkout/default execution behavior is unchanged.

Validation

• Managed owner real-Git suite: 20 passed, 1 existing Windows-specific skip.
• Dependency artifact/crash/worker-bridge focused suite: 11 passed.
• Runtime-host bundled npm and workspace-composition focused suites: 8 passed.
• Real materialized bundled npm smoke: npm 12.0.2 successfully completed hermetic npm ci on Node 26.6.0.
• Script suite: 124 passed, 1 existing skip.
• Third-party notice check: passed.
• Storage and runtime-host typechecks: passed.
• Targeted Biome checks and git diff --check: passed.

The repository-wide typecheck still reports pre-existing UI conversationKey typing failures outside this PR's paths; this PR does not modify that UI seam.

Release impact

The raw Windows resource payload adds approximately 14.64 MB before installer compression (bundled npm runtime plus manifest). Final installer deltas remain platform/release-pipeline dependent and should be measured by release CI.

中文说明

概要

这个 PR 为 managed workspace 增加一条经过验证的依赖环境边界。

它证明的主要不变量是：

managed execution 只能读取由 Maka 所有、可验证身份、并且从已准入 Git baseline 派生的依赖环境。只要 producer、artifact、workspace 或 identity 的证明缺失或发生变化，系统就必须在签发 execution scope 前 fail closed。

实现不会复制或复用 source checkout 中被忽略的 node_modules。

主要改动

• 新增 managed dependency artifact owner，覆盖 staging、durable receipt、原子发布、重开验证、active lease 和有界 LRU 清理。
• 环境身份绑定 manifest/lockfile hash、package manager、实际 Node 版本与 ABI、平台/架构和 policy version。
• 验证完整依赖树，并拒绝逃逸 symlink、producer drift、receipt drift、workspace drift 和 artifact 篡改。
• 将依赖环境绑定到 managed execution scope，通过只读逻辑投影让 Read、Glob、Grep 访问 node_modules/**。
• provisioning 完成后、scope 签发前，重新验证 Git head、workspace authority 和 dependency identity。
• 内置并验证 npm 12.0.2；物化时将其中已知存在问题的 tar 7.5.19 确定性替换为 7.5.22，并在 manifest 中记录补丁来源与最终树 hash。
• npm 使用 hermetic 配置、官方 registry、禁用 lifecycle scripts，并关闭 audit/funding 网络请求。
• 补齐 Electron resource 打包、第三方声明、打包资源验证和真实 bundled runtime smoke test。

能力边界

• source checkout 不进入依赖 authority 边界，source node_modules 永不准入。
• provisioning mode 在执行准入前确定，durable selection 后不能静默 fallback。
• 当前只接受精确 npm 12.0.2 和非 workspace 的 package-lock v3。
• links、lifecycle scripts、非 registry resolved URL、缺失 integrity 或超限输入都会被拒绝。
• 当前只开放 Read/Glob/Grep 的只读依赖访问；不开放 Shell/Build、依赖修改、secret、scratch，也不会默认启用 managed mode。
• 现有 attached checkout/default execution 行为不变。

验证

• managed owner real-Git：20 通过，1 个既有 Windows 条件 skip。
• dependency artifact/crash/worker bridge：11 通过。
• runtime-host bundled npm/workspace composition：8 通过。
• 真实 bundled npm smoke：npm 12.0.2 在 Node 26.6.0 下完成 hermetic npm ci。
• scripts：124 通过，1 个既有 skip。
• third-party notices、storage/runtime-host typecheck、定向 Biome 和 git diff --check 均通过。

仓库全量 typecheck 仍有本 PR 路径之外、既有的 UI conversationKey 类型错误；本 PR 没有修改该 UI seam。

包体影响

Windows 原始资源在 installer 压缩前约增加 14.64 MB（bundled npm runtime 与 manifest）。最终安装包增量仍需由各平台 release CI 实测。

[zhiiw]

Addressed the actionable authority gaps in 57aba6bb7.

Changes made

• The producer contract is now closed to the exact hermetic_dependency_builder_v1 capability. The authority rejects capabilities outside the fixed network, filesystem, secret, child-process, and lifecycle-script profile.
• environmentId and the durable receipt now bind both a producer policy digest and a producer runtime digest.
• The producer runtime digest covers the verified bundled npm runtime tree, the Node executable digest, Node version/ABI, platform, and architecture.
• The Node executable is revalidated immediately before the owned npm spawn; npm runtime inventory is also revalidated for every provision.
• Added a producer-mid-flight process-exit test. Restart removes the orphan staging directory and never publishes the partial artifact.
• Added a managed-owner regression where the producer writes a sentinel beside outputRoot; the managed Git worktree remains clean and never contains that sentinel.

Findings that did not require the proposed architecture expansion

dirname(outputRoot) is not the managed worktree. The artifact authority creates:

<storage-root>/managed-workspaces/dependency-environments/.staging/<id>/
  package.json
  package-lock.json
  node_modules/

The producer is never given the source or managed-worktree path. Manifest and lockfile bytes are read from the admitted Git baseline object and copied only into this Maka-owned staging project. The new regression test locks this boundary through the public owner path.

The lease counter is process-local by design, but GC is not exposed to multiple legitimate writer processes: ManagedWorkspaceOwner exists under the storage root's OS-level exclusive writer lock. A second Desktop/CLI writer cannot enter dependency provisioning or GC for the same root. The architecture document now states this explicitly and requires a new cross-process lease protocol before any future multi-writer mode.

Artifact reuse and workspace binding are already separate: the content-addressed dependency artifact can be shared, while baselineTreeOid + environmentId lease is combined only inside an owner-token-protected execution scope. No durable workspace binding row is introduced in M1.3; the document now names this distinction explicitly.

I did not add a generic OS sandbox abstraction to this PR. The exact capability is an admission contract, not a claim that a TypeScript type creates an OS sandbox. Production still has one consumer: the fully verified bundled npm runtime, with lifecycle scripts disabled, hermetic config, no secrets, and registry-only lockfile admission. Shell/Build or another producer would require a separate platform-I/O invariant and review.

Verification

• dependency identity/authority/crash tests: 9/9
• bundled npm producer tests: 5/5
• real-Git managed owner suite: 20 passed, 1 existing Windows skip
• storage and runtime-host typechecks: passed
• targeted Biome and git diff --check: passed

中文说明

57aba6bb7 已处理真正存在的 authority 缺口。

已完成修改

• producer contract 收紧为精确的 hermetic_dependency_builder_v1 capability；network、filesystem、secret、child-process 和 lifecycle-script profile 不匹配时，authority 直接拒绝。
• environmentId 与 durable receipt 现在同时绑定 producer policy digest 和 producer runtime digest。
• producer runtime digest 覆盖 bundled npm 完整 runtime tree、Node executable digest、Node version/ABI、平台和架构。
• 每次 provision 都重新验证 npm runtime inventory，并在实际 npm spawn 前紧邻验证 Node executable。
• 新增 producer 执行中进程退出测试：重启后清理 orphan staging，半成品永不发布。
• 新增 public owner 路径回归测试：producer 在 outputRoot 同级写入 sentinel，managed Git worktree 仍保持 clean 且不包含该文件。

不需要按原建议扩张架构的部分

dirname(outputRoot) 不是 managed worktree，而是：

<storage-root>/managed-workspaces/dependency-environments/.staging/<id>/
  package.json
  package-lock.json
  node_modules/

producer 从未拿到 source 或 managed-worktree path。manifest/lockfile 从已准入 Git baseline object 读取，只复制进 Maka-owned staging project。新增测试已经锁定该边界。

lease counter 虽然是进程内状态，但 GC 不会暴露给两个合法 writer：ManagedWorkspaceOwner 位于 storage-root OS 级独占 writer lock 之下。第二个 Desktop/CLI writer 无法进入同一 root 的 provisioning/GC。文档已明确：未来若引入 multi-writer，必须先新增跨进程 lease 协议。

artifact 与 workspace binding 也已分离：content-addressed artifact 可以共享；baselineTreeOid + environmentId lease 只在 owner-token 保护的 execution scope 中临时组合，M1.3 不新增 durable binding 表。

本 PR 没有引入泛化的 OS sandbox 抽象。精确 capability 是 admission contract，不会把 TypeScript 类型冒充操作系统 sandbox。当前生产消费者仍只有经过完整验证的 bundled npm runtime，且禁用 lifecycle scripts、使用 hermetic config、不注入 secret，并只准入官方 registry lockfile。未来 Shell/Build 或新 producer 必须作为新的 platform-I/O 不变量单独审查。

验证

• dependency identity/authority/crash：9/9
• bundled npm producer：5/5
• real-Git managed owner：20 通过，1 个既有 Windows skip
• storage/runtime-host typecheck：通过
• 定向 Biome 与 git diff --check：通过

[Astro-Han]

Thanks for the detailed follow-up and for all the care that has gone into this. I also really appreciate the thoughtful reviews you’ve contributed elsewhere in the repo.

I took another careful pass across the storage authority, npm producer, Runtime Host lifecycle, tests, and release path. A few parts look solid: the environment identity now binds the baseline inputs, runtime, policy, Node ABI, and platform; the receipt is kept outside the producer-owned artifact; and the publish/receipt process-crash convergence is well considered.

I also agree with two clarifications from the earlier discussion: the producer staging directory is not the managed Git worktree, and the storage-root OS writer lock means a separate cross-process lease protocol is not required for the current single-writer model.

I don’t think the current head is ready to merge yet, though. These are the concrete findings I could verify:

Findings

• [P1] GC can race a new acquire. GC checks the lease and pending maps, then asynchronously removes the artifact. A new acquire can register after that check and begin verification—or even obtain a lease—while the removal is already in progress. I think eviction needs an atomic per-digest state such as evicting, with acquire waiting or retrying while that state is active.

• [P1] Normal npm dependencies with bin entries fail on macOS/Linux. npm ci --ignore-scripts still creates node_modules/.bin/* symlinks, while the quota scan currently rejects every symlink. The existing producer fixture writes only regular files, and both real-runtime smoke tests use an empty lockfile, so they do not exercise this path. I’d suggest either allowing only relative symlinks that remain inside the dependency root, matching the final artifact verifier, or explicitly disabling bin links if they are intentionally unsupported. A real non-empty smoke with a package that provides a bin would lock this down.

• [P1] Every managed Read/Glob/Grep re-hashes the complete dependency tree. Each tool operation enters a new managed admission, acquires the environment again, and reads every dependency file to recompute the content hash. For a realistic node_modules, a single Read becomes O(the entire dependency tree), and the same cost repeats for every operation. I think the dependency lease and verification need to live at a wider execution lifecycle rather than at the individual filesystem-operation boundary.

• [P1] The production tool path does not yet consume this environment. The bundled producer is transported into Runtime Host and workspaceExecution is created, but I could not find a real user path that opens the managed baseline, creates the dependency profile, and sends Read/Glob/Grep through workspaceExecution. The built-in tools still receive the existing filesystem worker directly. This also means the release begins carrying the bundled npm payload before the feature has a production consumer.

• [P2] Shared publication inherits the first waiter’s AbortSignal. Later callers cannot cancel independently, while cancellation by the first caller aborts publication for other non-cancelled waiters. The shared build should own its own cancellation state, with each waiter responding independently and the producer cancelled only when no waiters remain.

• [P2] The durable publish path does not fsync the content tree. The code hashes the files and syncs the top-level directory, but the existing file-sync helper is not used for the produced files or nested directories. A power loss can therefore leave a durable receipt pointing to content that was not durably written.

• [P2] Empty dependency environments bypass the cache quota. Cache accounting is contentBytes + contentEntries * 4096, so an empty node_modules artifact costs zero. Distinct empty identities can accumulate directories and SQLite rows without ever becoming eligible for quota eviction. A fixed per-artifact metadata cost or an artifact-count limit would close this.

• [P2] Quota scans can overlap without bound. A new asynchronous full-tree scan starts every 250 ms without checking whether the previous scan is still running. Large installs can therefore accumulate concurrent traversals and amplify I/O. A single self-scheduling monitor would avoid that.

• [P2] The documented stable error contract is not preserved. Missing lockfiles, corrupt artifacts, identity conflicts, busy environments, and most producer failures are currently collapsed into managed_dependency_provision_failed; if they later reach the Host dispatcher, they can be reduced again to internal_failure. It would help to assign each error to its natural owner and preserve the typed code through the real consumer path.

• [P2] The aggregated npm notices do not represent the actual shipped closure. The generated runtime contains roughly 145 unique bundled package@version entries, while the aggregate notices omit about 129 of them. I’m not assuming this is automatically a legal violation because some package-local license files remain in the copied tree, but the aggregate notice and its completeness check are not currently evidence of the actual shipped inventory. Generating notices from the materialized runtime inventory would provide one authority.

• [P2] The Windows release workflow path filter omits several direct supply-chain inputs. Changes limited to the npm preparation/verification scripts, producer implementation, or npm notices can skip the real Windows package check.

Suggested direction

From the final-state perspective, I think the necessary invariant is much smaller than the current implementation:

For an admitted Git baseline, managed tools may read dependencies only from a Maka-owned environment derived from that baseline and a fixed producer policy. The environment remains stable for the execution and never falls back to source node_modules or the system package manager.

The smallest correct implementation I can see would avoid a persistent shared cache initially:

1. Provision one private dependency environment when a real managed execution first needs it.
2. Verify it once and keep one lease for the whole execution.
3. Route Read/Glob/Grep through that execution context.
4. Delete it when the execution ends, with orphan cleanup on restart.
5. Activate the bundled npm release resource only together with the real production consumer.

This removes the receipt database, shared inflight state, LRU GC, cross-task cache reconciliation, and per-operation hashing until product evidence shows that cross-task reuse is necessary.

If persistent reuse is already a firm requirement, I think the cleaner long-term design is to make the dependency environment a first-class immutable Storage artifact with one authoritative absent → building → ready → evicting state machine. Storage would own publication, receipts, verification, leases, and eviction; Runtime Host would acquire one environment as part of a ManagedExecutionContext; and Read/Glob/Grep would only consume that context. The producer would remain a narrow build adapter and would not own artifact identity, caching, or workspace binding.

These are alternatives rather than a request to implement both. Given the current size and the amount of evolution on main, the authority, producer, supply-chain, and production-consumer boundaries might also be useful places to split the work if that makes the rebase and review easier, but I mean that only as a suggestion.

Thanks again for pushing this forward. I’d be happy to take another look at the revision.

中文版本

感谢你详细回应前一轮反馈，也感谢你在这个 PR 上投入了这么多精力。你一直以来也为仓库里的其他 PR 提供了很多细致的审查，我非常感激。

我重新仔细检查了 storage authority、npm producer、Runtime Host 生命周期、测试和发行路径。目前有一些部分已经比较扎实：environment identity 现在绑定了 baseline 输入、runtime、policy、Node ABI 和平台；receipt 位于 producer 所有的 artifact 之外；artifact publish 与 receipt commit 之间的进程崩溃收敛也考虑得比较完整。

我也认同前一轮讨论中的两点澄清：producer staging directory 不是 managed Git worktree；在当前单 writer 模型下，storage-root 已经有操作系统级的独占 writer lock，因此暂时不需要额外的跨进程 lease 协议。

不过，我认为当前 head 还不适合合并。以下是我能够验证的具体问题：

Findings

• [P1] GC 可能与新的 acquire 发生竞态。 GC 检查 lease 和 pending map 后，会异步删除 artifact。新的 acquire 可以在检查完成后登记 pending，并在删除已经开始时验证同一个 artifact，甚至可能刚刚取得 lease。建议为每个 digest 增加原子的状态，例如 evicting；acquire 遇到该状态时等待或重试。

• [P1] macOS/Linux 上带有 bin 的正常 npm 依赖无法完成 provisioning。 即使使用 npm ci --ignore-scripts，npm 仍会创建 node_modules/.bin/* symlink，而当前 quota scan 会拒绝所有 symlink。现有 producer fixture 只写入普通文件，两条真实 runtime smoke 也都使用空 lockfile，因此没有覆盖这条路径。可以让扫描规则与最终 artifact verifier 保持一致，只允许仍位于 dependency root 内的相对 symlink；如果产品明确不支持 bin，也可以显式关闭 bin links。无论选择哪种策略，都建议增加一个带有 bin 的真实非空依赖 smoke。

• [P1] 每次 managed Read/Glob/Grep 都会重新哈希完整依赖树。 每个工具操作都会重新进入 managed admission、再次 acquire environment，并读取每个依赖文件来计算 content hash。对于真实的 node_modules，一次 Read 也会变成 O（整棵依赖树），而且每个操作都会重复这项成本。dependency lease 和验证更适合存在于更长的 execution 生命周期，而不是单次 filesystem operation。

• [P1] 生产工具路径目前没有真正消费这个 environment。 bundled producer 已经被传入 Runtime Host，workspaceExecution 也会被创建，但我没有找到真实用户路径去打开 managed baseline、创建 dependency profile，并让 Read/Glob/Grep 通过 workspaceExecution。built-in tools 仍然直接使用原有 filesystem worker。这也意味着发行版已经开始携带 bundled npm，但对应功能还没有 production consumer。

• [P2] 共享 publication 错误地继承了第一个 waiter 的 AbortSignal。 后续调用者无法独立取消，而第一个调用者取消时会连带中止其他仍然需要该 publication 的请求。共享 build 应该拥有自己的取消状态；每个 waiter 独立响应自己的取消，并且只在所有 waiter 都取消后才终止 producer。

• [P2] durable publish 没有真正 fsync 完整内容树。 当前实现会哈希文件并同步 artifact 顶层目录，但已有的文件同步 helper 没有用于生成的文件和嵌套目录。掉电后可能出现 receipt 已经持久化、内容却没有完整落盘的状态。

• [P2] 空 dependency environment 可以绕过 cache quota。 当前计费方式是 contentBytes + contentEntries * 4096，因此空的 node_modules artifact 成本为零。不同 identity 的空目录和 SQLite row 可以无限积累，而不会触发 quota eviction。可以增加每个 artifact 的固定 metadata 成本，或者同时限制 artifact 数量。

• [P2] quota scan 可能无限重叠。 当前每 250 ms 都会启动一次新的异步全树扫描，却不检查前一次扫描是否完成。大型依赖安装会积累多个并行遍历，放大 I/O。使用单个自调度的 monitor 会更稳妥。

• [P2] 文档中承诺的稳定错误合同没有得到保留。 lockfile 缺失、artifact corruption、identity conflict、busy environment 以及多数 producer failure，目前都会被折叠为 managed_dependency_provision_failed；如果之后进入 Host dispatcher，还可能再次变成 internal_failure。建议让每类错误由其自然 owner 定义，并沿真实 consumer path 保留 typed code。

• [P2] 聚合的 npm notices 没有覆盖实际发货的依赖 closure。 实际生成的 runtime 大约包含 145 个唯一的 package@version，而聚合 notices 大约缺少其中 129 个。我不会仅凭这一点断言存在法律问题，因为复制的 package 目录中可能仍包含各自的 license 文件；但当前聚合 notices 及其完整性检查不能证明实际 shipped inventory 已被覆盖。以物化后的 runtime inventory 为唯一权威来源会更可靠。

• [P2] Windows release workflow 的 path filter 漏掉了一些直接影响供应链的输入。 如果后续只修改 npm preparation/verification scripts、producer implementation 或 npm notices，可能不会触发真实的 Windows package check。

建议方向

从最终状态出发，我认为真正需要满足的不变量比当前实现更小：

对于一个已经准入的 Git baseline，managed tools 只能读取由该 baseline 和固定 producer policy 派生出来、由 Maka 所有的依赖环境。这个环境在一次 execution 中保持稳定，并且永远不能回退到 source node_modules 或系统 package manager。

我能看到的最小正确实现，是初期先不做持久化共享 cache：

1. 当真实 managed execution 第一次需要依赖时，创建一个私有 dependency environment。
2. 只验证一次，并在整个 execution 生命周期中持有同一个 lease。
3. 让 Read/Glob/Grep 全部通过这个 execution context。
4. execution 结束时删除环境，启动时清理 orphan staging。
5. bundled npm 只和真实 production consumer 一起进入发行版。

这样可以先删除 receipt database、共享 inflight state、LRU GC、跨任务 cache reconciliation 和每个工具操作重复哈希等复杂度，等真实产品数据证明跨任务复用确实必要时再增加。

如果跨任务持久化复用已经是明确需求，我认为更干净的长期方案是：把 dependency environment 建模为 Storage 管理的一等不可变 artifact，并由一个明确的 absent → building → ready → evicting 状态机统一管理。Storage 负责 publish、receipt、verification、lease 和 eviction；Runtime Host 在创建 ManagedExecutionContext 时 acquire 一次 environment；Read/Glob/Grep 只消费这个 context。Producer 则保持为一个很窄的 build adapter，不负责 artifact identity、cache 或 workspace binding。

这两个方案是不同选择，并不是建议同时实现。考虑到当前 PR 的规模以及 main 上 Runtime Host 相关路径已经发生了不少变化，架构文档中现有的 authority、producer、supply chain 和 production consumer 边界，也可以作为可选的拆分参考，以降低 rebase 和 review 难度；但这只是建议，并不是我的合并条件。

再次感谢你持续推动这项工作。我也很愿意在 revision 更新后继续审查。

[Astro-Han]

Last comment was reviewing at current head.

[jackwener]

感谢在这个大分支里把 managed dependency 的 identity、producer policy、crash convergence、release supply chain 和 consumer boundary 都系统地探索了一遍。这里积累的设计与 review 结论很有价值。

后续实现已经按 review 建议收敛成 current-main 上的增量 stack，而不是继续维护这个 40-file monolith：#2485 已合入 durable dependency artifact authority；#2620、#2621、#2622、#2623 分别承接 constrained npm producer、bundled runtime attestation、cancellable admission 和 production managed inspection / crash replay。#2620 的描述也明确它是 #2485 合入后的 first incremental slice。

继续保留本 PR 会让同一能力同时存在 monolithic 与 incremental 两套实现 authority，也会让已经迁移的 review 结论重复失效。因此关闭这个已被拆分 stack 取代的 umbrella implementation；后续工作和 review 继续在 #2620–#2623 上进行。

Thank you for the extensive design and implementation work in this branch. The work has since been re-sliced on current main: #2485 is merged, and #2620–#2623 carry the constrained producer, runtime attestation, cancellable admission, and production consumer/recovery path. I am closing this monolithic implementation so the repository has one incremental implementation authority. The useful work and review conclusions continue in that focused stack.