服务：提供本地 Fastify REST API 基线

[ZZDR1023]

背景

README 和两周计划描述了本地 Web UI / Fastify adapter，但仓库目前没有 src/server/main.ts，npm start 指向不存在的构建产物。后续 UI 需要一个薄、可测试且不绕过 Orchestrator 所有权的 REST 接口。

目标

提供本地单用户 Fastify API，用现有 Orchestrator 作为唯一业务入口，支持健康检查、创建运行、列出/查看运行、导出归档；长运行以异步 job 方式启动，不阻塞 HTTP 连接。

范围

• 仅新增/修改 src/server/**、tests/server-*.test.ts；如脚本与真实入口不一致，可最小修改 package.json，但不得新增依赖（Fastify 已存在）。不改 Orchestrator、RunStore、CLI、input 或 benchmark 文件。
• 导出可注入的 buildServer()，测试不得真实监听端口；src/server/main.ts 仅负责配置和启动。
• API 至少包括：GET /health、GET /api/runs、GET /api/runs/:id、POST /api/runs、GET /api/runs/:id/archive。
• POST /api/runs 严格校验 package path、runtime/execution 枚举和可选 provider/model/thinking；默认本地 fake/local；立即返回 202 与 job id，后台执行，并可查询 job 状态。
• 不返回原始 stack、凭据或任意宿主文件；错误 envelope 稳定且状态码正确；archive 仅允许已完成 run 的已验证 project.zip。
• 默认监听 127.0.0.1，不提供认证前不得绑定 0.0.0.0；CORS 默认关闭。
• 优雅关闭 server 和 Orchestrator/SQLite 资源；如 Orchestrator 缺少公开 close，只能在 server adapter 内使用明确生命周期边界，不得修改核心模块。

TDD / 验收

先写 Fastify inject Red tests，覆盖健康、schema 拒绝、404、202 job、失败 job、列表/详情、archive gating、无 stack 泄漏。实现后：

npm run check
npm run build

并启动编译后的 server，curl /health 后优雅关闭。不得在测试中调用真实 Pi、Docker 或网络。

非目标

• React UI、SSE/WebSocket、认证、多用户、远程部署；
• 修改 Orchestrator、输入提取或 Benchmark harness。

[ZZDR1023]

开始实施。

• Orca Run：run_48945588edab
• 计划 worktree：issue-5-fastify-api（从默认 main 独立创建）
• 唯一写入者：Pi worker
• 文件边界：仅 src/server/**、tests/server-*.test.ts；现有 package scripts 已指向正确入口，因此禁止修改 package/lock、Orchestrator、RunStore、CLI、input、benchmark
• 实现计划：可注入 buildServer() → 严格请求 Schema → 内存 job registry → Orchestrator adapter → archive gating → 安全错误 envelope/优雅关闭
• Red 测试：health、schema 400、404、202 job、失败 job、list/show、未完成 archive 拒绝、无 stack/host file 泄漏、默认 bind 127.0.0.1
• PR 目标：main，正文仅 Refs #5
• CI 验收：npm run check、npm run build；Fastify inject 全绿；编译后 server 启动、curl /health、优雅停止
• 人工验收：本机启动后调用 health/list/create/job/show/archive，确认不需要真实 Pi/Docker
• 非目标：React、SSE、认证、多用户、远程部署

[ZZDR1023]

Orca 派发已建立：Task task_fa5884ead316，Dispatch ctx_a21925d9fbcd，worktree /home/zzdr1023/orca/workspaces/modeling-agent/issue-5-fastify-api。从 origin/main 独立创建，当前正在 Red 阶段；worker 完成后将推送独立分支并创建目标为 main 的 PR。

[ZZDR1023]

CI/主控复核：退回回归修复。

已核对 PR #6、commit db40fe7b27848d0ab0feb02cf93e8d42e7fdb818 与 Dispatch ctx_a21925d9fbcd 一致；PR 只改允许的 5 个 server/test 文件，目标 main，CI verify 通过。主控在由该远端提交导出的独立副本中复跑：9 个 Vitest 文件 / 43 tests、7 个 Python tests、build 和 git diff --check 均通过。

但对抗性验收发现 archive 路径可通过 symlink 逃逸：

1. 创建 workspace 外的 ZIP-signature 文件，内容含 OUTSIDE-HOST-SECRET；
2. 在 workspace 内创建 project.zip -> <workspace 外文件> symlink；
3. GET /api/runs/run-symlink/archive 返回 200 application/zip，响应体等于外部文件。

根因：当前只对词法 resolve/relative 做边界检查，随后 stat/createReadStream 会跟随 symlink。该行为违反“archive 不得成为任意宿主文件读取入口”。

必须补的 Red 测试与修复：

• 最终 project.zip 为 symlink 时返回安全的 410 archive_gone，不得流出字节；
• archive 路径中任一中间目录为指向 workspace 外的 symlink 时同样拒绝；
• canonical workspace/archive 边界校验，且只接受常规文件；
• 在可行范围内避免 check-then-open 竞态（从已安全打开的文件句柄流式传输，而不是校验后按原路径重新打开）；
• 保持正常 archive、404/409/410、Content-Length、优雅关闭测试全绿。

旧 Dispatch 已完成，将按规范创建新的回归 Task/Dispatch，更新同一个 PR #6；主控不直接修改该分支。

[ZZDR1023]

回归派发已建立：Task task_73d36a31b6f3，Dispatch ctx_9e1b570a8d15，复用 PR #6 的原 worktree。旧 Dispatch ctx_a21925d9fbcd 已 completed/capability revoked；当前只有新的 Pi worker 拥有写入权。先补 archive 最终 symlink 与中间目录 symlink 的 Red 测试，再修复并更新同一个 PR #6。

[ZZDR1023]

Green / PR / CI / 主控复核：代码与自动化验证通过，待人验收。

• 原始实现：db40fe7b27848d0ab0feb02cf93e8d42e7fdb818
• 安全回归：c8e7f34feb2d5daf564e7c78c12046a74750b8f4
• PR： #6 ，目标 main，未合并
• Orca：原 Task task_fa5884ead316 / Dispatch ctx_a21925d9fbcd；回归 Task task_73d36a31b6f3 / Dispatch ctx_9e1b570a8d15
• Red：主控在 db40fe7 上构造 workspace 内 project.zip symlink 指向 workspace 外 ZIP，endpoint 返回 200 并流出 OUTSIDE-HOST-SECRET；回归测试已覆盖最终 symlink 与中间目录 symlink
• Green：修复使用 lexical + canonical workspace 检查、Linux O_NOFOLLOW、regular-file/ZIP signature 校验，并从同一已验证 FileHandle 流式返回
• 独立复测：9 个 Vitest 文件 / 45 tests；7 个 Python tests；npm run build；git diff --check，全部通过
• 黑盒复测：正常 ZIP 200 且字节/Content-Length 一致；最终 symlink 410 且无泄漏；中间目录 symlink 410 且无泄漏
• 服务复测：编译后的 server 在 127.0.0.1 启动，GET /health 返回 {"status":"ok"}，SIGTERM 正常退出码 0
• CI：run 31632633864，verify success，head c8e7f34

人工验收入口与前提

真实入口：本机 Linux，PR #6 worktree：

cd /home/zzdr1023/orca/workspaces/modeling-agent/issue-5-fastify-api
npm ci
npm run build
RUNS_ROOT="$(mktemp -d)"
MODELING_AGENT_HOST=127.0.0.1 \
MODELING_AGENT_PORT=44317 \
MODELING_AGENT_RUNS_ROOT="$RUNS_ROOT" \
npm start

前提：Node.js 24、Python 3.11、本地端口 44317 可用；默认 fake/local 路径不需要 Pi、Docker、网络或账号。API 无认证，因此只能在 loopback 验收。

人工验收步骤与预期

另开终端执行：

1. 健康检查：

   curl -sS http://127.0.0.1:44317/health

   预期：{"status":"ok"}。

2. 空运行列表：

   curl -sS http://127.0.0.1:44317/api/runs

   预期：稳定 JSON envelope；新 RUNS_ROOT 下 runs 为空数组。

3. 创建真实 fake/local run：

   curl -sS -X POST http://127.0.0.1:44317/api/runs \
     -H 'content-type: application/json' \
     --data '{"packagePath":"/home/zzdr1023/orca/workspaces/modeling-agent/issue-5-fastify-api/tests/fixtures/basic","runtime":"fake","execution":"local"}'

   预期：HTTP 202，返回 job.id；响应不回显 package 绝对路径。

4. 用返回的 job id 轮询：

   curl -sS http://127.0.0.1:44317/api/jobs/<job-id>

   预期：queued/running 最终变为 succeeded，并出现 runId；失败时为去敏后的固定错误 envelope，不含 stack、token、SQLite 或宿主路径。

5. 查询 run：

   curl -sS http://127.0.0.1:44317/api/runs/<run-id>

   预期：run 为 completed 或 completed_with_warnings、archiveAvailable=true；响应中不含 package_path、workspace_path、project_archive 或 event payload 私密内容。

6. 下载并验证归档：

   curl -fSLo /tmp/modeling-agent-api-project.zip \
     http://127.0.0.1:44317/api/runs/<run-id>/archive
   unzip -t /tmp/modeling-agent-api-project.zip

   预期：HTTP 200 application/zip，ZIP 完整可读。

7. 按 Ctrl-C 停止。预期进程优雅退出。另验证非 loopback 拒绝：

   MODELING_AGENT_HOST=0.0.0.0 MODELING_AGENT_PORT=44318 npm start

   预期：启动失败并明确拒绝 unauthenticated non-loopback host，不能监听端口。

成功判定、失败回报与清理

全部七步符合预期即人工验收通过。失败时请回报：步骤、HTTP 状态、去敏响应、Node/Python 版本和 PR head；不要粘贴凭据或私有题包路径。清理：停止 server，执行 rm -rf "$RUNS_ROOT" /tmp/modeling-agent-api-project.zip。

已知风险：archive hardening 依赖 Linux O_NOFOLLOW 与 /proc/self/fd；Node 当前没有 openat2(RESOLVE_BENEATH)，因此仍记录极窄的中间路径并发 rename race。已打开 archive 由同一 descriptor 固定，最终 symlink 与已解析到 workspace 外的路径会拒绝。非 Linux 可移植性不在本 Alpha PR 范围内。

[ZZDR1023]

人验收：失败，已退回回归修复。

主控按此前的真实 loopback fake/local 流程启动 PR #6 head c8e7f34feb2d5daf564e7c78c12046a74750b8f4 的编译 server：GET /health、空 GET /api/runs、POST /api/runs 均正常，但创建 job 后立即变为 failed，没有 runId；RunStore 中残留 queued/import run 且无 events。

精确根因已独立复现：编译产物执行 new FakeRuntimeAdapter() 时，其默认 SchemaRegistry 解析到不存在的 dist/schemas/problem-spec.v1.json，抛出 ENOENT。src/server/main.ts 为 Orchestrator 显式提供了 source schemas/，但 runtime 内部又构造了未注入的默认 registry；异常发生在 Orchestrator 的主 try 前，因此真实 API workflow 无法完成。npm run smoke（tsx source path）仍能通过，故原自动化未覆盖 compiled server 的 create/job/archive 全链路。

退回要求：

1. 以 Red 测试覆盖 node dist/src/server/main.js 在新临时 MODELING_AGENT_RUNS_ROOT 下的真实 POST /api/runs fake/local workflow，必须由 queued/running 到 succeeded，返回安全 runId，show 为 completed，archive 可下载并 unzip -t；不得仅 mock Orchestrator。
2. 修复 compiled source/production schema resolution 或 SchemaRegistry/FakeRuntime dependency injection，使 fake runtime 与 Orchestrator 使用同一有效版本化 Schema，不依赖不存在的 dist/schemas，且不破坏 source tsx、Pi runtime、CLI 或 replaceable runtime boundary。
3. 保持 loopback-only、CORS off、去敏 API response、archive descriptor safety、SIGTERM graceful shutdown 与 0.0.0.0 rejection。
4. 补充分支/compiled entry tests，完整 npm run check、npm run build、真实 loopback fake/local black-box、npm audit、git diff --check 后更新同一 PR feat: add local Fastify API baseline #6；不要合并或关闭 Issue。

证据：原 PR CI 31632633864 仍是 green，但不足以证明真实 compiled workflow。会创建新的 Task/Dispatch；当前 PR/Issue 保持开放。

[ZZDR1023]

Terra recovery attempt task_394d211d20ac / ctx_87c8109079ca 因模型端连续 HTTP 502 被主控 fence，未收到 worker_done；终端已停止，保留的候选修改仍在 PR #6 worktree，未提交/未推送。将创建新的 recovery Task/Dispatch，并使用备用 Terra provider 继续，PR 与 Issue 保持开放。

[ZZDR1023]

CI/主控复核：回归修复后代码与自动化验证通过，待人验收。

• authoritative completion：备用 Terra recovery Task task_db0269e47fba / Dispatch ctx_b8b4d6a45047，worker_done 与 PR #6 head 67edb6f2a0b21b1e721fbf11ae433edb5794654b 一致，capability 已撤销。先前 task_394d211d20ac / ctx_87c8109079ca 因模型 HTTP 502 被 fence，未作为交付依据。
• 修复：build 现在复制 versioned schemas 与 standalone Python runtime assets 至 dist/；server/Orchestrator 与 fake/Pi runtime 使用同一有效 SchemaRegistry。此前 compiled POST /api/runs 留下 queued/import run 的缺陷已被真实 HTTP regression 覆盖。
• 边界：PR 目标 main、正文仅 Refs #5；git diff --check 和允许文件范围检查通过。
• CI：verify 31724148547 成功。
• 主控独立复跑：干净 archive + lockfile 下 npm run check 通过（9 Vitest files / 48 tests、7 Python tests）；npm run build、npm run smoke、npm audit --audit-level=high 均通过，确认 7 个 schema 与 Python runtime assets 在 dist/。
• 主控真实编译黑盒：直接运行 node dist/src/server/main.js，fresh MODELING_AGENT_RUNS_ROOT 下 /health、空 list、POST /api/runs fake/local、job running -> succeeded、safe runId、show completed/archiveAvailable、archive download + unzip -t 全部通过；CORS 未开启，0.0.0.0 启动拒绝，SIGTERM exit 0。
• 对抗复测：完成真实 run 后，正常 archive 先成功；将最终 project.zip 或中间 link/ 替换为 workspace 外 ZIP symlink，endpoint 均返回去敏 410 archive_gone，外部 sentinel bytes 未流出。

待验收入口：PR #6 head 67edb6f2a0b21b1e721fbf11ae433edb5794654b。

人工验收步骤：

1. 在隔离 checkout 执行 npm ci && npm run build；准备新临时根：RUNS_ROOT="$(mktemp -d)"。
2. 启动：MODELING_AGENT_HOST=127.0.0.1 MODELING_AGENT_PORT=44317 MODELING_AGENT_RUNS_ROOT="$RUNS_ROOT" node dist/src/server/main.js。仅用 loopback，不要暴露端口。
3. 新终端执行 curl -sS http://127.0.0.1:44317/health，应为 {"status":"ok"}；再 GET /api/runs，应为 {status:"ok",runs:[]}。
4. POST { "packagePath": "<checkout>/tests/fixtures/basic", "runtime": "fake", "execution": "local" } 至 /api/runs。预期 HTTP 202、job id、无绝对 package path 回显。轮询 /api/jobs/<id>，预期经过 running 后 succeeded 并有 runId。
5. GET /api/runs/<runId>；预期 completed 或 completed_with_warnings、archiveAvailable:true，无 package_path、workspace_path、project_archive、stack、token、SQLite 路径或 event payload 私密内容。
6. 下载 /api/runs/<runId>/archive 到 /tmp/modeling-agent-api-project.zip，应为 HTTP 200 application/zip，unzip -t 成功。
7. Ctrl-C/SIGTERM 停止；预期 exit 0。另运行 MODELING_AGENT_HOST=0.0.0.0 MODELING_AGENT_PORT=44318 node dist/src/server/main.js，应失败且不监听。

成功判定：全部七步成功、API 始终 loopback-only、archive 为可读 ZIP 且无路径/secret 泄漏。失败回报请贴步骤、HTTP status、去敏 response、Node/Python 版本和 PR head；勿贴私有题包、cookie、token 或绝对私有路径。清理：停止 server，rm -rf "$RUNS_ROOT" /tmp/modeling-agent-api-project.zip。

残余风险：Linux archive hardening 依赖 /proc/self/fd 与 O_NOFOLLOW；Node 尚无 openat2(RESOLVE_BENEATH)，仍有已记录的极窄 intermediate rename race。