feat(graph-run): planning/reflection 轨迹落进 timeline.ndjson（42 号文档 Phase 4）

org-coder 等 9 个角色（含 _base 骨架模板）的四段式阶段流转靠调 bin/lemon.js task transition，打到 agent-chat.js 的 /task/transition—— 这个端点靠自己的 sessions Map 找会话，work graph 节点场景下找不到，阶段流转静默跳过，中间产物不进任何跨节点共享的轨迹。调研确认范围后选了最保守的实现：不改 bin/lemon.js 的 CLI 签名、不碰 agent-chat.js（当天正被另一个并行会话实时编辑，风险太高）。关键发现是 --artifact 参数本来就是 .../runs/{rootRunId}/nodes/{nodeRunId}/... 形状的路径，两个 ID 已经现成编码在里面，不需要给子进程塞新环境变量，不需要改一个字的 agent.md 提示词。 bin/lemon.js 在原有调用之外 best-effort 追加一次 POST /api/graph-runs/phase-note，新端点从 artifact 路径解出两个 ID，校验 run 真实存在后调 emitEvent() 追加 timeline 记录，只追加不碰 graph_run_nodes/graph_runs 任何一行——不影响 needs/produces 契约。 P0 拦截/OKR 更新两段旧逻辑维持原样，新端点是独立的第二条路径，不是迁移。新增测试 4 例，全量测试 1503/1506，零回归（剩余失败全部来自另一个并行会话进行中、还未提交的工作）。42 号文档 Phase 1-4 全部完工。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwG4b7Nq1NLR9eeE3M9Us9

feat(graph-run): planning/reflection 轨迹落进 timeline.ndjson（42 号文档 Phase 4）
org-coder 等 9 个角色（含 _base 骨架模板）的四段式阶段流转靠调 bin/lemon.js task transition，打到 agent-chat.js 的 /task/transition—— 这个端点靠自己的 sessions Map 找会话，work graph 节点场景下找不到，阶段流转静默跳过，中间产物不进任何跨节点共享的轨迹。调研确认范围后选了最保守的实现：不改 bin/lemon.js 的 CLI 签名、不碰 agent-chat.js（当天正被另一个并行会话实时编辑，风险太高）。关键发现是 --artifact 参数本来就是 .../runs/{rootRunId}/nodes/{nodeRunId}/... 形状的路径，两个 ID 已经现成编码在里面，不需要给子进程塞新环境变量，不需要改一个字的 agent.md 提示词。 bin/lemon.js 在原有调用之外 best-effort 追加一次 POST /api/graph-runs/phase-note，新端点从 artifact 路径解出两个 ID，校验 run 真实存在后调 emitEvent() 追加 timeline 记录，只追加不碰 graph_run_nodes/graph_runs 任何一行——不影响 needs/produces 契约。 P0 拦截/OKR 更新两段旧逻辑维持原样，新端点是独立的第二条路径，不是迁移。新增测试 4 例，全量测试 1503/1506，零回归（剩余失败全部来自另一个并行会话进行中、还未提交的工作）。42 号文档 Phase 1-4 全部完工。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwG4b7Nq1NLR9eeE3M9Us9
yibo
1 parent 0cb55d96
Showing 4 changed files with 223 additions and 2 deletions
bin/lemon.js
docs/todo/system-design/42-org-work-graph-reliability-followups.md
server/routes/graph-run.js
server/tests/unit/graph-run-phase-note.test.js
@@ -184,6 +184,16 @@ async function run() {
         phase: values.phase, artifact: values.artifact
       });
       console.log(JSON.stringify(res.data, null, 2));
+
+      // 42 号文档 Phase 4：额外打一次 graph-runs 的 phase-note 端点，把这次阶段流转
+      // 落进 timeline.ndjson（大多数调用方——legacy 会话式 agent——这个端点会安静
+      // no-op，因为 --artifact 不是 work graph 节点产物目录的形状；不影响上面那次
+      // 调用的结果，出错也不影响本命令的退出码）。
+      try {
+        await request('POST', '/graph-runs/phase-note', {
+          artifact: values.artifact, phase: values.phase, agentId: values.agentId
+        });
+      } catch { /* best-effort，静默丢弃 */ }
     }
     else if (command === 'pipeline create') {
       const { values } = parseArgs({ args: args.slice(2), options: {
 # 42. Org/Work Graph 扳撠  39 ﹝
-> ****嚗hase 1-3  撌脣嚗2026-08-30嚗hase 3 垢蝻箔甈∠撉砲秩hase 4  敺撌乓
+> ****嚗hase 1-4   撌脣嚗2026-08-30嚗hase 3 垢蝻箔甈∠撉砲秩雿歇蝻箏
 > ****嚗2026-08-30
 > ****嚗39-boss-agent-task-supervision.md](./39-boss-agent-task-supervision.md)  P1-P5 摰甈∠垢蝡舀遣  銝 goal  `ceo`   銝銝芸揪虜laywright 5/5 撉**1469 銝芸蝏選活瘚撠 3 銝芸瘝∟憸**遢﹝甈∪銝撌仿◇摨葵 phase
 > **霂餉◆**嚗葵 phase 膩甈∠嚗瘚雿辣/銵靘摰
@@ -93,7 +93,20 @@ Phase 4嚗imeline.ndjson  planning/reflection 頧刻蕨  蝏扳
 ---
-## 鈭hase 4嚗timeline.ndjson`  planning/reflection 頧刻蕨
+## 鈭hase 4嚗timeline.ndjson`  planning/reflection 頧刻蕨   撌脣嚗2026-08-30嚗
+
+**靚捏嚗挽霈∟銝甇伐**嚗grep` 隞 `system/agents/*/agent.md`嚗 `task transition`  9 銝芰嚗_base`code-planner`coder`org-coder`org-planner`org-writer`pricing-api-integrator`unit-tester`workgraph-planning`嚗葵 `zz-*` 瘚允銝**`_base` **撱 agent 憭爸璅⊥嚗餈恣葵閫靘銝"憭畾菜蓮"餈蝐餉蝥血遙雿誧 `_base` 閫
+
+**嚗摰銝芸撘**嚗AgentManager.callAgent()`  `metadata`嚗 `taskId`/`nodeRunId`/`rootRunId`嚗**餈蝡舀敹 hook嚗gent 霂颱**嚗誨釣 agent 蝘漣敶撠曹誑 `data/companies/{cid}/runs/{rootRunId}/nodes/{nodeRunId}/` 餈葵敶Ｙ內霂describeArtifactContract`嚗 `--artifact` 撠望餈葵敶辣頝臬**銝支葵 ID 撌脩蝻靚銝銝隡銝芸**嚗閬 `AgentManager`/摮遙雿憓閬銝銝芸 agent.md 內霂
+
+**摰**嚗挽霈⊿"銝斤"撖孵**銝 `bin/lemon.js`  CLI 蝑曉１ `agent-chat.js`**餈靽楝嚗
+- `bin/lemon.js`  `task transition` 隞支笆 `/agent/:agentId/task/transition`嚗egacy嚗摰銝 best-effort 甈⊥蝡舐 `POST /api/graph-runs/phase-note`嚗ody 隡 `artifact`/`phase`/`agentId`嚗仃韐仿蔣隞斗頨怎/
+- 蝡舐隞 `artifact` 頝臬迤圾 `rootRunId`/`nodeRunId`嚗撉 `rootRunId` 撖孵 run嚗撠望 legacy 隡楝敺耦嚗 `not-a-graph-artifact`嚗秤嚗撉 `graph-run-sse.emitEvent()` 餈賢 `kind:'agent.phase'`  timeline 霈啣ref`  `nodeRunId`
+- **`agent-chat.js` 摰瘝⊥**活撘鈭敶予餈葵辣甇◤銝銝芸僎銵蝻git status` 蝷箸漱靽格嚗蝣唬銝芣迤鋡怠鈭箸鈭急辣憌憭芷餈活 Phase 1-3 撌脩 `graph-run.js`嚗漣漱
+- **"銝"颲寧＆霈斗**嚗蝡舐靚 `emitEvent`嚗滲餈賢 timeline嚗apply` 隡 `null`嚗１ `graph_run_nodes`/`graph_runs` 隞颱銵閮鈭嚗靚
+- **霈曇恣 open 洵銝葵憸0 /OKR 停甇文**嚗"摰銝"舅畾菟餉 legacy `/task/transition` 銵銝sessions` Map 銝隡撠曹瓷閫血活銋瓷悟摰賑閫血蝡舐摰蝡洵鈭頝臬撖寞蝡舐宏
+
+**瘚**嚗server/tests/unit/graph-run-phase-note.test.js`嚗4 靘鈭抒頝臬 timeline 銝蔣楝敺耦銝笆摰歲餈楝敺耦撖嫣 run 銝摰歲餈瓷隡 artifact  `no-artifact`嚗 1503/1506嚗雿 3 銝芸仃韐亙銝銝芸僎銵迤餈葉瓷漱極雿
 **嚗葵 phase 憭抒銝迎**嚗org-coder` 挾撘ESEARCHLANXECUTEERIFY嚗蓮 `bin/lemon.js task transition`嚗 `agent-chat.js`  `/task/transition` 蝡舐葵蝡舐撌梁 `sessions` Map "敶暑頝"嚗 `org-coder` 雿蛹 work graph 頝粥 `graph-engine.js`  `AgentManager`  `session-pool.js`嚗 CLAUDE.md 撠梯扇敶"銝支葵鈭撟脩"銝芸銝芸拿org-coder`  work graph 瘚蓮誘嚗sessions.entries()` 銝摰畾菜蓮餉0 摰⊥KR 摮嚗**歲餈**嚗葉鈭抒嚗_research.md`/`_plan.md`/`_lessons.md`嚗 `graph_files` 憟漲嚗葵"銝"嚗**銝遙雿楊/頝刻鈭怎膘餈**嚗犖蝐餅 `ceo` 鈭"餈甇亙"嚗霂餃 agent 隡 transcript嚗GET /:id/nodes/:nodeRunId/transcript`嚗瓷
@@ -411,6 +411,47 @@ router.post(&#39;/:id/nodes/:nodeId/force-fail&#39;, h((req, res) =&gt; {
 }));
 /**
+ * POST /api/graph-runs/phase-note — 42 号文档 Phase 4：planning/reflection 轨迹落进 timeline。
+ * body: { artifact: string, phase?: string, agentId?: string }
+ *
+ * `bin/lemon.js task transition` 在打 legacy 的 `/api/agent/:agentId/task/transition`
+ * 之外，额外（best-effort、不影响主流程）打这一个端点。它不需要 `:id`——调用方（跑在
+ * work graph 节点里的 agent）不知道自己的 runId，只知道自己刚写的 `--artifact` 绝对路径；
+ * 这个路径的形状（`.../runs/{rootRunId}/nodes/{nodeRunId}/...`）本身就带着两个 ID
+ * （节点私有产物目录的既有约定，见 `graph-engine.js` 的 `nodeArtifactDir`/`runRootDir`），
+ * 从路径里解出来就行，不用改任何 agent.md 的提示词、也不用改 `AgentManager` 往子进程塞
+ * 新的环境变量。
+ *
+ * 解不出来 / 解出来的 rootRunId 不对应真实存在的 run（legacy 会话式 agent 调用这条命令时
+ * 就是这样——它们的 `--artifact` 压根不是这个路径形状）：安静跳过，返回 `{ok:false,
+ * reason:'not-a-graph-artifact'}`，不是错误——这条端点存在的前提就是"大多数调用方都用不上它"。
+ *
+ * 只做**追加**：不碰 `graph_run_nodes`/`graph_runs` 任何一行，不影响 needs/produces 契约、
+ * 不影响 validator 的判定依据（39 号文档 §七.2 定案的边界——private 产物不能变成契约输入）。
+ */
+router.post('/phase-note', h((req, res) => {
+  const { artifact, phase, agentId } = req.body || {};
+  if (typeof artifact !== 'string' || !artifact) {
+    return res.json({ ok: false, reason: 'no-artifact' });
+  }
+
+  const m = artifact.match(/[\\/]runs[\\/]([^\\/]+)[\\/]nodes[\\/]([^\\/]+)[\\/]/);
+  if (!m) return res.json({ ok: false, reason: 'not-a-graph-artifact' });
+  const [, rootRunId, nodeRunId] = m;
+
+  if (!getRun(rootRunId)) return res.json({ ok: false, reason: 'not-a-graph-artifact' });
+
+  const sse = require('../services/graph-run-sse');
+  const event = sse.emitEvent(
+    rootRunId, 'agent.phase',
+    `${agentId || '(未知 agent)'} 阶段流转 → ${phase || '(未知阶段)'}`,
+    { agentId: agentId || null, phase: phase || null, artifact },
+    { ref: nodeRunId, kind: 'agent.phase' }
+  );
+  res.json({ ok: true, rootRunId, nodeRunId, timelineEventId: event && event.timeline && event.timeline.ts });
+}));
+
+/**
  * POST /api/graph-runs/:id/budget — 「追加预算」（运维操作，不在 §四.C 五个操作之列）
  * body: { total_agent_calls?, total_tokens?, wallclock_ms?, resume?: boolean }
  * 可用条件：run_status = 'blocked'
+/**
+ * Unit Tests — POST /api/graph-runs/phase-note（42 号文档 Phase 4）
+ *
+ * `bin/lemon.js task transition` 额外打这个端点，把 agent 的阶段流转（RESEARCH/PLAN/
+ * EXECUTE/VERIFY 之类）落进 timeline.ndjson——org-coder 等角色调 legacy 的
+ * `/api/agent/:agentId/task/transition` 时，work graph 节点场景下那个端点的 sessions
+ * Map 找不到会话，静默跳过；这条端点从 --artifact 路径本身（节点私有产物目录的既有形状
+ * `.../runs/{rootRunId}/nodes/{nodeRunId}/...`）解出两个 ID，不需要任何新的环境变量或
+ * agent.md 改动。
+ *
+ * 钉住的边界（39 号文档 §七.2 定案）：这条端点只追加 timeline，绝不碰
+ * graph_run_nodes/graph_runs 任何一行——不影响 needs/produces 契约、不影响 validator
+ * 判定依据。
+ *
+ * 走真入口：把 router 挂到真 express 上 listen(0) 再 fetch，与 graph-run-route-io.test.js 同法。
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import express from 'express';
+
+const TEST_DB_PATH = '/tmp/test-graph-run-phase-note.sqlite';
+const DB_FILES = [TEST_DB_PATH, `${TEST_DB_PATH}-shm`, `${TEST_DB_PATH}-wal`];
+const MODULES = [
+  '../../services/graph-db',
+  '../../services/graph-service',
+  '../../services/org-graph-service',
+  '../../services/work-graph-db',
+  '../../services/company-paths',
+  '../../services/graph-run-sse',
+  '../../services/graph-engine',
+  '../../routes/graph-run',
+];
+
+describe('POST /api/graph-runs/phase-note', () => {
+  let wdb;
+  let sse;
+  let srv;
+  let base;
+  let runsDir;
+  const companyId = 'co-phase-note';
+
+  beforeAll(async () => {
+    require('../helpers/ensure-test-company').ensureTestCompany(companyId);
+    for (const f of DB_FILES) { try { fs.unlinkSync(f); } catch {} }
+    process.env.GRAPH_DB_PATH = TEST_DB_PATH;
+    runsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'phase-note-runs-'));
+    process.env.GRAPH_RUNS_DIR = runsDir;
+    for (const m of MODULES) delete require.cache[require.resolve(m)];
+    wdb = require('../../services/work-graph-db');
+    sse = require('../../services/graph-run-sse');
+
+    const app = express();
+    app.use(express.json());
+    app.use('/api/graph-runs', require('../../routes/graph-run'));
+    await new Promise((resolve) => {
+      srv = app.listen(0, '127.0.0.1', () => {
+        base = `http://127.0.0.1:${srv.address().port}`;
+        resolve();
+      });
+    });
+  });
+
+  afterAll(async () => {
+    if (srv) await new Promise((r) => srv.close(r));
+    require('../helpers/ensure-test-company').removeTestCompany(companyId);
+    for (const f of DB_FILES) { try { fs.unlinkSync(f); } catch {} }
+    try { fs.rmSync(runsDir, { recursive: true, force: true }); } catch {}
+    delete process.env.GRAPH_DB_PATH;
+    delete process.env.GRAPH_RUNS_DIR;
+    for (const m of MODULES) delete require.cache[require.resolve(m)];
+  });
+
+  function ensureAgents(ids) {
+    const db = wdb.getDb();
+    const now = new Date().toISOString();
+    const ins = db.prepare(`
+      INSERT OR IGNORE INTO system_agents
+        (id, name, scope, owner_company_id, legacy_path, status, created_at, updated_at)
+      VALUES (?, ?, 'public', NULL, ?, 'active', ?, ?)
+    `);
+    for (const id of new Set(ids)) ins.run(id, id, `system/agents/${id}`, now, now);
+  }
+
+  function makeRun() {
+    ensureAgents(['org-coder']);
+    const g = wdb.createWorkGraph({ companyId, nodes: ['org-coder'], edges: [] });
+    expect(g.errors || []).toEqual([]);
+    const run = wdb.createRun({ graphKind: 'work', graphId: g.id, companyId, executionMode: 'manual' });
+    require('../../services/graph-engine').markRunReady(run.id);
+    const node = wdb.getRunState(run.id).nodes[0];
+    return { runId: run.id, nodeRunId: node.id };
+  }
+
+  async function post(body) {
+    const r = await fetch(`${base}/api/graph-runs/phase-note`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return [r.status, await r.json()];
+  }
+
+  it('合法的节点产物路径 → 写进 timeline.ndjson，节点状态不受影响', async () => {
+    const { runId, nodeRunId } = makeRun();
+    const beforeStatus = wdb.getRunState(runId).nodes[0].status;
+    const artifact = `/Users/x/lemonboss/data/companies/${companyId}/runs/${runId}/nodes/${nodeRunId}/_plan.md`;
+
+    const [status, body] = await post({ artifact, phase: 'plan', agentId: `${companyId}:org-coder` });
+    expect(status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.rootRunId).toBe(runId);
+    expect(body.nodeRunId).toBe(nodeRunId);
+
+    // timeline.ndjson 里真的能查到这条记录
+    const raw = fs.readFileSync(sse.timelinePath(runId), 'utf8');
+    const lines = raw.trim().split('\n').map((l) => JSON.parse(l));
+    const mine = lines.find((l) => l.kind === 'agent.phase' && l.ref === nodeRunId);
+    expect(mine).toBeTruthy();
+    expect(mine.payload.phase).toBe('plan');
+    expect(mine.payload.artifact).toBe(artifact);
+    expect(mine.payload.agentId).toBe(`${companyId}:org-coder`);
+    expect(mine.root_run_id).toBe(runId);
+
+    // 不改契约面：节点状态原样，没有因为这条追加日志被结算或改动
+    expect(wdb.getRunState(runId).nodes[0].status).toBe(beforeStatus);
+  });
+
+  it('artifact 路径不是节点产物目录形状（legacy 会话式 agent 的调用） → ok:false，安静跳过', async () => {
+    const [status, body] = await post({
+      artifact: '/Users/x/lemonboss/system/agents/some-agent/co1/task-abc/_plan.md',
+      phase: 'plan',
+      agentId: 'co1:some-agent',
+    });
+    expect(status).toBe(200);
+    expect(body.ok).toBe(false);
+    expect(body.reason).toBe('not-a-graph-artifact');
+  });
+
+  it('artifact 路径形状对，但 rootRunId 不对应真实存在的 run → ok:false', async () => {
+    const [status, body] = await post({
+      artifact: `/Users/x/lemonboss/data/companies/${companyId}/runs/run_does_not_exist/nodes/rn_does_not_exist/_plan.md`,
+      phase: 'plan',
+    });
+    expect(status).toBe(200);
+    expect(body.ok).toBe(false);
+    expect(body.reason).toBe('not-a-graph-artifact');
+  });
+
+  it('没传 artifact → ok:false，reason:no-artifact', async () => {
+    const [status, body] = await post({ phase: 'plan' });
+    expect(status).toBe(200);
+    expect(body.ok).toBe(false);
+    expect(body.reason).toBe('no-artifact');
+  });
+});