From 9221998670e8842cdbbfb4fc5f94e73994252442 Mon Sep 17 00:00:00 2001 From: "marcin p. joachimiak" <4625870+realmarcin@users.noreply.github.com> Date: Thu, 19 Nov 2026 21:38:22 -0800 Subject: [PATCH] Preserve native preparation launch provenance and guard startup --- .../restart-preparation-launch-20261120.md | 39 ++++ .../launch_restart_preparation_20261120.py | 188 ++++++++++++++++++ .../restart-20261120/launch-summary.json | 27 +++ ...t_restart_preparation_launcher_20261120.py | 155 +++++++++++++++ 4 files changed, 409 insertions(+) create mode 100644 docs/validation/restart-preparation-launch-20261120.md create mode 100644 scripts/adhoc/launch_restart_preparation_20261120.py create mode 100644 scripts/adhoc/provenance/restart-20261120/launch-summary.json create mode 100644 tests/test_restart_preparation_launcher_20261120.py diff --git a/docs/validation/restart-preparation-launch-20261120.md b/docs/validation/restart-preparation-launch-20261120.md new file mode 100644 index 0000000..efb9704 --- /dev/null +++ b/docs/validation/restart-preparation-launch-20261120.md @@ -0,0 +1,39 @@ +# Native restart preparation launch + +One dedicated native preparation worker was launched from accepted candidate +`945c421c648fe09858eabf1f2a4447ab27f9eae3` through the installed work-account +wrapper and supported standalone mode. It stopped at a new checkout trust +prompt. No task input or prompt answer was sent. Scientific review coverage is +zero; A/B population counts remain unresolved. Worker library retrieval and +canonical save/readback have not been established. + +The exact original executed helper and actual receipt remain private and +unchanged. Their [digest mapping](../../scripts/adhoc/provenance/restart-20261120/launch-summary.json) +preserves issue [#228](https://github.com/CultureBotAI/EdgeMech/issues/228) +provenance without publishing operational logs or private bindings. The original +coordinator bootstrap provenance remains a separate parent-owned repair. + +The maintained [launcher](../../scripts/adhoc/launch_restart_preparation_20261120.py) +is a successor, not the producer of the historical launch receipt. It now uses +the CLAW-required lease context manager, revalidates canonical ownership under +the short lease, and refuses native execution if a repository/global lock remains. +Private tmux executable/socket/session bindings are explicit invocation inputs. +It inventories the existing server, refuses existing sessions or retained attempts, +sets pane retention before startup, and contains no prompt-input operation. +No native mutation was rerun to produce evidence for this successor. + +Independent static review identified `EDGE-RESTART-PRIVATE-LOG-001`: proposed +tracked provenance exposed operational bindings. The actual receipt and executed +helper were kept privately intact; only sanitized hashes and aggregate state are +tracked. The successor also removes hardcoded private tmux bindings. Separate +read-only review of the corrected final bytes is required before publication. + +Five focused offline tests cover launch after context release, retained-attempt +refusal, clone failure and release, lock refusal, residual-lock refusal, and +exclusive receipt preservation. They use synthetic execution and do not launch +agents. Final complete-suite results are recorded with the reviewed candidate. + +The parent owns census recovery. A transfer receipt is staging evidence; complete +census and producer-pin verification plus exhaustive historical assessment +reconciliation are still required before A/B freeze. The W5/W6, issue #220, +candidate-correction, source-family, evidence and resource gates remain unchanged. diff --git a/scripts/adhoc/launch_restart_preparation_20261120.py b/scripts/adhoc/launch_restart_preparation_20261120.py new file mode 100644 index 0000000..29f6c8c --- /dev/null +++ b/scripts/adhoc/launch_restart_preparation_20261120.py @@ -0,0 +1,188 @@ +#!/usr/bin/env python3 +"""Launch the single excluded native preparation worker; never send TUI input. + +Purpose: guarded standalone codex-work bootstrap for the authorized native campaign. +Inputs: explicit CLAW/coordinator/campaign roots, accepted request and commit, +and private tmux executable/socket/session binding passed as CLI arguments. +Outputs: isolated clone, retained tmux pane, immutable private stage receipts. +UTC date: 2026-11-20. Issue: CultureBotAI/EdgeMech#228 (helper provenance). +Provenance: new implementation of the installed boss guarded-bootstrap protocol; +does not modify, import, or rerun the original coordinator mutation helpers. +The executed initial version and receipt remain in private campaign storage; +only their hashes/result summary are tracked in scripts/adhoc/provenance/. +This maintained revision uses the +current CLAW AGENTS context-manager contract; it has not been rerun to recreate +historical evidence. Existing attempt guards prohibit a second worker launch. +Scientific coverage is always zero. Interactive prompts require separate handling +by the authorized human/root; this helper cannot answer or paste into any pane. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import subprocess +import sys +from datetime import datetime, timezone +from pathlib import Path + +REQUEST_SHA = "4af8b1cc2fe98032d5ff7f1d7ddb659e491310d3dfd0bcb7a370645c97048a4d" +INITIAL_HEAD = "945c421c648fe09858eabf1f2a4447ab27f9eae3" +ORIGIN = "https://github.com/CultureBotAI/EdgeMech.git" + + +def run(argv: list[str], *, cwd: Path | None = None) -> str: + return subprocess.run( + argv, cwd=cwd, check=True, capture_output=True, text=True, timeout=60 + ).stdout.strip() + + +def digest(path: Path) -> str: + return hashlib.sha256(path.read_bytes()).hexdigest() + + +def receipt(root: Path, stage: str, data: dict) -> Path: + path = root / f"{stage}.json" + record = { + "at_utc": datetime.now(timezone.utc).isoformat(), + "stage": stage, + "scientific_review_coverage": 0, + "classification": "EXCLUDED_PREPARATION_CANARY", + "helper_path": str(Path(__file__).resolve()), + "helper_sha256": digest(Path(__file__)), + **data, + } + with path.open("x") as stream: + json.dump(record, stream, indent=2) + stream.write("\n") + stream.flush() + os.fsync(stream.fileno()) + return path + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--claw-root", type=Path, required=True) + parser.add_argument("--coordinator-root", type=Path, required=True) + parser.add_argument("--campaign-root", type=Path, required=True) + parser.add_argument("--native", type=Path, required=True) + parser.add_argument("--wrapper", type=Path, required=True) + parser.add_argument("--tmux-bin", type=Path, required=True) + parser.add_argument("--tmux-socket", type=Path, required=True) + parser.add_argument("--session", required=True) + args = parser.parse_args() + if not args.tmux_bin.is_absolute() or not args.tmux_socket.is_absolute(): + raise SystemExit("tmux executable/socket inputs must be absolute") + if not args.session or any(c not in "abcdefghijklmnopqrstuvwxyz0123456789-" + for c in args.session): + raise SystemExit("session must contain only lowercase letters, digits, hyphens") + tmux_bin, socket, session = str(args.tmux_bin), str(args.tmux_socket), args.session + claw = args.claw_root.resolve() + coordinator = args.coordinator_root.resolve() + campaign = args.campaign_root.resolve() + if campaign != coordinator.parent or coordinator.name != "coordinator-checkout": + raise SystemExit("unexpected owned campaign/coordinator layout") + if digest(campaign / "REQUEST.md") != REQUEST_SHA: + raise SystemExit("request hash changed") + if run(["git", "rev-parse", "HEAD"], cwd=coordinator) != INITIAL_HEAD: + raise SystemExit("accepted coordinator runtime changed; re-plan before launch") + if run(["git", "remote", "get-url", "origin"], cwd=coordinator) != ORIGIN: + raise SystemExit("coordinator origin mismatch") + # Existing GUI server only. No -A and no fallback server/socket. + tmux = [tmux_bin, "-N", "-S", socket] + sessions = run([*tmux, "list-sessions", "-F", "#S"]).splitlines() + panes = run([*tmux, "list-panes", "-a", "-F", + "#{session_name}|#{pane_id}|#{pane_pid}|#{pane_current_path}"]) + if session in sessions: + raise SystemExit("preparation session already exists; inspect, never relaunch") + destination = campaign / "preparation-worker-01" + evidence = campaign / "preparation-launch-01" + if destination.exists() or evidence.exists(): + raise SystemExit("retained preparation attempt exists; inspect, never overwrite") + native = args.native.resolve(strict=True) + wrapper = args.wrapper.resolve(strict=True) + native_kind = run(["/usr/bin/file", "-b", str(native)]) + if "Mach-O" not in native_kind and "ELF" not in native_kind: + raise SystemExit("native must be the actual binary") + help_text = run([str(native), "--help"]) + if "--no-daemon" not in help_text: + raise SystemExit("standalone execution mode is unsupported") + sys.path[:0] = [str(claw), str(claw / "src")] + from plugins.lock_manager import LockManager + from plugins.repository_settings import RepositorySettings, merged_repository_environment + + target = RepositorySettings.from_environment( + environ=merged_repository_environment(claw / ".env") + ).get_target("edgemech") + repository = target.open() # validates the manifest-resolved Git identity + canonical_head = repository.head.commit.hexsha + evidence.mkdir(mode=0o700) + receipt(evidence, "01-plan", { + "request_sha256": REQUEST_SHA, "checkout": str(destination), + "head": INITIAL_HEAD, "canonical_root": str(target.path), + "canonical_head": canonical_head, "session": session, "socket": socket, + "tmux_bin": tmux_bin, + "inventory": panes.splitlines(), "native": str(native), + "native_sha256": digest(native), "wrapper": str(wrapper), + "wrapper_sha256": digest(wrapper), "occurrence_id": None, + "full_AB_frozen": False, "prompt_delivery": "not_attempted", + }) + os.environ["OPENCLAW_ORCHESTRATION_ROOT"] = str(claw) + manager = LockManager({"my_id": f"edge-preparation-{os.getpid()}"}) + try: + # CLAW AGENTS requires the lease-owned context manager in new code. + # All six subprocesses are bounded at 60s, below this short lease. + with manager.lock("edgemech", "create-restart-preparation-01", timeout=900): + target.open() # revalidate canonical ownership at metadata transition + if run(["git", "rev-parse", "HEAD"], cwd=coordinator) != INITIAL_HEAD: + raise RuntimeError("accepted coordinator runtime changed") + run(["git", "clone", "--shared", "--no-checkout", str(coordinator), + str(destination)]) + run(["git", "remote", "set-url", "origin", ORIGIN], cwd=destination) + run(["git", "checkout", "-b", "campaign/lbnl-preparation-20261120-01", + INITIAL_HEAD], cwd=destination) + if run(["git", "status", "--porcelain=v1"], cwd=destination): + raise RuntimeError("new preparation checkout is not clean") + receipt(evidence, "02-checkout", { + "checkout": str(destination), "head": run(["git", "rev-parse", "HEAD"], + cwd=destination), + "branch": "campaign/lbnl-preparation-20261120-01", + }) + except BaseException as exc: + receipt(evidence, "02-failed", {"error_type": type(exc).__name__, + "error": str(exc)}) + raise + if manager.check_lock("edgemech") or manager.is_global_locked(): + receipt(evidence, "02-lock-still-active", {"state": "NO_LAUNCH_ACTIVE_LOCK"}) + raise RuntimeError("repository/global lease still active; agent launch refused") + driver = destination / "scripts/adhoc/codex_work_helper_20261119.sh" + # Fixed bootstrap receives literal paths, never task text. Retain on exit + # before cd or agent startup; normal installed shell function/permissions. + bootstrap = ( + '"$1" -N -S "$2" set-option -p -t "$TMUX_PANE" remain-on-exit on ' + '&& cd -- "$3" && PATH="$4:$PATH" && export PATH ' + '&& exec /bin/bash --noprofile --norc "$5" "$6" "$7" --no-daemon' + ) + try: + pane = run([*tmux, "new-session", "-d", "-s", session, "-n", "primary", + "-c", str(destination), "-P", "-F", "#{pane_id}", + "/bin/sh", "-c", bootstrap, "sh", tmux_bin, socket, + str(destination), str(native.parent), str(driver), str(wrapper), str(native)]) + path = receipt(evidence, "03-launch", { + "pane": pane, "session": session, "socket": socket, + "checkout": str(destination), "head": INITIAL_HEAD, + "state": "LAUNCHED_INPUT_NOT_INSPECTED", "thread_id": None, + "native_pid": None, "model": None, "effort": None, + "prompt_delivery": "not_attempted", "metadata_lock_released": True, + }) + print(path) + except BaseException as exc: + receipt(evidence, "03-failed", {"error_type": type(exc).__name__, + "error": str(exc)}) + raise + + +if __name__ == "__main__": + main() diff --git a/scripts/adhoc/provenance/restart-20261120/launch-summary.json b/scripts/adhoc/provenance/restart-20261120/launch-summary.json new file mode 100644 index 0000000..7eaf27e --- /dev/null +++ b/scripts/adhoc/provenance/restart-20261120/launch-summary.json @@ -0,0 +1,27 @@ +{ + "date_utc": "2026-11-20", + "issue": "CultureBotAI/EdgeMech#228", + "purpose": "Preparation worker startup provenance; no scientific coverage", + "accepted_request_sha256": "4af8b1cc2fe98032d5ff7f1d7ddb659e491310d3dfd0bcb7a370645c97048a4d", + "accepted_runtime_commit": "945c421c648fe09858eabf1f2a4447ab27f9eae3", + "executed_helper_sha256": "8bd2fd8e8a3bd34cb741d150b025e943f44bc358a7e61cadefdb3395483c47e0", + "actual_launch_receipt_sha256": "0233deb844e0db2ba2c7e4d4e7f26acd353bde36b55ac8f72a213e4436c10fa2", + "preservation": "Original executed helper and actual receipt retained privately, byte-identical; neither rerun nor rewritten", + "workers_launched": 1, + "state_at_inspection": "awaiting_separate_trust_permission", + "task_prompt_delivered": false, + "scientific_review_coverage": 0, + "library_readiness_verified": false, + "canonical_readback_verified": false, + "queue_A_count": null, + "queue_B_count": null, + "successor": "scripts/adhoc/launch_restart_preparation_20261120.py", + "successor_live_execution": false, + "successor_changes": [ + "Lease-owned LockManager context manager and post-release launch gate", + "Private tmux session/socket/executable supplied explicitly at invocation", + "Original operational logs remain private; public provenance is digest-only" + ], + "independent_review_finding": "EDGE-RESTART-PRIVATE-LOG-001", + "scope_limit": "Startup and static engineering review are not scientific approval, library access, or production readiness" +} diff --git a/tests/test_restart_preparation_launcher_20261120.py b/tests/test_restart_preparation_launcher_20261120.py new file mode 100644 index 0000000..5515a2c --- /dev/null +++ b/tests/test_restart_preparation_launcher_20261120.py @@ -0,0 +1,155 @@ +"""Offline failure/ownership tests; never create a tmux server or real agent.""" + +from contextlib import contextmanager +from importlib.util import module_from_spec, spec_from_file_location +from pathlib import Path +from types import SimpleNamespace + +import pytest + +ROOT = Path(__file__).resolve().parents[1] +SPEC = spec_from_file_location( + "restart_launcher", ROOT / "scripts/adhoc/launch_restart_preparation_20261120.py" +) +launcher = module_from_spec(SPEC) +SPEC.loader.exec_module(launcher) + + +@pytest.fixture +def harness(tmp_path, monkeypatch): + campaign = tmp_path / "campaign" + coordinator = campaign / "coordinator-checkout" + coordinator.mkdir(parents=True) + (campaign / "REQUEST.md").write_text("authorized test request") + native = tmp_path / "native" + native.write_text("test executable placeholder") + wrapper = tmp_path / "wrapper" + wrapper.write_text("test wrapper placeholder") + state = {"held": False, "released": False, "launches": 0, "fail_clone": False, + "lock_refused": False, "residual_lock": False, "canonical_checks": 0} + mutations = [] + + class Manager: + def __init__(self, config): + pass + + @contextmanager + def lock(self, resource, operation, timeout): + assert resource == "edgemech" and timeout == 900 + if state["lock_refused"]: + raise RuntimeError("lock refused") + state["held"] = True + try: + yield + finally: + state["held"] = False + state["released"] = True + + def check_lock(self, resource): + return state["residual_lock"] + + def is_global_locked(self): + return False + + class Target: + path = tmp_path / "canonical" + + def open(self): + state["canonical_checks"] += 1 + return SimpleNamespace(head=SimpleNamespace(commit=SimpleNamespace(hexsha="canonical"))) + + settings = SimpleNamespace( + from_environment=lambda **kw: SimpleNamespace(get_target=lambda key: Target()) + ) + monkeypatch.setitem(launcher.sys.modules, "plugins.lock_manager", + SimpleNamespace(LockManager=Manager)) + monkeypatch.setitem(launcher.sys.modules, "plugins.repository_settings", SimpleNamespace( + RepositorySettings=settings, merged_repository_environment=lambda path: {} + )) + + def run(argv, *, cwd=None): + if "list-sessions" in argv: + return "unrelated-session" + if "list-panes" in argv: + return "unrelated-session|%0|1|/unrelated" + if argv[0] == "/usr/bin/file": + return "Mach-O 64-bit executable arm64" + if argv[-1] == "--help": + return "--no-daemon" + if argv[:3] == ["git", "rev-parse", "HEAD"]: + return launcher.INITIAL_HEAD + if argv[:4] == ["git", "remote", "get-url", "origin"]: + return launcher.ORIGIN + if argv[:2] == ["git", "status"]: + return "" + if argv[0] == "git": + assert state["held"] + mutations.append(argv) + if argv[1] == "clone": + if state["fail_clone"]: + raise RuntimeError("synthetic clone failure") + Path(argv[-1]).mkdir() + return "" + if "new-session" in argv: + assert not state["held"] and state["released"] + assert "-N" in argv and "-A" not in argv + assert "--no-daemon" in argv[argv.index("-c", argv.index("/bin/sh")) + 1] + state["launches"] += 1 + return "%9001" + raise AssertionError(argv) + + monkeypatch.setattr(launcher, "run", run) + monkeypatch.setattr(launcher, "REQUEST_SHA", launcher.digest(campaign / "REQUEST.md")) + monkeypatch.setattr(launcher.sys, "argv", ["launcher", "--claw-root", str(tmp_path), + "--coordinator-root", str(coordinator), "--campaign-root", str(campaign), + "--native", str(native), "--wrapper", str(wrapper), + "--tmux-bin", str(tmp_path / "tmux"), "--tmux-socket", str(tmp_path / "socket"), + "--session", "test-preparation"]) + return campaign, state, mutations + + +def test_launch_after_owned_context_releases_and_no_second_attempt(harness): + campaign, state, mutations = harness + launcher.main() + assert state["launches"] == 1 and state["canonical_checks"] == 2 + assert (campaign / "preparation-launch-01/03-launch.json").is_file() + count = len(mutations) + with pytest.raises(SystemExit, match="retained preparation attempt"): + launcher.main() + assert len(mutations) == count and state["launches"] == 1 + + +def test_clone_failure_preserves_receipt_and_releases_without_launch(harness): + campaign, state, _ = harness + state["fail_clone"] = True + with pytest.raises(RuntimeError, match="synthetic clone failure"): + launcher.main() + assert state["released"] and not state["held"] and state["launches"] == 0 + assert "synthetic clone failure" in (campaign / "preparation-launch-01/02-failed.json").read_text() + + +def test_refused_lease_creates_no_clone_or_agent(harness): + campaign, state, mutations = harness + state["lock_refused"] = True + with pytest.raises(RuntimeError, match="lock refused"): + launcher.main() + assert not mutations and state["launches"] == 0 + assert not (campaign / "preparation-worker-01").exists() + assert (campaign / "preparation-launch-01/02-failed.json").is_file() + + +def test_residual_lock_blocks_agent_after_context_exit(harness): + campaign, state, _ = harness + state["residual_lock"] = True + with pytest.raises(RuntimeError, match="lease still active"): + launcher.main() + assert state["launches"] == 0 + assert (campaign / "preparation-launch-01/02-lock-still-active.json").is_file() + + +def test_stage_receipt_refuses_overwrite_of_retained_attempt(tmp_path): + path = launcher.receipt(tmp_path, "original", {"state": "failed"}) + original = path.read_bytes() + with pytest.raises(FileExistsError): + launcher.receipt(tmp_path, "original", {"state": "replacement"}) + assert path.read_bytes() == original