fix(heartbeat): carry the closeout vision decision in the writeback guidance

The vision checkpoint contract already requires a per-agent vision decision at a
material closeout, but the guidance injected into every wake said only
`material->actual outcome`. A lane that followed it recorded the segment with a
`missing_required` checkpoint and paid for the decision on the next wake, which
opened on a checkpoint-missing replan obligation and spent itself reconstructing
facts that were in hand at closeout time.

The guidance now states the contract the product actually implements: a material
closeout - a material `delivery_outcome` on the agent lane, or a durable
`## Next Action` update - carries its own vision decision in the same
`refresh-state` call, an omission is repaired on the original turn through the
repair command the CLI returns, the goal cannot reach its terminal no-follow-up
state before the decision satisfies the checkpoint, and a segment does not
record an `unchanged` reason it did not earn. The sentence stays inside both
agent-facing budgets: the prompt body keeps its per-mode character allowance and
the hot-path interface envelope stays inside its 4800-character json budget.

The record-and-repair contract is deliberately untouched. An input-boundary
refusal was proposed earlier in this PR and withdrawn: it removed the
recorded-then-repaired path that the shipped host completion, same-turn
supplement, idempotent replay and external-delivery resume confirmation all
depend on, and 15 tests encode that path (they now stay green). Fixing the
guidance removes the waste at its source without retiring the recovery
mechanism.

Verified: tests/test_host_vision_recovery.py,
tests/control_plane/test_refresh_checkpoint_recovery.py,
tests/control_plane/test_refresh_checkpoint_isolation.py and
tests/test_state_refresh_agent_lane_action.py 64 passed;
tests/control_plane/test_cli_output_budget.py and
tests/control_plane/test_heartbeat_prompt_support.py 58 passed;
hot-path-interface-budget, heartbeat-prompt, goal-vision-refresh-state-budget,
goal-vision-replan-contract, blocker-push-runtime and docs-governance smokes ok.

Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com>

Author: huangruiteng

docs/development/control-plane-course/08-evidence-refresh-and-self-repair.md

@@ -312,15 +312,18 @@ if total_usage > GOAL_VISION_TOTAL_LIMIT:
 第二份 transcript。`examples/project/goal-vision-refresh-state-budget-smoke.py`
 同时验证写入正确性、预算与 repair delta。
 
-当 material refresh 没有 vision patch 或 unchanged reason 时，CLI 会产生 `vision_checkpoint_missing` acceptance gap。Todo 即使完成，也不能直接 terminal。
+正常调用应当在同一次写回里带上这个决定。当 agent lane 的 material closeout 没有 vision
+patch 或 unchanged reason 时，CLI 会记录 segment 并把 checkpoint 标成
+`vision_checkpoint_missing`，同时返回一条可直接执行的修复命令：在原 turn 用它补齐决定，
+settlement identity 不变、不会再花一次 spend。补齐之前，Todo 即使完成也不能宣告 terminal。
 
-修复选择有三种：
+要满足这个决定，路径仍是三种：
 
 1. 写一个 bounded vision patch；
 2. 明确记录 vision unchanged reason；
 3. 用 evidence 关闭或 supersede 该 vision frontier。
 
-不要为了消除 warning 随便写“unchanged”。Reason 必须与本轮 acceptance 事实一致。
+不要为了消除这个提示自动填一个空泛的“unchanged”。Reason 必须与本轮 acceptance 事实一致。
 
 ## Signal、Anchor 与 Feedback 不直接变成 Todo Truth
 

docs/reference/protocols/goal-vision-replan-contract-v0.md

@@ -232,6 +232,22 @@ Valid checkpoint decisions are:
 - `not_required`: no material closeout trigger was present, including a valid
   typed in-flight continuation.
 
+The closeout is where this requirement is met, so the writeback guidance every
+wake receives states it: a material closeout -- a material `delivery_outcome` on
+the agent lane, or a durable `## Next Action` update -- carries its own vision
+decision in the same `refresh-state` call, and does not record an `unchanged`
+reason the segment did not earn.
+
+An omission is recorded, not discarded, and is repaired in the same turn:
+`refresh-state` writes the segment with a `missing_required` checkpoint and
+returns the repair command that repeats the original invocation with the missing
+decision. The goal cannot reach its terminal no-follow-up state until that
+decision satisfies the checkpoint, and the same-turn supplement applies it to the
+original settlement identity rather than to a new one, so the repair neither
+re-authors the segment nor spends a second time. An in-flight continuation owes
+no decision, and neither does a closeout that carries no `agent_id`, because a
+per-agent decision requires an agent to make it.
+
 `missing_required` is not a chat reminder. Status keeps it in compact run
 history, quota filters it by current `agent_id`, and goal-frontier projection
 turns it into `acceptance_gaps[]`. If the current agent has no runnable

examples/control_plane/heartbeat-prompt-smoke.py

@@ -85,7 +85,10 @@ def user_output_policy(task_body: str, *, mode: str) -> dict[str, str]:
 def assert_sole_notification_authority(task_body: str, *, mode: str) -> None:
     body = normalized(task_body)
     assert "no-change=`surface_only`/no spend; unchanged->" in body, mode
-    assert "`--vision-unchanged-reason`; material->actual outcome." in body, mode
+    assert (
+        "`--vision-unchanged-reason`; material closeout->actual outcome"
+        "+vision决定; 缺则按返回命令同turn补齐，补齐前不terminal"
+    ) in body, mode
 
     if mode == "full":
         assert (
@@ -714,7 +717,10 @@ def main() -> int:
     ):
         assert "no-change=`surface_only`/no spend" in task, label
         assert "`--vision-unchanged-reason`" in task, label
-        assert "material->actual outcome" in task, label
+        assert "material closeout->actual outcome" in task, label
+        assert "同turn补齐" in task, label
+        assert "补齐前不terminal" in task, label
+        assert "勿空填unchanged" in task, label
     assert "if absent say" not in thin_task, thin_task
     assert "If false/0: quiet/no-user-todo" not in thin_task, thin_task
 

loopx/control_plane/heartbeat/rules.py

@@ -23,7 +23,8 @@
 )
 HEARTBEAT_VISION_WRITEBACK_RULE_SHORT = (
     "writeback: no-change=`surface_only`/no spend; "
-    "unchanged->`--vision-unchanged-reason`; material->actual outcome."
+    "unchanged->`--vision-unchanged-reason`; material closeout->actual outcome"
+    "+vision决定; 缺则按返回命令同turn补齐，补齐前不terminal；勿空填unchanged."
 )
 REWARD_MEMORY_OUTCOME_RULE = (
     "`reward_memory_recall.experiment.automatic_ingest=true`: reusable Todo outcomes "