fix(control-plane): require explicit mutation actors (#4816)

Author: huangruiteng

apps/presentation/dashboard/README.md

@@ -207,8 +207,8 @@ It provides a unified, coherent experience for managing long-running agent Goals
 
   ```bash
   loopx goal-lifecycle --goal-id <goal-id> --operation stop
-  loopx goal-lifecycle --goal-id <goal-id> --operation stop --execute
-  loopx goal-lifecycle --goal-id <goal-id> --operation resume --execute
+  loopx goal-lifecycle --goal-id <goal-id> --operation stop --actor-kind owner --execute
+  loopx goal-lifecycle --goal-id <goal-id> --operation resume --actor-kind owner --execute
   loopx quota status --goal-id <goal-id>
   ```
 

docs/book/chapters/workspace-v1.md

@@ -101,10 +101,13 @@ Preview 冻结规范化参数、影响范围和当前 revision。Apply 只能执
 
 ```bash
 loopx goal-lifecycle --goal-id <goal-id> --operation stop
-loopx goal-lifecycle --goal-id <goal-id> --operation stop --execute
+loopx goal-lifecycle --goal-id <goal-id> --operation stop --actor-kind owner --execute
 loopx quota status --goal-id <goal-id>
 ```
 
+执行 lifecycle transition 时必须显式传入 `--actor-kind owner` 或 `controller`；
+匿名预览仍然保持只读。
+
 暂停会让该 Goal 退出 active attention，并使有效自动运行 quota 投影为 0；Todo、历史、证据和配置
 仍保留。恢复使用显式 `resume --execute`，且不会绕过 Todo、Gate 或 quota。不要把 stop 写成
 “完成 Goal”，也不要用改 quota 的方式意外恢复一个被 owner 停止的 Goal。

docs/book/en/chapters/workspace-v1.md

@@ -111,10 +111,13 @@ For example, the first Goal-stop command is preview-only:
 
 ```bash
 loopx goal-lifecycle --goal-id <goal-id> --operation stop
-loopx goal-lifecycle --goal-id <goal-id> --operation stop --execute
+loopx goal-lifecycle --goal-id <goal-id> --operation stop --actor-kind owner --execute
 loopx quota status --goal-id <goal-id>
 ```
 
+Executed lifecycle transitions require an explicit `--actor-kind owner` or
+`controller`; anonymous previews remain read-only.
+
 Stopping a Goal removes it from active attention and projects zero effective automatic-run quota while
 preserving Todos, history, evidence, and configuration. Explicit `resume --execute` restores scheduling
 eligibility but does not bypass Todo, Gate, or quota rules. Do not describe stop as completing the Goal, and

docs/guides/codex-app-autonomous-goal-experience.md

@@ -207,7 +207,7 @@ loopx history --goal-id "$GOAL_ID"
 
 ```bash
 loopx goal-lifecycle --goal-id "$GOAL_ID" --operation stop
-loopx goal-lifecycle --goal-id "$GOAL_ID" --operation stop --execute
+loopx goal-lifecycle --goal-id "$GOAL_ID" --operation stop --actor-kind owner --execute
 ```
 
 **预期效果：**
@@ -225,7 +225,7 @@ loopx goal-lifecycle --goal-id "$GOAL_ID" --operation stop --execute
 **输入：**
 
 ```bash
-loopx goal-lifecycle --goal-id "$GOAL_ID" --operation resume --execute
+loopx goal-lifecycle --goal-id "$GOAL_ID" --operation resume --actor-kind owner --execute
 loopx quota should-run \
   --goal-id "$GOAL_ID" \
   --agent-id "$AGENT_ID" \

docs/guides/getting-started.md

@@ -866,6 +866,7 @@ loopx operator-gate \
 
 loopx reward \
   --goal-id your-project-goal \
+  --actor-kind owner \
   --decision continue_route \
   --reward positive \
   --reason-summary "validation improved and the route is worth extending"

docs/guides/personal-workspace-user-guide.md

@@ -108,13 +108,16 @@ CLI 提供同一套可预览、可验证的生命周期操作：
 loopx goal-lifecycle --goal-id <goal-id> --operation stop
 
 # 确认执行，再读取 quota 验证自动推进已暂停
-loopx goal-lifecycle --goal-id <goal-id> --operation stop --execute
+loopx goal-lifecycle --goal-id <goal-id> --operation stop --actor-kind owner --execute
 loopx quota status --goal-id <goal-id>
 
 # 恢复；不会绕过其他运行门禁
-loopx goal-lifecycle --goal-id <goal-id> --operation resume --execute
+loopx goal-lifecycle --goal-id <goal-id> --operation resume --actor-kind owner --execute
 ```
 
+`--execute` 必须显式声明 `--actor-kind owner` 或 `controller`；不带 actor 的
+预览仍保持只读。写入的 activation receipt 会保留该 actor kind。
+
 执行时，LoopX 会写入权威 source registry、同步全局 registry，并验证两端 readback；任一端未验证成功时不会宣称操作完成。
 
 切换到 SSH 状态来源后，只有来源与本机 OpenSSH 配置中的精确 Host alias 绑定时，

docs/heartbeat-automation-prompt.md

@@ -658,7 +658,9 @@ hint directly, otherwise do nothing. For the uniquely matched current heartbeat,
 
 If `automation_update` is unavailable in the session and
 `scheduler_hint.app_automation.fallback_hint.available=true`, run the bound
-`fallback_hint.cli_args` (`loopx-apply-rrule`) once instead. It backs up
+`fallback_hint.cli_args` (`loopx-apply-rrule`) once instead. The fallback
+requires the projected registered `--agent-id`; there is no implicit Agent
+default. It backs up
 `codex-dev.db`, syncs the automation TOML and SQLite row, and runs the bound
 ACK; direct SQLite edits bypass the app API, so this is a bounded fallback and
 never the routine path. The bridge reuses the provided parent Turn for its

docs/integration.md

@@ -573,12 +573,17 @@ editing the run JSON by hand:
 ```bash
 loopx reward \
   --goal-id project-goal \
+  --actor-kind owner \
   --decision continue_route \
   --reward positive \
   --reason-summary "comparable validation improved and the route is worth extending" \
   --follow-up "promote to the next longer-window check"
 ```
 
+Durable reward writes require an explicit `--actor-kind owner` or
+`--actor-kind controller`; `--dry-run` remains available without an actor.
+The selected kind is stored with the run-bound overlay.
+
 By default the command attaches feedback to the latest compact run for the
 goal. Pass `--run-generated-at <timestamp>` to target an older run. The writer
 appends a JSONL overlay to the same `index.jsonl`; it does not mutate private
@@ -604,6 +609,7 @@ overlay instead of creating a separate memory store:
 ```bash
 loopx reward \
   --goal-id project-goal \
+  --actor-kind owner \
   --decision route_correction \
   --reward mixed \
   --reason-summary "fix lifecycle counters before adding more benchmark cases" \
@@ -629,6 +635,7 @@ the durable loop in one CLI call:
 ```bash
 loopx reward \
   --goal-id project-goal \
+  --actor-kind owner \
   --decision continue_route \
   --reward positive \
   --reason-summary "comparable validation improved and the route is worth extending" \

docs/product/roadmaps/experiment-controller-milestone.md

@@ -102,6 +102,7 @@ Use `loopx reward` to append this compact signal to an existing run:
 ```bash
 loopx reward \
   --goal-id example-experiment-goal \
+  --actor-kind owner \
   --run-generated-at 2026-06-01T00:00:00+00:00 \
   --decision continue_route \
   --reward positive \

docs/reference/contracts/dashboard-reward-write-boundary.md

@@ -38,6 +38,9 @@ A browser append endpoint may be implemented only when all of these are true:
 - The payload has already passed the same validation as `/reward/dry-run`.
 - The response remains compact and does not return `index_path`, `json_path`,
   `markdown_path`, local absolute paths, or raw private evidence.
+- The trusted loopback adapter records `actor_kind=owner` in both preview and
+  append receipts; the canonical CLI requires an explicit owner/controller
+  actor kind for a durable write.
 
 ## Preview Handshake