baa-conductor

T-016-worker-persistence.md

 1---
 2task_id: T-016
 3title: Worker 本地持久化
 4status: done
 5branch: feat/T-016-worker-persistence
 6repo: /Users/george/code/baa-conductor
 7base_ref: main@c5e007b
 8depends_on:
 9  - T-005
10  - T-006
11write_scope:
12  - apps/worker-runner/**
13  - packages/checkpointing/**
14  - packages/logging/**
15updated_at: 2026-03-22
16---
17
18# T-016 Worker 本地持久化
19
20## 目标
21
22把 worker-runner 从“内存态结构”推进到“会把 meta/state/log/checkpoint 真正写入本地目录”的程度。
23
24## 统一开工要求
25
26- 必须从当前最新 `origin/main` 切出该分支
27- 新 worktree 进入后先执行 `npx --yes pnpm install`
28- 不允许从其他任务分支切分支
29
30## 本任务包含
31
32- 本地目录创建
33- `meta.json`、`state.json` 写入
34- `worker.log`、`stdout.log`、`stderr.log` 落盘
35- checkpoint 文件真正写入 `checkpoints/`
36
37## 本任务不包含
38
39- 真实 Codex 子进程接入
40- D1 checkpoint 上报
41- failover 恢复全链路
42
43## 建议起始文件
44
45- `apps/worker-runner/src/runner.ts`
46- `apps/worker-runner/src/checkpoints.ts`
47- `packages/checkpointing/src/index.ts`
48- `packages/logging/src/*`
49
50## 交付物
51
52- 本地持久化 runner 骨架
53- checkpoint 文件真正落盘
54
55## 验收
56
57- `npx --yes pnpm --filter @baa-conductor/worker-runner typecheck`
58- `npx --yes pnpm --filter @baa-conductor/checkpointing typecheck`
59- 能明确说明哪些文件会落到本地 runtime 目录
60
61## files_changed
62
63- `apps/worker-runner/src/runner.ts`
64- `packages/checkpointing/src/index.ts`
65- `packages/checkpointing/src/node-shims.ts`
66- `packages/logging/src/index.ts`
67- `packages/logging/src/node-shims.ts`
68- `packages/logging/src/persistence.ts`
69- `coordination/tasks/T-016-worker-persistence.md`
70
71## commands_run
72
73- `npx --yes pnpm install`
74- `npx --yes pnpm --filter @baa-conductor/logging typecheck`
75- `npx --yes pnpm --filter @baa-conductor/checkpointing typecheck`
76- `npx --yes pnpm --filter @baa-conductor/worker-runner typecheck`
77- `npx --yes pnpm exec tsc -p apps/worker-runner/tsconfig.json --outDir <tmp> --module commonjs`
78- `DIST_ROOT=<tmp> RUNTIME_ROOT=<tmp> node <<'EOF' ... EOF`
79
80## result
81
82- `worker-runner` 现在会创建本地 run 目录，并在初始化时写入 `meta.json`、`state.json`、空的 `worker.log` / `stdout.log` / `stderr.log`。
83- 生命周期事件、stdout/stderr chunk、checkpoint 写入后都会同步刷新本地 `state.json`，不再只停留在内存态。
84- `summary` 与 `log_tail` checkpoint 会真实落到 `checkpoints/`，并已通过临时 CommonJS 编译验证生成 `0001-summary.json`、`0002-log-tail.txt`。
85
86## risks
87
88- 真实 Codex 子进程尚未接入，当前只验证了 placeholder/custom executor 路径下的本地持久化。
89- `git_diff`、`test_output` 等更大 checkpoint 负载还没有实际生成端，当前仅补齐了文件写入基础设施。
90
91## next_handoff
92
93- 将真实 worker 执行器接到 `appendStreamChunkPersisted` / `recordLifecycleEventPersisted`，保持 stdout/stderr 与状态文件持续落盘。
94- 在后续 checkpoint 任务里直接复用 `persistCheckpointRecord` 扩展 `git_diff`、`test_output` 的实际产出。
95
96## notes
97
98- `2026-03-21`: 创建第三波任务卡