宜博 / lemonboss

27-p4-parallel-and-artifacts.md 68.7 KB

27-P4. 并行执行与产物索引

所属: 27 Graph Agent 架构 的 Phase P4 版本: v0.2（阶段 A/B/C 均已实现，见 §五 2026-08-21 记录；T5 是可插拔桩子，真实计费接口未接） 日期: 2026-08-16 前置: P0/P1/P2/P3 均已实现。本文档建立在 P3 已落地的执行引擎之上（server/services/graph-engine.js / work-graph-db.js / graph-run-sse.js / goal-contract.js，commit c3abf4a）。 命名: 遵循 27-NAMING，节点名按层级轴（org-planner / org-coder-validator），本体名不带前缀。 配套: 27-E2E §7.4（fan-out 的两个阻塞点）、27-EXAMPLE 阶段 6（fan-out/fan-in 的具体场景）

〇、关于编号：这个 P4 不是原来那个 P4

27 号总纲 §六 里原本的「P4 回退 + Loop-Validator」已经并入 P3 实现完毕（总纲该行已标注「已并入上一行，不再单列」）——双层熔断、五项结构校验含 fail-fallback-edge、三层暂停/停止级联、按 contract_hash 判据的重试，全部在 c3abf4a 落地。

本文档回收这个空出来的编号，装的是 P3 明确排除、且现在成为最大能力缺口的内容。与 P5（自我进化）/ P6（DevLoop 收编）不冲突，是它们之前的一步。

〇.5、上级背景：黑灯工厂差距评估（2026-08-21）

用户原话（提问）：

lemonboss 现在离我们想做的黑灯工厂，能够自主 7*24 小时，自我规划，自我改进，自我迭代，自我完成任务的 graph org agent 系统，还有多远

评估结论（基于当时代码库状态 + system-design/27 系列文档）：

图引擎地基（P0~P3）扎实——org/work graph 统一执行引擎、暂停/重试/回退/熔断、真 Claude CLI 跑通、控制台都已落地并有真跑验收，这部分不是障碍。离「黑灯工厂」还有三个主要缺口：

  1. 真并发/无人值守跑不起来 —— 即本文档要做的 P4。现在一家公司同时只有一个 active root run，是单线程步进（advanceOne 一次只拾取一个 ready 节点），没有 fan-out 真并发，也没有为无人值守设计的看门狗/异常恢复层。7×24 意味着要能同时开很多任务、扛得住某个节点卡死或进程崩溃，这套目前没有。
  2. 自我改进闭环是半成品 —— P5（自我进化）对应的 dream 机制（29 号文档）刚实现：能定时把 agent 经验蒸馏回 memory.md/SKILL.md/soul.md/agent.md，但"蒸馏出来的结论对不对"只能人工抽查，没有自动校验，也没有 REST/控制台入口去监督它。更麻烦的是几条已知的本体装配漏洞——org-coder 没有共享本体会静默退化成通用 Base Agent；devloop 的 impl/test 节点根本没有 agent.md；work 节点执行时 org node 的 agent.md 硬截断前 2000 字、且只加载 agent.md，soul/tools/identity/user 全部不进提示词。自我改进要改的是这些本体，本体装配本身有静默漏洞，改进闭环就是在往一个不完整的东西上写。
  3. 没有真正的"自我规划"层 —— 现在的 org graph / work graph 都是 orggraph-planning / workgraph-planning 根据人给的目标生成的一次性产物，OKR/任务系统的驱动权还在人手上。定时的只有 dream（整理记忆），没有"自主决定下一步该做什么任务/该设什么目标"的常驻调度层——这一层连设计文档都还没有（不在现有 P5/P6 范围内）。

优先级建议：P4 并行（本文档）→ 补本体装配的静默坑（不然自我改进在改错东西）→ P6 收编统一循环 → 把 dream 的"结论对不对"自动化 → 最后才是自主任务生成层（目前完全空白，需要新设计）。

本文档要设计的 P4 是这份差距评估里排第一的缺口，也是三者中唯一已有详细设计（§四）且已全部落地（阶段 A/B/C，见 §五 2026-08-21 记录）的部分——T5 是可插拔桩子（真实计费接口待确认后再接），T11（专门的测试任务）没有单独立项，测试随每个任务同批写掉了。

一、目标与非目标

目标

  1. fan-out 并行执行 —— 解除 P3「一次只推进一个节点」的限制，让同一波次的多个 ready 节点真正并发跑。
  2. 同一 system agent 的多实例隔离 —— 这是并行的前置条件，卡在两个既有不变量上（§三.2）。
  3. 解除「一家公司同时只有一个 active root run」约束 —— P3 v1 用一个唯一索引强制它（§三.3），并行能力具备后应放开。
  4. 产物统一目录 + files.json 索引 —— 所有 org/work graph 节点 agent 的产出物落在 data/companies/{companyId}/ 下按 task 分目录，根目录 files.json 作为输入输出的统一检索入口，供所有 agent 引用。

非目标

  • 不做 L4（system agent 自我迭代）—— 属 P5，见 27-E2E §八。
  • 不做 DevLoop 收编 —— 属 P6。
  • 不做跨公司的并行调度（多公司同时跑的全局资源仲裁）—— 本阶段并发上限按「单机总量」控制即可，见 §四.4。
  • 不做节点执行中途的断点续传 —— 沿用 P3 的重试语义（整个节点重跑）。
  • 不做把 conversations/ 与 system/tasklog/ 下的历史记录纳入 files.json —— 那是运行态日志，不是产物。

二、背景：为什么并行是现在最大的缺口

27-EXAMPLE 阶段 6 描述的典型场景是：org-coder 把工作拆成三个可并行的 unit，各自跑完再 fan-in 到整合节点。这是 R-6 原话里明确要求的（「可以 fan out 并行多个 phase 的 code subagent」）。

P3 把图结构和 join 语义都做好了，唯独没做并行本身：

  • ✅ graph-engine.js:1078 —— 出边评估时「目标节点若所有入边条件都满足则置 ready」，fan-in 的 join 语义已经正确。
  • ✅ 图上可以有多个节点同时处于 ready。
  • ❌ graph-engine.js:908 —— 拾取 ready 节点的 SQL 是 ... WHERE status = 'ready' ORDER BY created_at, id **LIMIT 1**。所以三个并行分支只会被一个一个串行跑掉。

也就是说，图已经是 DAG，波次也分得出来，只是每次只走一个节点。这不是设计缺陷，是 P3 刻意的范围切分——因为并行会立刻撞上 §三.2 的两个不变量。

三、现状代码走查（决定设计边界的关键证据）

3.1 引擎侧：单节点拾取

server/services/graph-engine.js:908：

SELECT * FROM graph_run_nodes WHERE run_id = ? AND status = 'ready'
  ORDER BY created_at, id LIMIT 1

advanceOne(runId) 的语义是「拾取一个 ready 节点 → running → 执行 → 评估出边 → 把满足条件的下游置 ready → 返回，不循环往下跑」（文件头注释 16-17 行）。手动模式一次点击一步、自动模式靠外层反复调用，两者共用同一原语——这个设计在 P4 要保留，只是原语从「一个」变成「一批」。

3.2 两个阻塞不变量（并行的真正门槛）

① CONVENTIONS.md:155：

任意 (pid, agent) 同时只允许 1 个 status=running

如果并行跑三个 org-coder 的子任务，它们是同一个 system agent 的三次调用，直接违反这条。

② session-pool.js:29-32 的会话 key：

getKey(agentName, agentConfig, workDir, scope) {
  const base = `acp:${agentName}:${agentConfig.client}:${agentConfig.deploy}:${workDir}`;
  return scope ? `${base}:${scope}` : base;
}

同 agent 同 workDir 会复用同一个 session。并发调用会撞在一起——两个并行分支的对话会互相污染上下文。

💡 关键发现：getKey 的签名已经预留了 scope 参数，但第 45 行实际调用时是 this.getKey(agentName, agentConfig, workDir)——没传。也就是说隔离机制的挂载点已经在，只是从未被使用。这让 P4 的改动比预想小得多。

3.3 一家公司只允许一个 active root run

work-graph-db.js:108-110：

CREATE UNIQUE INDEX IF NOT EXISTS idx_graph_runs_one_active_root
  ON graph_runs(company_id)
  WHERE parent_run_id IS NULL AND run_status IN ('ready','running','paused');

company.js:1188 的注释写明这是「v1 约束（27-P3P4 §一非目标）」。注意这条约束在 org 层就存在，不是等到 work 层 fan-out 才需要——因为 org graph 本身也是被这套引擎跑的。

3.4 现成的 fan-out 实现（可借鉴，但不在图引擎里）

orchestrator.js:265 的 executeWithDependencies()：Scheduler.getExecutionGroups() 按 dependsOn 分组 → Promise.allSettled 组内并行、组间串行（天然 fan-in 屏障）→ 单点失败降级成 {status:'ERROR', retryable} 而不终结整组。

这套东西图引擎没有用（消费方只有 orchestrator 和 result-tracker）。P4 不必直接复用它的代码，但它的错误降级策略值得照搬：单个分支失败不应该让整批一起崩。

3.5 并发上限的既有约定

docs/prd/newfunction/_spec/plan-cost-concurrency.md §④ 已经给出三层上限的数字，P4 应当对齐而不是另立一套：

层级 上限 原因
项目内 L1 并行 ≤ 5 每个 Claude CLI ≈ 100MB RAM + 1 CPU core
单机系统并发 ≤ 20 个 ACP session 合理 RAM 占用 ≈ 2GB
同 company 项目并发 ≤ 3 避免单用户挤占
Bash 子进程 ≤ 50 防 fork bomb

3.6 产物目录现状

⚠️ 本节写于 2026-08-16，下面两个 ❌ 已经不成立了（2026-08-20 校准）。 留着原文是因为它记录了当时的判断依据；当前状态看这一段的校准块。

  • ✅ goal-contract.js 已实现验收契约的跨节点传递（R-15.6 验收先行）。
  • ✅ graph-engine.js 有节点级产物路径。
  • ❌ 没有 files.json → ✅ 阶段 C 已落地，但形态换了：产物索引做成了 graph_files 表（recordFile / findFiles / rebuildFilesFromNodes）， 不是 files.json 文件。表比文件多拿到两样东西：部分唯一索引保证「同一路径只有一个当前版本」， 以及 superseded_by 让历史版本可共存。守卫 graph-files-index.test.js 七条， 含「删掉索引后能从节点行重建」和「两个 task 的同名产物不互相覆盖」。
  • ❌ 产物按 agent 分目录 → ✅ 已按 run/node 分目录： data/companies/{cid}/runs/{rootRunId}/nodes/{nodeRunId}/， 跨 org node 的共享产物在 runs/{rootRunId}/artifacts/。 同一 agent 在不同任务下的产出因此天然不混。

2026-08-20 顺带修掉一个存量库缺陷：生产库里还留着产物索引加版本之前的 无条件唯一索引 idx_graph_files_path，导致重试时同路径第二次写必撞、 被降级成一条 timeline —— 产物索引在任何有重试的 run 上都不全，而且不报错。 详见 27-P3B §六ter。

四、设计方案

4.1 advanceOne → advanceBatch（保持原语单一）

不新增第二个推进原语。P3 「手动与自动共用同一个 advanceOne」的设计要保留，只把「拾取一个」放宽为「拾取一批」：

// 拾取至多 N 个 ready 节点（N = 本 run 的有效并发额度，见 4.4）
advanceBatch(runId, { maxConcurrency })  →  { results: [...], activated: [...] }
  • 手动模式：maxConcurrency = 1，行为与今天的 advanceOne 完全一致——「下一步」仍然只推进一个节点，用户能看清每一步。
  • 自动模式：maxConcurrency = 有效额度，一次拾取整批并发跑。
  • advanceOne(runId) 保留为 advanceBatch(runId, {maxConcurrency: 1}) 的薄封装，P3 已有的调用方和测试不用改。

拾取的原子性 —— 决策（2026-08-21，推翻本节上一版）：不需要新开一个包裹整批的 BEGIN IMMEDIATE 事务。直接复用 advanceOne 今天已经在用的同一个原语——sse.transitionNode(runId, nodeId, 'ready', 'running', ...)，单行条件 UPDATE ... WHERE status='ready'（graph-engine.js:1369 原话：「ready → running 的条件更新就是并发闸门」）。这条语句本身在 SQLite 单写者模型下已经是原子的。

const candidates = db.prepare(
  `SELECT * FROM graph_run_nodes WHERE run_id=? AND status='ready' ORDER BY created_at, id LIMIT ?`
).all(runId, maxConcurrency);

const claimed = candidates.filter(node =>
  sse.transitionNode(runId, node.id, 'ready', 'running', ...)   // advanceOne 今天调的同一个函数
);
// 拾取阶段全程同步、零 I/O；下一步才 await 真正的 agent 调用
const results = await Promise.allSettled(claimed.map(node => executeNode(node)));

为什么不需要包裹事务：两个并发 advanceBatch 即使 SELECT 到同一批候选节点，也是逐行在 transitionNode 上竞争——每一行只有一个调用者拿到 changes=1，另一个拿到 0 直接跳过。最终两边拾取到的集合天然无交集（§六 验收点 2），不需要把「数出还有空位」到「占上」捆成一个不可分事务——那是 work-graph-db.js:1437 建 run 时才需要的手法（它是「先数活跃 run 数、再判断、再写」这种读-判-写耦合在一起的多语句决策，必须原子；节点拾取没有这种耦合，每一行的归属独立由它自己的 UPDATE 决定）。

已知且接受的代价：某次 advanceBatch 可能因为在部分候选节点上输掉竞争，实际拾到的节点数少于 maxConcurrency（即使还有别的 ready 节点没进这次的 LIMIT 窗口）。自动模式下一轮循环会补上，不必现在解决。

4.2 同一 agent 的多实例隔离

这是并行的前置条件，必须先做。

利用 §三.2 发现的现成挂载点——SessionPool.getKey() 的 scope 参数：

// 图引擎调用 AgentManager 时带上 scope，取值用节点运行实例 id（graph_run_nodes.id）
// 同一 system agent 的两次并发调用因此落在两个不同的 session 上，互不污染
const scope = `gr:${nodeRunId}`;

为什么用 graph_run_nodes.id 而不是 def_node_id：同一个定义节点在重试时会有多次 attempt，但同一时刻只有一个在跑；而并行的是不同定义节点引用同一本体。用运行实例 id 天然满足「并发的两个调用一定拿到不同 scope」。

CONVENTIONS.md §12 第一条不变量要相应放宽：

旧：任意 (pid, agent) 同时只允许 1 个 status=running
新：任意 (pid, agent, scope) 同时只允许 1 个 status=running

⚠️ 这条不变量属于 DevLoop 的规格文件。改它意味着修改 docs/prd/newfunction/*.html 再跑 npm run spec:extract（_spec/ 是生成物，不能手改，pre-commit hook 会拦）。这是 P4 里唯一一处要动 DevLoop 规格的地方，且只是放宽维度、不改语义。

workDir 保持不变：仍然是 agent 的私有目录。P1 §3.3 已论证过 workDir 必须指向私有目录（CLI 子进程以它为 cwd 读 soul.md 等相对路径文件），并行不改变这一点——隔离靠 session scope，不靠换目录。

4.3 部分失败的 fan-in 语义

三个并行分支，2 成功 1 失败，fan-in 节点怎么办？

沿用 P3 已实现的 join 语义，不加特例：graph-engine.js:1078 的规则是「所有入边条件都满足才置 ready」。失败的那条分支走的是 fail 边，不满足 fan-in 节点的 success 入边条件，所以 fan-in 节点不会被点亮，图停在那里——这正是期望行为。

并发下的 join 正确性证明（2026-08-21，落实 T6 前先确认过再写代码）：A、B 两个并行分支都喂给 fan-in 节点 C，会不会两边都在对方提交前读到「还没齐」，谁都不去点亮 C？不会——settleNode（graph-engine.js:1514）是纯同步函数，内部（写自己状态 → activateSuccessTargets 读兄弟节点状态 → 可能 markReady）全程没有一个 await，全是同步的 better-sqlite3 调用。Node 事件循环单线程，await agentExecutor(ctx) 一旦 resolve，从那之后到 settleNode 跑完是不可打断的一整个 tick——A、B 谁的 agent 调用先 resolve 不重要，谁的 settleNode 后跑，谁就会看到两边状态都已提交，从而正确点亮 C。真正并发的只有 await 着的 agent 调用本身（正是 T6 要并行的那部分）。结论：join 不需要额外事务或锁，activateSuccessTargets/markReady 原样复用即可。

T4/T6 的具体切法：把 advanceOne 里「拾取之后」的整段（建 ctx → await 执行 → settleNode，graph-engine.js:1379-1505）抽成一个可复用函数（如 runClaimedNode(runId, run, pickedNode, opts)），advanceOne 与 advanceBatch 的并行路径共用它：

// T4 的拾取只到「置 running」为止（见 §4.1）；执行与结算是这里
const settled = await Promise.allSettled(
  claimed.map(node => runClaimedNode(runId, run, node, opts))
);

runClaimedNode 内部原有的 try/catch（把 agent 调用异常转成 fail outcome 喂给 settleNode，而不是往外抛）已经是主要的错误containment；Promise.allSettled 补的是最后一道防线——万一 settleNode 自己有 bug 抛出去，也不会拖垮同批里其它节点的 promise。

已知且不打算优化的冗余：一批里多个节点并发结算，各自 settleNode 末尾都会调一次 settleRun(runId)——同一个 run 短时间内被判定收敛好几次，幂等但浪费，不是 bug，不在本阶段处理范围。

需要补的是可观测性，不是新语义：

  • run 层面要能回答「我卡在等哪几个节点」。控制台已有的节点状态足以推导，但要在 UI 上显式标出「fan-in 节点 X 在等 A(fail) / B(success) / C(success)」，否则用户只看到「不动了」。
  • 失败分支按 P3 既有路径处理（fail 出边 → 归因 → 回退或 blocked），P4 不改。

4.4 并发额度：三层，逐层取小

决策（2026-08-21）：暂时不做「三层配额审批」这套东西——公司级 active root run 数、单机 session 数都不设硬顶（下面表格降级为参考数字，不是要实现的约束），唯一要卡的门是账户欠费（一旦欠费，不允许发起新的 agent 调用）。

⚠️ 欠费检查目前在代码里不存在——全仓库搜过 graph-engine.js，唯一的门是 checkBudget(run)（graph-engine.js:2334），那是任务级的 agent-call/token 预算池（R-15 那套「只增不减的共池」），跟「账户是否欠费」是两个不同维度的概念，不能互相顶替。P4 范围内不新建账户级欠费系统；如果这道门确实要在 P4 上线前接通，需要先确认计费系统那边有没有现成的余额/欠费状态可查——这是一个依赖，不是设计问题，先问清楚再决定要不要塞进 T5。

恢复语义决策（2026-08-21）：欠费挂起直接复用 suspendRunTree（graph-engine.js:2383）——跟预算耗尽走同一条路：root run → blocked，全树非终态 run 置 pause_requested=1，只是 reason 从 'budget-exhausted' 换成 'billing-arrears'。这套三层级联暂停/恢复（pauseRun / startRunSync / resumeDescendants，graph-engine.js:2506-2578）已经实现并测过，不需要为欠费再发明一套状态机。

但有一个真实缺口：今天从 blocked 恢复靠人手点「启动」（admitOrRequeue('blocked'→'running')，注释原话「解除 blocked 的正当入口是...点一下启动」）。欠费清零不会有人去点——这正是「7×24 无人值守缺看门狗」那个更大缺口的一个具体实例。P4 范围内需要补的是一个自动恢复触发器：欠费状态清除时，批量对所有 run_status='blocked' AND block_reason='billing-arrears' 的 root run 调 startRun。触发源是计费系统的事件/轮询，不是图引擎自己能感知的——这也是为什么欠费检查本身要先问清楚计费系统那边的依赖（上一段已经点出）。

在那道门接通之前，advanceBatch 相当于「无限额度」，唯一还在起作用的数字上限是 T1 已经落地的 SessionPool.maxSessions（防止单机字面意义上被并发的 Claude CLI 子进程压垮，是内存/CPU 层面的保命阀，跟欠费门是两回事，不因为这条决策而放松）。

对齐 §三.5 的既有数字，不另立一套（下表现改为参考基线，非本阶段要实现的硬约束）：

层级 上限 落在哪
单个 run 默认 5 graph_runs 新增 max_concurrency 列，建 run 时写入，可按任务覆盖
单公司 默认 3 个 active root run 替换 §三.3 那个「只允许 1 个」的唯一索引
单机 ≤ 20 个 ACP session SessionPool 加 maxSessions（plan-cost-concurrency.md §④ 已经提出要加这个配置，至今未加）

有效额度 = min(三层剩余)。advanceBatch 拾取前先算这个值，为 0 就本轮不拾取（不是报错，等下一轮）。 按 2026-08-21 决策作废：不算三层 min，只剩单公司/单机两个数字本身也不设硬顶。advanceBatch 唯一还要看的额度就是本 run 的 max_concurrency（SELECT 的 LIMIT），不需要为它算「剩余」——因为再没有别的层可以让它变小。

任务级总预算不变：P3 已实现「按 root_run_id 共池的 backward_count + 任务级预算挂 root run」，并行不改变预算语义——并行只是让预算烧得更快，这一点要在控制台的成本提示里体现。

4.5 解除单 root run 约束

-- 替换 work-graph-db.js:108 的 idx_graph_runs_one_active_root
DROP INDEX IF EXISTS idx_graph_runs_one_active_root;
-- 不再用唯一索引硬限，改为建 run 时按 4.4 的「单公司额度」做计数检查

为什么从「索引强制」改为「计数检查」：唯一索引只能表达「≤1」，表达不了「≤3」。计数检查要放在同一个事务里（先 SELECT COUNT(*) 再 INSERT），否则并发建 run 会超额。

4.6 产物统一目录 + 产物索引表（R-19 定案后重写）

v0.2 重写：本节原设计是「公司根放一个 files.json」。27-REQ R-19 改为建 sqlite 表，并把「边即输入输出」这层显式化。原设计的目录约定保留。

为什么这一节从「优化项」变成「阻塞项」

第四次真 CLI 冒烟（自动模式）跑出的断点：org-planner-prd 失败，它自己的归因说得很准 —— 「不是上游没产出，是它的产出结构上到不了我手上」。核实：上游 brd 的 brd.md / contract.json 落在它自己的节点私有目录，共享区 artifacts/ 只有 project-root.json 与 task-goal.json，而 brd --success--> prd 这条边 不携带任何文件引用。

同一张 work graph 内部，上游到下游没有任何数据通路。这不是引擎 bug —— 边一直只承载控制流（condition / edge_kind / fail_reason）， 而 27-P3/P4 §四.B.3 把 R-4 要的「边的输入输出」 落成了从 output_ref 推断的 UI 展示，没有实体。推断的那一端是私有目录，下游读不到。

结论：不通这条路，任何多节点的图都只能跑完第一个节点。 它不依赖并行，应从 P4 里 单独拆出来先做。

目录约定（沿用原设计）

data/companies/{companyId}/
  tasks/{taskId}/
    brd.md · prd.md · sdd.md
    acceptance.json        验收契约（goal-contract.js 的路径归并到这里）✅ R19-B 已完成
    {nodeName}/            节点私有的中间产物（attempt-{n}.json 等）

按 task 分目录而不是平铺：同一家公司会跑很多 task，平铺的话第二个 task 的 prd.md 会覆盖第一个。按 task 分既避免覆盖，也保留历史。

R19-B 真实状态（2026-08-17）：acceptance.json 这一格已落地 —— goal-contract.js 写在 {companyRoot}/tasks/{taskId}/acceptance.json（taskId 从 runs/{rootRunId}/artifacts/task-goal.json 推），落盘同一次调用里进 graph_files （kind='acceptance'，superseded_by 版本链），下游 validator 靠 describeInputs 查 TASK_SHARED_KINDS 拿到绝对路径。旧落点 runs/{r}/artifacts/acceptance.json 保留只读兜底。 还没做的三件（别当已解决）：① verdicts/ 故意留在 run 级、没搬； ② 三个产出模板的 tools.md 仍教 agent 把 goal-benchmark.json / goal-test-script/*.js 写进 $R/artifacts/，所以契约内相对路径要在两个根里找；③ companyRootDir / taskDirRel 目前在 graph-engine.js 与 goal-contract.js 里各一份镜像，待提取到共享位置。 三件的判据与删除条件见 27-goal-contract-format §八。 brd.md / prd.md / sdd.md 这几格仍在节点私有目录，不在本条范围内。

不走 workspace/（R-19.3 定案）：workspace/ 的现有语义是 06-沙盒自治 定的 「Agent 自治领地，框架不干预」。产物索引要的是「框架管着的、可检索的交付物区」, 两种所有权混在一个目录里，索引就无法保证不漂移。

根路径用代码推导，不入库（R-19.3 定案）：库里只存相对公司根的路径。 理由是库里存绝对路径会烂 —— W13 清掉的那 10 条 legacy_path 悬空行就是这个病 （指向早已删除的目录）。推导方式与现有 runRootDir / nodeArtifactDir 一致， 需要覆盖时给环境变量（测试隔离已在用 GRAPH_RUNS_DIR 这招）。 另：库里没有 companies 表，公司是 company.json + 目录扫描，所以也没有 「company 表的定义」这个落点。

两类数据流，都要（R-19.3 定案①）

纯「文件挂在边上」有硬伤：边是 (from, to) 二元关系，只能表达相邻节点间的传递。 而 R-9.3 定的「验收产物由 planner 生成、由 validator 执行」是非相邻依赖 —— org graph 是 org-planner → org-coder → org-validator，acceptance.json 从 planner 流到 validator，跳过 coder，这两个节点之间没有边。

沿边传递 任务级共享
例 brd.md → 紧邻的 prd 节点 acceptance.json → 任意下游 validator
绑定方式 边上声明契约（kind） 挂在 task 上，按 kind 检索
受拓扑相邻性限制 是 否

契约与实例分两阶段（R-19.4）

workgraph-planning 画图时不可能知道文件名（节点还没跑），但它能声明 「这条边传一份 brd」。所以：

  • 规划时：边上声明契约（kind），落 graph_edge_contracts
  • 运行时：节点产出落盘后，引擎记实例（rel_path），落 graph_files

由此得到一个原设计没有的收益：引擎能在节点跑之前校验「你声明要吃 brd，但上游没有任何 节点产 brd」。这类图结构错误现在完全查不出来，只能等跑到那一步 agent 说「我拿不到输入」 （第四次真跑正是这么发现的）。

表结构

-- 产物实例：运行时由**引擎**追加。不靠 agent 自觉写，否则索引必然与实际文件漂移
-- （本轮已被验证过多次：凡「靠 agent 自觉」的环节几乎全部落空）。
CREATE TABLE IF NOT EXISTS graph_files (
  id                      TEXT PRIMARY KEY,     -- gf_<nanoid>
  company_id              TEXT NOT NULL,
  task_id                 TEXT,                 -- 任务级共享产物按它检索
  rel_path                TEXT NOT NULL,        -- **相对公司根**，根由代码推导
  kind                    TEXT NOT NULL,        -- brd|prd|sdd|acceptance|contract|artifact|log
  produced_by_run_id      TEXT,
  produced_by_node_run_id TEXT,                 -- 与 graph_run_nodes.output_ref 同源
  created_at              TEXT NOT NULL,
  superseded_by           TEXT                  -- 同名产物的版本链，可空
);

-- 边上声明的数据契约：规划时写，只有 kind 没有实例。
-- edge_layer 区分两层边表 —— org_graph_edges.id 是 INTEGER、work_graph_edges.id 是 TEXT，
-- 与 graph_run_nodes.def_node_id 同一处类型不整齐（见 27-P3/P4 §四.A.2 的注）。
CREATE TABLE IF NOT EXISTS graph_edge_contracts (
  id          TEXT PRIMARY KEY,
  edge_layer  TEXT NOT NULL CHECK (edge_layer IN ('org','work')),
  edge_id     TEXT NOT NULL,
  kind        TEXT NOT NULL,
  required    INTEGER NOT NULL DEFAULT 1,       -- 0 = 可选输入，缺了不算错
  created_at  TEXT NOT NULL
);

引擎怎么用

产出侧：节点结算时，除了写 output_ref（节点级指针，不变）， 再按落盘的文件往 graph_files 追加实例。两者关系与原设计一致 —— output_ref 回答「我这次跑出了什么」，graph_files 回答「这家公司有哪些产物、谁能用」， 后者由前者派生，所以要有 rebuild 能力（索引损坏时从节点行重建，类比 _rebuildIndex()）。

输入侧（这是补上断点的关键）：节点执行前，引擎按 「该节点入边声明的 kind」+「本 task 的共享产物」去 graph_files 查实例， 把真实路径拼进提示词。

这比原设计的「注入一句『索引在 files.json，按 kind/taskId 自己检索』」更可靠： 后者仍然依赖 agent 自觉去查、自觉拼对路径，而第四次真跑证明 agent 拼不出来 —— 引擎直接把输入递到它手上，不给它猜的机会。

落地状态（R-19.A：声明侧接通）

环 谁做 状态
产生（规划时声明契约） workgraph-planning 模板约束九：forward 边写 produces / needs（kind 取值域 = ARTIFACT_KINDS，backward 边禁止声明） ✅ 已落地
传递（落库） work 层 work-graph-db.createWorkGraph 插边后调 declareEdgeContract；org 层 org-graph-service.writeGraph / patchGraph 同（insertEdge 改为回传行 id，重复边被去重键吞掉时挂到同一条边上） ✅ 已落地，declareEdgeContract 不再是零调用方
落库（运行时实例） graph-engine.indexNodeOutputs，kind 优先取出边声明 ✅ 925d9db
读回（拼进提示词） graph-engine.describeInputs，inboundContracts 现在真的非空 ✅ 已实测（graph-edge-contracts.test.js 走 advanceOne 真入口验四环闭合）
R-19.4 结构校验 validateGraph 新增规则 6 data-contract：needs 的 kind 在图上没有任何出边声明产出 → 拒，错误形态与既有五项一致（{rule, detail}）。work 层通过 validateWorkGraph 复用同一份实现，两层同时生效 ✅ 已落地

两个键而不是一个（produces 走产出侧、needs 走消费侧）是 R-19.4 能成立的前提： 合成一个键的话，同一行契约既是「上游产出」又是「下游要吃」， 「声明要吃 X 但没人产 X」永远自洽 —— 那条校验会退化成一条永不报错的空跑规则。 required:false 是显式逃生口：产出方不在本图（acceptance 由上一层 org graph / artifacts/ 给）时用它。

尚未接通的一环（已接通，见下面第六次真跑）：system/work-graph-templates/*.json 四张骨架的边 原先没有 produces 声明，所以「照抄骨架」得到的图不传数据，全靠规划 agent 自己按约束九补。 四张骨架现已补齐 produces/needs（backward 边一条都没动），第六次真跑实测规划 agent 会把骨架上的声明连同结构一起改编下来 —— 见「第六次真 CLI 冒烟」验收点⑤。

第五次真 CLI 冒烟：第四次那个断点复验通过（2026-08-17，未改一行代码）

跑法：主仓库 vite（5173）+ worktree wf_55ba803e-5ac-6 的真 CLI 服务（3010，data/ 独立， LEMONBOSS_DISABLE_WATCHDOG=1）。公司 r19smoke，手动模式，预算 total_agent_calls 实跑 3/15。 被测版本 = 925d9db + 当时工作树里未提交的 R-19.A 改动（这批改动随后进了 1ea9efa）； 1ea9efa 里新加的 role 列与控制台三字段不在本轮被测范围内。

验收点 结果
建公司 → orggraph-planning 真跑落图自雇 ✅ 未被打破。org-analyst / org-designer / org-validator 三节点 + 正向边 + 两条 backward fail 边；规划本体没混进 org 节点
R19-A：真实规划 agent 会不会在边上声明契约 ✅ 成立。约束九全文（### 约束九 / kind 取值域 / backward 禁令 / 自查 5bis）确实进了它的提示词（28597 字，未被 2000 字截断）。它自己写出 {"from":"org-analyst-brd","to":"org-analyst-prd","condition":"success","produces":["brd"]} 与 {...,"to":"org-analyst-validator","produces":["prd"],"needs":["brd"]}，两条 backward 边干净。落库 graph_edge_contracts 3 行（edge_layer='work'）—— declareEdgeContract 第一次有真实调用方写出真实行
落库侧：节点产出进不进索引 ✅ 成立。org-analyst-brd success 后 graph_files 两行：brd.md→kind=brd（按出边声明定的）、contract.json→kind=contract（按文件名兜底）
读回侧：下游提示词里有没有上游产物的真实绝对路径（本轮核心） ✅ 成立，断点关闭。org-analyst-prd（prd-planning）的真实提示词里出现：
[上游输入 —— 引擎已按图上声明的数据契约解析好，直接读这些路径]
- brd：…/runs/run_fc7e9b8a29d5/nodes/rn_2e8dbb1c6ed7/brd.md
- contract（任务级共享）：…/rn_2e8dbb1c6ed7/contract.json
对照第四次真跑同一个本体的提示词：[上游输入 一次都没出现过
下游还会不会说「拿不到输入」 ✅ 不会了。prd 节点第一个动作就是 Read 那条绝对路径，随后自评「BRD 完整（5 条 in_scope / 7 条 out_of_scope / 5 条可判定度量），无需打回」，attempt-0.json 记 verdict:"produced" + brd_in_scope_covered:"5/5"。节点 success，fail_reason=null
四环（产生→传递→落库→读回） ✅ 真 CLI 下逐环有物证：agent 写 JSON → 引擎 createWorkGraph → graph_edge_contracts 3 行 + graph_files 4 行 → 提示词里的绝对路径

同轮暴露的两条不对称（都不是本轮改动引入的）：

  1. 落库通道走的是降级路径，不是 REST 端点。POST /api/company/:id/work-graphs 实际不存在（真跑实测 404，全仓库无该路由）。规划 agent 按 agent.md 的降级约定把图 JSON 写到 workspace/workgraph-<taskId>.json、由引擎接手落库 —— 契约在这条路上没丢 （normalizeContracts 在 work-graph-db.normalizeEdges 里，与入口无关）。 但模板里那段 curl 是必然 404 的死路径，每次真跑都要浪费 agent 一轮试探。
  2. org 层的声明侧实际零产出。writeGraph → declareContracts 代码在，但 orggraph-planning/agent.md 一个字都没提数据契约（grep -c 'produces\|数据契约' = 0）， 所以真跑后 graph_edge_contracts 里 edge_layer='org' 0 行。 org 层这一半仍是「实现在、无真实调用方」。

第六次真 CLI 冒烟：org 层四环闭合（2026-08-17）

跑法：worktree wf_9fbefcf9-79e-5，真 CLI 服务 3010（data/ 是 worktree 自己的 —— company-service.js:18 与 graph-db.js:34 都从 __dirname/../../data 派生，所以生产 data/graph.sqlite 结构上碰不到），LEMONBOSS_DISABLE_WATCHDOG=1（启动日志有 [Watchdog] ⏸️ 已由 LEMONBOSS_DISABLE_WATCHDOG=1 关闭）。公司 smoke6，org run run_5274dad6b10c 手动模式，子 run run_0691b85eb7fc。 被测版本 = 2b77f8c + 工作树里未提交的四份改动（org 层读回方 describeOrgContracts、 orggraph-planning 约束五、workgraph-planning 去死端点、四张骨架补 produces/needs）。

证据一律取 Claude CLI 自己的 transcript 原文（~/.claude/projects/<agent-cwd>/*.jsonl 里第一条 user 消息 = 引擎真的发出去的那段字），不用 timeline 推断。

单测基线：npm run test:unit 在 worktree 里 837 passed / 6 skipped，83 个文件中 82 通过。 唯一失败的 server/tests/integration/graph-agent-p1-acceptance.test.js 是环境性失败、不是回归： 它在 :75 断言 data/companies/idearun/agents/evolver-youtube-crawler/agent.md 存在， 而 data/companies/ 被 .gitignore 忽略，全新 worktree 里结构上不可能有这份 fixture （该断言是作者刻意加的「别让测试空跑通过」保险）。对账：主树基线 829 passed / 80 文件， 本轮新增三个测试文件共 14 条，失败套件里 6 条没跑 → 829 + 14 − 6 = 837，与实测逐数吻合， 即既有用例零回归。

验收点 结果
① org 层声明真的落库 ✅ graph_edge_contracts 里 edge_layer='org' 4 行（第五次真跑是 0 行）。边 1 org-planner→org-coder：produces[prd] + produces[acceptance]；边 2 org-coder→org-validator：produces[artifact] + needs[acceptance]。两条 backward 边（3/4）零契约行
② org 契约进没进规划 agent 的提示词（本轮核心） ✅ 成立。发给 workgraph-planning 的提示词（52 677 字节）第 746 行逐字出现 ## ③bis org-planner 在上一层图上的数据契约（引擎已解析，不要自己猜路径），其下「你这一层必须产出的东西（硬约束）」列出 acceptance / prd —— 正是 org 边 1 上声明的两个 kind。四环里的「读回」这一环闭合
③ 声明侧的语义质量 ✅ 超出预期。needs 被用在真正的隔节点中继上：org-validator 要吃的 acceptance 产出方是 org-planner（非紧邻上游 org-coder），所以单独写 needs。规划记录 workspace/orggraph-plan.md 第 6 节「数据契约自查」表填满了，含 data-contract 规则预检、kind 取值域预检、以及「粒度：org 层比 work 层粗一档」自查 —— 约束五被完整吸收，不是照抄
④ 死端点 ✅ agent 不再 curl POST /api/company/:id/work-graphs。全 transcript 里该字符串只出现在提示词里（两处，见下面的不对称②），agent 侧零调用。它按新 Step 7 把图写成项目根下的绝对路径 projects/p-xdc09a/workgraph-T-msx3w8xm.json（没有写 workspace/ 那条与写入边界冲突的旧路径），并自己 require 引擎的 validateWorkGraph 预检了一遍才交回。落库一轮通过，plan 无 rejected
⑤ 骨架 json 的声明起作用了吗 ✅ 照抄并正确改编。宿主是 org-planner → 选 planner.json；任务是单文件 CLI 于是砍掉 sdd 节点，产出的四条 forward 边契约与骨架同形：brd→prd produces[brd]、prd→benchmark produces[prd]、benchmark→validator produces[acceptance] + needs[brd,prd]（骨架原文是 needs[brd,prd,sdd]，它跟着删掉了 sdd —— 说明是理解后改编，不是字面复制），三条 backward 边零声明。落库 edge_layer='work' 5 行
⑥ 回归：第五次那条已成立的链路 ✅ 没被 resolveInboundLines 抽函数搞坏。org-planner-prd（prd-planning）的真实提示词逐字复现第五次的形状：
[上游输入 —— 引擎已按图上声明的数据契约解析好，直接读这些路径]
- brd：…/runs/run_5274dad6b10c/nodes/rn_9836aeb60827/brd.md
- contract（任务级共享）：…/rn_9836aeb60827/contract.json
一个 ⚠️ 都没有。行为侧也一致：prd agent 的头两个动作就是 Read 这两条绝对路径，随后判「BRD 完整且五问齐备，无需打回」，节点 attempt 0 一次 success
产出侧 kind 认领 ✅ brd.md→kind=brd、prd.md→kind=prd，两者都是按出边 produces 声明定的（不是文件名兜底）；contract.json→kind=contract 按文件名

归因上的诚实交代：⑤ 这一条无法把功劳单独归给 ③bis 还是骨架 —— planner.json 本身就在 benchmark→validator 上写了 produces[acceptance]、在 prd→sdd 上写了 produces[prd]， 所以「acceptance 与 prd 都有节点产出」这个结果两条路径都能推出来，本轮是同向叠加， 不构成对 ③bis 的独立验证。③bis 的独立证据只有验收点②（那段文字确实进了提示词）。 要把两者分开，得构造一个骨架覆盖不到的 kind（例如 org 边上声明 produces[log]）再看它补不补。

跑法上踩到的一个坑（我自己造成的，写下来免得下一轮再踩）： 第一次跑 org-planner-brd 时节点被判 fail / fail_reason=boundary_escape 而进 blocked， 而 agent 本身一个越界写入都没有。node.boundary 事件的 entries 只有一条： M docs/todo/system-design/27-p4-parallel-and-artifacts.md —— 那是我在节点跑的同时编辑本文件。 applyBoundaryGuard（graph-engine.js:2829）拍调用前后两次全仓库 git status， 差集里的每一条都算当前节点的越界；splitUnattributable（:2807）当时的豁免名单只有 system/agents/*/{todo.md,plan.md,memory.md,_lessons.md,.claude/scheduled_tasks.json} （旧名 AGENT_RUNTIME_STATE_RE），文档、源码、任何别的并发写入都不在豁免内。

28 号改造后这条豁免已放宽成整棵注册表树：AGENT_REGISTRY_TREE_RE = /^system\/agents\//。 原因是新本体的落点搬进了被 git 跟踪的 system/agents/{id}/，运行期招聘会以 ?? system/agents/{newId}/ 一整条目录项进 git status，旧的五文件名名单接不住、 会把成功的招聘节点判成 boundary_escape（gitignore 挡不住这一类：新本体本来就要进版本库）。 但本节这个坑一个字都没变：docs/ 不在 system/agents/ 下，真跑期间人工编辑本文件 照样会冤枉正在跑的节点 —— 判罚范围收窄的只有注册表树。详见 28 号设计 §5.5b。 结论：真跑期间不要在同一个工作树里改任何被 git 跟踪的文件 —— 这条约束此前只写成 「关掉 Master 巡检」，但巡检只是并发写入的一种，人工编辑同样会冤枉节点。 （重试后 attempt 1 一次 success，所以这只是浪费一次调用，不影响上表任何结论； 但重试本身留下了一个副作用文件 contract.prev.json，它落成了 kind=artifact —— 见下面第 4 条。）

同轮暴露的四条不对称（都不是本轮改动引入的，且都不在本轮可改文件内）：

  1. 引擎提示词与新模板在 wg_ 上直接对立，而且同处一条提示词里。 workgraph-planning/agent.md 第 329/361 行（进了提示词）说「别自己编 wg_ id」 「不许出现 wg_ + 12 位十六进制，引擎优先匹配这个形状并当成已落库的图 id，查不到就整轮作废」； 而 graph-engine.js:832 拼出的第 775 行说「已经自行落库成功时，改为回一行 workGraphId: wg_xxx」。 本轮 agent 选择了听模板（没写 wg_），但这是运气而非保证。修法：删掉 graph-engine.js 那一行 —— agent 永远不可能「自行落库成功」，那个分支对它来说只是陷阱。
  2. 同一处还留着「端点尚未上线」的措辞（graph-engine.js:829 → 提示词第 770 行）， 暗示将来会上线；新模板的口径是 NO-SUCH-ENDPOINT — 从来没有实现过。两边措辞不一致。 顺带一提，graph-engine.js:832 那个内联 JSON 示例的边是 {"from":"...","to":"...","condition":"success"} —— 一个 produces 都没有， 与模板「forward 边基本都要写 produces」正相反。三处（829/832/835）都在同一段字符串数组里， 一次改完最省事。
  3. org 层 produces 在产出侧没有认领方（已知上限，非回归）：org 节点是 subgraph， deriveChildOutcome 不回 outputRef → output_ref 恒 null → indexNodeOutputs 第一行就 return。 org 边上的 produces 能不能真的查到实例，完全取决于子 run 里的 work 节点把文件登记成对的 kind （graph_files 按 (company_id, task_id) 检索，子 run 继承同一个 task_id）。 本轮 org run 只推进到第一个 org node，没有验到第二个 org node 的入边把路径查出来 —— ③bis 的「上游节点交给你的输入」那一半（resolveInboundLines 拼绝对路径）在真跑里仍未被覆盖， 下一次真跑应当专门推到第二个 org node。 间接旁证：resolveInboundLines 是 describeInputs 与 describeOrgContracts 共用的同一个函数 （graph-engine.js:3226），验收点⑥已经证明它在真跑里能拼出正确绝对路径； org 层缺的只是「这条 org 入边上确实有声明 + 索引里确实有实例」这个具体组合的现场，不是代码路径。
  4. contract.prev.json 会被当成产物索引进去（kind=artifact）。它是 retryNode 为算契约 hash 留的快照（retry 响应里的 contractSnapshot.file），不是节点交付物。产出侧没把它排除， 于是每次人工重试都会给 graph_files 添一行噪声。validator.json 那条「刻意零 produces」的 注释里已经写过同类道理（attempt-{n}.json 被排除在索引外），contract.prev.json 漏了。 修法：indexNodeOutputs 的排除名单加上它。

控制台读回端（R19-C：R-4「边的输入输出」的字面落地）

此前 27-P3/P4 §四.B.3 第 2 个 tab 把 R-4 落成了 「渲染 output_ref 指向的文件」+「原始产出 vs 被消费的形态」，数据流是推断的 —— 所以那个 tab 只看得见自己的产出，看不见「我的输入从哪来」「我的产出给了谁」。 R-19 之后这两件事有实体（graph_edge_contracts × graph_files），控制台按实体重写：

展示块 数据与规则 状态
输入 · 入边声明的契约 × 索引里的实例 逐 kind 一行：沿边传递 / 任务级共享、解析到的绝对路径 / ⚠️ 查不到实例、required、以及这一行 agent 到底看不看得到（引擎对「可选 + 无实例」整行省略）。join 规则与 describeInputs 同源（同 kind 后来者胜、backward 入边不是数据来源） ✅ web/src/components/graph-console/io-model.js + NodeDetailPanel.vue 的 io tab
输出 · 本节点产出并登记进索引的实例 taskFiles 里 produced_by_node_run_id = 本节点 的行，各自 kind / 时间 / 是否被新版本取代；节点级指针 output_ref 与公司级索引的分工写在块首 ✅ 同上
出边契约 · 我的产出给了谁 每条 forward 出边一组 kind 药丸，三态：我产的 ✓ / 索引里有但不是我产的（标「由 X 产出」，合法，引擎按 task+kind 检索）/ 整个 task 都没有实例 ⚠️（= R-19.4 那类跑之前就能看出来的图结构错误） ✅ 同上
画布上的边 只有声明过契约的边多画一枚小药丸（必需的那个 kind 占位、其余折 +N、全量与 ?=可选进 <title>）；GAP_X 只有 52px，第二个标签就会压线，所以克制到一枚 ✅ WorkGraphCanvas.vue
tab 徽标 必需输入解析不到的条数标成「输入输出 ⚠️N」，不用点进去才发现 ✅
前置：路由字段 GET /api/graph-runs/:id 要补三个字段：companyRoot（= companyRootDir(run.company_id)，库里只存相对路径）、taskFiles（= findFiles({companyId, taskId})）、edges[].contracts（= edgeContracts(layer, e.id)，readDefGraph 已回 edge.id）。三者都是现成导出函数 ✅ 已接（1ea9efa）。缺字段时的降级行为保留：三块整块降级并点名缺哪一个，不做任何推断（推断出来的数据流正是第四次真跑栽的坑）。⚠️ 降级分支已被真跑实测过、接通后的正常分支还没有：第五次真跑用的是 1ea9efa 之前的构建，那时节点详情「输入输出」tab 只显示降级横幅「产物索引未随响应下发…GET /api/graph-runs/:id 还没返回 companyRoot / taskFiles / edges[].contracts」，画布 forward 边上也没有契约药丸——即当时 R-19 的数据通路引擎侧已通、控制台侧看不见。接上之后界面能否真的显示解析出的绝对路径，留待下一次真跑复验
graph_edge_contracts.role produces / needs 的非对称在 declareEdgeContract 处被丢掉（表里没有 role 列），落库后两者不可区分 ❌ 未落库：所以「这条边声明的 kind 有没有实例」只能看索引本身，而不能按 role 判定谁该产它

五、任务划分

# 任务 文件 依赖
T1 ✅ SessionPool 加 maxSessions 上限 + 调用方传 scope —— 已完成（27-P3C §15.5-2，守卫 session-pool-max.test.js / session-pool-scope-key.test.js） server/src/core/session-pool.js 无
T2 DevLoop 规格：§12 第一条不变量放宽为 (pid, agent, scope)。改 HTML 后必须跑 npm run spec:extract docs/prd/newfunction/*.html 无
T3 ✅ graph_runs 加 max_concurrency 列（可空，NULL 用新导出常量 DEFAULT_MAX_CONCURRENCY=5，对齐 plan-cost-concurrency.md §④）；createRun 新增 maxConcurrency 参数并持久化 —— 2026-08-21 已完成（迁移块 + createRun INSERT 都改了，hasColumn 判断 + ALTER TABLE ADD COLUMN 照抄既有存量库迁移写法）。DROP idx_graph_runs_one_active_root 那半本来就已完成（27-P3C 批 4），不用动 server/services/work-graph-db.js 无
T4 ✅ advanceBatch(runId, {maxConcurrency})：maxConcurrency<=1 直接委托 advanceOne（零行为差异，不是反过来让 advanceOne 委托 advanceBatch——见函数注释里的理由）；>1 时 SELECT ... LIMIT 取候选，循环调 sse.transitionNode 逐行拾取（不包裹事务，§4.1 决策的完整论证）。2026-08-21 已实现并测过 server/services/graph-engine.js T3 ✅
T5 ✅ 并发额度计算（三层取小）+ 额度为 0 时的等待语义 2026-08-21 已实现，按可插拔桩子的方式落地（用户明确选择：真实计费接口未定前先搭桩子）。setBillingGate(fn) 与 setAgentExecutor 同款注入模式，未注入时 checkBilling 恒「未欠费」，对现有行为零影响；欠费时复用 suspendRunTree（新增 reason/summary 参数，reason='billing-arrears'），写进新增的 graph_runs.block_reason 列；startRunSync「启动」清空该列；resumeBillingClearedRuns() 是自动恢复触发器（扫 block_reason='billing-arrears' 的 blocked root run，欠费真清了就代其 startRun），调度源（webhook/轮询）留给计费接口接通之后再定。顺带修了一个真 bug：advanceBatch 原来 budget 门查在候选查询之前，导致「已收敛只是恰好预算也耗尽」的 run 被误判成挂起而不是 completed——已改成候选先查、budget/billing 门后查，跟 advanceOne 的既有顺序对齐。新测试 graph-engine-billing-gate.test.js（7 条），临时 worktree 隔离验证（见下方实现记录） server/services/graph-engine.js T1, T3, T4
T6 ✅ 把 advanceOne 拾取之后的整段（建 ctx → 执行 → settleNode）抽成 runClaimedNode(...)，advanceBatch 用 Promise.allSettled 并发跑 claimed 节点。fan-in join 复用现有 activateSuccessTargets/markReady，不需要新事务/锁（并发安全性证明见 §4.3）。2026-08-21 已实现并测过 server/services/graph-engine.js T4 ✅
T7 ✅ 产物索引：追加、查询、rebuild —— 已完成，形态换成 graph_files 表（见 §3.6 校准块），不是 files.json server/services/work-graph-db.js —
T8 ✅ 产物按 run/node 分目录 + 节点产出后自动进索引 —— 已完成（runs/{rootRunId}/nodes/{nodeRunId}/） server/services/graph-engine.js —
T9 node agent 的 prompt 注入 files.json 检索说明 很可能已经被 R-19 做掉、不用再建：R-19 的设计哲学（§4.6「读回侧」）明确拒绝了「注入一句『自己去索引里查』」这条路——describeInputs/resolveInboundLines 已经把声明过契约的输入直接解析成绝对路径塞进提示词，不依赖 agent 自己检索。T9 原始设想的场景（agent 主动查询未在边上声明的共享产物）目前没有对应的可调用工具——Claude CLI 只读被塞进提示词或提示它去 Read 的路径，graph_files 表对它是不可见的。先确认这个场景是否真的需要，需要则要设计一个新工具而不是「prompt 里加一句话」，不需要则直接划掉 system/templates/base/agent.md 等 T7
T10 ✅ 控制台：fan-in 等待态可视化（「在等哪几个节点」）+ 并行运行中的多节点高亮 —— 2026-08-21 已实现。新增 join-status.js（resolveJoinWait/joinWaitLabel，判据与引擎 activateSuccessTargets 同源），WorkGraphCanvas.vue 给 pending 的真 fan-in 节点画「⏳done/total」徽标 + 悬停明细；多节点高亮不需要新代码（.dot.running 已经按每节点各自状态渲染，T4/T6 落地时就生效了）；顺手把从未被任何调用方传值的 nextNodeId 改成 nextNodeIds 数组，接上 run.max_concurrency web/src/components/WorkGraphCanvas.vue、web/src/components/graph-console/{join-status.js,GraphRunPane.vue} T6
T11 ✅ 测试：批量拾取的并发幂等... 没有单独立项：随 T4/T6/T5 各自的实现同批写了（graph-engine-advance-batch.test.js 12 条、graph-engine-billing-gate.test.js 7 条、join-status.check.js 6 条断言），覆盖面与本行原计划一致（并发幂等/部分失败停等/额度生效都在），files.json rebuild 那半属于阶段 C（早就测过，见 T7/T8 状态） server/tests/unit/ T4-T8

三个阶段

阶段 含 交付 可否独立上线
A · 隔离 T1 ✅, T2 同一 agent 可安全并发调用 —— T1 已完成，只剩 T2（DevLoop 规格放宽） 基本具备
B · 并行 ✅ T3 ✅ T4 ✅ T6 ✅ T5 ✅（桩子）T10 ✅ fan-out 真正并发；解除单 root run 约束 ✅ 依赖 A，2026-08-21 全部完成
C · 产物索引 T7-T9 files.json + 按 task 分目录 ✅ 完全独立于 A/B，可最先做

阶段 C 与 A/B 无依赖，如果想先看到效果，可以先做 C（它是用户明确要求过的第 3 项）。

2026-08-20 校准：C 已经完成，A 的 T1 也完成了（都是在 P3C 那几批里顺手落的， 当时没回来更新这份文档）。真正剩下的是 B：max_concurrency 列、advanceBatch、 三层额度取小、并行执行与部分失败降级，以及 T10 的控制台可视化。 这一段是「文档落后于代码」的又一例 —— 判断 P4 还剩多少工作量时， 先照着任务表逐条 grep 一遍代码，别照文档估。

2026-08-21 实现记录（T3/T4/T6）：

  • server/services/work-graph-db.js：graph_runs 加 max_concurrency（可空列 + 存量库迁移）， 新导出常量 DEFAULT_MAX_CONCURRENCY=5，createRun 新增 maxConcurrency 参数并校验/持久化。
  • server/services/graph-engine.js：把 advanceOne 拾取节点之后的整段（建 ctx → 执行 → settleNode） 原样抽成 runClaimedNode(runId, run, def, defNode, nodeName, picked, opts)，advanceOne 改成调它 （逐字同行为，靠现有 40 个用例背书，跑绿）。新增 advanceBatch(runId, opts)：maxConcurrency<=1 委托 advanceOne；>1 时按 §4.1 决策逐行 sse.transitionNode 拾取（不包裹事务）、 Promise.allSettled 并发跑 runClaimedNode。两者都从 module.exports 导出。
  • 新测试 server/tests/unit/graph-engine-advance-batch.test.js（5 条，diamond 图 entry→{a,b,c}→join）： fan-out 真并行（不借助 setImmediate/sleep，靠「advanceBatch 在自己第一次 await 之前全程同步」 这条性质直接同步断言）、批量拾取跳过已被抢走的候选、部分失败时 join 保持 pending 且 run 收敛到 blocked、maxConcurrency<=1 委托行为、run.max_concurrency 持久化生效。
  • 全量 npx vitest run：147 文件 / 1347 用例全绿，零回归。
  • 没做的：advanceBatch 还没接进 runAuto/路由——自动模式今天仍然只调 advanceOne， 实际生产流量拿不到并行，这是接下来的线（大概率是 T10 之前、或与它同批）。T5（欠费门 + 自动恢复 触发器）仍卡在计费系统接口确认，T10（控制台可视化）未动。

2026-08-21 追加：advanceBatch 接进 advanceTree/runAuto（同一天，紧接上面那批）：

  • advanceTree（runAuto 每一步都调它）里 advanceOne(r.id, opts) 换成 advanceBatch(r.id, opts)—— 「推最深的一个 active run」这个 tree-walk 逻辑不变，变的是「推」这一步本身现在能一次 claim 一批。 .driver 的调用方（生产路由、测试）一律只读 .ok，不依赖 .node/.results 的具体形状—— 核实过全仓库唯一消费方是 advanceTree 自己的循环判定 + 两个 blind-spot 测试文件，两者都只用 .ok，这次改动不需要做返回形状的兼容层。
  • 审这段时抓到一个真 bug 并顺手修了：advanceBatch 的 no-ready-node / taken-by-other 分支原来写的是 ok:true，跟 advanceOne 用 result() helper 的惯例（这两种情形一律 ok:false） 不一致。不修的话接进 runAuto 后，一个已经收敛的 run 会被自动循环一路空转到 maxSteps（1000） 才停——不是崩溃，但是真实的效率/语义回归，而且正好是旧测试从没试过「对已收敛的 run 连续调 advanceBatch」才漏掉的那种 bug。已修好并补了回归用例。
  • 新增 2 条测试（同一文件）：ok:false 语义与 advanceOne 对齐（直接绕开引擎构造 「run_status 还是 running 但没有 ready/running 节点」这个状态，同款手法 graph-engine.test.js 已经在用）；runAuto/advanceTree 端到端确实吃到并行——用真实 setTimeout 延迟（不是同步 deferred）证明 a/b/c 三个 executor 调用有时间窗口重叠，不是「反正都同步排到一起」的假象。
  • 全量 npx vitest run：147 文件 / 1350 用例全绿，零回归。
  • 仍然没做的：advanceTree 一次只推「最深的一个」active run，兄弟子 run（比如两个并行 subgraph 节点各自起的子 run）不会同时被推——它们靠 runAuto 外层循环一轮一轮轮流服务， 不是真并发（已在 advanceTree 加了 ponytail 注释记这笔）。真并发目前只发生在同一个 run 内部。这个跨 run 兄弟并发是否值得做，留给 T10 之后再看有没有真实场景撞上。

2026-08-21 追加：T5 落地（同一天，紧接上面那批）：

  • 用户明确决策：欠费判据「先搭可插拔的桩子」——真实计费接口依赖计费系统那边确认，不等它， 先把挂载点和恢复机制落地。setBillingGate(fn) 与 setAgentExecutor/setPlanWorkGraph 同款注入模式；checkBilling(run) 未注入时恒 {ok:true, inArrears:false}。两处调用点 （advanceOne、advanceBatch）都紧跟在 checkBudget 之后——欠费是账户级门，预算是 任务级门，两个维度不合并。
  • suspendRunTree(run, opts) 加了 reason/summary 参数（默认值保持旧调用方——checkBudget 那条路径——行为不变），欠费走同一个函数只是 reason='billing-arrears'。graph_runs 新增 block_reason 列（suspendRunTree 写、startRunSync「启动」时无条件清空）+ 复合索引 (run_status, block_reason) WHERE parent_run_id IS NULL，配 resumeBillingClearedRuns() 的扫描查询：找出所有欠费挂起的 root run，对每条重新查一次欠费状态，清了就代其 startRun。 谁来调用这个扫描函数、多久扫一次，留给计费系统事件/轮询接通之后再定。
  • 审这段时抓到第二个真 bug：advanceBatch 原来是「先查 budget、再查候选」，跟 advanceOne 的既有顺序（先确认真有 ready 候选，才查 budget——advanceOne 注释原话 「拾到了 ready 节点（=真要花钱了）才查，避免空转时把已跑完的 run 误挂起」）反着来。 后果：一个已经收敛（零 ready 节点）只是恰好预算也耗尽的 run，会被误判成 budget-exhausted 而不是正确收敛到 completed。接欠费门之前先把这个顺序修对， 两道新旧门用同一个正确的位置。
  • 新增测试 graph-engine-billing-gate.test.js（7 条）：零影响、advanceOne/advanceBatch 欠费挂起、startRunSync 清空 block_reason、resumeBillingClearedRuns 正确恢复/放过、 按 companyId 限定扫描、上面那条排序 bug 的回归用例。
  • 踩到并处理了一次真实的并发编辑事故：写 T5 期间发现 work-graph-db.js 被另一个会话 同时编辑（重写 validateFailFallback，31 号文档那条线，当时未完成、会让 51 个测试失败）， 与我的 block_reason 改动混在同一份工作区文件里。没有跟着 git add -A，改用 git diff 自动生成的 patch 只保留自己的 3 处 hunk（git apply --recount --cached）， 再用一次性的 git worktree add --detach 临时工作树（跑完 git worktree remove 清掉） 把这批 staged 内容单独跑一遍全量测试，确认自己的改动跟对方未完成的那部分互不依赖， 最后才 commit。过程中还手滑把上一条 commit 的说明文字贴成了另一条无关 commit 的原文， 用 git commit --amend 当场改正（那次 amend 合法——是刚提交、还没推送、也没有任何东西 叠在它上面的自己的commit，不是在改别人的历史）。这条经验值得记：共享工作目录下， commit 前先 git diff 走查一遍两个待提交文件的内容，不要假设「我改的文件只有我的改动」。

六、验收标准

  1. 并发隔离：同一 system agent 被两个并行节点同时调用，两次对话的上下文互不污染（各自有独立 session）。
  2. 批量拾取幂等：并发调用两次 advanceBatch，拾取到的节点集合无交集，且没有节点被漏掉。
  3. fan-out 真并行：一张有 3 个并行分支的图，自动模式下三个节点同时处于 running（而不是依次），且总墙钟明显短于串行。
  4. 部分失败停等：3 个并行分支中 1 个失败时，fan-in 节点保持 pending 不被点亮；控制台能显示「在等哪几个节点」。
  5. 额度生效：max_concurrency=2 的 run 上有 5 个 ready 节点时，同时 running 的不超过 2 个。
  6. 单公司多 run：同一公司可同时有 3 个 active root run，第 4 个被拒绝且错误信息明确。
  7. 手动模式不变：maxConcurrency=1，「下一步」行为与 P3 完全一致（P3 已有测试全绿）。
  8. files.json：节点产出后索引自动追加；删掉 files.json 后 rebuild 能从节点行完整重建；两个 task 的同名产物（都叫 prd.md）不互相覆盖。

七、影响面

文件 改动
server/src/core/session-pool.js maxSessions 上限；getKey 的 scope 参数实际启用
server/src/core/agent-manager.js 调用 getKey 时传 scope
server/services/work-graph-db.js graph_runs.max_concurrency 列；DROP 单 root run 唯一索引
server/services/graph-engine.js advanceBatch；额度计算；并行执行与错误降级；产物路径改 tasks/{taskId}/
server/services/company-files-index.js 新增
server/services/goal-contract.js 契约文件路径归并到 tasks/{taskId}/
web/src/views/GraphConsole.vue fan-in 等待态、多节点并行高亮
docs/prd/newfunction/*.html §12 不变量放宽（改完必须跑 npm run spec:extract）
system/templates/base/agent.md files.json 检索说明

明确不改：P3 的 join 语义（graph-engine.js:1078 已正确）、熔断与预算语义、手动/自动共用同一原语的设计、workDir 指向私有目录的约定（P1 §3.3 已论证）。

八、风险 / Open Questions

  1. 并行让预算烧得更快，但预算语义不变。任务级总预算是「只增不减的共池」（P3 已实现），并行不改变总量，只改变消耗速率。控制台的成本提示需要相应更新——用户点「自动」时看到的预估时间会大幅缩短，但花费不变。
  2. 改 DevLoop 规格的连带风险（T2）。§12 第一条不变量是 DevLoop 的，放宽它理论上不影响 DevLoop 自身（它的 runProject 波内本来就是串行的），但必须跑一遍 DevLoop 全部测试确认。
  3. maxSessions 上限触顶时的行为未定。额度为 0 时是「等待下一轮」还是「拒绝并报错」？本文档 §4.4 选了前者（不报错、等下一轮），但如果一个 run 长期抢不到额度会静默卡住——需要一个「等待超时」告警，否则表现为「不动了」。留待实现时定阈值。 按 2026-08-21 决策已解决：公司级/机器级不再设硬顶，「长期抢不到额度」这个场景基本不会出现了。账户欠费门定了——复用 suspendRunTree 的挂起语义（reason='billing-arrears'），跟预算耗尽是同一条路径，不发明第二种失败形态。新缺口：欠费清零后的恢复今天要人手点「启动」，无人值守场景下没人点——需要一个自动恢复触发器（欠费状态清除时批量对 blocked 的 root run 调 startRun），细节见 §4.4 决策块。欠费检查本身怎么接、恢复触发器订阅什么事件源，都要等计费系统那边的接口确认。
  4. files.json 的并发写入。并行节点会同时追加索引，需要串行化（文件锁或走 SQLite）。本文档设计的是 JSON 文件形态（符合用户要求「一个 files.json 文件」），但并发追加是真实风险——可能需要退化为「引擎内单写者队列」。 已随 §4.6 的 v0.2 重写作废：产物索引早就从「一个 files.json 文件」改成了 graph_files SQLite 表（阶段 C 已完成）。并发追加不需要文件锁——indexNodeOutputs 是 settleNode 内部的同步调用，跟 §4.3 证明 join 不需要额外锁是同一个道理（Node 单线程事件循环 + better-sqlite3 单写者，写表本身已经串行）。这条风险不成立，留着只是防止以后有人照旧设计去实现一个不存在的 JSON 文件锁。
  5. 产物索引的 consumedBy/契约声明的准确性。graph_edge_contracts 的 needs/produces 是声明式的（规划时写「这条边应该传什么」），不是实测的。如果规划 agent 声明错了，validateGraph 的 data-contract 规则能拦住「声明要吃的 kind 全图没人产」这类静态错误，但拦不住「声明的 kind 与实际语义对不上」这种语义错误。缓解方式不变：索引/契约是给 agent 的强提示（引擎直接把解析出的路径递到提示词里），不是不可绕过的约束，agent 仍可读同一 task 下任何已登记的产物。

九、与其他阶段的关系

  • P3：本阶段完全建立在 P3 的引擎之上，不推翻任何 P3 决策。P3 的「手动/自动共用同一原语」「join 语义」「熔断与预算」「三层暂停级联」全部保留。
  • P5（自我进化 / L4）：无依赖，可并行推进。但 L4 的「agent dream 离线批处理」会受益于 files.json——跨公司汇总当日执行经验时，产物索引是天然的输入源。
  • P6（DevLoop 收编）：T2 放宽的不变量是 P6 的前置——DevLoop 的 runProject 波内串行（loop-controller.js:609 注释 // 串行跑）正是被同一条不变量挡住的，P4 做完后 DevLoop 自己也能并行。