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/__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/machine_defaults.py b/loopx/capabilities/goal_closeout/machine_defaults.py new file mode 100644 index 0000000000..ae0a9eecbb --- /dev/null +++ b/loopx/capabilities/goal_closeout/machine_defaults.py @@ -0,0 +1,146 @@ +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 _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=_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. 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, + "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/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 b67a82024a..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 @@ -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,9 +546,57 @@ 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 + ): + payload["closeout"] = _stop_closeout_payload( + source_registry=source_registry, + runtime_root_override=runtime_root_override, + goal_id=normalized_goal_id, + 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 9d0e676b06..eb3f5b7a05 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 .lifecycle.goal_closeout 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/lifecycle/__init__.py b/loopx/lifecycle/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/loopx/lifecycle/goal_closeout.py b/loopx/lifecycle/goal_closeout.py new file mode 100644 index 0000000000..ba496bdf7f --- /dev/null +++ b/loopx/lifecycle/goal_closeout.py @@ -0,0 +1,221 @@ +from __future__ import annotations + +import json +import time +from pathlib import Path +from typing import Any + +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" +GOAL_CLOSEOUT_LEDGER_FILENAME = "closeout-ledger.jsonl" +_MAX_CAPTURE_BYTES = 8192 + + +def goal_closeout_ledger_path(runtime_root: Path, goal_id: str) -> Path: + 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]: + 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 _write_ledger( + ledger_dir: Path, + record: dict[str, Any], +) -> tuple[Path, bool, str | None]: + path = ledger_dir / GOAL_CLOSEOUT_LEDGER_FILENAME + 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 _decode_capture(value: bytes) -> str: + return value[:_MAX_CAPTURE_BYTES].decode("utf-8", errors="replace") + + +def run_goal_closeout( + *, + runtime_root: Path, + goal_id: str, + repo: str | None, + 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. + + 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: + 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: + 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": safe_goal_id, + "repo": repo or "", + "state_file": state_file or "", + "terminal_reason": terminal_reason, + "runtime_root": str(runtime_root), + "trigger": trigger, + } + started = time.monotonic() + exit_code: int | None = None + timed_out = False + 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: + status = "failed" + result.update( + { + "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": 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 {}), + } + ledger_path, ledger_recorded, ledger_error = _write_ledger( + selected_ledger_dir, 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/runtime.py b/loopx/runtime.py index 1ad1cc68bc..7c081e75db 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,8 @@ 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 + closeout_request: dict[str, Any] | None = None if execute: from .control_plane.coordination.shadow_management import ( runtime_artifact_lock_target, @@ -237,6 +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)) + archived_state_file = destination / "ACTIVE_GOAL_STATE.md" + declared_state_file = ( + archive_goal.get("state_file") if archive_goal else None + ) + # 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": ( + 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, + } + if closeout_request is not None: + from .lifecycle.goal_closeout import run_goal_closeout + + closeout = run_goal_closeout(**closeout_request) return { "ok": True, @@ -250,6 +289,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_hook.py b/tests/capabilities/test_goal_closeout_hook.py new file mode 100644 index 0000000000..f8eb955dd2 --- /dev/null +++ b/tests/capabilities/test_goal_closeout_hook.py @@ -0,0 +1,248 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +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: + 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 + + +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 new file mode 100644 index 0000000000..85ea4891e8 --- /dev/null +++ b/tests/capabilities/test_goal_closeout_terminal_hooks.py @@ -0,0 +1,330 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +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.lifecycle.goal_closeout import GOAL_CLOSEOUT_LEDGER_FILENAME +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 + +_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 + 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") + + +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"] 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"]