feat(869-c4): activation version-coupling assertion (Part of #869)

Part of #869

Mos (id-11) Gate-16 merge: independent APPROVE @90eb48fa (fail-closed identity locks byte-unchanged verified), author id2 != approver id11, clean mosaic-coder author, CI green wp1992. #869 Point-1 CODE COMPLETE (C1/C3/C5/C2/C4).

Co-authored-by: jason.woltje <jason@diversecanvas.com>
Co-committed-by: jason.woltje <jason@diversecanvas.com>

packages/mosaic/src/mutator-gate/mutator-gate.acceptance.spec.ts

@@ -47,6 +47,22 @@ const piLifecyclePath = join(frameworkRoot, 'runtime/pi/lease-lifecycle.ts');
 const prdyInitPath = join(frameworkRoot, 'tools/prdy/prdy-init.sh');
 const prdyUpdatePath = join(frameworkRoot, 'tools/prdy/prdy-update.sh');
 const remediationHandlerPath = join(frameworkRoot, 'tools/qa/remediation-hook-handler.sh');
+
+// C4 (#869 Point-1): launch-runtime.py now asserts, before anything else,
+// that the CLI's advertised lease-activation capability (normally read via
+// the hidden `mosaic __lease-capability` subcommand) matches what
+// enforcement expects — see framework/tools/lease-broker/
+// activation_version_gate.py. This suite drives launch-runtime.py directly
+// as a subprocess (never through the real `mosaic` CLI), so — exactly like
+// the fake broker (daemon.py) and fake `claude` binaries already used
+// below — it must supply a fake activation-capability probe rather than
+// depend on a real `mosaic` binary being on PATH. `MOSAIC_LEASE_VERSION_PROBE_COMMAND`
+// is launch-runtime.py's injection point for that fake; this literal
+// {name, version} pair must be kept in sync with
+// `EXPECTED_ACTIVATION_CAPABILITY` (activation_version_gate.py) and
+// `LEASE_ACTIVATION_CAPABILITY` (lease-activation-probe.ts) — all three
+// currently agree on v1.
+const leaseCapabilityProbeStub = `python3 -c "import json; print(json.dumps({'name': 'lease-runtime-activation', 'version': 1}))"`;
 const children: ChildProcess[] = [];
 const temporaryRoots: string[] = [];
 
@@ -184,6 +200,7 @@ raise SystemExit(0 if len(session_id) == 64 and denied else 1)
       MOSAIC_PRDY_RUNTIME: 'claude',
       MOSAIC_LEASE_BROKER_SOCKET: socket,
       MOSAIC_RUNTIME_GENERATION: '1',
+      MOSAIC_LEASE_VERSION_PROBE_COMMAND: leaseCapabilityProbeStub,
     },
   });
 }
@@ -743,6 +760,7 @@ describe('whole mutator-class lease gate', () => {
           ...process.env,
           MOSAIC_LEASE_BROKER_SOCKET: socket,
           MOSAIC_RUNTIME_GENERATION: '1',
+          MOSAIC_LEASE_VERSION_PROBE_COMMAND: leaseCapabilityProbeStub,
         },
       },
     );
@@ -761,6 +779,7 @@ describe('whole mutator-class lease gate', () => {
           ...process.env,
           MOSAIC_LEASE_BROKER_SOCKET: join(tmpdir(), 'missing-mosaic-broker.sock'),
           MOSAIC_RUNTIME_GENERATION: '1',
+          MOSAIC_LEASE_VERSION_PROBE_COMMAND: leaseCapabilityProbeStub,
         },
       },
     );
@@ -878,6 +897,7 @@ raise SystemExit(0 if len(session_id) == 64 and hook_present and observers_prese
           PATH: `${binDir}:${process.env.PATH ?? ''}`,
           MOSAIC_LEASE_BROKER_SOCKET: socket,
           MOSAIC_RUNTIME_GENERATION: '1',
+          MOSAIC_LEASE_VERSION_PROBE_COMMAND: leaseCapabilityProbeStub,
         },
         proxyGate: () =>
           Promise.resolve({

packages/mosaic/src/mutator-gate/runtime_tools_unittest.py

@@ -39,6 +39,18 @@ LAUNCHER = load_tool("lease_runtime_launcher", "launch-runtime.py")
 GATE = load_tool("lease_mutator_gate", "mutator-gate.py")
 
 
+def matching_activation_probe(*_args: object, **_kwargs: object) -> dict[str, object]:
+    """Fake activation-capability probe matching what enforcement expects
+    (C4, #869 Point-1). Injected into `LAUNCHER.main()` calls below that are
+    exercising OTHER branches (registration, exec, generation init, ...) so
+    the new version-coupling gate — which runs before those — never blocks
+    on host state (no real `mosaic` CLI on PATH in a test sandbox). The
+    version-coupling gate's OWN behavior (match/mismatch/absent) is covered
+    by its dedicated red-first tests in `version_coupling_unittest.py`."""
+
+    return dict(LAUNCHER.EXPECTED_ACTIVATION_CAPABILITY)
+
+
 class FakeSocket:
     def __init__(self, *chunks: bytes):
         self.chunks = list(chunks)
@@ -95,6 +107,7 @@ class LaunchRuntimeTest(unittest.TestCase):
             request=request,
             execute=execute,
             initialize_generation=initialize_generation,
+            probe_activation_capability=matching_activation_probe,
         )
 
         self.assertEqual(result, 0)
@@ -127,6 +140,7 @@ class LaunchRuntimeTest(unittest.TestCase):
             request=lambda *_args: {"ok": True, "session_id": "e" * 64},
             execute=lambda *args: executed.append(args),
             initialize_generation=lambda *_args: None,
+            probe_activation_capability=matching_activation_probe,
         )
         self.assertEqual(result, 0)
         self.assertEqual(
@@ -153,6 +167,7 @@ class LaunchRuntimeTest(unittest.TestCase):
             request=lambda *_args: {"ok": True, "session_id": "f" * 64},
             execute=lambda *args: executed.append(args),
             initialize_generation=lambda *_args: None,
+            probe_activation_capability=matching_activation_probe,
         )
         self.assertEqual(result, 0)
         self.assertEqual(executed[0][0:2], ("pi", ["pi", "--print", "hello"]))
@@ -188,6 +203,7 @@ class LaunchRuntimeTest(unittest.TestCase):
                     environ=environment,
                     request=lambda *_args, value=reply: value,
                     execute=lambda *args: executed.append(args),
+                    probe_activation_capability=matching_activation_probe,
                 )
                 self.assertEqual(result, 1)
                 self.assertEqual(executed, [])
@@ -203,6 +219,7 @@ class LaunchRuntimeTest(unittest.TestCase):
                     initialize_generation=lambda *_args: (_ for _ in ()).throw(
                         OSError("unsafe state")
                     ),
+                    probe_activation_capability=matching_activation_probe,
                 ),
                 1,
             )
@@ -220,6 +237,7 @@ class LaunchRuntimeTest(unittest.TestCase):
                         environ={"MOSAIC_LEASE_BROKER_SOCKET": "/x"},
                         request=request,
                         execute=lambda *_args: self.fail("must not execute"),
+                        probe_activation_capability=matching_activation_probe,
                     ),
                     1,
                 )
@@ -233,6 +251,7 @@ class LaunchRuntimeTest(unittest.TestCase):
                     request=lambda *_args: {"ok": True, "session_id": "c" * 64},
                     execute=lambda *_args: (_ for _ in ()).throw(OSError("missing")),
                     initialize_generation=lambda *_args: None,
+                    probe_activation_capability=matching_activation_probe,
                 ),
                 1,
             )

packages/mosaic/src/mutator-gate/version_coupling_unittest.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Red-first tests for issue #869 Point-1 C4 — the enforcement/activation
+version-coupling assertion at the `launch-runtime.py` seam.
+
+Root cause under test (#828 restated): the lease broker's ENFORCEMENT half
+(this toolkit) and its ACTIVATION half (`execLeaseGatedRuntime()` in
+`launch.ts`, chained through `launch-runtime.py`) shipped on different
+channels and drifted. C1 (`lease-activation-probe.ts`) gave the activation
+half a versioned, machine-checkable identity
+(`LEASE_ACTIVATION_CAPABILITY`, printed via the hidden CLI subcommand
+`mosaic __lease-capability`). C4 (this module + `activation_version_gate.py`)
+is the assertion that actually USES that identity: enforcement must refuse
+to proceed — loudly, with an actionable remediation message, never a
+silent pass — unless the activation capability it observes exactly matches
+what enforcement expects.
+
+Every case here drives the seam with injected fakes/stubs (a fake
+`probe_activation_capability` callable at the `launch-runtime.py` level, or
+a fake `run` transport at the `activation_version_gate` level) — never a
+real broker, a real installed CLI, or a real `mosaic` binary on PATH.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import subprocess
+import sys
+import unittest
+from contextlib import redirect_stderr
+from pathlib import Path
+
+
+TOOLS_DIR = Path(__file__).parents[2] / "framework/tools/lease-broker"
+if str(TOOLS_DIR) not in sys.path:
+    sys.path.insert(0, str(TOOLS_DIR))
+
+
+def load_tool(module_name: str, filename: str):
+    spec = importlib.util.spec_from_file_location(module_name, TOOLS_DIR / filename)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"unable to load {filename}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+# Loaded under distinct module names from runtime_tools_unittest.py's own
+# LAUNCHER/GATE loads — importlib.util.module_from_spec() gives each load a
+# fresh module object regardless of name collisions, but distinct names keep
+# tracebacks/debugging unambiguous when both files run in the same process.
+LAUNCHER = load_tool("lease_runtime_launcher_version_coupling", "launch-runtime.py")
+VERSION_GATE = load_tool("lease_activation_version_gate_test", "activation_version_gate.py")
+
+
+def matching_capability() -> dict[str, object]:
+    return dict(VERSION_GATE.EXPECTED_ACTIVATION_CAPABILITY)
+
+
+class AssertActivationCapabilityMatchesTest(unittest.TestCase):
+    """Unit-level coverage of `activation_version_gate.py`'s own assertion,
+    isolated from the launch-runtime.py seam it is wired into below."""
+
+    def test_matching_capability_passes_silently(self) -> None:
+        VERSION_GATE.assert_activation_capability_matches(matching_capability())
+        # No exception is the assertion; nothing further to check.
+
+    def test_absent_capability_fails_closed_not_silent_pass(self) -> None:
+        with self.assertRaises(VERSION_GATE.VersionCouplingError) as raised:
+            VERSION_GATE.assert_activation_capability_matches(None)
+        message = str(raised.exception)
+        self.assertIn("#869", message)
+        self.assertIn("upgrade", message.lower())
+
+    def test_version_mismatch_message_is_actionable(self) -> None:
+        expected = {"name": "lease-runtime-activation", "version": 1}
+        mismatched = {"name": "lease-runtime-activation", "version": 2}
+        with self.assertRaises(VERSION_GATE.VersionCouplingError) as raised:
+            VERSION_GATE.assert_activation_capability_matches(mismatched, expected)
+        message = str(raised.exception)
+        self.assertIn("v2", message)
+        self.assertIn("v1", message)
+        self.assertIn("#869", message)
+        self.assertIn("upgrade", message.lower())
+        self.assertIn("version skew", message.lower())
+
+    def test_name_mismatch_fails_loud(self) -> None:
+        expected = {"name": "lease-runtime-activation", "version": 1}
+        mismatched = {"name": "some-other-capability", "version": 1}
+        with self.assertRaises(VERSION_GATE.VersionCouplingError) as raised:
+            VERSION_GATE.assert_activation_capability_matches(mismatched, expected)
+        message = str(raised.exception)
+        self.assertIn("some-other-capability", message)
+        self.assertIn("lease-runtime-activation", message)
+        self.assertIn("#869", message)
+
+    def test_reversed_drift_newer_activation_than_enforcement_expects_also_fails(self) -> None:
+        # A build/deploy where ACTIVATION shipped ahead of ENFORCEMENT is
+        # exactly as much version skew as the reverse (#828's actual shape
+        # was enforcement ahead of activation) — the assertion must not special
+        # case direction.
+        expected = {"name": "lease-runtime-activation", "version": 1}
+        newer_activation = {"name": "lease-runtime-activation", "version": 2}
+        with self.assertRaises(VERSION_GATE.VersionCouplingError):
+            VERSION_GATE.assert_activation_capability_matches(newer_activation, expected)
+
+
+class ProbeActivationCapabilityTest(unittest.TestCase):
+    """Coverage of the probe's command resolution and fail-closed transport
+    handling — never spawns a real `mosaic` process."""
+
+    def test_returns_none_when_mosaic_is_not_resolvable_on_path(self) -> None:
+        result = VERSION_GATE.default_probe_activation_capability(
+            {"PATH": "/nonexistent-bin-dir-for-869-c4-test"}
+        )
+        self.assertIsNone(result)
+
+    def test_override_command_is_parsed_and_the_probe_subcommand_is_not_double_appended(
+        self,
+    ) -> None:
+        captured: list[list[str]] = []
+
+        class FakeCompleted:
+            returncode = 0
+            stdout = '{"name": "lease-runtime-activation", "version": 1}'
+
+        def fake_run(argv: list[str], **_kwargs: object) -> FakeCompleted:
+            captured.append(argv)
+            return FakeCompleted()
+
+        result = VERSION_GATE.default_probe_activation_capability(
+            {VERSION_GATE.MOSAIC_COMMAND_OVERRIDE_VAR: "/fake/mosaic __lease-capability"},
+            run=fake_run,
+        )
+        self.assertEqual(result, {"name": "lease-runtime-activation", "version": 1})
+        self.assertEqual(captured, [["/fake/mosaic", "__lease-capability"]])
+
+    def test_fails_closed_on_nonzero_exit_malformed_json_and_missing_fields(self) -> None:
+        class NonZeroExit:
+            returncode = 1
+            stdout = '{"name": "lease-runtime-activation", "version": 1}'
+
+        class MalformedOutput:
+            returncode = 0
+            stdout = "not-json"
+
+        class MissingVersion:
+            returncode = 0
+            stdout = '{"name": "lease-runtime-activation"}'
+
+        class WrongShapeVersion:
+            returncode = 0
+            stdout = '{"name": "lease-runtime-activation", "version": "1"}'
+
+        class BooleanVersion:
+            # bool is a subclass of int in Python; must not be accepted as
+            # a version number.
+            returncode = 0
+            stdout = '{"name": "lease-runtime-activation", "version": true}'
+
+        for fake in (
+            NonZeroExit(),
+            MalformedOutput(),
+            MissingVersion(),
+            WrongShapeVersion(),
+            BooleanVersion(),
+        ):
+            with self.subTest(stdout=fake.stdout, returncode=fake.returncode):
+                result = VERSION_GATE.default_probe_activation_capability(
+                    {VERSION_GATE.MOSAIC_COMMAND_OVERRIDE_VAR: "/fake/mosaic"},
+                    run=lambda *_a, fake=fake, **_kw: fake,
+                )
+                self.assertIsNone(result)
+
+    def test_fails_closed_on_timeout_and_transport_error(self) -> None:
+        def timeout_run(*_args: object, **_kwargs: object) -> None:
+            raise subprocess.TimeoutExpired(cmd="mosaic", timeout=2.0)
+
+        def oserror_run(*_args: object, **_kwargs: object) -> None:
+            raise OSError("no such file or directory")
+
+        for run_fake in (timeout_run, oserror_run):
+            with self.subTest(run=run_fake.__name__):
+                result = VERSION_GATE.default_probe_activation_capability(
+                    {VERSION_GATE.MOSAIC_COMMAND_OVERRIDE_VAR: "/fake/mosaic"},
+                    run=run_fake,
+                )
+                self.assertIsNone(result)
+
+
+class LaunchRuntimeVersionCouplingSeamTest(unittest.TestCase):
+    """End-to-end (still fully faked) coverage of the seam as wired into
+    `launch-runtime.py`'s `main()` — the strongest natural enforcement point
+    per the C4 card, run before any broker registration."""
+
+    def _run(self, *, probe):
+        calls: dict[str, object] = {}
+
+        def request(_path: Path, payload: dict[str, object]) -> dict[str, object]:
+            calls["registered"] = True
+            calls["request"] = payload
+            return {"ok": True, "session_id": "a" * 64}
+
+        def execute(command: str, argv: list[str], environment: dict[str, str]) -> None:
+            calls["executed"] = (command, argv, environment)
+
+        def initialize_generation(_path: Path, _generation: int) -> None:
+            calls["generation_initialized"] = True
+
+        stderr = io.StringIO()
+        with redirect_stderr(stderr):
+            result = LAUNCHER.main(
+                ["--runtime", "claude", "--", "claude", "--print", "hello"],
+                environ={"MOSAIC_LEASE_BROKER_SOCKET": "/run/test/broker.sock"},
+                request=request,
+                execute=execute,
+                initialize_generation=initialize_generation,
+                probe_activation_capability=probe,
+            )
+        return result, stderr.getvalue(), calls
+
+    def test_matching_activation_version_passes_and_the_gate_proceeds(self) -> None:
+        result, stderr_text, calls = self._run(probe=lambda *_a, **_kw: matching_capability())
+        self.assertEqual(result, 0)
+        self.assertEqual(stderr_text, "")
+        self.assertTrue(calls.get("registered"))
+        self.assertIn("executed", calls)
+
+    def test_version_mismatch_fails_loud_denies_and_never_registers_or_execs(self) -> None:
+        expected = LAUNCHER.EXPECTED_ACTIVATION_CAPABILITY
+        mismatched = {"name": expected["name"], "version": expected["version"] + 1}
+        result, stderr_text, calls = self._run(probe=lambda *_a, **_kw: mismatched)
+
+        self.assertEqual(result, LAUNCHER.EXIT_VERSION_SKEW)
+        self.assertNotEqual(result, 0)
+        self.assertIn("#869", stderr_text)
+        self.assertIn(f"v{mismatched['version']}", stderr_text)
+        self.assertIn(f"v{expected['version']}", stderr_text)
+        self.assertIn("upgrade", stderr_text.lower())
+        # Never reaches broker registration or exec — the version gate is a
+        # hard stop, not advisory.
+        self.assertNotIn("registered", calls)
+        self.assertNotIn("executed", calls)
+
+    def test_name_mismatch_fails_loud(self) -> None:
+        expected = LAUNCHER.EXPECTED_ACTIVATION_CAPABILITY
+        mismatched = {"name": "some-other-capability", "version": expected["version"]}
+        result, stderr_text, calls = self._run(probe=lambda *_a, **_kw: mismatched)
+
+        self.assertEqual(result, LAUNCHER.EXIT_VERSION_SKEW)
+        self.assertIn("#869", stderr_text)
+        self.assertIn("some-other-capability", stderr_text)
+        self.assertNotIn("registered", calls)
+        self.assertNotIn("executed", calls)
+
+    def test_absent_activation_capability_fails_closed_not_a_silent_pass(self) -> None:
+        result, stderr_text, calls = self._run(probe=lambda *_a, **_kw: None)
+
+        self.assertEqual(result, LAUNCHER.EXIT_VERSION_SKEW)
+        self.assertNotEqual(result, 0)
+        self.assertIn("#869", stderr_text)
+        self.assertNotIn("registered", calls)
+        self.assertNotIn("executed", calls)
+
+    def test_version_gate_runs_before_and_independently_of_broker_registration(self) -> None:
+        def request_must_not_be_called(*_args: object, **_kwargs: object) -> dict[str, object]:
+            self.fail("broker must not be contacted when activation version is mismatched")
+
+        stderr = io.StringIO()
+        with redirect_stderr(stderr):
+            result = LAUNCHER.main(
+                ["--runtime", "claude", "--", "claude"],
+                environ={"MOSAIC_LEASE_BROKER_SOCKET": "/run/test/broker.sock"},
+                request=request_must_not_be_called,
+                probe_activation_capability=lambda *_a, **_kw: None,
+            )
+        self.assertEqual(result, LAUNCHER.EXIT_VERSION_SKEW)
+
+    def test_dedicated_exit_code_never_collides_with_usage_or_registration_codes(self) -> None:
+        # Distinctness guard: a version-skew denial must never be mistaken
+        # for the pre-existing usage error (64) or registration/exec
+        # fail-closed code (1) this script already owns.
+        self.assertNotIn(LAUNCHER.EXIT_VERSION_SKEW, (0, 1, 64))
+
+
+if __name__ == "__main__":
+    unittest.main()