Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -528,6 +528,12 @@ evidence → recovery; continuation → governance.
| What evidence changed? | Compact run history, validation, blockers, and accepted writeback. |
| May the loop continue? | Quota, capabilities, safe fallback, scheduler hints, and stop conditions. |

Preview a Goal stop with `loopx goal-lifecycle --goal-id <id> --operation stop`;
use `--operation resume` to restore eligibility. Apply the transition with
`--actor-kind owner --execute`, retaining a fresh `--expected-state-fingerprint`
when supplied by the Goal actions view. The ordinary and standalone
[`loopx-core`](packages/loopx-core/README.md) CLI use the same lifecycle owner.

<details>
<summary>Architecture, control-plane surfaces and runtime responsibilities</summary>

Expand Down
6 changes: 6 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -463,6 +463,12 @@ Kernel 把控制面归结为五个用户可以直接行动的问题。每个问
| 证据发生了什么变化? | 紧凑 run history、验证、blocker 和已接受 writeback。 |
| Loop 是否可以继续? | Quota、capability、安全侧路、scheduler hint 和停止条件。 |

用 `loopx goal-lifecycle --goal-id <id> --operation stop` 预览 Goal 停止;
改用 `--operation resume` 可恢复资格。加入 `--actor-kind owner --execute`
执行变更;Goal actions 视图提供了新鲜指纹时,保留
`--expected-state-fingerprint`。普通 CLI 与独立
[`loopx-core`](packages/loopx-core/README.md) CLI 使用同一个生命周期 owner。

<details>
<summary>架构、控制面能力与运行责任</summary>

Expand Down
24 changes: 24 additions & 0 deletions docs/architecture/rfcs/monorepo-distribution-split-v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -4619,3 +4619,27 @@ view shows its independently checked result in the same conversation.
overhead or complete-cost benefit, actual-model adoption, full D2/D5,
R1/M3, Goal completion or C1 default cutover. Preserve earlier checkpoints,
failures, budgets and acceptance requirements.


### 2026-11-16 — Standalone lifecycle commands reach the existing owner

- **Gap:** standalone Core bundled the existing Goal activation implementation
but omitted `goal-lifecycle` from selected CLI loading. A supported stop/resume
request fell through to the intentionally absent full CLI before reaching its
owner.
- **Delta:** select only the existing command, registrar and handler. Actor,
source identity, expected fingerprint, preview, partial-write readback and
errors remain on the original activation service and typed state owner.
Unrelated commands and top-level help retain lazy loading; App and messaging
controls retain their existing owner.
- **Ownership boundary:** the existing native outer-controller guard now
recognizes lifecycle execution for its managed Goal. Owner/controller labels
cannot bypass that guard; preview, other Goals and ordinary execution remain
available. The same guard protects selected and full CLI entrypoints.
- **Source evidence:** owner-only command help, complete-parser comparison,
source stop/resume and anonymous/stale-fingerprint refusal regressions protect
V2/V3 reachability and ordinary CLI parity. Planned activation timestamps are
validated independently rather than compared across separate invocations.
- **Boundary:** this is a source wiring repair. Installed Core and composition
qualification, interrupted original-Task recovery, complete context/closure,
actual models, costs, full R1/M3 and C1 cutover remain separate acceptance.
20 changes: 20 additions & 0 deletions docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -3575,3 +3575,23 @@ workspace 批准和脚本模型工作。桌面视图在采用检查后显示原
current-C1 实际组合;不证明完整 process/network 闭包、自然进程
drain、实测 overhead 或完整成本收益、真实模型采用、完整 D2/D5、R1/M3、
Goal 完成或 C1 默认切换。保留既有 checkpoints、失败、预算和验收要求。


### 2026-11-16 — 独立发行包的生命周期命令到达原 owner

- **缺口:**独立 Core 已包含原 Goal activation 实现,但 selected CLI loading
未选入 `goal-lifecycle`。支持的 stop/resume 请求在到达 owner 前,落入有意
省略的完整 CLI。
- **增量:**仅选入既有命令、registrar 与 handler。Actor、source identity、
expected fingerprint、preview、partial-write 读回与错误继续由原 activation
service 和 typed state owner 持有。无关命令及顶层 help 保持 lazy loading;
App 与消息控制继续使用既有 owner。
- **写入归属边界:**既有 native outer-controller guard 现在识别其受管 Goal 的
生命周期执行。Owner/controller 标签不能绕过该 guard;preview、其他 Goal
与普通执行继续可用。同一个 guard 保护 selected 及完整 CLI 入口。
- **源码证据:**仅加载命令 owner 的 help、完整 parser 对照、源码 stop/resume、
anonymous 与 stale-fingerprint 拒绝回归,保护 V2/V3 入口可达性及普通 CLI
parity。计划 activation 的时间戳独立校验,不在不同调用之间比较相等。
- **边界:**本次是源码接线修复。Installed Core 与组合资格、被中断原 Task 的
恢复、完整 context/closure、真实模型、成本、完整 R1/M3 及 C1 cutover 仍是
独立验收。
11 changes: 11 additions & 0 deletions loopx/cli_runtime.py
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@
"heartbeat-prompt",
"heartbeat-prequota",
"goal-acceptance",
"goal-lifecycle",
"host-mode-plan",
"capability",
"history",
Expand Down Expand Up @@ -528,6 +529,10 @@ def _build_selected_parser(command: str) -> LoopXArgumentParser:
from .cli_commands.goal_acceptance import register_goal_acceptance_command

register_goal_acceptance_command(subparsers, add_subcommand_format)
elif command == "goal-lifecycle":
from .cli_commands.goal_lifecycle import register_goal_lifecycle_command

register_goal_lifecycle_command(subparsers)
elif command == "host-mode-plan":
from .cli_commands.host_mode_plan import register_host_mode_plan_command

Expand Down Expand Up @@ -596,6 +601,12 @@ def _dispatch_common_command(
args, registry_path=registry_path, runtime_root_arg=args.runtime_root,
output_format=output_format, print_payload=print_payload,
)
if args.command == "goal-lifecycle":
from .cli_commands.goal_lifecycle import handle_goal_lifecycle_command

return handle_goal_lifecycle_command(
args, registry_path=registry_path, print_payload=print_payload,
)
if args.command == "performance-diagnosis":
from .capabilities.performance_diagnosis.cli import handle_performance_diagnosis_command

Expand Down
2 changes: 2 additions & 0 deletions loopx/kunluncode_goal_mode/guards.py
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,8 @@ def native_controller_cli_write_block(arguments: Any) -> dict[str, Any] | None:
operation = f"task-lease {lease_command}".strip()
elif command == "turn" and getattr(arguments, "turn_command", None) == "run-once":
operation = "turn run-once"
elif command == "goal-lifecycle" and getattr(arguments, "execute", False):
operation = f"goal-lifecycle {getattr(arguments, 'operation', '')}".strip()
elif command in {
"archive-runtime",
"configure-goal",
Expand Down
98 changes: 98 additions & 0 deletions tests/test_cli_entrypoint.py
Original file line number Diff line number Diff line change
Expand Up @@ -519,6 +519,7 @@ def test_command_reference_does_not_require_default_runtime_route(
(["agent-directory", "--help"], "loopx.cli_commands.agent_directory", "loopx.cli_commands.agent_directory"),
(["agent-capabilities", "--help"], "loopx.cli_commands.agent_capabilities", "loopx.cli_commands.agent_capabilities"),
(["goal-acceptance", "--help"], "loopx.cli_commands.goal_acceptance", "loopx.cli_commands.goal_acceptance"),
(["goal-lifecycle", "--help"], "loopx.cli_commands.goal_lifecycle", "loopx.cli_commands.goal_lifecycle"),
(["host-mode-plan", "--help"], "loopx.cli_commands.host_mode_plan", "loopx.cli_commands.host_mode_plan"),
(["goal-portfolio", "--help"], "loopx.cli_commands.summary_all_registration", "loopx.cli_commands.summary_all"),
(["global-summary", "--help"], "loopx.cli_commands.summary_all_registration", "loopx.cli_commands.summary_all"),
Expand Down Expand Up @@ -999,6 +1000,10 @@ def test_selected_parser_matches_full_help_and_diagnostics() -> None:
argv_cases.extend([["goal-acceptance", "--help"], ["goal-acceptance", "inspect"],
["goal-acceptance", "unknown-action", "--goal-id", "goal"],
["goal-acceptance", "inspect", "--goal-id", "goal", "--unknown-option"]])
argv_cases.extend([["goal-lifecycle", "--help"], ["goal-lifecycle", "--operation", "stop"],
["goal-lifecycle", "--goal-id", "goal", "--operation", "unknown"],
["goal-lifecycle", "--goal-id", "goal", "--operation", "stop", "--actor-kind", "unknown"],
["goal-lifecycle", "--goal-id", "goal", "--operation", "stop", "--unknown-option"]])
selected = run_cli_batch("loopx.entrypoint", argv_cases)
full = run_cli_batch("loopx.cli", argv_cases)

Expand Down Expand Up @@ -1319,6 +1324,99 @@ def test_selected_goal_acceptance_refusals_match_without_full_cli(tmp_path, argu
assert registry.read_bytes() == before


@pytest.mark.parametrize("arguments, expected", [
(["--operation", "stop"], 0),
(["--operation", "resume"], 0),
(["--operation", "stop", "--execute"], 1),
(["--operation", "stop", "--actor-kind", "owner", "--execute",
"--expected-state-fingerprint", "0" * 64], 1),
])
def test_selected_goal_lifecycle_preserves_preview_and_refusals(tmp_path, arguments, expected):
from datetime import datetime

registry, runtime = write_command_fixture(tmp_path)
before = registry.read_bytes()
argv = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json",
"goal-lifecycle", "--goal-id", "perf-goal", *arguments]
selected = run_cli_main("loopx.entrypoint", argv, forbidden_modules=("loopx.cli",))
full = run_cli_main("loopx.cli", argv)
assert selected.returncode == full.returncode == expected
assert selected.stderr == full.stderr
payload = json.loads(selected.stdout)
legacy = json.loads(full.stdout)
for result in (payload, legacy):
if "activation" in result:
# Proposed activation timestamps are generated for each invocation.
assert datetime.fromisoformat(result["activation"].pop("updated_at")).tzinfo is not None
assert payload == legacy
assert payload["written"] is False and payload["ok"] is (expected == 0)
assert registry.read_bytes() == before


@pytest.mark.parametrize("module", ["loopx.entrypoint", "loopx.cli"])
def test_goal_lifecycle_stop_resume_reaches_existing_source_owner(tmp_path, module):
registry, runtime = write_command_fixture(tmp_path)
prefix = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json",
"goal-lifecycle", "--goal-id", "perf-goal"]
for operation, state in (("stop", "stopped"), ("resume", "active")):
before = registry.read_bytes()
preview = run_cli_main(module, [*prefix, "--operation", operation],
forbidden_modules=("loopx.cli",) if module == "loopx.entrypoint" else ())
assert preview.returncode == 0, preview.stderr
assert registry.read_bytes() == before
fingerprint = json.loads(preview.stdout)["observed_state_fingerprint"]
result = run_cli_main(module, [*prefix, "--operation", operation,
"--actor-kind", "owner", "--expected-state-fingerprint", fingerprint, "--execute"],
forbidden_modules=("loopx.cli",) if module == "loopx.entrypoint" else ())
assert result.returncode == 0, result.stderr
payload = json.loads(result.stdout)
assert payload["written"] and payload["readback"]["verified"]
assert json.loads(registry.read_text())["goals"][0]["activation"]["state"] == state


@pytest.mark.parametrize("module", ["loopx.entrypoint", "loopx.cli"])
@pytest.mark.parametrize("operation", ["stop", "resume"])
@pytest.mark.parametrize("actor", ["owner", "controller"])
def test_goal_lifecycle_cannot_override_outer_controller(tmp_path, module, operation, actor):
registry, runtime = write_command_fixture(tmp_path)
before = registry.read_bytes()
prefix = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json",
"goal-lifecycle", "--goal-id", "perf-goal", "--operation", operation, "--actor-kind", actor]
environment = {"LOOPX_KUNLUNCODE_OUTER_CONTROLLER": "1",
"LOOPX_KUNLUNCODE_OUTER_GOAL_ID": "perf-goal"}
forbidden = ("loopx.cli",) if module == "loopx.entrypoint" else ()
preview = run_cli_main(module, prefix, forbidden_modules=forbidden, environment=environment)
assert preview.returncode == 0, preview.stderr
assert json.loads(preview.stdout)["written"] is False
assert registry.read_bytes() == before
blocked = run_cli_main(module, [*prefix, "--execute"],
forbidden_modules=forbidden, environment=environment)
assert blocked.returncode == 2 and blocked.stdout == ""
payload = json.loads(blocked.stderr)
assert payload["error_code"] == "kunluncode_outer_controller_write_owned"
assert payload["goal_id"] == "perf-goal"
assert payload["operation"] == f"goal-lifecycle {operation}"
assert registry.read_bytes() == before


@pytest.mark.parametrize("module", ["loopx.entrypoint", "loopx.cli"])
@pytest.mark.parametrize("controller, owned_goal", [("0", "perf-goal"), ("1", "other-goal")])
def test_goal_lifecycle_preserves_unowned_goal_operations(tmp_path, module, controller, owned_goal):
registry, runtime = write_command_fixture(tmp_path)
prefix = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json",
"goal-lifecycle", "--goal-id", "perf-goal", "--actor-kind", "owner", "--execute"]
environment = {"LOOPX_KUNLUNCODE_OUTER_CONTROLLER": controller,
"LOOPX_KUNLUNCODE_OUTER_GOAL_ID": owned_goal}
forbidden = ("loopx.cli",) if module == "loopx.entrypoint" else ()
for operation, state in (("stop", "stopped"), ("resume", "active")):
result = run_cli_main(module, [*prefix, "--operation", operation],
forbidden_modules=forbidden, environment=environment)
assert result.returncode == 0, result.stderr
payload = json.loads(result.stdout)
assert payload["written"] and payload["readback"]["verified"]
assert json.loads(registry.read_text())["goals"][0]["activation"]["state"] == state


@pytest.mark.parametrize("format_name", ["json", "markdown"])
@pytest.mark.parametrize("arguments, expected_code", [
(["--intent", "watch_each_turn", "--host-capability", "visible_session",
Expand Down
82 changes: 82 additions & 0 deletions tests/test_core_distribution.py
Original file line number Diff line number Diff line change
Expand Up @@ -465,6 +465,88 @@ def _spends(runtime):
for line in index.read_text().splitlines()) if index.exists() else 0


def test_installed_core_goal_lifecycle_preserves_work_and_resumes_execution(core_python, task):
workspace, runtime, registry, arguments = task
host_started = workspace / "lifecycle-host-started"
host_script = workspace / "lifecycle-host.py"
host_script.write_text(
"import pathlib\npathlib.Path('lifecycle-host-started').write_text('started')\n" + HOST_SOURCE,
)
arguments = list(arguments)
arguments[arguments.index("--host-adapter-command-json") + 1] = json.dumps(
[core_python, "-I", str(host_script)],
)
todo_argv = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json",
"todo", "list", "--goal-id", GOAL]
original_todo = json.loads(_run(core_python, todo_argv, workspace).stdout)["todos"][0]
todo_id = original_todo["todo_id"]
lease_argv = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json",
"task-lease", "inspect", "--goal-id", GOAL, "--todo-id", todo_id]
original_lease = json.loads(_run(core_python, lease_argv, workspace).stdout)["lease"]
global_registry = runtime / "registry.global.json"
prefix = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json",
"goal-lifecycle", "--goal-id", GOAL]
for operation, state in (("stop", "stopped"), ("resume", "active")):
before = (registry.read_bytes(), global_registry.read_bytes())
preview = json.loads(_run(core_python, [*prefix, "--operation", operation], workspace).stdout)
assert preview["dry_run"] and not preview["written"]
assert (registry.read_bytes(), global_registry.read_bytes()) == before
refused = json.loads(_run(core_python, [*prefix, "--operation", operation,
"--execute"], workspace, expected=1).stdout)
assert refused["written"] is False
stale = json.loads(_run(core_python, [*prefix, "--operation", operation,
"--actor-kind", "owner", "--expected-state-fingerprint", "0" * 64,
"--execute"], workspace, expected=1).stdout)
assert stale["error_kind"] == "goal_action_stale" and stale["written"] is False
assert (registry.read_bytes(), global_registry.read_bytes()) == before
result = json.loads(_run(core_python, [*prefix, "--operation", operation,
"--actor-kind", "owner", "--expected-state-fingerprint", preview["observed_state_fingerprint"],
"--execute"], workspace).stdout)
assert result["written"] and result["readback"]["verified"]
for path in (registry, global_registry):
goal = next(goal for goal in json.loads(path.read_text())["goals"] if goal["id"] == GOAL)
assert goal["activation"]["state"] == state
assert json.loads(_run(core_python, todo_argv, workspace).stdout)["todos"][0] == original_todo
assert json.loads(_run(core_python, lease_argv, workspace).stdout)["lease"] == original_lease
if state == "stopped":
blocked = json.loads(_run(core_python, arguments, workspace, expected=1).stdout)
assert blocked["ok"] is False, blocked
# An entered executor preserves uncertainty in its error response.
# Independent fixture observations below establish actual effects.
for effect in ("host_invoked", "state_written", "quota_spent"):
value = blocked["effects"][effect]
assert value is False or value is None, blocked
assert _spends(runtime) == 0
assert not host_started.exists()
assert not (workspace / "host-invocations").exists()
assert not (workspace / "squares.json").exists()
result = json.loads(_run(core_python, arguments, workspace).stdout)
key = _assert_committed(core_python, workspace, runtime, result)
assert host_started.read_text() == "started"
replay = json.loads(_run(core_python, [*arguments, "--resume-turn-key", key], workspace).stdout)
_assert_committed(core_python, workspace, runtime, replay)
assert replay["effects"]["host_invoked"] is False
assert replay["effects"]["state_written"] is False
assert replay["effects"]["quota_spent"] is False


@pytest.mark.parametrize("operation", ["stop", "resume"])
@pytest.mark.parametrize("actor", ["owner", "controller"])
def test_installed_core_goal_lifecycle_respects_outer_controller(core_python, task, operation, actor):
workspace, runtime, registry, arguments = task
before = (registry.read_bytes(), (runtime / "registry.global.json").read_bytes())
prefix = ["--registry", str(registry), "--runtime-root", str(runtime), "--format", "json",
"goal-lifecycle", "--goal-id", GOAL, "--operation", operation, "--actor-kind", actor]
environment = {"LOOPX_KUNLUNCODE_OUTER_CONTROLLER": "1", "LOOPX_KUNLUNCODE_OUTER_GOAL_ID": GOAL}
preview = json.loads(_run(core_python, prefix, workspace, environment=environment).stdout)
assert preview["written"] is False
blocked = _run(core_python, [*prefix, "--execute"], workspace, environment=environment, expected=2)
assert blocked.stdout == ""
assert json.loads(blocked.stderr)["error_code"] == "kunluncode_outer_controller_write_owned"
assert (registry.read_bytes(), (runtime / "registry.global.json").read_bytes()) == before
assert _spends(runtime) == 0 and not (workspace / "host-invocations").exists()


def _assert_committed(core_python, workspace, runtime, result):
assert result["status"] == "committed", result
assert result["validation"]["status"] == "passed"
Expand Down
Loading