From 7423d748adbfd7cee0c01ff03e314ed82bc5a8ee Mon Sep 17 00:00:00 2001 From: ChengLong GU <88359731+gcl-coder@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:02:53 +0800 Subject: [PATCH 1/4] feat(goal-closeout): add bounded terminal-state hook executor Refs #8918. Signed-off-by: ChengLong GU <88359731+gcl-coder@users.noreply.github.com> --- loopx/capabilities/goal_closeout/__init__.py | 1 + loopx/capabilities/goal_closeout/hooks.py | 218 ++++++++++++++++++ .../goal_closeout/machine_defaults.py | 69 ++++++ .../machine_configuration/builtins.py | 5 + tests/capabilities/test_goal_closeout_hook.py | 140 +++++++++++ 5 files changed, 433 insertions(+) create mode 100644 loopx/capabilities/goal_closeout/__init__.py create mode 100644 loopx/capabilities/goal_closeout/hooks.py create mode 100644 loopx/capabilities/goal_closeout/machine_defaults.py create mode 100644 tests/capabilities/test_goal_closeout_hook.py diff --git a/loopx/capabilities/goal_closeout/__init__.py b/loopx/capabilities/goal_closeout/__init__.py new file mode 100644 index 0000000000..002d1dfa3f --- /dev/null +++ b/loopx/capabilities/goal_closeout/__init__.py @@ -0,0 +1 @@ +"""Terminal Goal closeout hooks owned by the machine configuration.""" diff --git a/loopx/capabilities/goal_closeout/hooks.py b/loopx/capabilities/goal_closeout/hooks.py new file mode 100644 index 0000000000..607fa8052b --- /dev/null +++ b/loopx/capabilities/goal_closeout/hooks.py @@ -0,0 +1,218 @@ +from __future__ import annotations + +import json +import os +import signal +import subprocess +import tempfile +import time +from pathlib import Path +from typing import Any + +from ...control_plane.runtime.time import now_local_iso +from ...file_lock import LockAcquisitionPolicy, exclusive_file_lock +from ..machine_configuration.builtins import build_builtin_machine_configuration_registry +from ..machine_configuration.store import read_machine_configuration +from .machine_defaults import normalize_goal_closeout_configuration + +GOAL_CLOSEOUT_PAYLOAD_SCHEMA_VERSION = "loopx_goal_closeout_v1" +GOAL_CLOSEOUT_LEDGER_SCHEMA_VERSION = "loopx_goal_closeout_invocation_v0" +GOAL_CLOSEOUT_LEDGER_FILENAME = "closeout-ledger.jsonl" +_MAX_CAPTURE_BYTES = 8192 + + +class _Capture: + """Read only a bounded prefix from a binary temporary file.""" + + def __init__(self, handle: Any) -> None: + self.handle = handle + + def text(self) -> str: + self.handle.seek(0) + return self.handle.read(_MAX_CAPTURE_BYTES).decode("utf-8", errors="replace") + + +def goal_closeout_ledger_path(runtime_root: Path, goal_id: str) -> Path: + return runtime_root / "goals" / goal_id / GOAL_CLOSEOUT_LEDGER_FILENAME + + +def _read_configuration(runtime_root: Path) -> tuple[dict[str, Any] | None, str | None]: + try: + configuration = read_machine_configuration( + runtime_root, + registry=build_builtin_machine_configuration_registry(), + namespace_ids=("goal_closeout",), + ) + except Exception as exc: # semantically fail-open for the terminal command + return None, f"{type(exc).__name__}: {exc}" + if not configuration: + return None, None + raw = configuration.get("namespaces", {}).get("goal_closeout") + if raw is None: + return None, None + try: + return normalize_goal_closeout_configuration(raw), None + except Exception as exc: + return None, f"{type(exc).__name__}: {exc}" + + +def _terminate(process: subprocess.Popen[bytes]) -> None: + """Kill the command and its descendants, then reap the direct child.""" + + try: + os.killpg(process.pid, signal.SIGKILL) + except (AttributeError, PermissionError, ProcessLookupError, OSError): + try: + process.kill() + except OSError: + pass + try: + process.wait(timeout=5) + except subprocess.TimeoutExpired: + pass + + +def _write_ledger( + runtime_root: Path, + goal_id: str, + record: dict[str, Any], +) -> tuple[Path, bool, str | None]: + path = goal_closeout_ledger_path(runtime_root, goal_id) + try: + path.parent.mkdir(parents=True, exist_ok=True) + with exclusive_file_lock( + path, + policy=LockAcquisitionPolicy.MUTATION, + operation="goal_closeout_ledger_append", + ): + with path.open("a", encoding="utf-8") as handle: + handle.write(json.dumps(record, ensure_ascii=False) + "\n") + return path, True, None + except Exception as exc: # the terminal command already ran; never block it + return path, False, f"{type(exc).__name__}: {exc}" + + +def run_goal_closeout( + *, + runtime_root: Path, + goal_id: str, + repo: str | None, + state_file: str | None, + terminal_reason: str, + trigger: str, +) -> dict[str, Any]: + """Run the configured closeout command once and record the attempt. + + The caller's terminal transition has already committed. Every failure in + this function is returned, never raised, so the command that finished the + Goal keeps its own result. + """ + + result: dict[str, Any] = { + "schema_version": GOAL_CLOSEOUT_LEDGER_SCHEMA_VERSION, + "goal_id": goal_id, + "trigger": trigger, + "terminal_reason": terminal_reason, + "status": "not_configured", + "ledger_recorded": False, + } + try: + configuration, configuration_error = _read_configuration(runtime_root) + if configuration_error is not None: + result.update( + { + "status": "configuration_error", + "error": configuration_error, + } + ) + return result + if configuration is None: + return result + command = list(configuration.get("command") or []) + result["command"] = command + if not command: + return result + + payload = { + "schema_version": GOAL_CLOSEOUT_PAYLOAD_SCHEMA_VERSION, + "goal_id": goal_id, + "repo": repo or "", + "state_file": state_file or "", + "terminal_reason": terminal_reason, + "runtime_root": str(runtime_root), + "trigger": trigger, + } + started = time.monotonic() + timed_out = False + with tempfile.TemporaryFile(mode="w+b") as stdout_handle: + with tempfile.TemporaryFile(mode="w+b") as stderr_handle: + process = subprocess.Popen( + command, + stdin=subprocess.PIPE, + stdout=stdout_handle, + stderr=stderr_handle, + cwd=repo if repo and Path(repo).is_dir() else None, + start_new_session=True, + ) + try: + process.communicate( + input=json.dumps(payload, ensure_ascii=False).encode("utf-8"), + timeout=float(configuration["timeout_seconds"]), + ) + except subprocess.TimeoutExpired: + timed_out = True + _terminate(process) + duration_ms = int((time.monotonic() - started) * 1000) + stdout_text = _Capture(stdout_handle).text() + stderr_text = _Capture(stderr_handle).text() + exit_code = process.returncode + if timed_out: + status = "timeout" + elif exit_code == 0: + status = "success" + else: + status = "failed" + result.update( + { + "status": status, + "exit_code": exit_code, + "timed_out": timed_out, + "duration_ms": duration_ms, + "stdout": stdout_text, + "stderr": stderr_text, + } + ) + record = { + "schema_version": GOAL_CLOSEOUT_LEDGER_SCHEMA_VERSION, + "recorded_at": now_local_iso(), + "goal_id": goal_id, + "trigger": trigger, + "terminal_reason": terminal_reason, + "command": command, + "status": status, + "exit_code": exit_code, + "timed_out": timed_out, + "duration_ms": duration_ms, + "stdout": stdout_text, + "stderr": stderr_text, + } + ledger_path, ledger_recorded, ledger_error = _write_ledger( + runtime_root, goal_id, record + ) + result.update( + { + "ledger_path": str(ledger_path), + "ledger_recorded": ledger_recorded, + } + ) + if ledger_error is not None: + result["ledger_error"] = ledger_error + except Exception as exc: + result.update( + { + "status": "internal_error", + "error": f"{type(exc).__name__}: {exc}", + } + ) + return result + diff --git a/loopx/capabilities/goal_closeout/machine_defaults.py b/loopx/capabilities/goal_closeout/machine_defaults.py new file mode 100644 index 0000000000..4a45705be8 --- /dev/null +++ b/loopx/capabilities/goal_closeout/machine_defaults.py @@ -0,0 +1,69 @@ +from __future__ import annotations + +from collections.abc import Mapping +from typing import Any + +from ..machine_configuration.contract import MachineConfigurationNamespace + +GOAL_CLOSEOUT_CONFIGURATION_SCHEMA = "loopx_goal_closeout_configuration_v0" +DEFAULT_CLOSEOUT_TIMEOUT_SECONDS = 30 +MAX_CLOSEOUT_TIMEOUT_SECONDS = 600 + + +def normalize_goal_closeout_configuration( + raw: Mapping[str, Any], +) -> dict[str, Any]: + unknown = sorted(set(raw) - {"schema_version", "command", "timeout_seconds"}) + if unknown: + raise ValueError( + "goal_closeout contains unsupported fields: " + ", ".join(unknown) + ) + if raw.get("schema_version") != GOAL_CLOSEOUT_CONFIGURATION_SCHEMA: + raise ValueError( + "goal_closeout must use " + GOAL_CLOSEOUT_CONFIGURATION_SCHEMA + ) + raw_command = raw.get("command", []) + if not isinstance(raw_command, (list, tuple)): + raise ValueError("goal_closeout command must be an array of strings") + command: list[str] = [] + for part in raw_command: + if not isinstance(part, str) or not part.strip(): + raise ValueError( + "goal_closeout command entries must be non-empty strings" + ) + command.append(part) + raw_timeout = raw.get("timeout_seconds", DEFAULT_CLOSEOUT_TIMEOUT_SECONDS) + if isinstance(raw_timeout, bool) or not isinstance(raw_timeout, int): + raise ValueError("goal_closeout timeout_seconds must be an integer") + if not 1 <= raw_timeout <= MAX_CLOSEOUT_TIMEOUT_SECONDS: + raise ValueError( + "goal_closeout timeout_seconds must be between 1 and " + f"{MAX_CLOSEOUT_TIMEOUT_SECONDS}" + ) + return { + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "command": command, + "timeout_seconds": raw_timeout, + } + + +def goal_closeout_machine_configuration_namespace() -> MachineConfigurationNamespace: + return MachineConfigurationNamespace( + namespace="goal_closeout", + schema_versions=frozenset({GOAL_CLOSEOUT_CONFIGURATION_SCHEMA}), + normalize=normalize_goal_closeout_configuration, + project_public=lambda value: dict(value), + apply_public_update=lambda _current, update: dict(update), + title="Terminal Goal closeout command", + description=( + "Optional machine-wide command run after a Goal reaches a terminal " + "transition (stop, retirement or runtime archive). The command is " + "best effort, receives one bounded JSON payload on stdin, and can " + "never block the LoopX command that triggered it." + ), + default_configuration={ + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "command": [], + "timeout_seconds": DEFAULT_CLOSEOUT_TIMEOUT_SECONDS, + }, + ) diff --git a/loopx/capabilities/machine_configuration/builtins.py b/loopx/capabilities/machine_configuration/builtins.py index 8e26aab087..85d18cfa84 100644 --- a/loopx/capabilities/machine_configuration/builtins.py +++ b/loopx/capabilities/machine_configuration/builtins.py @@ -31,6 +31,11 @@ "loopx.capabilities.machine_configuration.goal_storage", "goal_storage_machine_configuration_namespace", ), + ( + "goal_closeout", + "loopx.capabilities.goal_closeout.machine_defaults", + "goal_closeout_machine_configuration_namespace", + ), ( "manager_runtime", "loopx.capabilities.manager_runtime.machine_profile", diff --git a/tests/capabilities/test_goal_closeout_hook.py b/tests/capabilities/test_goal_closeout_hook.py new file mode 100644 index 0000000000..ca73db9c98 --- /dev/null +++ b/tests/capabilities/test_goal_closeout_hook.py @@ -0,0 +1,140 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +from loopx.capabilities.goal_closeout.hooks import ( + GOAL_CLOSEOUT_LEDGER_FILENAME, + run_goal_closeout, +) +from loopx.capabilities.goal_closeout.machine_defaults import ( + GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, +) +from loopx.capabilities.machine_configuration.builtins import ( + build_builtin_machine_configuration_registry, +) +from loopx.capabilities.machine_configuration.store import ( + configure_machine_configuration, +) + + +def _configure(root: Path, *, command: list[str], timeout_seconds: int = 5) -> None: + configuration = { + "schema_version": "loopx_machine_configuration_v0", + "namespaces": { + "goal_closeout": { + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "command": command, + "timeout_seconds": timeout_seconds, + } + }, + } + registry = build_builtin_machine_configuration_registry() + preview = configure_machine_configuration( + runtime_root=root, + configuration=configuration, + registry=registry, + ) + payload = configure_machine_configuration( + runtime_root=root, + configuration=configuration, + registry=registry, + execute=True, + expected_plan_revision=preview["plan_revision"], + ) + assert payload["ok"], payload + + +def _ledger_rows(root: Path, goal_id: str) -> list[dict[str, object]]: + path = root / "goals" / goal_id / GOAL_CLOSEOUT_LEDGER_FILENAME + return [ + json.loads(line) + for line in path.read_text(encoding="utf-8").splitlines() + if line.strip() + ] + + +def test_unconfigured_closeout_runs_nothing_and_writes_no_ledger(tmp_path: Path) -> None: + result = run_goal_closeout( + runtime_root=tmp_path, + goal_id="fixture", + repo=None, + state_file=None, + terminal_reason="retired", + trigger="retire", + ) + assert result["status"] == "not_configured" + assert result["ledger_recorded"] is False + assert not (tmp_path / "goals" / "fixture" / GOAL_CLOSEOUT_LEDGER_FILENAME).exists() + + +def test_closeout_receives_bounded_payload_and_records_ledger(tmp_path: Path) -> None: + payload_path = tmp_path / "payload.json" + command = [sys.executable, "-c", "import sys; open(sys.argv[1], 'w').write(sys.stdin.read())", str(payload_path)] + _configure(tmp_path, command=command) + + result = run_goal_closeout( + runtime_root=tmp_path, + goal_id="fixture", + repo="/tmp/fixture-repo", + state_file="/tmp/fixture-state.md", + terminal_reason="retired", + trigger="retire", + ) + + assert result["status"] == "success", result + payload = json.loads(payload_path.read_text(encoding="utf-8")) + assert payload == { + "schema_version": "loopx_goal_closeout_v1", + "goal_id": "fixture", + "repo": "/tmp/fixture-repo", + "state_file": "/tmp/fixture-state.md", + "terminal_reason": "retired", + "runtime_root": str(tmp_path), + "trigger": "retire", + } + assert result["ledger_recorded"] is True + rows = _ledger_rows(tmp_path, "fixture") + assert len(rows) == 1 + assert rows[0]["status"] == "success" + assert rows[0]["exit_code"] == 0 + + +def test_closeout_timeout_is_bounded_and_never_raises(tmp_path: Path) -> None: + _configure( + tmp_path, + command=[sys.executable, "-c", "import time; time.sleep(30)"], + timeout_seconds=1, + ) + result = run_goal_closeout( + runtime_root=tmp_path, + goal_id="fixture", + repo=None, + state_file=None, + terminal_reason="stopped", + trigger="stop", + ) + assert result["status"] == "timeout" + assert result["timed_out"] is True + assert result["ledger_recorded"] is True + assert 900 <= result["duration_ms"] < 10000 + + +def test_closeout_command_failure_is_reported_without_blocking(tmp_path: Path) -> None: + _configure( + tmp_path, + command=[sys.executable, "-c", "import sys; print('bad', file=sys.stderr); sys.exit(7)"], + ) + result = run_goal_closeout( + runtime_root=tmp_path, + goal_id="fixture", + repo=None, + state_file=None, + terminal_reason="archived", + trigger="archive", + ) + assert result["status"] == "failed" + assert result["exit_code"] == 7 + assert "bad" in result["stderr"] + assert result["ledger_recorded"] is True From a9b4f101f9dee4bbedcbf34bd811c8118800dd56 Mon Sep 17 00:00:00 2001 From: ChengLong GU <88359731+gcl-coder@users.noreply.github.com> Date: Thu, 19 Nov 2026 11:46:29 +0800 Subject: [PATCH 2/4] feat(goal-closeout): invoke terminal hook on stop, retire and archive Signed-off-by: ChengLong GU <88359731+gcl-coder@users.noreply.github.com> --- loopx/capabilities/goal_closeout/hooks.py | 13 +- .../control_plane/goals/activation_service.py | 37 +++ loopx/global_registry.py | 37 +++ loopx/runtime.py | 35 +++ .../test_goal_closeout_terminal_hooks.py | 217 ++++++++++++++++++ 5 files changed, 335 insertions(+), 4 deletions(-) create mode 100644 tests/capabilities/test_goal_closeout_terminal_hooks.py diff --git a/loopx/capabilities/goal_closeout/hooks.py b/loopx/capabilities/goal_closeout/hooks.py index 607fa8052b..c3587ee05b 100644 --- a/loopx/capabilities/goal_closeout/hooks.py +++ b/loopx/capabilities/goal_closeout/hooks.py @@ -73,11 +73,10 @@ def _terminate(process: subprocess.Popen[bytes]) -> None: def _write_ledger( - runtime_root: Path, - goal_id: str, + ledger_dir: Path, record: dict[str, Any], ) -> tuple[Path, bool, str | None]: - path = goal_closeout_ledger_path(runtime_root, goal_id) + path = ledger_dir / GOAL_CLOSEOUT_LEDGER_FILENAME try: path.parent.mkdir(parents=True, exist_ok=True) with exclusive_file_lock( @@ -100,6 +99,7 @@ def run_goal_closeout( state_file: str | None, terminal_reason: str, trigger: str, + ledger_dir: Path | None = None, ) -> dict[str, Any]: """Run the configured closeout command once and record the attempt. @@ -196,8 +196,13 @@ def run_goal_closeout( "stdout": stdout_text, "stderr": stderr_text, } + selected_ledger_dir = ( + ledger_dir + if ledger_dir is not None + else goal_closeout_ledger_path(runtime_root, goal_id).parent + ) ledger_path, ledger_recorded, ledger_error = _write_ledger( - runtime_root, goal_id, record + selected_ledger_dir, record ) result.update( { diff --git a/loopx/control_plane/goals/activation_service.py b/loopx/control_plane/goals/activation_service.py index b67a82024a..20070d48cb 100644 --- a/loopx/control_plane/goals/activation_service.py +++ b/loopx/control_plane/goals/activation_service.py @@ -406,6 +406,7 @@ def set_goal_activation_state( return payload sync_payload: dict[str, Any] | None = None + closeout_goal: dict[str, Any] | None = None with project_registry_transaction( source_registry, operation="set_goal_activation_state", @@ -472,6 +473,7 @@ def set_goal_activation_state( ) return payload locked_goal = _goal(source_payload, normalized_goal_id) + closeout_goal = dict(locked_goal) locked_state = goal_activation_state(locked_goal) if locked_state is not before_state: payload.update( @@ -544,6 +546,41 @@ def set_goal_activation_state( (sync_payload or {}).get("recommended_action") or f"rerun loopx sync-global --goal-id {normalized_goal_id} after repairing the shared registry route" ) + if ( + execute + and target_state is GoalActivationState.STOPPED + and changed + and payload.get("ok") + and payload.get("written") + and closeout_goal is not None + ): + from ...capabilities.goal_closeout.hooks import run_goal_closeout + + closeout_runtime_root = resolve_runtime_root( + load_registry(source_registry), + runtime_root_override, + registry_path=source_registry, + ) + state_file = closeout_goal.get("state_file") + if not state_file: + state_file = ( + source_registry.parent + / "goals" + / normalized_goal_id + / "ACTIVE_GOAL_STATE.md" + ) + payload["closeout"] = run_goal_closeout( + runtime_root=closeout_runtime_root, + goal_id=normalized_goal_id, + repo=( + str(closeout_goal.get("repo")) + if closeout_goal.get("repo") + else None + ), + state_file=str(state_file), + terminal_reason="stopped", + trigger="goal-lifecycle-stop", + ) return payload diff --git a/loopx/global_registry.py b/loopx/global_registry.py index 9d0e676b06..7874347587 100644 --- a/loopx/global_registry.py +++ b/loopx/global_registry.py @@ -571,6 +571,9 @@ def _retire_global_registry_reduction( "inspections": inspections, "global_goal_count_before": len(current_goals), "global_goal_count_after": len(retained_goals), + "retired_goals": [ + dict(matches_by_id[goal_id][0]) for goal_id in requested_ids + ], }, backup_label="retire-goal-backup", ) @@ -656,6 +659,39 @@ def retire_global_registry_goals( receipt = mutation["receipt"] backup_path = mutation["backup_path"] + closeouts: list[dict[str, Any]] = [] + if execute: + from .capabilities.goal_closeout.hooks import run_goal_closeout + + for retired_goal in receipt.get("retired_goals", []): + goal_id = str(retired_goal.get("id") or "").strip() + if not goal_id: + continue + state_file = retired_goal.get("state_file") + if not state_file: + state_file = runtime_root / "goals" / goal_id / "ACTIVE_GOAL_STATE.md" + goal_runtime_dir = runtime_root / "goals" / goal_id + closeout_ledger_dir = ( + goal_runtime_dir + if goal_runtime_dir.is_dir() + else runtime_root / "closeout" / goal_id + ) + closeouts.append( + run_goal_closeout( + runtime_root=runtime_root, + goal_id=goal_id, + repo=( + str(retired_goal.get("repo")) + if retired_goal.get("repo") + else None + ), + state_file=str(state_file), + terminal_reason="retired", + trigger="retire-global-goal", + ledger_dir=closeout_ledger_dir, + ) + ) + return { "ok": True, "schema_version": "loopx_global_goal_retirement_v0", @@ -674,6 +710,7 @@ def retire_global_registry_goals( "wrote": execute, "updated_at": updated_at, "global_registry_writability": writability, + "closeouts": closeouts, } diff --git a/loopx/runtime.py b/loopx/runtime.py index 1ad1cc68bc..84081b51f8 100644 --- a/loopx/runtime.py +++ b/loopx/runtime.py @@ -116,6 +116,14 @@ def archive_runtime_goal( safe_goal_id = validate_goal_id_path_segment(goal_id) registered_ids = {str(goal.get("id")) for goal in registry_goals(registry)} registry_member = safe_goal_id in registered_ids + archive_goal = next( + ( + goal + for goal in registry_goals(registry) + if str(goal.get("id")) == safe_goal_id + ), + None, + ) if registry_member and not allow_registered: raise ValueError( "goal exists in registry; pass --allow-registered only after confirming it is obsolete" @@ -138,6 +146,7 @@ def archive_runtime_goal( destination = unique_archive_path(archive_base, safe_goal_id, timestamp) _validate_archive_destination(source, destination) + closeout: dict[str, Any] | None = None if execute: from .control_plane.coordination.shadow_management import ( runtime_artifact_lock_target, @@ -237,6 +246,31 @@ def archive_runtime_goal( _validate_archive_destination(source, destination) destination.parent.mkdir(parents=True, exist_ok=True) shutil.move(str(source), str(destination)) + from .capabilities.goal_closeout.hooks import run_goal_closeout + + archived_state_file = destination / "ACTIVE_GOAL_STATE.md" + declared_state_file = ( + archive_goal.get("state_file") if archive_goal else None + ) + closeout = run_goal_closeout( + runtime_root=runtime_root, + goal_id=safe_goal_id, + repo=( + str(archive_goal.get("repo")) + if archive_goal and archive_goal.get("repo") + else None + ), + state_file=( + str(archived_state_file) + if archived_state_file.exists() + else str(declared_state_file) + if declared_state_file + else None + ), + terminal_reason="archived", + trigger="archive-runtime", + ledger_dir=destination, + ) return { "ok": True, @@ -250,6 +284,7 @@ def archive_runtime_goal( "dry_run": not execute, "archived": execute, "action": "moved" if execute else "would-move", + "closeout": closeout, "checks": [ "goal id is a single path segment", "source runtime goal directory exists", diff --git a/tests/capabilities/test_goal_closeout_terminal_hooks.py b/tests/capabilities/test_goal_closeout_terminal_hooks.py new file mode 100644 index 0000000000..8d2894dbac --- /dev/null +++ b/tests/capabilities/test_goal_closeout_terminal_hooks.py @@ -0,0 +1,217 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +from loopx.capabilities.goal_closeout.hooks import GOAL_CLOSEOUT_LEDGER_FILENAME +from loopx.capabilities.goal_closeout.machine_defaults import ( + GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, +) +from loopx.capabilities.machine_configuration.builtins import ( + build_builtin_machine_configuration_registry, +) +from loopx.capabilities.machine_configuration.store import ( + configure_machine_configuration, +) +from loopx.control_plane.goals.activation_service import set_goal_activation_state +from loopx.global_registry import retire_global_registry_goals, sync_project_registry_to_global +from loopx.runtime import archive_runtime_goal + + +def _write_json(path: Path, payload: dict[str, object]) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8") + + +def _configure_closeout(root: Path, payload_path: Path) -> None: + configuration = { + "schema_version": "loopx_machine_configuration_v0", + "namespaces": { + "goal_closeout": { + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "command": [ + sys.executable, + "-c", + "import sys; open(sys.argv[1], 'a').write(sys.stdin.read())", + str(payload_path), + ], + "timeout_seconds": 5, + } + }, + } + registry = build_builtin_machine_configuration_registry() + preview = configure_machine_configuration( + runtime_root=root, + configuration=configuration, + registry=registry, + ) + payload = configure_machine_configuration( + runtime_root=root, + configuration=configuration, + registry=registry, + execute=True, + expected_plan_revision=preview["plan_revision"], + ) + assert payload["ok"], payload + + +def _ledger(root: Path, goal_id: str) -> list[dict[str, object]]: + path = root / "goals" / goal_id / GOAL_CLOSEOUT_LEDGER_FILENAME + return [ + json.loads(line) + for line in path.read_text(encoding="utf-8").splitlines() + if line.strip() + ] + + +def test_stop_runs_closeout_once_and_dry_run_does_not(tmp_path: Path) -> None: + runtime_root = tmp_path / "runtime" + project = tmp_path / "project" + source_registry = project / ".loopx" / "registry.json" + _write_json( + source_registry, + { + "schema_version": "0.1", + "common_runtime_root": str(runtime_root), + "goals": [ + { + "id": "goal-one", + "display_name": "Closeout fixture", + "repo": str(project), + "quota": {"compute": 1, "allowed_slots": 4, "spent_slots": 0}, + } + ], + }, + ) + synced = sync_project_registry_to_global( + registry_path=source_registry, + runtime_root_override=str(runtime_root), + goal_id="goal-one", + dry_run=False, + ) + assert synced["ok"] is True + global_registry = runtime_root / "registry.global.json" + payload_path = tmp_path / "payloads.jsonl" + _configure_closeout(runtime_root, payload_path) + + preview = set_goal_activation_state( + registry_path=global_registry, + goal_id="goal-one", + state="stopped", + actor_kind="owner", + execute=False, + ) + assert "closeout" not in preview + + stopped = set_goal_activation_state( + registry_path=global_registry, + goal_id="goal-one", + state="stopped", + actor_kind="owner", + execute=True, + ) + assert stopped["ok"] is True, stopped + assert stopped["closeout"]["status"] == "success", stopped + payload = json.loads(payload_path.read_text(encoding="utf-8").splitlines()[0]) + assert payload["goal_id"] == "goal-one" + assert payload["terminal_reason"] == "stopped" + assert payload["repo"] == str(project) + rows = _ledger(runtime_root, "goal-one") + assert len(rows) == 1 + + repeated = set_goal_activation_state( + registry_path=global_registry, + goal_id="goal-one", + state="stopped", + actor_kind="owner", + execute=True, + ) + assert "closeout" not in repeated + assert len(_ledger(runtime_root, "goal-one")) == 1 + + +def test_retire_runs_closeout_for_each_retired_goal(tmp_path: Path) -> None: + runtime_root = tmp_path / "runtime" + global_registry = runtime_root / "registry.global.json" + project = tmp_path / "project" + _write_json( + global_registry, + { + "schema_version": "0.1", + "registry_role": "global-local", + "goals": [ + { + "id": "retired-goal", + "display_name": "Retired fixture", + "repo": str(project), + "source_registry": str(tmp_path / "missing" / "registry.json"), + "state_file": str(tmp_path / "missing" / "ACTIVE_GOAL_STATE.md"), + } + ], + }, + ) + payload_path = tmp_path / "payloads.jsonl" + _configure_closeout(runtime_root, payload_path) + + result = retire_global_registry_goals( + runtime_root_override=str(runtime_root), + goal_ids=["retired-goal"], + execute=True, + ) + assert result["ok"] is True, result + assert len(result["closeouts"]) == 1 + assert result["closeouts"][0]["status"] == "success", result + payload = json.loads(payload_path.read_text(encoding="utf-8").splitlines()[0]) + assert payload["goal_id"] == "retired-goal" + assert payload["terminal_reason"] == "retired" + assert payload["repo"] == str(project) + ledger_path = Path(result["closeouts"][0]["ledger_path"]) + assert ledger_path.is_file() + assert json.loads(ledger_path.read_text(encoding="utf-8").splitlines()[0])["status"] == "success" + + +def test_archive_runs_closeout_after_move_without_recreating_source(tmp_path: Path) -> None: + project = tmp_path / "project" + registry_path = project / ".loopx" / "registry.json" + runtime_root = project / ".loopx" / "runtime" + source = runtime_root / "goals" / "archived-goal" + source.mkdir(parents=True) + (source / "ACTIVE_GOAL_STATE.md").write_text("state\n", encoding="utf-8") + (source / "expected.txt").write_text("kept\n", encoding="utf-8") + _write_json( + registry_path, + { + "schema_version": 1, + "common_runtime_root": ".loopx/runtime", + "goals": [ + { + "id": "archived-goal", + "display_name": "Archive fixture", + "repo": str(project), + "state_file": ".loopx/runtime/goals/archived-goal/ACTIVE_GOAL_STATE.md", + } + ], + }, + ) + payload_path = tmp_path / "payloads.jsonl" + _configure_closeout(runtime_root, payload_path) + + result = archive_runtime_goal( + registry_path=registry_path, + runtime_root_override=None, + goal_id="archived-goal", + archive_root=None, + allow_registered=True, + execute=True, + ) + assert result["ok"] is True, result + assert result["closeout"]["status"] == "success", result + archive_path = Path(result["archive_path"]) + assert not source.exists() + assert (archive_path / "expected.txt").read_text(encoding="utf-8") == "kept\n" + assert (archive_path / GOAL_CLOSEOUT_LEDGER_FILENAME).is_file() + payload = json.loads(payload_path.read_text(encoding="utf-8").splitlines()[0]) + assert payload["goal_id"] == "archived-goal" + assert payload["terminal_reason"] == "archived" + assert payload["state_file"] == str(archive_path / "ACTIVE_GOAL_STATE.md") From 3d784d44a92c7349ec0fb4201f392ed9799d8a86 Mon Sep 17 00:00:00 2001 From: ChengLong GU <88359731+gcl-coder@users.noreply.github.com> Date: Thu, 19 Nov 2026 12:20:51 +0800 Subject: [PATCH 3/4] fix(goal-closeout): harden the terminal hook boundary Run the command from the lifecycle layer so control-plane keeps its import boundary, validate the Goal id before any write, reuse the capped process runtime for bounded output and process-tree cleanup, and record launch failures in the ledger. Keep the command local-private: the Dashboard sees configured/timeout only and cannot persist a command. Signed-off-by: ChengLong GU <88359731+gcl-coder@users.noreply.github.com> --- loopx/capabilities/configuration_ui.py | 8 ++ .../goal_closeout/machine_defaults.py | 83 ++++++++++- .../capabilities/machine_configuration/cli.py | 6 + .../machine_configuration/contract.py | 20 ++- .../control_plane/goals/activation_service.py | 65 +++++---- loopx/extensions/process_runtime.py | 2 + loopx/global_registry.py | 2 +- loopx/lifecycle/__init__.py | 0 .../hooks.py => lifecycle/goal_closeout.py} | 134 +++++++++--------- loopx/runtime.py | 2 +- tests/capabilities/test_goal_closeout_hook.py | 116 ++++++++++++++- .../test_goal_closeout_terminal_hooks.py | 2 +- .../test_machine_configuration_contract.py | 1 + tests/test_chat_machine_configuration_api.py | 101 ++++++++++++- 14 files changed, 435 insertions(+), 107 deletions(-) create mode 100644 loopx/lifecycle/__init__.py rename loopx/{capabilities/goal_closeout/hooks.py => lifecycle/goal_closeout.py} (64%) diff --git a/loopx/capabilities/configuration_ui.py b/loopx/capabilities/configuration_ui.py index e991c2d0e9..19cf9b1096 100644 --- a/loopx/capabilities/configuration_ui.py +++ b/loopx/capabilities/configuration_ui.py @@ -125,6 +125,14 @@ def capability_configuration_editor( _field("max_trials", "Maximum proposed trials", "number", minimum=0, maximum=2, required=True), ], }, + "goal_closeout": { + "supported_scopes": ["machine"], "writable_scopes": ["machine"], + "fields": [ + _field("timeout_seconds", "Closeout timeout (seconds)", "number", + minimum=1, maximum=600, required=True, + description="Bounds one terminal hook invocation. The command itself is local-private: configure it with the machine-config CLI, never through the Dashboard."), + ], + }, "goal_storage": { "supported_scopes": ["machine"], "writable_scopes": ["machine"], "fields": [_field("new_goal_provider", "New Goal storage provider", "select", diff --git a/loopx/capabilities/goal_closeout/machine_defaults.py b/loopx/capabilities/goal_closeout/machine_defaults.py index 4a45705be8..ae0a9eecbb 100644 --- a/loopx/capabilities/goal_closeout/machine_defaults.py +++ b/loopx/capabilities/goal_closeout/machine_defaults.py @@ -47,19 +47,96 @@ def normalize_goal_closeout_configuration( } +def _public_goal_closeout_configuration( + value: Mapping[str, Any], +) -> dict[str, Any]: + """Publish whether a command exists, never the local program or its path.""" + + normalized = normalize_goal_closeout_configuration(value) + return { + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "configured": bool(normalized["command"]), + "timeout_seconds": normalized["timeout_seconds"], + } + + +def _apply_goal_closeout_public_update( + current: Mapping[str, Any] | None, + update: Mapping[str, Any], +) -> dict[str, Any]: + """Let the Dashboard change only the public timeout, not the command.""" + + base = ( + normalize_goal_closeout_configuration(current) + if current is not None + else { + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "command": [], + "timeout_seconds": DEFAULT_CLOSEOUT_TIMEOUT_SECONDS, + } + ) + unknown = sorted(set(update) - {"schema_version", "configured", "timeout_seconds"}) + if unknown: + raise ValueError( + "goal_closeout public update contains unsupported fields: " + + ", ".join(unknown) + ) + if "schema_version" in update and ( + update["schema_version"] != GOAL_CLOSEOUT_CONFIGURATION_SCHEMA + ): + raise ValueError( + "goal_closeout must use " + GOAL_CLOSEOUT_CONFIGURATION_SCHEMA + ) + if "configured" in update and bool(update["configured"]) != bool(base["command"]): + raise ValueError( + "goal_closeout configured is derived from the locally configured command" + ) + merged = dict(base) + if "timeout_seconds" in update: + merged["timeout_seconds"] = update["timeout_seconds"] + return normalize_goal_closeout_configuration(merged) + + +def _apply_goal_closeout_local_update( + current: Mapping[str, Any] | None, + update: Mapping[str, Any], +) -> dict[str, Any]: + """Let the local operator CLI write the command the Dashboard cannot.""" + + base = ( + normalize_goal_closeout_configuration(current) + if current is not None + else { + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "command": [], + "timeout_seconds": DEFAULT_CLOSEOUT_TIMEOUT_SECONDS, + } + ) + unknown = sorted(set(update) - {"schema_version", "command", "timeout_seconds"}) + if unknown: + raise ValueError( + "goal_closeout update contains unsupported fields: " + ", ".join(unknown) + ) + return normalize_goal_closeout_configuration({**base, **dict(update)}) + + def goal_closeout_machine_configuration_namespace() -> MachineConfigurationNamespace: return MachineConfigurationNamespace( namespace="goal_closeout", schema_versions=frozenset({GOAL_CLOSEOUT_CONFIGURATION_SCHEMA}), normalize=normalize_goal_closeout_configuration, - project_public=lambda value: dict(value), - apply_public_update=lambda _current, update: dict(update), + project_public=_public_goal_closeout_configuration, + apply_public_update=_apply_goal_closeout_public_update, + local_only_fields=frozenset({"command"}), + apply_local_update=_apply_goal_closeout_local_update, title="Terminal Goal closeout command", description=( "Optional machine-wide command run after a Goal reaches a terminal " "transition (stop, retirement or runtime archive). The command is " "best effort, receives one bounded JSON payload on stdin, and can " - "never block the LoopX command that triggered it." + "never block the LoopX command that triggered it. Keep the command " + "local-private: write it with the machine-config CLI; the Dashboard " + "only sees whether one is configured and may adjust the timeout." ), default_configuration={ "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, diff --git a/loopx/capabilities/machine_configuration/cli.py b/loopx/capabilities/machine_configuration/cli.py index fdcc0b7940..15f81d171b 100644 --- a/loopx/capabilities/machine_configuration/cli.py +++ b/loopx/capabilities/machine_configuration/cli.py @@ -276,6 +276,9 @@ def handle_machine_configuration_command( namespace=args.namespace, namespace_configuration=configuration, registry=registry, + # The local operator CLI is the trusted writer for fields + # the loopback Dashboard may only read. + allow_local_only=True, ) payload = configure_machine_configuration( runtime_root=runtime_root, @@ -290,6 +293,9 @@ def handle_machine_configuration_command( namespace=args.namespace, namespace_configuration=configuration, registry=registry, + # The local operator CLI is the trusted writer for fields + # the loopback Dashboard may only read. + allow_local_only=True, ) payload = configure_machine_configuration( runtime_root=runtime_root, diff --git a/loopx/capabilities/machine_configuration/contract.py b/loopx/capabilities/machine_configuration/contract.py index 6ee32708a9..13017e74fe 100644 --- a/loopx/capabilities/machine_configuration/contract.py +++ b/loopx/capabilities/machine_configuration/contract.py @@ -33,6 +33,11 @@ class MachineConfigurationNamespace: description: str | None = None documentation: Mapping[str, str] | None = None default_configuration: Mapping[str, Any] | None = None + # Fields only the local operator CLI may write. The loopback Dashboard + # routes merge through this contract too, so without this split a public + # namespace update could persist an arbitrary executable path. + local_only_fields: frozenset[str] = frozenset() + apply_local_update: PublicUpdater | None = None def __post_init__(self) -> None: if not _NAMESPACE_RE.fullmatch(self.namespace): @@ -197,10 +202,18 @@ def merge_machine_configuration_namespace( namespace: str, namespace_configuration: Mapping[str, Any], registry: MachineConfigurationRegistry, + allow_local_only: bool = False, ) -> dict[str, Any]: """Build one whole-document update while preserving sibling namespaces.""" contract = registry.resolve(namespace) + if not allow_local_only: + blocked = sorted(set(namespace_configuration) & contract.local_only_fields) + if blocked: + raise ValueError( + "machine-configuration namespace only accepts these fields from " + f"the local CLI: {', '.join(blocked)}" + ) # Namespace updates are also the recovery path for an installed namespace # whose previously valid value no longer satisfies the current contract. # Keep the stored value opaque until the owning namespace has replaced it; @@ -228,8 +241,13 @@ def merge_machine_configuration_namespace( raise TypeError( f"machine_configuration.namespaces.{namespace} must be an object" ) + updater = ( + contract.apply_local_update + if allow_local_only and contract.apply_local_update is not None + else contract.apply_public_update + ) updated_namespace = _mapping( - contract.apply_public_update(current_namespace, namespace_configuration), + updater(current_namespace, namespace_configuration), f"machine_configuration.namespaces.{namespace}", ) return normalize_machine_configuration( diff --git a/loopx/control_plane/goals/activation_service.py b/loopx/control_plane/goals/activation_service.py index 20070d48cb..368d3b2ea9 100644 --- a/loopx/control_plane/goals/activation_service.py +++ b/loopx/control_plane/goals/activation_service.py @@ -1,5 +1,6 @@ from __future__ import annotations +from collections.abc import Mapping from contextlib import ExitStack, nullcontext from dataclasses import dataclass from enum import Enum @@ -406,7 +407,6 @@ def set_goal_activation_state( return payload sync_payload: dict[str, Any] | None = None - closeout_goal: dict[str, Any] | None = None with project_registry_transaction( source_registry, operation="set_goal_activation_state", @@ -554,36 +554,49 @@ def set_goal_activation_state( and payload.get("written") and closeout_goal is not None ): - from ...capabilities.goal_closeout.hooks import run_goal_closeout - - closeout_runtime_root = resolve_runtime_root( - load_registry(source_registry), - runtime_root_override, - registry_path=source_registry, - ) - state_file = closeout_goal.get("state_file") - if not state_file: - state_file = ( - source_registry.parent - / "goals" - / normalized_goal_id - / "ACTIVE_GOAL_STATE.md" - ) - payload["closeout"] = run_goal_closeout( - runtime_root=closeout_runtime_root, + payload["closeout"] = _stop_closeout_payload( + source_registry=source_registry, + runtime_root_override=runtime_root_override, goal_id=normalized_goal_id, - repo=( - str(closeout_goal.get("repo")) - if closeout_goal.get("repo") - else None - ), - state_file=str(state_file), - terminal_reason="stopped", - trigger="goal-lifecycle-stop", + closeout_goal=closeout_goal, ) return payload +def _stop_closeout_payload( + *, + source_registry: Path, + runtime_root_override: str | None, + goal_id: str, + closeout_goal: Mapping[str, Any], +) -> dict[str, Any]: + """Run the terminal hook after a committed stop transition.""" + + from ...lifecycle.goal_closeout import run_goal_closeout + + closeout_runtime_root = resolve_runtime_root( + load_registry(source_registry), + runtime_root_override, + registry_path=source_registry, + ) + state_file = closeout_goal.get("state_file") + if not state_file: + state_file = ( + source_registry.parent + / "goals" + / goal_id + / "ACTIVE_GOAL_STATE.md" + ) + return run_goal_closeout( + runtime_root=closeout_runtime_root, + goal_id=goal_id, + repo=str(closeout_goal.get("repo")) if closeout_goal.get("repo") else None, + state_file=str(state_file), + terminal_reason="stopped", + trigger="goal-lifecycle-stop", + ) + + def render_goal_activation_markdown(payload: dict[str, Any]) -> str: lines = [ "# Goal Activation", diff --git a/loopx/extensions/process_runtime.py b/loopx/extensions/process_runtime.py index bb7875e279..50e1e2786c 100644 --- a/loopx/extensions/process_runtime.py +++ b/loopx/extensions/process_runtime.py @@ -89,6 +89,7 @@ class CappedProcessResult: returncode: int stdout: bytes failure_kind: str | None = None + stderr: bytes = b"" def _wait_for_process(process: subprocess.Popen[bytes] | subprocess.Popen[str], timeout: float) -> bool: @@ -713,4 +714,5 @@ def write_stdin() -> None: returncode=returncode, stdout=bytes(stdout), failure_kind="timeout" if timed_out else limit_kind, + stderr=bytes(stderr), ) diff --git a/loopx/global_registry.py b/loopx/global_registry.py index 7874347587..eb3f5b7a05 100644 --- a/loopx/global_registry.py +++ b/loopx/global_registry.py @@ -661,7 +661,7 @@ def retire_global_registry_goals( closeouts: list[dict[str, Any]] = [] if execute: - from .capabilities.goal_closeout.hooks import run_goal_closeout + from .lifecycle.goal_closeout import run_goal_closeout for retired_goal in receipt.get("retired_goals", []): goal_id = str(retired_goal.get("id") or "").strip() diff --git a/loopx/lifecycle/__init__.py b/loopx/lifecycle/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/loopx/capabilities/goal_closeout/hooks.py b/loopx/lifecycle/goal_closeout.py similarity index 64% rename from loopx/capabilities/goal_closeout/hooks.py rename to loopx/lifecycle/goal_closeout.py index c3587ee05b..ba496bdf7f 100644 --- a/loopx/capabilities/goal_closeout/hooks.py +++ b/loopx/lifecycle/goal_closeout.py @@ -1,19 +1,21 @@ from __future__ import annotations import json -import os -import signal -import subprocess -import tempfile import time from pathlib import Path from typing import Any -from ...control_plane.runtime.time import now_local_iso -from ...file_lock import LockAcquisitionPolicy, exclusive_file_lock -from ..machine_configuration.builtins import build_builtin_machine_configuration_registry -from ..machine_configuration.store import read_machine_configuration -from .machine_defaults import normalize_goal_closeout_configuration +from ..capabilities.goal_closeout.machine_defaults import ( + normalize_goal_closeout_configuration, +) +from ..capabilities.machine_configuration.builtins import ( + build_builtin_machine_configuration_registry, +) +from ..capabilities.machine_configuration.store import read_machine_configuration +from ..control_plane.runtime.time import now_local_iso +from ..extensions.process_runtime import run_capped_process +from ..file_lock import LockAcquisitionPolicy, exclusive_file_lock +from ..paths import validate_goal_id_path_segment GOAL_CLOSEOUT_PAYLOAD_SCHEMA_VERSION = "loopx_goal_closeout_v1" GOAL_CLOSEOUT_LEDGER_SCHEMA_VERSION = "loopx_goal_closeout_invocation_v0" @@ -21,19 +23,9 @@ _MAX_CAPTURE_BYTES = 8192 -class _Capture: - """Read only a bounded prefix from a binary temporary file.""" - - def __init__(self, handle: Any) -> None: - self.handle = handle - - def text(self) -> str: - self.handle.seek(0) - return self.handle.read(_MAX_CAPTURE_BYTES).decode("utf-8", errors="replace") - - def goal_closeout_ledger_path(runtime_root: Path, goal_id: str) -> Path: - return runtime_root / "goals" / goal_id / GOAL_CLOSEOUT_LEDGER_FILENAME + safe_goal_id = validate_goal_id_path_segment(goal_id) + return runtime_root / "goals" / safe_goal_id / GOAL_CLOSEOUT_LEDGER_FILENAME def _read_configuration(runtime_root: Path) -> tuple[dict[str, Any] | None, str | None]: @@ -56,22 +48,6 @@ def _read_configuration(runtime_root: Path) -> tuple[dict[str, Any] | None, str return None, f"{type(exc).__name__}: {exc}" -def _terminate(process: subprocess.Popen[bytes]) -> None: - """Kill the command and its descendants, then reap the direct child.""" - - try: - os.killpg(process.pid, signal.SIGKILL) - except (AttributeError, PermissionError, ProcessLookupError, OSError): - try: - process.kill() - except OSError: - pass - try: - process.wait(timeout=5) - except subprocess.TimeoutExpired: - pass - - def _write_ledger( ledger_dir: Path, record: dict[str, Any], @@ -91,6 +67,10 @@ def _write_ledger( return path, False, f"{type(exc).__name__}: {exc}" +def _decode_capture(value: bytes) -> str: + return value[:_MAX_CAPTURE_BYTES].decode("utf-8", errors="replace") + + def run_goal_closeout( *, runtime_root: Path, @@ -116,6 +96,17 @@ def run_goal_closeout( "status": "not_configured", "ledger_recorded": False, } + try: + safe_goal_id = validate_goal_id_path_segment(goal_id) + except ValueError as exc: + result.update({"status": "invalid_goal_id", "error": str(exc)}) + return result + result["goal_id"] = safe_goal_id + selected_ledger_dir = ( + ledger_dir + if ledger_dir is not None + else goal_closeout_ledger_path(runtime_root, safe_goal_id).parent + ) try: configuration, configuration_error = _read_configuration(runtime_root) if configuration_error is not None: @@ -135,7 +126,7 @@ def run_goal_closeout( payload = { "schema_version": GOAL_CLOSEOUT_PAYLOAD_SCHEMA_VERSION, - "goal_id": goal_id, + "goal_id": safe_goal_id, "repo": repo or "", "state_file": state_file or "", "terminal_reason": terminal_reason, @@ -143,31 +134,39 @@ def run_goal_closeout( "trigger": trigger, } started = time.monotonic() + exit_code: int | None = None timed_out = False - with tempfile.TemporaryFile(mode="w+b") as stdout_handle: - with tempfile.TemporaryFile(mode="w+b") as stderr_handle: - process = subprocess.Popen( - command, - stdin=subprocess.PIPE, - stdout=stdout_handle, - stderr=stderr_handle, - cwd=repo if repo and Path(repo).is_dir() else None, - start_new_session=True, - ) - try: - process.communicate( - input=json.dumps(payload, ensure_ascii=False).encode("utf-8"), - timeout=float(configuration["timeout_seconds"]), - ) - except subprocess.TimeoutExpired: - timed_out = True - _terminate(process) - duration_ms = int((time.monotonic() - started) * 1000) - stdout_text = _Capture(stdout_handle).text() - stderr_text = _Capture(stderr_handle).text() - exit_code = process.returncode - if timed_out: + failure_kind: str | None = None + stdout_text = "" + stderr_text = "" + launch_error: str | None = None + try: + completed = run_capped_process( + command, + stdin=json.dumps(payload, ensure_ascii=False).encode("utf-8"), + timeout_seconds=float(configuration["timeout_seconds"]), + output_limit_bytes=_MAX_CAPTURE_BYTES, + # Never hold a directory handle inside a worktree that the + # archive transition is deleting. + cwd=None, + ) + except OSError as exc: + launch_error = f"{type(exc).__name__}: {exc}" + except Exception as exc: + launch_error = f"{type(exc).__name__}: {exc}" + else: + exit_code = completed.returncode + failure_kind = completed.failure_kind + timed_out = failure_kind == "timeout" + stdout_text = _decode_capture(completed.stdout) + stderr_text = _decode_capture(completed.stderr) + duration_ms = int((time.monotonic() - started) * 1000) + if launch_error is not None: + status = "launch_error" + elif timed_out: status = "timeout" + elif failure_kind is not None: + status = "output_limit" elif exit_code == 0: status = "success" else: @@ -177,30 +176,30 @@ def run_goal_closeout( "status": status, "exit_code": exit_code, "timed_out": timed_out, + "failure_kind": failure_kind, "duration_ms": duration_ms, "stdout": stdout_text, "stderr": stderr_text, } ) + if launch_error is not None: + result["error"] = launch_error record = { "schema_version": GOAL_CLOSEOUT_LEDGER_SCHEMA_VERSION, "recorded_at": now_local_iso(), - "goal_id": goal_id, + "goal_id": safe_goal_id, "trigger": trigger, "terminal_reason": terminal_reason, "command": command, "status": status, "exit_code": exit_code, "timed_out": timed_out, + "failure_kind": failure_kind, "duration_ms": duration_ms, "stdout": stdout_text, "stderr": stderr_text, + **({"error": launch_error} if launch_error is not None else {}), } - selected_ledger_dir = ( - ledger_dir - if ledger_dir is not None - else goal_closeout_ledger_path(runtime_root, goal_id).parent - ) ledger_path, ledger_recorded, ledger_error = _write_ledger( selected_ledger_dir, record ) @@ -220,4 +219,3 @@ def run_goal_closeout( } ) return result - diff --git a/loopx/runtime.py b/loopx/runtime.py index 84081b51f8..21bbba5dfb 100644 --- a/loopx/runtime.py +++ b/loopx/runtime.py @@ -246,7 +246,7 @@ def archive_runtime_goal( _validate_archive_destination(source, destination) destination.parent.mkdir(parents=True, exist_ok=True) shutil.move(str(source), str(destination)) - from .capabilities.goal_closeout.hooks import run_goal_closeout + from .lifecycle.goal_closeout import run_goal_closeout archived_state_file = destination / "ACTIVE_GOAL_STATE.md" declared_state_file = ( diff --git a/tests/capabilities/test_goal_closeout_hook.py b/tests/capabilities/test_goal_closeout_hook.py index ca73db9c98..f8eb955dd2 100644 --- a/tests/capabilities/test_goal_closeout_hook.py +++ b/tests/capabilities/test_goal_closeout_hook.py @@ -4,19 +4,25 @@ import sys from pathlib import Path -from loopx.capabilities.goal_closeout.hooks import ( - GOAL_CLOSEOUT_LEDGER_FILENAME, - run_goal_closeout, -) +import pytest + from loopx.capabilities.goal_closeout.machine_defaults import ( GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, ) from loopx.capabilities.machine_configuration.builtins import ( build_builtin_machine_configuration_registry, ) +from loopx.capabilities.machine_configuration.contract import ( + merge_machine_configuration_namespace, + project_machine_configuration, +) from loopx.capabilities.machine_configuration.store import ( configure_machine_configuration, ) +from loopx.lifecycle.goal_closeout import ( + GOAL_CLOSEOUT_LEDGER_FILENAME, + run_goal_closeout, +) def _configure(root: Path, *, command: list[str], timeout_seconds: int = 5) -> None: @@ -138,3 +144,105 @@ def test_closeout_command_failure_is_reported_without_blocking(tmp_path: Path) - assert result["exit_code"] == 7 assert "bad" in result["stderr"] assert result["ledger_recorded"] is True + + +def test_invalid_goal_id_is_rejected_before_any_command_or_ledger( + tmp_path: Path, +) -> None: + marker = tmp_path / "ran.txt" + _configure( + tmp_path, + command=[sys.executable, "-c", "open(sys.argv[1], 'w').write('x')", str(marker)], + ) + + result = run_goal_closeout( + runtime_root=tmp_path, + goal_id="../escape", + repo=None, + state_file=None, + terminal_reason="retired", + trigger="retire", + ) + + assert result["status"] == "invalid_goal_id" + assert result["ledger_recorded"] is False + assert not marker.exists() + assert not (tmp_path / "goals").exists() + + +def test_missing_executable_is_recorded_as_a_launch_error(tmp_path: Path) -> None: + _configure(tmp_path, command=[str(tmp_path / "missing-closeout-binary")]) + + result = run_goal_closeout( + runtime_root=tmp_path, + goal_id="fixture", + repo=None, + state_file=None, + terminal_reason="retired", + trigger="retire", + ) + + assert result["status"] == "launch_error" + assert result["ledger_recorded"] is True + assert "FileNotFoundError" in result["error"] + rows = _ledger_rows(tmp_path, "fixture") + assert len(rows) == 1 + assert rows[0]["status"] == "launch_error" + assert "FileNotFoundError" in str(rows[0]["error"]) + + +def test_public_projection_hides_the_command_and_public_update_rejects_it( + tmp_path: Path, +) -> None: + command = [sys.executable, "-c", "raise SystemExit(0)"] + _configure(tmp_path, command=command) + registry = build_builtin_machine_configuration_registry() + stored = json.loads( + (tmp_path / "machine" / "configuration.json").read_text(encoding="utf-8") + ) + + projected = project_machine_configuration(stored, registry=registry) + public = projected["namespaces"]["goal_closeout"] + assert public == { + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "configured": True, + "timeout_seconds": 5, + } + assert str(tmp_path) not in json.dumps(projected) + assert sys.executable not in json.dumps(projected) + + with pytest.raises(ValueError, match="local CLI: command"): + merge_machine_configuration_namespace( + stored, + namespace="goal_closeout", + namespace_configuration={ + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "command": ["/bin/sh", "-c", "id > /tmp/pwned"], + }, + registry=registry, + ) + + merged = merge_machine_configuration_namespace( + stored, + namespace="goal_closeout", + namespace_configuration={ + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "timeout_seconds": 9, + }, + registry=registry, + ) + assert merged["namespaces"]["goal_closeout"]["command"] == command + assert merged["namespaces"]["goal_closeout"]["timeout_seconds"] == 9 + + local = merge_machine_configuration_namespace( + stored, + namespace="goal_closeout", + namespace_configuration={ + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "command": command, + "timeout_seconds": 9, + }, + registry=registry, + allow_local_only=True, + ) + assert local["namespaces"]["goal_closeout"]["command"] == command diff --git a/tests/capabilities/test_goal_closeout_terminal_hooks.py b/tests/capabilities/test_goal_closeout_terminal_hooks.py index 8d2894dbac..63872c12f9 100644 --- a/tests/capabilities/test_goal_closeout_terminal_hooks.py +++ b/tests/capabilities/test_goal_closeout_terminal_hooks.py @@ -4,7 +4,6 @@ import sys from pathlib import Path -from loopx.capabilities.goal_closeout.hooks import GOAL_CLOSEOUT_LEDGER_FILENAME from loopx.capabilities.goal_closeout.machine_defaults import ( GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, ) @@ -16,6 +15,7 @@ ) from loopx.control_plane.goals.activation_service import set_goal_activation_state from loopx.global_registry import retire_global_registry_goals, sync_project_registry_to_global +from loopx.lifecycle.goal_closeout import GOAL_CLOSEOUT_LEDGER_FILENAME from loopx.runtime import archive_runtime_goal diff --git a/tests/capabilities/test_machine_configuration_contract.py b/tests/capabilities/test_machine_configuration_contract.py index aa1e8db415..0677070bae 100644 --- a/tests/capabilities/test_machine_configuration_contract.py +++ b/tests/capabilities/test_machine_configuration_contract.py @@ -352,6 +352,7 @@ def test_builtin_catalog_lists_every_owner_in_namespace_order() -> None: "codex_chat", "context_delivery", "explore_harness", + "goal_closeout", "goal_storage", "manager_runtime", "periodic_report", diff --git a/tests/test_chat_machine_configuration_api.py b/tests/test_chat_machine_configuration_api.py index 637008efa0..00745dced2 100644 --- a/tests/test_chat_machine_configuration_api.py +++ b/tests/test_chat_machine_configuration_api.py @@ -329,6 +329,86 @@ def test_real_chat_http_invalid_namespace_has_safe_repair_path( server.server_close() +def test_goal_closeout_http_update_cannot_write_a_command(tmp_path: Path) -> None: + from loopx.capabilities.machine_configuration.builtins import ( + build_builtin_machine_configuration_registry, + ) + + handler = _Handler( + tmp_path, + body={ + "namespace": "goal_closeout", + "namespace_configuration": { + "schema_version": "loopx_goal_closeout_configuration_v0", + "command": ["/bin/sh", "-c", "id > /tmp/pwned"], + }, + }, + ) + registry = build_builtin_machine_configuration_registry() + + with pytest.raises(ValueError, match="local CLI: command"): + handler._machine_configuration_namespace_update( + handler.body, registry=registry + ) + assert not (tmp_path / "machine" / "configuration.json").exists() + + timeout_only = _Handler( + tmp_path, + body={ + "namespace": "goal_closeout", + "namespace_configuration": { + "schema_version": "loopx_goal_closeout_configuration_v0", + "timeout_seconds": 12, + }, + }, + ) + configuration = timeout_only._machine_configuration_namespace_update( + timeout_only.body, registry=registry + ) + assert configuration["namespaces"]["goal_closeout"] == { + "schema_version": "loopx_goal_closeout_configuration_v0", + "command": [], + "timeout_seconds": 12, + } + + +def test_goal_closeout_real_http_rejects_a_command_update(tmp_path: Path) -> None: + from loopx.chat_server import ChatHTTPServer, ChatRequestHandler + + server = ChatHTTPServer(("127.0.0.1", 0), ChatRequestHandler) + server.runtime_root = tmp_path + server.verbose = False + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + connection = http.client.HTTPConnection(*server.server_address, timeout=5) + try: + connection.request( + "POST", + CHAT_MACHINE_CONFIGURATION_PREVIEW_PATH, + body=json.dumps( + { + "namespace": "goal_closeout", + "namespace_configuration": { + "schema_version": "loopx_goal_closeout_configuration_v0", + "command": ["/bin/sh", "-c", "id > /tmp/pwned"], + }, + } + ), + headers={"Content-Type": "application/json"}, + ) + response = connection.getresponse() + assert response.status == 400 + body = json.loads(response.read()) + assert body["ok"] is False + assert "local CLI: command" in body["error"] + assert not (tmp_path / "machine" / "configuration.json").exists() + finally: + connection.close() + server.shutdown() + thread.join(timeout=5) + server.server_close() + + def test_inspection_lists_registered_namespaces_without_local_refs( tmp_path: Path, ) -> None: @@ -343,6 +423,7 @@ def test_inspection_lists_registered_namespaces_without_local_refs( "codex_chat", "context_delivery", "explore_harness", + "goal_closeout", "goal_storage", "manager_runtime", "periodic_report", @@ -367,6 +448,14 @@ def test_inspection_lists_registered_namespaces_without_local_refs( "planning_horizon_goal": True, "yardstick_enabled": False, } + assert namespace_catalog["goal_closeout"]["configuration_template"] == { + "schema_version": "loopx_goal_closeout_configuration_v0", + "configured": False, + "timeout_seconds": 30, + } + assert namespace_catalog["goal_closeout"]["configuration_template"].get( + "command" + ) is None assert namespace_catalog["change_quality_qualification"][ "configuration_template" ] == { @@ -447,7 +536,15 @@ def test_machine_catalog_discovers_goal_features_without_granting_machine_writes ) # Machine-only capabilities are the ones a Goal cannot override: the # manager profile, native host defaults, steward executor and storage target. - assert set(machine) - {"manager_runtime", "steward_executor", "goal_storage", "codex_chat", "context_delivery"} == { + machine_only = { + "manager_runtime", + "steward_executor", + "goal_storage", + "codex_chat", + "context_delivery", + "goal_closeout", + } + assert set(machine) - machine_only == { feature["feature_id"] for feature in goal["features"] } assert machine["pull_request_review"]["available_scopes"] == ["machine", "goal"] @@ -463,7 +560,7 @@ def test_machine_catalog_discovers_goal_features_without_granting_machine_writes for capability_id, item in machine.items(): assert "current" not in item assert "commands" not in item - if capability_id in {"manager_runtime", "steward_executor", "goal_storage", "codex_chat", "context_delivery"}: + if capability_id in machine_only: assert item["available_scopes"] == ["machine"] assert item["machine_namespace"] == capability_id assert item["configuration_editor"]["writable_scopes"] == ["machine"] From a00dd3763a863a228520c03a236242c6c7b1eb02 Mon Sep 17 00:00:00 2001 From: ChengLong GU <88359731+gcl-coder@users.noreply.github.com> Date: Thu, 19 Nov 2026 17:53:58 +0800 Subject: [PATCH 4/4] fix(goal-closeout): run the archive hook after canonical locks release archive_runtime_goal held the runtime-artifact, source, maintenance and registry locks while the terminal hook ran, so a slow operator command blocked every other registry writer for up to the configured timeout. The archive transition now resolves the hook facts under the locked snapshot and invokes the hook once every lock is released. Signed-off-by: ChengLong GU <88359731+gcl-coder@users.noreply.github.com> --- loopx/runtime.py | 27 +++-- .../test_goal_closeout_terminal_hooks.py | 113 ++++++++++++++++++ 2 files changed, 129 insertions(+), 11 deletions(-) diff --git a/loopx/runtime.py b/loopx/runtime.py index 21bbba5dfb..7c081e75db 100644 --- a/loopx/runtime.py +++ b/loopx/runtime.py @@ -147,6 +147,7 @@ def archive_runtime_goal( _validate_archive_destination(source, destination) closeout: dict[str, Any] | None = None + closeout_request: dict[str, Any] | None = None if execute: from .control_plane.coordination.shadow_management import ( runtime_artifact_lock_target, @@ -246,31 +247,35 @@ def archive_runtime_goal( _validate_archive_destination(source, destination) destination.parent.mkdir(parents=True, exist_ok=True) shutil.move(str(source), str(destination)) - from .lifecycle.goal_closeout import run_goal_closeout - archived_state_file = destination / "ACTIVE_GOAL_STATE.md" declared_state_file = ( archive_goal.get("state_file") if archive_goal else None ) - closeout = run_goal_closeout( - runtime_root=runtime_root, - goal_id=safe_goal_id, - repo=( + # Resolve the hook facts under the snapshot, but run the operator + # command only after every canonical lock is released. + closeout_request = { + "runtime_root": runtime_root, + "goal_id": safe_goal_id, + "repo": ( str(archive_goal.get("repo")) if archive_goal and archive_goal.get("repo") else None ), - state_file=( + "state_file": ( str(archived_state_file) if archived_state_file.exists() else str(declared_state_file) if declared_state_file else None ), - terminal_reason="archived", - trigger="archive-runtime", - ledger_dir=destination, - ) + "terminal_reason": "archived", + "trigger": "archive-runtime", + "ledger_dir": destination, + } + if closeout_request is not None: + from .lifecycle.goal_closeout import run_goal_closeout + + closeout = run_goal_closeout(**closeout_request) return { "ok": True, diff --git a/tests/capabilities/test_goal_closeout_terminal_hooks.py b/tests/capabilities/test_goal_closeout_terminal_hooks.py index 63872c12f9..85ea4891e8 100644 --- a/tests/capabilities/test_goal_closeout_terminal_hooks.py +++ b/tests/capabilities/test_goal_closeout_terminal_hooks.py @@ -55,6 +55,76 @@ def _configure_closeout(root: Path, payload_path: Path) -> None: ) assert payload["ok"], payload +_LOCK_PROBE = r""" +import pathlib +import sys + +repo_root, runtime_root, goal_id, registry_path, output_path = sys.argv[1:6] +sys.path.insert(0, repo_root) + +from loopx.control_plane.coordination.shadow_management import ( + runtime_artifact_lock_target, +) +from loopx.file_lock import exclusive_cross_runtime_file_lock + + +def probe(target): + try: + with exclusive_cross_runtime_file_lock(target, timeout_seconds=0): + return "FREE" + except Exception: + return "HELD" + + +lines = [ + probe(runtime_artifact_lock_target(pathlib.Path(runtime_root), goal_id)), + probe(pathlib.Path(registry_path)), +] +pathlib.Path(output_path).write_text("\n".join(lines), encoding="utf-8") +""" + + +def _configure_lock_probe_closeout( + root: Path, + *, + output_path: Path, + goal_id: str, + registry_path: Path, +) -> None: + configuration = { + "schema_version": "loopx_machine_configuration_v0", + "namespaces": { + "goal_closeout": { + "schema_version": GOAL_CLOSEOUT_CONFIGURATION_SCHEMA, + "command": [ + sys.executable, + "-c", + _LOCK_PROBE, + str(Path(__file__).resolve().parents[2]), + str(root), + goal_id, + str(registry_path), + str(output_path), + ], + "timeout_seconds": 10, + } + }, + } + registry = build_builtin_machine_configuration_registry() + preview = configure_machine_configuration( + runtime_root=root, + configuration=configuration, + registry=registry, + ) + payload = configure_machine_configuration( + runtime_root=root, + configuration=configuration, + registry=registry, + execute=True, + expected_plan_revision=preview["plan_revision"], + ) + assert payload["ok"], payload + def _ledger(root: Path, goal_id: str) -> list[dict[str, object]]: path = root / "goals" / goal_id / GOAL_CLOSEOUT_LEDGER_FILENAME @@ -215,3 +285,46 @@ def test_archive_runs_closeout_after_move_without_recreating_source(tmp_path: Pa assert payload["goal_id"] == "archived-goal" assert payload["terminal_reason"] == "archived" assert payload["state_file"] == str(archive_path / "ACTIVE_GOAL_STATE.md") + + +def test_archive_runs_closeout_after_canonical_locks_are_released(tmp_path: Path) -> None: + project = tmp_path / "project" + registry_path = project / ".loopx" / "registry.json" + runtime_root = project / ".loopx" / "runtime" + source = runtime_root / "goals" / "locked-goal" + source.mkdir(parents=True) + (source / "ACTIVE_GOAL_STATE.md").write_text("state\n", encoding="utf-8") + _write_json( + registry_path, + { + "schema_version": 1, + "common_runtime_root": ".loopx/runtime", + "goals": [ + { + "id": "locked-goal", + "display_name": "Archive lock fixture", + "repo": str(project), + "state_file": ".loopx/runtime/goals/locked-goal/ACTIVE_GOAL_STATE.md", + } + ], + }, + ) + probe_path = tmp_path / "lock-probe.txt" + _configure_lock_probe_closeout( + runtime_root, + output_path=probe_path, + goal_id="locked-goal", + registry_path=registry_path, + ) + + result = archive_runtime_goal( + registry_path=registry_path, + runtime_root_override=None, + goal_id="locked-goal", + archive_root=None, + allow_registered=True, + execute=True, + ) + assert result["ok"] is True, result + assert result["closeout"]["status"] == "success", result + assert probe_path.read_text(encoding="utf-8").splitlines() == ["FREE", "FREE"]