完成 Editor Agent P2 持久任务与运行时收口

新增 Web Project runtime job、持久日志、lease、取消、expired、stale 和 active preview guard 状态机

接入 api-server Web Project runtime worker 与 TempDirBuildRuntime 构建执行链路

补齐 SpacetimeDB procedure、spacetime-client facade、shared contracts 和前端 web-project client 契约

更新 /editor/agent 的 runtime job 恢复、日志回填、SSE 重连、取消按钮和 active preview 刷新恢复

新增 P2 dev smoke 脚本，并让完整 npm run dev 默认以 all 角色启动 P2 worker

补充 P2 自动化测试、浏览器 smoke 验收记录、开发运维文档和 Hermes 踩坑记忆

.hermes/shared-memory/decision-log.md

@@ -2253,3 +2253,60 @@
 - 决策：P2 不直接跳到长驻 Docker 工作区或 Shell，而是先新增 `web_project_runtime_job`、worker / lease / controller、日志分页和 SSE 重连，再抽象 `SandboxRuntime`。第一版 SandboxRuntime 可继续复用当前 temp-dir runner，Docker / gVisor / Kata / microVM 作为后续执行面实现；snapshot 仍是唯一事实源，sandbox diff 必须转为 `WebProjectPatch` 并经过 api-server 校验后落库。
 - 影响范围：`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`、`docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md`、`docs/technical/【技术方案】EditorAgentMockAgentP1落地计划-2026-06-15.md`、Web Project runtime job 后续实现。
 - 验证方式：P2 落地时需覆盖 runtime job 状态机、worker claim / renew / complete / fail、failed / cancelled / expired / stale 不覆盖 active preview、日志分页 / SSE 重连、真实浏览器 happy path 和破坏构建保留上一版预览。
+
+## 2026-06-17 Editor Agent P2 runtime job API 只能经 spacetime-client facade
+
+- 背景：P2-03 开始把 `web_project_runtime_job` 暴露给 api-server 和前端恢复链路；如果 api-server 直接拼 generated procedure 或下发 worker lease，会让后续 P2-04 / P2-05 的 worker 边界变脆。
+- 决策：Web Project runtime job 的 `create / get / list open / claim / renew / complete / fail / cancel / stale / expire / append log / list logs` 统一封装在 `server-rs/crates/spacetime-client/src/web_project.rs` facade。api-server HTTP 只暴露创建、读取、取消、未终态列表和日志分页；HTTP DTO 不下发 worker `lease_token`。P2-04 起 `POST /api/runtime/web-project/projects/{projectId}/preview-builds` 只创建 preview build 并入队 `web_project_runtime_job(kind=preview_build)`，不再在请求内抢占 preview build slot、启动 runner 或提前推进 `active_preview_build_id`。
+- 影响范围：`server-rs/crates/spacetime-client/src/web_project.rs`、`server-rs/crates/spacetime-client/src/mapper/web_project.rs`、`server-rs/crates/api-server/src/web_project.rs`、`shared-contracts`、`packages/shared`、P2 后续 worker / preview build 迁移。
+- 验证方式：`cargo test -p spacetime-client web_project --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server web_project_runtime_job --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run test -- src/services/web-project --reporter verbose`、`npm run test -- src/components/editor/agent/WebProjectAgentEditorPage.test.tsx --reporter verbose`、`npm run typecheck`、`npm run check:spacetime-schema`。
+- 关联文档：`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-06-17 Editor Agent P2 Runtime Worker 默认不伪造预览成功
+
+- 背景：P2-05 需要先落地 Web Project runtime worker 的 claim / lease / log / complete / fail 骨架，但真实 SandboxRuntime 与 runner 写回将在 P2-06 接入；如果骨架阶段把 preview build 标成 succeeded，会让前端拿到没有 artifact / preview URL 的假成功。
+- 决策：新增 `GENARRATIVE_PROCESS_ROLE=web-project-runtime-worker`，并支持 `GENARRATIVE_PROCESS_ROLE=all` 与 HTTP 同进程并行启动。P2-05 worker 默认 `GENARRATIVE_WEB_PROJECT_RUNTIME_WORKER_DRY_RUN_RESULT=fail`，只验证领取、日志、续租和失败闭环；显式 `success` 只允许无 preview build 绑定的 runtime job 完成。preview build 绑定任务的 dry-run 失败会先通过 runtime job lease fail，再 best-effort 将 linked `web_project_preview_build` 标记 failed 并广播 SSE；该两步不是同一 SpacetimeDB transaction，后续若要强一致需补组合 procedure。
+- 影响范围：`server-rs/crates/api-server/src/web_project_runtime_worker.rs`、`server-rs/crates/api-server/src/main.rs`、`server-rs/crates/api-server/src/config.rs`、`server-rs/crates/api-server/src/web_project.rs`、P2-06 SandboxRuntime 接入。
+- 验证方式：`cargo test -p api-server web_project_runtime_worker --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
+- 关联文档：`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-06-17 Editor Agent P2 TempDirBuildRuntime 先接入 worker
+
+- 背景：P2-06 要把 P1 `web-project-runner` 从请求内后台任务迁到持久 runtime worker，同时为后续 Docker / gVisor / microVM 执行面留出 `SandboxRuntime` 抽象。
+- 决策：在 `api-server` 内新增 `web_project_preview_runtime`，定义第一版 `SandboxRuntime` trait 与 `TempDirBuildRuntime`，当前实现继续以受控子进程调用 `web-project-runner`，不直接开放 Shell，也不把 runner 改成 in-process 构建。worker 对 linked preview build job 追加 hydrate / build / artifact / preview 阶段日志，runner 成功后先 `complete_web_project_runtime_job` 复用 active snapshot stale 校验，再 best-effort 写 `web_project_preview_build=succeeded` 和 preview token / URL；runner 失败只失败当前 runtime job 和 linked preview build，不生成新 preview。
+- 一致性备注：runtime job 与 preview build 仍是两次 SpacetimeDB procedure，worker 在 runner 结束后先做最终续租再写终态，降低 lease 过期造成的部分写回风险；彻底单事务完成、失败和 stale 组合 procedure 或 reconcile 仍归入 P2-07 Active Preview Guard / Stale 收口。
+- 影响范围：`server-rs/crates/api-server/src/web_project_preview_runtime.rs`、`server-rs/crates/api-server/src/web_project_runtime_worker.rs`、`server-rs/crates/api-server/src/web_project.rs`、`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+- 验证方式：`cargo test -p web-project-runner --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server web_project_runtime_worker --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server web_project --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
+- 关联文档：`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-06-17 Editor Agent P2 active preview 推进必须单事务完成
+
+- 背景：P2-06 成功路径先完成 runtime job，再 best-effort 写 preview build succeeded；如果旧 snapshot job 在新 snapshot 成为 active 后才完成，或两次写回中间失败，可能留下 job/build 状态不一致或错误推进 preview 的风险。
+- 决策：P2-07 新增 `complete_web_project_preview_build_runtime_job_and_return` 组合 procedure。runner 成功后，worker 只生成 artifact / preview token / preview URL / logs 的 finish plan，再通过 `spacetime-client` facade 调用该 procedure；SpacetimeDB 在同一 transaction 内校验 worker lease、preview build 绑定和 `job.snapshot_id == web_project.active_snapshot_id`，然后同时写 runtime job、preview build 与 `active_preview_build_id`。若 snapshot 已 stale，即使 runner 成功也只把 runtime job 和 preview build 标为 `stale`，不生成 preview URL、不覆盖 active preview。
+- 影响范围：`server-rs/crates/spacetime-module/src/web_project.rs`、`server-rs/crates/spacetime-client/src/web_project.rs`、`server-rs/crates/spacetime-client/src/mapper/web_project.rs`、`server-rs/crates/api-server/src/web_project_runtime_worker.rs`、`server-rs/crates/api-server/src/web_project_preview_runtime.rs`、前端 stale 展示测试和 P2 文档。
+- 验证方式：`npm run spacetime:generate`、`cargo check -p spacetime-module --target wasm32-unknown-unknown --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-client web_project --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server web_project_runtime_worker --manifest-path server-rs/Cargo.toml`、`npm run test -- src/services/web-project/webProjectSse.test.ts src/components/editor/agent/WebProjectAgentEditorPage.test.tsx --reporter verbose`、`npm run check:spacetime-schema`。
+- 关联文档：`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-06-17 Editor Agent P2 允许原生纯逻辑单测使用 SpacetimeDB ABI 桩
+
+- 背景：`spacetime-module` 的 `runtime_job` 用例只验证 lease token、claimable、terminal status、stale 清理和失败结果结构等纯 Rust helper；但 Windows native `cargo test` 会链接整个 crate，`spacetimedb-bindings-sys` 的 WASM 宿主 ABI 符号（如 `procedure_start_mut_tx`、`datastore_insert_bsatn`、`console_log`）没有原生宿主提供，导致测试体执行前就 `LNK2019` / `LNK1120`。
+- 决策：在 `server-rs/crates/spacetime-module/src/test_stubs.rs` 中用 `#[cfg(all(test, not(target_arch = "wasm32")))]` 提供 25 个 test-only ABI 桩，只满足原生测试链接；`console_log` 静默 no-op，其余桩只用于暴露误调用。该桩不进入 WASM 构建，也不允许把 native 单测误当成 SpacetimeDB runtime 行为测试。
+- 影响范围：`server-rs/crates/spacetime-module/src/lib.rs`、`server-rs/crates/spacetime-module/src/test_stubs.rs`、P2 计划文档和 `.hermes/shared-memory/pitfalls.md`。
+- 验证方式：`cargo test -p spacetime-module runtime_job --manifest-path server-rs/Cargo.toml` 通过 6 个纯逻辑用例；`cargo check -p spacetime-module --target wasm32-unknown-unknown --manifest-path server-rs/Cargo.toml` 通过。
+- 关联文档：`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`、`.hermes/shared-memory/pitfalls.md`。
+
+## 2026-06-17 Editor Agent P2 runtime job 取消优先于 worker 结果
+
+- 背景：P2-08 开始支持用户取消 queued / running Web Project runtime job；如果 worker 已经跑到 runner 末尾，仍可能在用户取消后继续 complete / fail，并生成 preview URL 或把 linked preview build 写成 failed。
+- 决策：取消请求是 runtime job 终态写回的最高优先级。`spacetime-module` 的 `complete_web_project_runtime_job`、`fail_web_project_runtime_job` 和 `complete_web_project_preview_build_runtime_job` 都必须在同一 transaction 内先检查 `cancel_requested_at`，命中后写 `cancelled`、清理 worker lease、禁止生成 artifact preview token / URL、禁止推进 `active_preview_build_id`。Queued cancel 由 HTTP cancel handler 同步把 linked preview build 写成 `cancelled`；running cancel 由 worker heartbeat / 最终续租检测后收敛，当前 TempDir runner 暂不承诺强杀子进程。
+- 影响范围：`server-rs/crates/spacetime-module/src/web_project.rs`、`server-rs/crates/api-server/src/web_project_runtime_worker.rs`、`server-rs/crates/api-server/src/web_project_preview_runtime.rs`、`server-rs/crates/api-server/src/web_project.rs`、`src/services/web-project/webProjectClient.ts`、`src/components/editor/agent/WebProjectAgentEditorPage.tsx`。
+- 验证方式：`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-module runtime_job --manifest-path server-rs/Cargo.toml`、`npm run test -- src/services/web-project src/components/editor/agent --reporter verbose`、`npm run typecheck`。
+- 关联文档：`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`。
+
+## 2026-06-17 Editor Agent P3 先采用远程同容器 Agent MVP
+
+- 背景：P2 完成后，`/editor/agent` 已具备 runtime job、worker / lease、日志恢复、取消 / stale 和 `SandboxRuntime` 抽象；为了加快真实 Agent 和远程 Container 落地，需要在不推翻 P1 / P2 控制面的前提下先跑通 MVP。
+- 决策：P2 后新增长期架构文档，明确真实 Agent、用户工作区、Agent 私有 shell、ShellPolicy / CommandGuard、ToolBridge、LLM Broker 与后续容器拆分边界。P3 采用 Remote Agent Server + Remote Container 执行面。第一版允许真实 Agent 与用户 workspace 位于同一个 Remote Container，Agent 可以使用完整 shell，但用户不开放 shell；所有 shell 命令必须经过 `ShellPolicy` / `CommandGuard` 接口，MVP 可先 `AllowAllShellPolicy`，后续再补正式 allowlist / denylist / 审批规则。Agent 调 LLM 通过 `LLM Broker`，Container 不持有长期 provider key。Container 内修改只能收集 diff 转 `WebProjectPatch`，由 api-server 校验后保存 snapshot；前端不直连 Container，preview 继续走 Preview Gateway + iframe sandbox。
+- 影响范围：`/editor/agent` P3 计划、Remote Agent Server、runtime job kind、ShellPolicy / ToolBridge / SandboxRuntime 抽象、LLM Broker、后续 Agent / Workspace 双容器拆分。
+- 验证方式：P3 MVP 必须覆盖真实 Agent 处理用户需求、Remote Container hydrate snapshot、Agent shell 经 ShellPolicy 审计、patch 校验落 snapshot、自动触发 preview build、刷新恢复 agent job / 日志 / active preview、失败不覆盖上一版 preview。
+- 关联文档：`docs/technical/【技术方案】EditorAgent远程Agent与工作区沙箱架构-2026-06-17.md`、`docs/planning/【开发计划】EditorAgentP3远程AgentContainerMVP计划-2026-06-17.md`、`docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md`。

.hermes/shared-memory/pitfalls.md

@@ -1324,13 +1324,13 @@
 - 验证：查看 `server-rs/Cargo.toml` default-members，并按相关 SpacetimeDB 文档执行模块构建。
 - 关联：`server-rs/Cargo.toml`、`docs/technical/RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md`。
 
-## Windows 原生 `spacetime-module` 单测会链接缺失 SpacetimeDB 宿主符号
+## Windows 原生 `spacetime-module` 纯逻辑单测需要 test-only ABI 桩
 
-- 现象：在 Windows 上执行 `cargo test -p spacetime-module --manifest-path server-rs/Cargo.toml` 可能编译到链接阶段后失败，出现 `LNK2019` / `LNK1120`，缺失 `datastore_insert_bsatn`、`procedure_start_mut_tx`、`console_log` 等 SpacetimeDB 宿主符号。
-- 原因：`spacetime-module` 依赖的 SpacetimeDB runtime API 面向 wasm 宿主环境，原生 test exe 链接不到这些宿主导出。
-- 处理：日常语法和类型验证使用 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`；需要验证模块行为时走 SpacetimeDB publish/dev 或模块域纯 Rust crate 的单测，不把该原生链接错误当作业务测试失败。
-- 验证：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 能通过；原生 `cargo test` 若仍报上述宿主符号缺失，按当前限制记录为未执行。
-- 关联：`server-rs/crates/spacetime-module`、`docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`。
+- 现象：Windows native target 执行 `cargo test -p spacetime-module runtime_job --manifest-path server-rs/Cargo.toml` 曾在链接阶段失败，报 `LNK2019` / `LNK1120`，缺失 `datastore_insert_bsatn`、`procedure_start_mut_tx`、`console_log` 等 SpacetimeDB 宿主符号；这些 runtime job 用例本身只测纯 Rust helper，并不调用 SpacetimeDB 表或 procedure 宿主 ABI。
+- 原因：`spacetime-module` 的正常发布目标是 SpacetimeDB WASM module，`spacetimedb-bindings-sys` 声明的宿主 ABI 由 SpacetimeDB WASM 运行时注入；Windows native `cargo test` 会把整个 crate 链成原生测试 exe，即使测试体不触碰宿主 ABI，链接器也需要这些符号。
+- 处理：`server-rs/crates/spacetime-module/src/test_stubs.rs` 在 `#[cfg(all(test, not(target_arch = "wasm32")))]` 下为本次缺失的 25 个 ABI 符号提供桩实现，`console_log` 静默 no-op，其余桩用于暴露误调用。该方案只允许跑不访问 `ctx.db`、表扫描 / 写入、procedure transaction、JWT、identity、bytes source/sink 等宿主能力的纯逻辑单测；真实 SpacetimeDB 行为仍必须走 wasm target check、bindings 生成、schema guard、publish/dev 或端到端 smoke。
+- 验证：`cargo test -p spacetime-module runtime_job --manifest-path server-rs/Cargo.toml` 通过 6 个纯逻辑用例；`cargo check -p spacetime-module --target wasm32-unknown-unknown --manifest-path server-rs/Cargo.toml` 通过，确认 test-only 桩不影响 WASM module 构建。
+- 关联：`server-rs/crates/spacetime-module/src/test_stubs.rs`、`server-rs/crates/spacetime-module/src/lib.rs`、`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`。
 
 ## Rust 构建不要让不可用的 sccache 阻断 rustc
 
@@ -2262,3 +2262,11 @@
 - 处理：preview gateway 服务 artifact 的成功响应统一带 `Access-Control-Allow-Origin: *`，但仍保留独立 origin、`sandbox="allow-scripts"` 和 CSP `connect-src 'none'`，不要为了修加载问题放宽 iframe sandbox。
 - 验证：`cargo test -p api-server web_project --manifest-path server-rs/Cargo.toml`，并用浏览器 smoke 确认 iframe 中计数按钮从 `已点击 0 次` 变为 `已点击 1 次`。
 - 关联：`server-rs/crates/api-server/src/web_project_preview_gateway.rs`、`docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md`。
+
+## Editor Agent P2 smoke 不能从裸 dev:api-server 开始
+
+- 现象：运行 `npm run dev:api-server` 后，api-server 在启动阶段请求 SpacetimeDB `/v1/identity` 失败；或者完整 dev ready 后提交 Web 工程构建一直 queued；或者单独启动 `GENARRATIVE_PROCESS_ROLE=web-project-runtime-worker` 时订阅 / procedure 调用 401。
+- 原因：`dev:api-server` 只启动 Rust API 进程，不会自动启动 standalone，也不会发布当前 `spacetime-module` 或引导 Web Project service identity；P2 runtime job 还必须有 `web-project-runtime-worker` 消费。完整 `dev` 会先启动 SpacetimeDB 并 publish module，Windows native 冷编译 / 首次 publish 可能超过 5 分钟；收口后完整 `npm run dev` 会为 api-server 注入 `GENARRATIVE_PROCESS_ROLE=all`。拆分终端手动 worker 若没有复用本轮 dev 脚本创建的 `GENARRATIVE_SPACETIME_TOKEN`，会以错误 identity 连接并 401。
+- 处理：`/editor/agent` P2 端到端 smoke 优先运行 `npm run dev -- --no-interactive --api-timeout-seconds 900`，等待完整栈 ready 后再执行 `npm run check:editor-agent-p2-smoke` 和真实浏览器步骤。若拆分终端，必须先 `npm run dev:spacetime` 等待发布完成，再启动 `npm run dev:api-server` 和 `npm run dev:web`；手动 worker 必须显式带同一个 `GENARRATIVE_SPACETIME_SERVER_URL`、`GENARRATIVE_SPACETIME_DATABASE` 和 `GENARRATIVE_SPACETIME_TOKEN`。
+- 验证：`.app/dev-stack.json` 里的 `spacetime`、`api-server`、`web` 和 `web-project-preview` URL 与实际 HTTP 探测一致；`npm run check:editor-agent-p2-smoke` 通过后，再在浏览器完成计数按钮、破坏构建、连续提交、取消和刷新恢复 smoke。浏览器自动化无法进入 `sandbox="allow-scripts"` 的 preview iframe 时，直接打开后端签发的 preview URL 验证交互。
+- 关联：`scripts/dev.mjs`、`scripts/check-editor-agent-p2-smoke.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/planning/【开发计划】EditorAgentP2持久任务与SandboxRuntime计划-2026-06-16.md`。