Turn Lifecycle

文件与 Symbol

文件	Symbol	Runtime 语义
turn-run-shell.ts	createTurnAgentRunContext()	一轮开始前构造不可随意漂移的 Turn-owned execution context
turn-run-shell.ts	TurnRunOptions / TurnRunContext	请求输入与运行期 owner 分离
turn-observation.ts	turnStarted()	Turn lifecycle start fact
turn-observation.ts	toolStarted() / toolCompleted()	Tool lifecycle fact
turn-settle.ts	collectText() / collectAgentMessage()	流式输出先收集，不等于 durable completion
turn-settle.ts	settleCompletedTurn()	timing、memory、labeling 等 completion hook
turn-settle.ts	persistFinalState()	最终 durable boundary
turn-settle.ts	buildResult()	已确认事实投影为返回结果

调用关系

createTurnAgentRunContext(input)
  ├─ resolvePrivacyMode()
  ├─ create provider/summarization session
  ├─ prepareAgentProfilePromptSnapshot()
  ├─ build toolSession middleware
  ├─ build TurnAgentScope
  └─ return dispose()/commit owners

run / stream
  ↓
turnStarted()
  ↓
toolStarted() ── tool execution ── toolCompleted()
  ↓
persistStepCheckpoint()*
  ↓
settleCompletedTurn()
  ↓
persistFinalState()
  ↓
buildResult()

关键点：**创建 Turn Context、产生 Observation、持久化、返回 Result 是不同阶段。**模型输出不能跨过这些阶段直接宣布 Runtime 状态。

本地定位

rg -n "createTurnAgentRunContext|TurnRunContext|turnStarted|toolStarted|toolCompleted|settleCompletedTurn|persistFinalState|buildResult" source/host/runner

固定源码

• turn-run-shell.ts
• turn-observation.ts
• turn-settle.ts

关联知识文章

• 一次 Run 如何被推进：Lifecycle、State Machine 与 Node Transition — Turn 开始前先构造 Runtime-owned Context；createTurnAgentRunContext()
• Multi-Agent 为什么容易失控：Context Isolation 与 Planning Failure — Turn Scope 在 Runtime 创建时就已经被约束；createTurnAgentRunContext() → TurnAgentScope → toolSession
• Coding Agent 的工作环境是什么：Workspace 与 Filesystem State — Turn Context 同时持有 shell-watch / resource owner；createTurnAgentRunContext() → shellWatchHost
• Shadow Harness 从哪些边界开始：Architecture、Domain Model 与 Model Adapter — 真实工程把 Turn Context / Observation / Settlement 拆成不同 owner；createTurnAgentRunContext()