fix(graph-engine): 卡在 running 且背后进程已死的节点持续性存活扫描（45 号文档 Part A-C）

真实事故：h3video 公司 h3-story-draft 节点卡在 status=running，背后 CLI 会话已死但服务器进程没重启，开机一次性孤儿扫描/goal-task 巡检/wallclock 看门狗均看不到，ceo 被转发问题后绕过引擎自己拉会话，陷入死循环。 - sweepStaleRunningAgentCalls + startStaleAgentCallWatchdog：运行时长超阈值（默认 25 分钟）的 agent_call 节点判 infra_flake 原地重跑，5 分钟一次巡检，挂进 server/index.js - ceo/tools.md 补 force-fail 端点（已有，未改代码）的使用文档 + 禁止自拉会话的规则 - ceo/heartbeat.md 同步更新"不用管的"一节 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WjFL1nfPDqZnJeuskYHwvs

fix(graph-engine): 卡在 running 且背后进程已死的节点持续性存活扫描（45 号文档 Part A-C）
真实事故：h3video 公司 h3-story-draft 节点卡在 status=running，背后 CLI 会话已死但服务器进程没重启，开机一次性孤儿扫描/goal-task 巡检/wallclock 看门狗均看不到，ceo 被转发问题后绕过引擎自己拉会话，陷入死循环。 - sweepStaleRunningAgentCalls + startStaleAgentCallWatchdog：运行时长超阈值（默认 25 分钟）的 agent_call 节点判 infra_flake 原地重跑，5 分钟一次巡检，挂进 server/index.js - ceo/tools.md 补 force-fail 端点（已有，未改代码）的使用文档 + 禁止自拉会话的规则 - ceo/heartbeat.md 同步更新"不用管的"一节 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WjFL1nfPDqZnJeuskYHwvs
yibo
1 parent 364788ae
Showing 7 changed files with 407 additions and 13 deletions
docs/README.md
docs/todo/system-design/45-graph-run-node-liveness-recovery.md
server/index.js
server/services/graph-engine.js
server/tests/unit/graph-engine-stale-agent-call-sweep.test.js
system/agents/ceo/heartbeat.md
system/agents/ceo/tools.md
@@ -61,7 +61,7 @@ Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `d
 | [37-org-graph-department-scoping.md](./todo/system-design/37-org-graph-department-scoping.md) | 📝 **设计讨论，调用点扫描已完成，尚未立项实现**。现状 org graph 按 `company_id` 单例（`27-P2` 标题原文即"公司级"），塞不下 HR/财务/市场这类跟"交付流水线"无关的公司常设职能——`system/agents/hr/`（"招·留·管·退"）本体已存在却从没被装进任何图，全靠 fire-and-forget chat 招聘、无图执行审计轨迹。提议把 org graph 作用域从 `company_id` 升级为 `(company_id, department_id)`，一家公司可装配多张部门图，每张仍保持人工固定/慢变/可审计。全仓库调用点扫描结论：改造面是最初估算的 4 倍——真正的单点真相在 `work-graph-db.js:readDefGraph` 的裸 SQL 不变式（不在服务层），还牵涉两个易混淆服务文件间必须字节级一致的重复唯一索引、独立的 `graph-seed-service.js` 对账子系统、`company-hire-org-layer.test.js` 专属测试、`orggraph-planning`/`task-planning` 两份 agent 人设文档的自我认知改写 |
 | [36-prd-agent-methodology-training-feasibility.md](./todo/system-design/36-prd-agent-methodology-training-feasibility.md) | 📝 **调研 + 阶段一/二均已完成**。回应"落地页太单薄是不是该用 Innovator 先训练专业 agent、再用 Dream 持续迭代"——认同方向。**阶段一**：`graph-engine.js` 结算节点后把 `success`/`fail:<reason>` 写进本体 `memory.md`（此前只有人类对话路径会写，Dream 天天空转）。**阶段二**：新建独立试验节点 `prd-methodology-trial` 走真实 Hunt→Digest→Evolve，2 轮收敛（96/97 分，真实基线 50 分），三个真实历史项目反推验证方法论有效；过程中连带修复同一个 2026-08-16 改名批次遗留的 5 处 `innovator`→`org-innovator` 死链（后端两处硬编码、前端"重新训练"按钮、`/api/agent/list` 展示 id 来源的四个 `config.json`），以及 `AgentScaffold` 默认模板一处裸相对路径缺陷。结论：FDE 对方法论类角色确实管用，但收敛速度/验收严谨度依赖任务书显式写明的自纠正要求，非免人工黑盒。环节 3（训练产物 → 雇佣本体转换）尚未开工 |
 | [34-validator-scored-without-real-deliverable.md](./todo/system-design/34-validator-scored-without-real-deliverable.md) | 📝 **调研记录，checklist 已查完**。最初以为 `org-coder-impl` 从未产出任何 HTML/CSS，后来发现真实网站其实存在于 `graph_files` 索引不覆盖的「项目根」目录（已顺手修：控制台「产物」面板现在会展示项目根）。追加查清 validator 有没有真的做浏览器级检查——中途自我订正一次：不是"没工具做不到"（`bash` 能走到仓库自带的 Playwright，另一条对照任务证明可行），是**没人教它这么做**；抽查另外两个项目根后发现**验证严谨度完全不稳定**（同类任务有的做了真实 Playwright 级验证、有的只做静态正则、有的没验证就被取消），根因很可能是新招聘的 `unit-tester` 本体撞上了 [32 号文档](./todo/system-design/32-hire-body-fill-reliability.md) 那类"装配没填充完"的真实样本，不是平台工具限制 |
-| [45-graph-run-node-liveness-recovery.md](./todo/system-design/45-graph-run-node-liveness-recovery.md) | 📝 **设计中，未实现**。真实事故：h3video 公司一个 `agent_call` 节点卡在 `status=running`、背后 CLI 进程已死，服务器主进程没重启——心跳（纯 LLM 驱动）、开机一次性孤儿扫描（`sweepOrphanedRunningNodes`，只在进程启动时跑一次）、goal/task 巡检（判据是 `blocked`，不是 `running`）、wallclock 看门狗（按预算不按存活）四层机制全部盖不到；`ceo` 心跳指令写"引擎自己有重试机制"但实际没有持续性巡检，导致 `ceo` 被转发问题后自己绕过引擎直接拉会话，陷入死循环。提案拆四个 Part：A 把孤儿扫描从"开机一次"升级成"持续性存活扫描"（复用 `SessionPool`）、B 给 agent 一个正确的"重试卡住节点"工具而非自己拉会话、C 更新 `heartbeat.md` 措辞、D（可选）节点补显式心跳字段 |
+| [45-graph-run-node-liveness-recovery.md](./todo/system-design/45-graph-run-node-liveness-recovery.md) | ✅ **Part A/B/C 已实现**（2026-08-31），**Part D 有意延后**。真实事故：h3video 公司一个 `agent_call` 节点卡在 `status=running`、背后 CLI 进程已死，服务器主进程没重启——心跳（纯 LLM 驱动）、开机一次性孤儿扫描、goal/task 巡检（判据是 `blocked` 不是 `running`）、wallclock 看门狗（按预算不按存活）四层机制全盖不到；`ceo` 被转发问题后自己绕过引擎拉会话，陷入死循环。**Part A**：调查发现 `SessionPool` 是每次调用现造即回收的一次性对象，没有可查询的存活注册表，原设计不可行，改用「运行时长超阈值（默认 25 分钟）+ 只扫 `agent_call` 节点」，新函数 `sweepStaleRunningAgentCalls`/`startStaleAgentCallWatchdog`（`graph-engine.js`），5 条新单测。**Part B**：`force-fail` 端点（42 号文档已实现）本身就够用，零新后端代码，只在 `ceo/tools.md` 补了使用文档 + 明确禁止绕过引擎自拉会话。**Part C**：`ceo/heartbeat.md` 同步更新。**Part D**（节点补显式心跳字段，消除 Part A 阈值判据的误伤局限）未做，见文内「实现记录」的理由 |
 | [43-task-decomposition-granularity.md](./todo/system-design/43-task-decomposition-granularity.md) | ✅ **Phase 0-4 全部已实现**（2026-08-31）。回应"org-planner 出 brd/prd/sdd 后，任务看板能不能展示成 task/sub-task 树，coder-validator 按清单逐条开发验收"。`tasks` 加 `acceptance_mode`/`parent_task_id`（后者复用既有列）；`task-planning` 判断要不要拆（硬规则 5 开例外让 LLM 写这一个字段）；org-planner 收尾把 `acceptance.md` 物化成子任务；`coder-validator` 新增 `task subtask-result` 工具逐条上报，`settleNode()` 新增闸门强制核对子任务全 `completed` 才认 success；看板加子任务展示。**落地时订正了一处原计划想岔的架构假设**：org-planner 在 org 层永远是 `subgraph` 节点（不是 agent_call），真跑数据显示它当前展开成的 `planner.json` 5 节点子图里，`goal-benchmark`/`planner-validator` 两节点常被 skip，`acceptance.md` 未必真的产出——钩子已改成扫子 run 全节点、找不到就优雅降级为 holistic，不阻塞主产出，但"子任务一定会长出来"这件事目前是尽力而为不是保证，见文档"实现记录"一节的遗留风险说明。全量单测 1120/1123 通过（3 个失败与本次改动无关，本次改动前即存在） |
 ## todo/future/（暂缓，非当前重心）
 # 45 ﾂｷ 蜊｡蝨ｨ `running` 荳碑レ蜷手ｿ帷ｨ句ｷｲ豁ｻ逧 graph 闃らせ梧ｲ｡譛我ｻｻ菴墓惻蛻ｶ莨夐譁ｰ謐｡襍ｷ譚･
-> **迥ｶ諤**: 統 隶ｾ隶｡荳ｭ梧悴螳樒鴫縲よ悽譁｡｣蜿ｪ譏ｯ隸頑妙 + 菫ｮ豕墓署譯茨ｼ御ｾ**豐｡譛 CTO縲∝宵譛 CEO** 逧ｽ灘燕蝗｢髦滄鄂ｮ荳具ｼ
-> 逕ｱ莠ｺ域荳倶ｸ谺｡荳馴葎螟炊逧ｼ夊ｯ晢ｼ画潔荳矩擇逧 Part 諡騾先擅謾ｹ縲
+> **迥ｶ諤**: 笨 **Part A/B/C 蟾ｲ螳樒鴫**2026-08-31会ｼ**Part D 譛ｪ螳樒鴫域怏諢丞ｻｶ蜷趣ｼ瑚ｧ∬ｯ･闃よ眠蠅櫁ｯｴ譏趣ｼ**縲
+> Part A 關ｽ蝨ｰ譌ｶ蟇ｹ譛蛻晉噪隶ｾ隶｡蛛壻ｺｸ谺｡隶｢豁｣窶披碑ｧ∽ｸ矩擇縲御ｺ斐∝ｮ樒鴫隶ｰ蠖輔搾ｼ悟悪謖峨悟屁縲∝ｻｺ隶ｮ菫ｮ豕輔榊次譁
+> 逶ｴ謗･蜴ｻ莉｣遐謇ｾ SessionPool 逶ｸ蜈ｳ逧ｸ懆･ｿ碁ぅ譚｡霍ｯ郤ｿ隹衍蜷主愛螳壻ｸ榊庄陦鯉ｼ悟ｷｲ謾ｹ驕薙
 > **譌･譛**: 2026-08-31
 > **蜿醍鴫蝨ｺ譎ｯ**喇3video 蜈ｬ蜿ｸ goal `G-mtgmij2n-26d8` / task `T-mtgmij2n-d7ac`亥､ｪ遨ｺ豁悟鴬鬚相迚ｼ臥噪
 > `h3-story` 髦ｶ谿ｵ蟄仙崟驥鯉ｼ形h3-story-draft` 闃らせnodeKind: agent_call`形rn_04a9474682f3`
@@ -159,7 +160,69 @@ Claude CLI 蟄占ｿ帷ｨ玖蟾ｱ豁ｻ莠/陲ｫ荳ｭ譁ｭ縲ＡsweepOrphanedRunningNodes` 莉手ｿ帷
 ---
-## 莠斐∽ｸ榊惠譛ｬ譁｡｣闌峩蜀
+## 莠斐∝ｮ樒鴫隶ｰ蠖包ｼ2026-08-31
+
+### Part A售essionPool 譁ｹ譯郁ｰ衍蜷主愛螳壻ｸ榊庄陦鯉ｼ梧隼逕ｨ霑占｡梧慮髟ｿ髦亥ｼ
+
+蜀吶悟屁縲∝ｻｺ隶ｮ菫ｮ豕輔肴慮莉･荳ｺ `SessionPool`server/src/core/session-pool.js`画弍荳ｪ謖∫ｻｭ蟄伜惠縲∝庄譟･隸｢
+逧ｼ夊ｯ晄ｳｨ蜀瑚｡ｨ悟ｮ樣刔蜴ｻ謗･逧慮蛟吝書邇ｰ**荳肴弍**啻server/services/graph-engine.js` 驥梧ｯ丈ｸ谺｡
+`agent_call` 闃らせ豢ｾ蜿鷹譏ｯ `defaultAgentExecutor`377 陦鯉ｼ臥鴫騾荳荳ｪ `new AgentManager({}, ...)`
+隹畑扈捺據育爆閾ｳ謌仙粥荵滉ｸ譬ｷ蛾ぅ荳ｪ `AgentManager`/`SessionPool` 蟆ｱ豐｡莠ｺ蠑慕畑莠ｼ檎ｭ臥捩陲ｫ GC窶披**蜈ｨ莉灘ｺ
+豐｡譛我ｸ荳ｪ"霑吩ｸｪ闃らせ閭悟錘霑俶怏豐｡譛画ｴｻ霑帷ｨ"逧戟扈ｭ諤ｧ逋ｻ隶ｰ螟**縲よ潔蜴溯ｮ｡蛻貞渚譟･ key 莨壽ｰｸ霑懈衍荳榊芦檎ｭ我ｺ
+荳荳顔ｺｿ蟆ｱ謚頑園譛芽ｶｿ蛟ｼ逧鰍轤ｹ蜈ｨ蛻､謌仙ｭ､蜆ｿ瑚ｿ呎弍譛ｬ蜿ｯ閭ｽ騾謌千噪荳谺｡逵溷ｮ櫁ｯｯ莨､悟･ｽ蝨ｨ隶ｾ隶｡髦ｶ谿ｵ逧
+"霑吩ｸｪ諤晁ｷｯ隕∽ｸ崎ｦ∬｡悟ｾ鈴"霑吩ｸ豁･蜈亥★莠ｼ御ｻ｣遐∵ｲ｡譛臥逹髞咏噪蛛ｮｾ蜀吩ｸ句悉縲
+
+**謾ｹ逧婿譯**啻sweepStaleRunningAgentCalls`graph-engine.js`蛾蝗槫芦蜥檎鴫譛
+`sweepOrphanedRunningNodes`/`sweepWallclockBudgets` 蜷御ｸ荳ｪ鬟朱勦遲臥ｺｧ逧愛謐ｮ窶披斐瑚ｿ占｡梧慮髟ｿ雜ｿｸ荳ｪ
+菫晏ｮ磯蛟ｼ縲搾ｼ磯ｻ倩ｮ､ 25 蛻帖会ｼ御ｸ榊★逵溷ｮ槫ｭ俶ｴｻ謗｢豬九ょ宵謇ｫ `node_kind='agent_call'` 逧鰍轤ｹsubgraph`
+闃らせ逧慮髟ｿ讓ｪ霍ｨ螟壻ｸｪ蜀Κ隹畑悟酔荳蝗ｺ螳夐蛟ｼ螂嶺ｸ雁悉隸ｯ莨､髱｢螳悟荳榊庄謗ｧ梧悽谺｡荳榊★瑚ｷ溷屁.4 蜴滓署譯育噪
+逅罰荳閾ｴ会ｼ嬾ode_kind 譏ｯ螳壻ｹ牙ｱょｭ玲ｮｵ御ｸ榊惠 `graph_run_nodes` 陦ｨ荳奇ｼ悟愛譁ｭ譌ｶ謖 `run_id` 郛灘ｭ
+`defIndex(run)` 騾占｡梧ｸ蟇ｹ碁∩蜈榊酔荳荳ｪ run 驥檎噪螟壻ｸｪ蛟咎芽｡碁螟崎ｯｻ荳驕榊ｮ壻ｹ牙崟縲
+
+螟咲畑 `sweepOrphanedRunningNodes` 蜀ｱゅ形transitionNode` + `routeFailure`縲埼ぅ谿ｵ騾ｻ霎托ｼ梧歓謌
+蜈ｱ逕ｨ逧 `_reapStaleRunningNodes(rows, summary)`御ｸ､荳ｪ隹畑譁ｹ蜷譟･閾ｪ蟾ｱ逧 `rows`縲よ撃
+`startStaleAgentCallWatchdog`5 蛻帖荳谺｡逧 `setInterval` + `unref()`会ｼ瑚ｵｷ霍醍せ蝨ｨ
+`server/index.js`檎ｴｧ霍溷惠蠅咎帖逵矩葎迢鈴ぅ谿ｵ蜷朱擇悟ｼ譛ｺ蜈郁｡･荳谺｡蜈ｨ驥乗沖謠丞襍ｷ螳壽慮蝎ｨ悟酔荳荳ｪ蠖｢迥ｶ縲
+
+豬玖ｯ包ｼ啻server/tests/unit/graph-engine-stale-agent-call-sweep.test.js`5 荳ｪ逕ｨ萓具ｼ郁ｶ蛟ｼ蛻､螳/
+譛ｪ雜蛟ｼ荳榊勘/髦亥ｼ蜿ｯ隹/subgraph 荳榊惠闌峩蜀/譌蛟咎画慮螳蛾撕 no-op会ｼ瑚ｷ滓里譛臥噪
+`graph-engine-orphan-sweep.test.js`/`graph-engine-wallclock-watchdog.test.js` 蜷御ｸ螂鈴囈遖ｻ謇区ｳ輔
+蜈ｨ驥 `vitest run server/tests/unit` 1134/1136 騾夊ｿｼ亥嘗 2 荳ｪ螟ｱ雍･譏ｯ `.env.example` 蜿倬譬ｸ蟇ｹ荳
+豬玖ｯ id 遞ｳ螳壽ｧ螳亥梱瑚ｷ滓悽谺｡謾ｹ蜉ｨ逧枚莉ｶ譌蜈ｳ梧隼蜉ｨ蜑榊ｰｱ蟾ｲ蟄伜惠峨
+
+**蟾ｲ遏･螻髯**亥ｦょｮ櫁ｮｰ蠖包ｼ御ｸ肴弍謗ｩ逶厄ｼ会ｼ夐蛟ｼ蛻､謐ｮ荳肴弍逵溷ｮ槫ｭ俶ｴｻ謗｢豬銀披比ｸ荳ｪ蠑ょｸｸ諷｢菴悄逧ｿ伜惠霍醍噪蜊墓ｬ｡
+隹畑螯よ棡雜ｿ 25 蛻帖御ｼ夊｢ｫ隸ｯ蛻､謌先ｭｻ謗峨∝次蝨ｰ驥崎ｷ托ｼ井ｻ｣莉ｷ譏ｯ豬ｪ雍ｹ荳谺｡逵溷ｮ櫁ｰ畑御ｸ咲Ι attempt 隶｡謨ｰ
+荳堺ｼ壼ｯｼ閾ｴ謨ｰ謐ｮ髞吩ｹｱ会ｼ帛渚霑擂荳荳ｪ蛻壽ｭｻ荳榊芦 25 蛻帖逧鰍轤ｹ瑚ｿ呎ｮｵ譌ｶ髣ｴ驥瑚ｿ俶弍豐｡莠ｺ邂｡瑚ｷ"霑帷ｨ矩蜷ｯ"
+荵句､冶ｿ吩ｸ邀ｻ螟ｱ雍･荵句燕逧憾諤∫嶌豈疲弍蜃謾ｹ蝟ｼ御ｽｸ肴弍"遶句綾蜿醍鴫"縲りｦ∝★蛻ｰ譖ｴ蜃ｼ碁怙隕 Part D 驍｣遘咲悄螳
+蠢ｷｳ菫｡蜿ｷ縲
+
+### Part B啻force-fail` 遶ｯ轤ｹ蟾ｲ扈冗鴫謌仙ｭ伜惠悟宵陦･莠 tools.md 譁｡｣
+
+隹衍蜿醍鴫 `POST /api/graph-runs/:id/nodes/:nodeId/force-fail`server/routes/graph-run.js:395`
+螳樒鴫 `graph-engine.js` 逧 `forceFailNode`42 蜿ｷ譁｡｣ Phase 1b 蟾ｲ扈丞★螳御ｺｼ瑚ｯｭ荵牙ｮ悟蛹ｹ驟崎ｿ咎隕∫噪
+荳懆･ｿ壼宵蝨ｨ闃らせ `status='running'` 譌ｶ蜿ｯ逕ｨ御ｼ `failReason:"infra_flake"` 莨夊ｵｰ蜴溷慍驥崎ｷ台ｸ咲Ι
+`attempt`御ｼ蛻ｫ逧/荳堺ｼ襍ｰ豁｣蟶ｸ螟ｱ雍･霍ｯ逕ｱ縲**豐｡蜀吩ｸ陦梧眠蜷守ｫｯ莉｣遐**悟宵蝨ｨ `system/agents/ceo/tools.md`
+陦･莠悟今菴冗噪 run 闃らせ縲堺ｸ闃ゑｼ域惹ｹ域衍蛻ｰ逵滓ｭ｣蜊｡菴冗噪驍｣荳螻ゅ∵惹ｹ郁ｰｿ吩ｸｪ遶ｯ轤ｹ会ｼ悟ｹｶ謚翫御ｽ荳崎ｯ･逕ｨ逧
+蟾･蜈ｷ縲崎｡ｨ驥碁ぅ譚｡"荳崎ｮｸ遒ｰ graph_run_nodes"逧ｧ謾ｹ謌仙ｸｦ蜚ｯ荳萓句､厄ｼ悟酔譌ｶ譁ｰ蠅樔ｸ譚｡"荳崎ｮｸ閾ｪ蟾ｱ諡我ｼ夊ｯ晏悉
+莠ｲ閾ｪ霍"逧ｧ窶披皮峩謗･蟇ｹ蠎碑ｿ呎ｬ｡豁ｻ蠕ｪ邇ｯ莠区腐逧蝗縲
+
+### Part C啻heartbeat.md` 蟾ｲ譖ｴ譁ｰ
+
+"荳咲畑邂｡逧"荳闃らせ蜷堺ｺ Part A 逧ｸ､荳ｪ蜃ｽ謨ｰ悟ｹｶ蜉莠ｸ譚｡譁ｰ遶闃ゑｼ梧遑ｮ"逕ｨ謌ｷ荳ｻ蜉ｨ霓ｬ蜿醍噪蜊｡菴丈ｻｻ蜉｡"霑咏ｧ
+蝨ｺ譎ｯ隸･襍ｰ tools.md 逧ｸ､豁･豬∫ｨ具ｼ御ｸ崎ｮｸ閾ｪ蟾ｱ諡我ｼ夊ｯ昴
+
+### Part D壻ｻ肴悴螳樒鴫檎炊逕ｱ荳榊序
+
+Part A 關ｽ蝨ｰ蜷趣ｼ訓art D 逧ｻｷ蛟ｼ蛻､譁ｭ豐｡蜿倪披斐悟屁縲∝ｻｺ隶ｮ菫ｮ豕輔榊次譁ぅ蜿･"蜈亥★ Part A 鬪瑚ｯ∵譜譫懶ｼ御ｸ榊､溷
+荳願ｿ吩ｸｪ"萓晉┯謌千ｫ具ｼ瑚御ｸ泌屏荳ｺ Part A 譛扈域弍髦亥ｼ蛻､謐ｮ井ｸ肴弍逵溷ｮ槫ｭ俶ｴｻ謗｢豬具ｼ会ｼ訓art D郁鰍轤ｹ陦･譏ｾ蠑
+`last_heartbeat_at`檎罰鬩ｱ蜉ｨ螳噪 CLI 莨夊ｯ晏ｮ壽悄蝗槫牙ｦよ棡逵溷★瑚陦･荳 Part A 邇ｰ蝨ｨ霑吩ｸｪ"蠑ょｸｸ諷｢逧
+逵溷ｮ樔ｻｻ蜉｡莨夊｢ｫ隸ｯ蛻､"逧ｱ髯舌ゆｽｿ咎怙隕∵滑 nodeRunId 荳贋ｸ区枚荳霍ｯ遨ｿ騾丞芦 `ClaudeCliProtocol` 逧
+蟾･蜈ｷ謇ｧ陦悟ｿｷｳ蝗櫁ｰ育岼蜑埼ぅ螻ょ刻隶ｮ莉｣遐∝ｮ悟荳咲衍驕 graph 闃らせ逧ｭ伜惠会ｼ梧隼蜉ｨ髱｢蜥碁｣朱勦驛ｽ譏取仞譖ｴ螟ｧ
+霑呎ｬ｡豐｡蛛夲ｼ檎蕗扈吩ｸ倶ｸ谺｡譛臥悄螳櫁ｯｯ莨､譬ｷ譛ｬ縲∝ｼ蠕玲兜蜈･譌ｶ蜀榊､炊縲
+
+---
+
+## 蜈ｭ縲∽ｸ榊惠譛ｬ譁｡｣闌峩蜀
 - `ceo` 霑呎ｬ｡蜈ｷ菴謎ｸｺ莉荵井ｼ夐匚蜈･"think 豁ｻ蠕ｪ邇ｯ"域弍荳肴弍蟾･蜈ｷ隹畑蜊剰ｮｮ譛ｬ霄ｫ譛 bug縲∬ｿ俶弍郤ｯ邊ｹ陲ｫ蜊｡菴冗憾諤
   謳樊莠渚螟崎謌題ｿｽ髣ｮ俄披碑ｿ呎弍 harness/agent 陦御ｸｺ螻る擇逧琉鬚假ｼ瑚ｷ"闃らせ隸･諤惹ｹ郁｢ｫ閾ｪ蜉ｨ謐｡蝗樊擂"譏ｯ荳､蝗樔ｺ具ｼ
@@ -222,6 +222,20 @@ async function start() {
             } catch (err) {
                 console.error('[Startup] 墙钟看门狗启动失败:', err.message);
             }
+            // 45 号文档 Part A：持续性存活扫描。上面 sweepOrphanedRunningNodes 只在开机那一刻
+            // 抓「上一个进程实例被杀掉留下的孤儿」，抓不住「进程没重启、驱动某个 agent_call
+            // 节点的 CLI 会话中途死掉/被打断」这一半（真实事故：h3video 公司 h3-story-draft
+            // 节点）。同样先补一次全量扫描，再起 5 分钟兜底定时器，形状同墙钟看门狗。
+            try {
+                const engine = require('./services/graph-engine');
+                const swept = engine.sweepStaleRunningAgentCalls();
+                if (swept.swept.length) {
+                    console.log(`[Startup] 💤 存活扫描：处理 ${swept.swept.length} 条运行超时的 agent_call 节点`);
+                }
+                engine.startStaleAgentCallWatchdog();
+            } catch (err) {
+                console.error('[Startup] 存活扫描看门狗启动失败:', err.message);
+            }
             const heartbeatService = require('./services/heartbeat-service');
             heartbeatService.start();
             // 公司级心跳 (Pipeline 自动驱动)
@@ -3132,11 +3132,16 @@ function stopWallclockWatchdog() {
  *   测试用任意时刻构造场景。
  * @returns {{scanned:number, swept:Array<{runId:string, nodeRunId:string, infraRerun:boolean}>}}
  */
-function sweepOrphanedRunningNodes(cutoffIso) {
-  const rows = getDb()
-    .prepare(`SELECT id, run_id FROM graph_run_nodes WHERE status = 'running' AND started_at IS NOT NULL AND started_at < ?`)
-    .all(cutoffIso);
-
+/**
+ * 共用的「判孤儿→infra_flake 结算」内层循环，`sweepOrphanedRunningNodes`（开机一次性）与
+ * `sweepStaleRunningAgentCalls`（45 号文档 Part A：持续性存活扫描）各自查自己的 `rows`，
+ * 结算逻辑完全一致，不重复抄一遍 `transitionNode`+`routeFailure` 那一段。
+ *
+ * @param {Array<{id:string, run_id:string}>} rows
+ * @param {string} summary 落进 timeline 的人读摘要，两个调用方文案不同
+ * @returns {{scanned:number, swept:Array<{runId:string, nodeRunId:string, infraRerun:boolean}>}}
+ */
+function _reapStaleRunningNodes(rows, summary) {
   const swept = [];
   for (const row of rows) {
     try {
@@ -3147,7 +3152,7 @@ function sweepOrphanedRunningNodes(cutoffIso) {
       const changed = sse.transitionNode(row.run_id, row.id, 'running', 'fail', {
         failReason: INFRA_FLAKE_REASON,
         failNodeRef: null, outputRef: null, agentRunId: null, childRunId: null, completedAt: now(),
-      }, { summary: `开机孤儿节点清扫：服务器重启前处于 running，背后进程已不存在，判 infra_flake 交给既有熔断/重跑逻辑` });
+      }, { summary });
       if (!changed) continue; // 0 行 = 已经被别的路径结算过了，不重复处理
       const nodeRun = getRunNode(row.id);
@@ -3155,12 +3160,94 @@ function sweepOrphanedRunningNodes(cutoffIso) {
       routeFailure(row.run_id, def, nodeRun, out, null);
       swept.push({ runId: row.run_id, nodeRunId: row.id, infraRerun: out.infraRerun });
     } catch (err) {
-      console.error(`[graph-engine] sweepOrphanedRunningNodes node=${row.id} 异常: ${err.message}`);
+      console.error(`[graph-engine] _reapStaleRunningNodes node=${row.id} 异常: ${err.message}`);
     }
   }
   return { scanned: rows.length, swept };
 }
+function sweepOrphanedRunningNodes(cutoffIso) {
+  const rows = getDb()
+    .prepare(`SELECT id, run_id FROM graph_run_nodes WHERE status = 'running' AND started_at IS NOT NULL AND started_at < ?`)
+    .all(cutoffIso);
+  return _reapStaleRunningNodes(rows, `开机孤儿节点清扫：服务器重启前处于 running，背后进程已不存在，判 infra_flake 交给既有熔断/重跑逻辑`);
+}
+
+const STALE_AGENT_CALL_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+// 45 号文档 Part A 调查结论：graph 节点派发用的 AgentManager/SessionPool 是每次调用现造、
+// 调用完即回收的一次性对象（`defaultAgentExecutor`，本文件 377 行），全仓库没有一个持续存在、
+// 可查询的"这个节点背后还有没有活进程"的注册表——`sweepOrphanedRunningNodes` 能用的
+// "跟本次进程启动时间比"这条判据，对"进程没重启、单次调用中途死掉"这种情况完全用不上
+// （持续性）。在补一个真正的存活信号（45 号文档 Part D：驱动节点的 CLI 会话定期回写
+// last_heartbeat）之前，只能退而求其次——按「运行时长超过一个保守阈值」判定，与
+// `sweepWallclockBudgets` 对 run 级预算的处理是同一种取舍：可能会误判一个异常慢的真实
+// 长任务，也可能漏判一个刚死不久还没到阈值的节点，不是精确的存活探测。
+// 阈值只按 node_kind='agent_call' 收窄——subgraph 节点的"运行时长"横跨多个内部真实调用，
+// 拿同一个固定阈值判它会误伤得离谱，那类节点的存活状态应该递归看它的子 run，本次不做。
+const DEFAULT_STALE_AGENT_CALL_THRESHOLD_MS = 25 * 60 * 1000;
+
+/**
+ * 45 号文档 Part A：把「开机一次性孤儿扫描」延伸出一条持续性版本，抓"进程没重启、但驱动
+ * 某个 agent_call 节点的 CLI 会话中途死掉/被打断"这一半开机扫描看不到的场景（真实事故：
+ * h3video 公司 `h3-story-draft` 节点，见 45 号文档时间线）。
+ *
+ * 判据是"运行时长超过阈值"而不是真实存活探测，见上面 `DEFAULT_STALE_AGENT_CALL_THRESHOLD_MS`
+ * 那段注释里记的取舍——这是已知的、暂时接受的局限，不是本函数的 bug。
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.thresholdMs] 运行超过多久判定为"大概率死了"，默认 25 分钟
+ * @param {string} [opts.nowIso] 参照的"当下"时刻，默认真实当前时间；测试用固定值构造场景
+ * @returns {{scanned:number, swept:Array<{runId:string, nodeRunId:string, infraRerun:boolean}>}}
+ */
+function sweepStaleRunningAgentCalls(opts = {}) {
+  const thresholdMs = opts.thresholdMs ?? DEFAULT_STALE_AGENT_CALL_THRESHOLD_MS;
+  const nowIso = opts.nowIso || now();
+  const cutoffIso = new Date(Date.parse(nowIso) - thresholdMs).toISOString();
+
+  // node_kind 是定义层字段（work_graph_nodes/org_graph_nodes），graph_run_nodes 这张运行时表
+  // 只有 def_node_id——先按「running 超过阈值」把候选行都拿出来，再用 defIndex(run) 逐个查
+  // 它对应的定义节点是不是 agent_call，把 subgraph 节点过滤掉（defIndex 内部已缓存不了，
+  // 这里按 run_id 手动缓存一下，避免同一个 run 里多个候选节点重复读同一张定义图）。
+  const rows = getDb()
+    .prepare(`SELECT id, run_id, def_node_id FROM graph_run_nodes
+                WHERE status = 'running' AND started_at IS NOT NULL AND started_at < ?`)
+    .all(cutoffIso);
+
+  const defCache = new Map();
+  const agentCallRows = rows.filter((row) => {
+    let def = defCache.get(row.run_id);
+    if (def === undefined) {
+      const run = getRun(row.run_id);
+      def = run ? defIndex(run) : null;
+      defCache.set(row.run_id, def);
+    }
+    const node = def && def.nodes.get(row.def_node_id);
+    return node && node.nodeKind === 'agent_call';
+  });
+
+  return _reapStaleRunningNodes(
+    agentCallRows,
+    `持续性存活扫描：agent_call 节点 running 超过 ${Math.round(thresholdMs / 60000)} 分钟，判 infra_flake 交给既有熔断/重跑逻辑（45 号文档 Part A）`
+  );
+}
+
+let staleAgentCallSweepTimer = null;
+
+/** 起兜底定时器，形状照抄 `startWallclockWatchdog`：`unref()` + 幂等只留一个。 */
+function startStaleAgentCallWatchdog(intervalMs = STALE_AGENT_CALL_SWEEP_INTERVAL_MS, thresholdMs) {
+  if (staleAgentCallSweepTimer) return staleAgentCallSweepTimer;
+  staleAgentCallSweepTimer = setInterval(() => {
+    try { sweepStaleRunningAgentCalls({ thresholdMs }); } catch (err) { console.error(`[graph-engine] 存活扫描看门狗异常: ${err.message}`); }
+  }, intervalMs);
+  if (typeof staleAgentCallSweepTimer.unref === 'function') staleAgentCallSweepTimer.unref();
+  return staleAgentCallSweepTimer;
+}
+
+function stopStaleAgentCallWatchdog() {
+  if (staleAgentCallSweepTimer) clearInterval(staleAgentCallSweepTimer);
+  staleAgentCallSweepTimer = null;
+}
+
 /**
  * 扣减（「只增不减」，§四.A.3）。始终写 root run 那一行。
  * ponytail: 读-改-写不是原子的，当前单进程串行驱动（runAuto 一次只推一个节点）下够用；
@@ -5130,6 +5217,11 @@ module.exports = {
   // 42 号文档 Phase 1a：开机孤儿节点清扫（服务器重启杀掉 in-flight 进程，节点行留在 running）
   sweepOrphanedRunningNodes,
+  // 45 号文档 Part A：持续性存活扫描（进程没重启、agent_call 节点中途死掉的那一半开机扫描看不到）
+  sweepStaleRunningAgentCalls,
+  startStaleAgentCallWatchdog,
+  stopStaleAgentCallWatchdog,
+
   // 重试级联判据（§四.C 末段）
   diffContracts,
   applyRetryCascade,
+/**
+ * Unit Tests — graph-engine 的持续性存活扫描（45 号文档 Part A）
+ *
+ * 场景：服务器主进程没有重启，但驱动某个 agent_call 节点的 Claude CLI 会话在调用中途
+ * 死掉/被打断，`graph_run_nodes.status` 永远停在 'running'。开机一次性孤儿扫描
+ * （`sweepOrphanedRunningNodes`，按「早于本次进程启动时间」判定）看不到这种情况——本文件
+ * 测的是它的持续性版本：`sweepStaleRunningAgentCalls`，按「running 超过一个阈值」判定，
+ * 且只扫 `node_kind='agent_call'`（subgraph 节点的"运行时长"横跨多个内部调用，不适用
+ * 同一固定阈值，本次不做）。
+ *
+ * 隔离手法与 graph-engine-orphan-sweep.test.js 一致。
+ */
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+describe('graph-engine 持续性存活扫描', () => {
+  let wdb;
+  let engine;
+  let runsDir;
+  const TEST_DB_PATH = '/tmp/test-graph-engine-stale-agent-call-sweep.sqlite';
+
+  beforeAll(() => {
+    for (const f of [TEST_DB_PATH, `${TEST_DB_PATH}-shm`, `${TEST_DB_PATH}-wal`]) {
+      try { fs.unlinkSync(f); } catch {}
+    }
+    process.env.GRAPH_DB_PATH = TEST_DB_PATH;
+    runsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'graph-engine-stale-agent-call-sweep-'));
+    process.env.GRAPH_RUNS_DIR = runsDir;
+    for (const m of [
+      '../../services/graph-db',
+      '../../services/graph-service',
+      '../../services/org-graph-service',
+      '../../services/work-graph-db',
+      '../../services/graph-run-sse',
+      '../../services/graph-engine',
+    ]) {
+      delete require.cache[require.resolve(m)];
+    }
+    wdb = require('../../services/work-graph-db');
+    engine = require('../../services/graph-engine');
+  });
+
+  afterAll(() => {
+    for (const f of [TEST_DB_PATH, `${TEST_DB_PATH}-shm`, `${TEST_DB_PATH}-wal`]) {
+      try { fs.unlinkSync(f); } catch {}
+    }
+    delete process.env.GRAPH_DB_PATH;
+    try { fs.rmSync(runsDir, { recursive: true, force: true }); } catch {}
+    delete process.env.GRAPH_RUNS_DIR;
+  });
+
+  beforeEach(() => {
+    const db = wdb.getDb();
+    db.pragma('foreign_keys = OFF');
+    db.exec(`
+      DELETE FROM graph_run_loop_records;
+      DELETE FROM graph_run_nodes;
+      DELETE FROM graph_runs;
+      DELETE FROM work_graph_edges;
+      DELETE FROM work_graph_nodes;
+      DELETE FROM work_graphs;
+      DELETE FROM system_agents;
+    `);
+    db.pragma('foreign_keys = ON');
+    engine.setAgentExecutor(null);
+  });
+
+  let seq = 0;
+  const nextCompany = () => `co-stale-${++seq}`;
+
+  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 buildWorkRun({ companyId, nodes, edges }) {
+    ensureAgents(nodes);
+    const g = wdb.createWorkGraph({ companyId, nodes, edges });
+    expect(g.errors || []).toEqual([]);
+    const run = wdb.createRun({ graphKind: 'work', graphId: g.id, companyId, executionMode: 'manual' });
+    engine.markRunReady(run.id);
+    return { runId: run.id };
+  }
+
+  const nodeByName = (runId, name) => wdb.getRunState(runId).nodes.find((n) => n.name === name);
+
+  function markAsRunning(runId, nodeName, startedAtIso) {
+    const node = nodeByName(runId, nodeName);
+    wdb.getDb()
+      .prepare(`UPDATE graph_run_nodes SET status = 'running', started_at = ?, updated_at = ? WHERE id = ?`)
+      .run(startedAtIso, startedAtIso, node.id);
+    return node.id;
+  }
+
+  const NOW = '2026-08-31T10:00:00.000Z';
+
+  it('agent_call 节点 running 超过阈值判定为存活超时，走 infra_flake 原地重跑', () => {
+    const companyId = nextCompany();
+    const { runId } = buildWorkRun({ companyId, nodes: ['w'], edges: [] });
+    // 默认阈值 25 分钟；30 分钟前开始 = 超阈值
+    markAsRunning(runId, 'w', '2026-08-31T09:30:00.000Z');
+
+    const result = engine.sweepStaleRunningAgentCalls({ nowIso: NOW });
+
+    expect(result.scanned).toBe(1);
+    expect(result.swept).toHaveLength(1);
+    expect(result.swept[0]).toMatchObject({ runId, infraRerun: true });
+    const fresh = nodeByName(runId, 'w');
+    expect(fresh.status).toBe('ready');
+    expect(fresh.attempt).toBe(0);
+  });
+
+  it('running 未超过阈值的节点不受影响（大概率还在真实跑）', () => {
+    const companyId = nextCompany();
+    const { runId } = buildWorkRun({ companyId, nodes: ['w'], edges: [] });
+    // 5 分钟前开始，远低于默认 25 分钟阈值
+    markAsRunning(runId, 'w', '2026-08-31T09:55:00.000Z');
+
+    const result = engine.sweepStaleRunningAgentCalls({ nowIso: NOW });
+
+    expect(result.scanned).toBe(0);
+    expect(nodeByName(runId, 'w').status).toBe('running');
+  });
+
+  it('阈值可调：传更短的 thresholdMs 会让原本"没超时"的节点也被扫到', () => {
+    const companyId = nextCompany();
+    const { runId } = buildWorkRun({ companyId, nodes: ['w'], edges: [] });
+    markAsRunning(runId, 'w', '2026-08-31T09:55:00.000Z'); // 5 分钟前
+
+    const result = engine.sweepStaleRunningAgentCalls({ nowIso: NOW, thresholdMs: 60 * 1000 }); // 阈值 1 分钟
+
+    expect(result.scanned).toBe(1);
+    expect(nodeByName(runId, 'w').status).toBe('ready');
+  });
+
+  it('subgraph 节点不在扫描范围内，即使 running 很久也不受影响', () => {
+    const companyId = nextCompany();
+    ensureAgents(['s']);
+    const g = wdb.createWorkGraph({ companyId, nodes: [{ nodeName: 's', nodeKind: 'subgraph' }], edges: [] });
+    expect(g.errors || []).toEqual([]);
+    const run = wdb.createRun({ graphKind: 'work', graphId: g.id, companyId, executionMode: 'manual' });
+    engine.markRunReady(run.id);
+    markAsRunning(run.id, 's', '2026-08-31T08:00:00.000Z'); // 2 小时前，远超阈值
+
+    const result = engine.sweepStaleRunningAgentCalls({ nowIso: NOW });
+
+    expect(result.scanned).toBe(0);
+    expect(nodeByName(run.id, 's').status).toBe('running');
+  });
+
+  it('没有任何超时节点时是安静的 no-op', () => {
+    const companyId = nextCompany();
+    buildWorkRun({ companyId, nodes: ['w'], edges: [] }); // 节点是 ready，不是 running
+    const result = engine.sweepStaleRunningAgentCalls({ nowIso: NOW });
+    expect(result).toEqual({ scanned: 0, swept: [] });
+  });
+});
@@ -18,4 +18,13 @@
 ## 不用管的
 - 正在排队 / 正在跑但没超时的 task——那是调度器的活，不用你盯
-- 纯技术性的失败（比如基础设施抖动）——引擎自己有重试和熔断机制
+- 纯技术性的失败（比如基础设施抖动）——引擎自己有重试和熔断机制（`sweepOrphanedRunningNodes` +
+  `sweepStaleRunningAgentCalls`，见 45 号文档 Part A；后者是持续性扫描，25 分钟自动处理一次，
+  **心跳例行扫描不用替它兜底**，不要主动去查每条 running task 卡了多久）
+
+## 用户直接把"这条任务卡住了"转给你时该怎么办
+
+心跳例行扫描不用管上面那条，但如果是**用户主动**转发过来、明确让你看一条卡住的任务，按
+`tools.md`「卡住的 run 节点」一节的两步处理（先查、再用 `force-fail` 端点）。**不要自己对着
+卡住的 run/节点拉起一个新的 agent 会话去亲自跑一遍**——那是绕过引擎，会跟卡住的状态打架；
+上一次这么干直接陷入了工具调用死循环，最后靠人手动中断才停下（见 45 号文档时间线）。
@@ -78,6 +78,56 @@ curl -s -X POST &quot;${LEMON_API_BASE:-http://localhost:3010/api}/company/&lt;companyId
 ---
+## 卡住的 run 节点：只能用这一个端点处理，不许自己动手
+
+一条 task 的 `runId`（从 `GET /:companyId/goals/<goalId>` 的 task 摘要里能看到）对应一棵 graph
+run 树。如果一条 task 长时间 `running` 不动、你判断需要介入，**只能**走下面这两步，
+**不许**做的事情见本节末尾。
+
+### 1. 先查，找到真正卡住的那个节点
+
+```bash
+curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/graph-runs/<runId>" \
+  -H "x-internal-token: $LEMON_INTERNAL_TOKEN"
+```
+
+返回里 `nodes[]` 是这一层的节点状态，`childRuns[]` 是往下展开出的子 run（org 节点会展开成
+work graph 子 run）。**卡住的往往不是你拿到的第一层 `runId`，是它 `childRuns[]` 里那个**
+——顺着 `childRuns[].id` 递归 `GET` 下去，找到最深那一层里 `status: 'running'` 且
+`agentRunId`/`childRunId` 都是 `null` 的节点，那才是真正卡死、没有背后进程在跑的那一个。
+
+### 2. 确认是真卡死之后，用这个端点让引擎按既有失败路由处理
+
+```bash
+curl -s -X POST "${LEMON_API_BASE:-http://localhost:3010/api}/graph-runs/<那一层真正卡住的runId>/nodes/<nodeId>/force-fail" \
+  -H "x-internal-token: $LEMON_INTERNAL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"failReason":"infra_flake"}'
+```
+
+`failReason` 传 `infra_flake`：这是"不是这个节点自己的错，是基础设施打断"的既有语义，引擎会
+原地重跑、不烧这个节点的 `attempt` 计数。**只有 `nodeId` 属于你上一步在 `<那一层真正卡住的
+runId>` 下面查到的、status 恰好是 `running` 的节点时，这个端点才会生效**（其他状态会直接
+400 报错，不会误伤）。
+
+不确定要不要传 `infra_flake`（比如你怀疑是节点自己的逻辑问题，不是纯粹的基础设施打断）：
+不传 `failReason`，默认走 `operator_intervention`，节点会转 `fail` 交给正常的失败路由/回退边
+处理，而不是原地重跑——两者的区别只是"该不该算这个节点头上"，出错方向选保守的那个就好。
+
+### 你不该做的事（45 号文档记录过一次真实事故）
+
+- **不要自己直接对着这个 run/节点拉起一个新的 agent 会话去"亲自跑一遍"**——那是绕过引擎，
+  会跟卡住的状态本身打架，产生冲突/重复调用，上一次这么干直接陷入死循环，最后靠人手动中断
+  才停下。你能做的只有上面这一个端点，没有第二条路。
+- 不要对**不是 `running`** 的节点调 `force-fail`（会直接报错，这不是漏做校验，是刻意的边界）。
+- 判断"卡住多久算该管"：目前没有一个精确的存活探测，只能凭经验——如果这条 task 的进度
+  （goal 详情里的 `progress`）长时间（半小时以上）没有变化，且你手头没有别的信息能解释
+  为什么慢，可以认为大概率是死了。引擎自己也有一条持续性扫描会在 25 分钟后自动处理同类情况
+  （见 `docs/todo/system-design/45-graph-run-node-liveness-recovery.md` Part A）——多数情况下
+  不需要你手动介入，这一节是给"用户直接把卡住的任务转给你、要你立刻看一下"这种场景兜底的。
+
+---
+
 ## 什么时候该提新任务、什么时候该改优先级
 - **一条 task 长时间 `blocked` 或 `failed`**（预算耗尽 / 依赖死锁 / 反复回退熔断）：看它的
@@ -100,5 +150,6 @@ curl -s -X POST &quot;${LEMON_API_BASE:-http://localhost:3010/api}/company/&lt;companyId
 |---|---|
 | `POST /:companyId/org-graph/replan` | 改组织结构是 `orggraph-planning` 的事，不是你的判断范围 |
 | 任何招聘 / 解雇端点 | 公司缺角色是 HR 与 `orggraph-planning` 的活，你发现"缺人"应该提一条 task 说明缺口，不是自己动手改编制 |
-| 直接改 `graph_runs` / `graph_run_nodes`（没有这类端点，但如果你找到裸 SQL 或内部函数也一样不许碰） | 执行状态由引擎维护，你只通过 goals/tasks 这层 REST 接口操作 |
+| 直接改 `graph_runs` / `graph_run_nodes`（裸 SQL 或内部函数） | 执行状态由引擎维护；**唯一的例外**是上面"卡住的 run 节点"一节写明的 `force-fail` 端点，别的一律不许碰 |
+| 对着卡住的 run/节点自己拉起一个新的 agent 会话"亲自跑一遍" | 绕过引擎会跟卡住的状态打架，上一次这么干陷入了死循环（45 号文档）——只能用 `force-fail` 端点，没有第二条路 |
 | `POST /:companyId/tasks`（不带 `draft:true`） | 会立刻烧预算，见上面的强调 |