feat: add pinned cross-repo Developer OS kernel harness v3

.github/workflows/repository-intelligence.yml

@@ -2,7 +2,7 @@ name: Repository Intelligence CI
 on:
   pull_request:
   push:
-    branches: ["feat/repository-intelligence-v1", "feat/repository-intelligence-v2", "feat/repository-intelligence-v3", "feat/governed-developer-os-v1", "feat/governed-developer-os-v2"]
+    branches: ["feat/repository-intelligence-v1", "feat/repository-intelligence-v2", "feat/repository-intelligence-v3", "feat/governed-developer-os-v1", "feat/governed-developer-os-v2", "feat/governed-developer-os-v3"]
 permissions:
   contents: read
 jobs:

README.md

@@ -62,3 +62,16 @@ OpenHands `repo.read`, `test.execute`, and `repo.patch` capabilities.
 The binding layer remains proposal-only and network-free. HPL must still admit
 the consequential request and mint the ExecutionToken before any mutation can
 occur.
+
+
+## Cross-repository kernel harness v3
+
+```bash
+repo-intel kernel-run hpl-read-binding.json \
+  --kernel-root /path/to/apex-hpl-governed-kernel \
+  --out kernel-harness-receipt.json
+```
+
+The harness pins the kernel checkout to the certified Developer OS Agentic
+Runner head and defaults to admission-only. External effects require explicit
+`--execute`, after which HPL admission still remains mandatory.

docs/GOVERNED_DEVELOPER_OS_KERNEL_HARNESS_V3.md

@@ -0,0 +1,33 @@
+# Cross-repository Developer OS harness v3
+
+This tranche connects the Developer OS repository to the separately certified
+HPL kernel runner.
+
+The harness does not import kernel internals. It invokes:
+
+```text
+python -m hpl.runtime.agentic_runner
+```
+
+inside an explicitly supplied kernel checkout.
+
+Before invocation, the harness requires the kernel checkout HEAD to equal the
+certified runner baseline:
+
+```text
+a5d2d913e41fd9a80212825921d0919fd8320b3b
+```
+
+This prevents a different local kernel implementation from silently receiving a
+binding.
+
+Default behavior is admission-only. `--execute` is never implied; the caller
+must request it explicitly. Even then, the kernel runner must still admit the
+binding and mint the HPL ExecutionToken before RuntimeEngine can execute.
+
+The harness does not inject credentials, OpenHands endpoints, or authorization
+material. Operator environment configuration remains outside this layer.
+
+CI mocks the subprocess boundary. It proves command construction, commit pinning,
+admission-only defaults, and explicit execution semantics; it does not perform a
+live cross-repository or OpenHands effect.

repo_intelligence/__init__.py

@@ -6,6 +6,7 @@
 from .scope import build_openhands_scope
 from .developer_os import build_developer_plan, reconcile_developer_run
 from .hpl_binding import build_repo_patch_binding, build_repo_read_binding, build_test_execute_binding
+from .kernel_harness import invoke_kernel_binding, verify_kernel_checkout
 
 __all__=[
     "build_repository_graph",
@@ -16,6 +17,8 @@
     "build_repo_read_binding",
     "build_test_execute_binding",
     "build_repo_patch_binding",
+    "invoke_kernel_binding",
+    "verify_kernel_checkout",
     "load_architecture_contract",
     "validate_architecture_contract",
 ]

repo_intelligence/cli.py

@@ -8,6 +8,7 @@
 from .scope import build_openhands_scope
 from .developer_os import build_developer_plan
 from .hpl_binding import build_repo_read_binding, build_test_execute_binding
+from .kernel_harness import invoke_kernel_binding
 
 
 def _write(path:str,data:dict)->None:
@@ -54,6 +55,13 @@ def main()->None:
     t.add_argument("--test-path",required=True)
     t.add_argument("--out",default="hpl-test-binding.json")
 
+    k=sub.add_parser("kernel-run")
+    k.add_argument("binding")
+    k.add_argument("--kernel-root",required=True)
+    k.add_argument("--execute",action="store_true")
+    k.add_argument("--trace-dir")
+    k.add_argument("--out",default="kernel-harness-receipt.json")
+
     a=p.parse_args()
 
     if a.cmd=="graph":
@@ -76,9 +84,17 @@ def main()->None:
     elif a.cmd=="hpl-read-binding":
         plan=json.loads(Path(a.developer_plan).read_text(encoding="utf-8"))
         data=build_repo_read_binding(plan,conversation_id=a.conversation_id,path=a.path)
-    else:
+    elif a.cmd=="hpl-test-binding":
         plan=json.loads(Path(a.developer_plan).read_text(encoding="utf-8"))
         data=build_test_execute_binding(plan,workspace=a.workspace,test_path=a.test_path)
+    else:
+        binding=json.loads(Path(a.binding).read_text(encoding="utf-8"))
+        data=invoke_kernel_binding(
+            binding,
+            kernel_root=a.kernel_root,
+            execute=a.execute,
+            trace_dir=a.trace_dir,
+        )
 
     _write(a.out,data)
 

repo_intelligence/kernel_harness.py

@@ -0,0 +1,125 @@
+"""Cross-repository Governed Developer OS harness v3.
+
+This harness invokes the certified kernel-side Agentic Runner as a separate
+process. It pins the kernel repository to an exact commit before invocation.
+Default mode is admission-only; external effects require explicit execute=True.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+CERTIFIED_KERNEL_RUNNER_HEAD="a5d2d913e41fd9a80212825921d0919fd8320b3b"
+
+
+class KernelHarnessError(RuntimeError):
+    pass
+
+
+def _canon(v:object)->str:
+    return json.dumps(v,sort_keys=True,separators=(",",":"),ensure_ascii=False)
+
+
+def _sha(v:object)->str:
+    return "sha256:"+hashlib.sha256(_canon(v).encode("utf-8")).hexdigest()
+
+
+def verify_kernel_checkout(
+    kernel_root:str|Path,
+    *,
+    expected_head:str=CERTIFIED_KERNEL_RUNNER_HEAD,
+)->Path:
+    root=Path(kernel_root).resolve()
+    if not root.is_dir() or not (root/".git").exists():
+        raise KernelHarnessError("kernel_root must be an ordinary git worktree")
+    result=subprocess.run(
+        ["git","rev-parse","HEAD"],
+        cwd=root,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode!=0:
+        raise KernelHarnessError("unable to resolve kernel HEAD")
+    actual=result.stdout.strip()
+    if actual!=expected_head:
+        raise KernelHarnessError(
+            f"kernel HEAD mismatch: expected {expected_head}, actual {actual}"
+        )
+    runner=root/"src"/"hpl"/"runtime"/"agentic_runner.py"
+    if not runner.is_file():
+        raise KernelHarnessError("certified kernel runner file is missing")
+    return root
+
+
+def invoke_kernel_binding(
+    binding:dict,
+    *,
+    kernel_root:str|Path,
+    python_executable:str="python",
+    execute:bool=False,
+    trace_dir:str|Path|None=None,
+    timeout_seconds:int=60,
+    expected_kernel_head:str=CERTIFIED_KERNEL_RUNNER_HEAD,
+)->dict:
+    root=verify_kernel_checkout(kernel_root,expected_head=expected_kernel_head)
+    if not isinstance(binding,dict) or not str(binding.get("binding_sha256","")).startswith("sha256:"):
+        raise KernelHarnessError("binding must contain a deterministic binding_sha256")
+
+    with tempfile.TemporaryDirectory(prefix="developer-os-kernel-") as tmp:
+        tmp_path=Path(tmp)
+        binding_path=tmp_path/"binding.json"
+        result_path=tmp_path/"kernel-result.json"
+        binding_path.write_text(
+            json.dumps(binding,indent=2,sort_keys=True)+"\n",
+            encoding="utf-8",
+        )
+
+        cmd=[
+            python_executable,
+            "-m",
+            "hpl.runtime.agentic_runner",
+            str(binding_path),
+            "--out",
+            str(result_path),
+        ]
+        if trace_dir is not None:
+            cmd.extend(["--trace-dir",str(Path(trace_dir).resolve())])
+        if execute:
+            cmd.append("--execute")
+
+        env=None
+        # The caller owns environment configuration for OpenHands/HPL. We avoid
+        # injecting credentials or service endpoints here.
+        result=subprocess.run(
+            cmd,
+            cwd=root,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=int(timeout_seconds),
+            env=env,
+        )
+        if not result_path.is_file():
+            raise KernelHarnessError(
+                f"kernel runner produced no result (exit={result.returncode})"
+            )
+        payload=json.loads(result_path.read_text(encoding="utf-8"))
+        if not isinstance(payload,dict):
+            raise KernelHarnessError("kernel runner result must be an object")
+
+    core={
+        "schema_version":"1.0",
+        "authority_semantics":"kernel_runner_separate_process",
+        "execution_requested":bool(execute),
+        "binding_sha256":binding["binding_sha256"],
+        "kernel_head":expected_kernel_head,
+        "kernel_result":payload,
+        "kernel_exit_code":result.returncode,
+    }
+    core["harness_receipt_sha256"]=_sha(core)
+    return core

tests/test_kernel_harness.py

@@ -0,0 +1,89 @@
+from pathlib import Path
+from unittest import mock
+import json
+
+from repo_intelligence.kernel_harness import (
+    CERTIFIED_KERNEL_RUNNER_HEAD,
+    KernelHarnessError,
+    invoke_kernel_binding,
+    verify_kernel_checkout,
+)
+
+
+def _binding():
+    return {
+        "schema_version":"1.0",
+        "authority_semantics":"hpl_admission_required",
+        "execution_authorized":False,
+        "proposal":{},
+        "request":{},
+        "policy":{},
+        "binding_sha256":"sha256:"+"a"*64,
+    }
+
+
+def test_verify_kernel_checkout_requires_exact_head(tmp_path:Path):
+    (tmp_path/".git").mkdir()
+    (tmp_path/"src"/"hpl"/"runtime").mkdir(parents=True)
+    (tmp_path/"src"/"hpl"/"runtime"/"agentic_runner.py").write_text("x=1\n",encoding="utf-8")
+    ok=mock.Mock(returncode=0,stdout=CERTIFIED_KERNEL_RUNNER_HEAD+"\n")
+    with mock.patch("repo_intelligence.kernel_harness.subprocess.run",return_value=ok):
+        assert verify_kernel_checkout(tmp_path)==tmp_path.resolve()
+
+
+def test_verify_kernel_checkout_refuses_wrong_head(tmp_path:Path):
+    (tmp_path/".git").mkdir()
+    with mock.patch(
+        "repo_intelligence.kernel_harness.subprocess.run",
+        return_value=mock.Mock(returncode=0,stdout="0"*40+"\n"),
+    ):
+        try:
+            verify_kernel_checkout(tmp_path)
+        except KernelHarnessError:
+            pass
+        else:
+            raise AssertionError("expected KernelHarnessError")
+
+
+def test_harness_defaults_to_admission_only(tmp_path:Path):
+    (tmp_path/".git").mkdir()
+    (tmp_path/"src"/"hpl"/"runtime").mkdir(parents=True)
+    (tmp_path/"src"/"hpl"/"runtime"/"agentic_runner.py").write_text("x=1\n",encoding="utf-8")
+
+    calls=[]
+    def fake_run(cmd,**kwargs):
+        calls.append(cmd)
+        if cmd[:3]==["git","rev-parse","HEAD"]:
+            return mock.Mock(returncode=0,stdout=CERTIFIED_KERNEL_RUNNER_HEAD+"\n",stderr="")
+        out=Path(cmd[cmd.index("--out")+1])
+        out.write_text(json.dumps({"admission":{"status":"admitted"},"runtime":None}),encoding="utf-8")
+        return mock.Mock(returncode=0,stdout="",stderr="")
+
+    with mock.patch("repo_intelligence.kernel_harness.subprocess.run",side_effect=fake_run):
+        receipt=invoke_kernel_binding(_binding(),kernel_root=tmp_path)
+
+    runner_cmd=calls[1]
+    assert "--execute" not in runner_cmd
+    assert receipt["execution_requested"] is False
+    assert receipt["kernel_result"]["runtime"] is None
+
+
+def test_harness_execute_is_explicit(tmp_path:Path):
+    (tmp_path/".git").mkdir()
+    (tmp_path/"src"/"hpl"/"runtime").mkdir(parents=True)
+    (tmp_path/"src"/"hpl"/"runtime"/"agentic_runner.py").write_text("x=1\n",encoding="utf-8")
+
+    calls=[]
+    def fake_run(cmd,**kwargs):
+        calls.append(cmd)
+        if cmd[:3]==["git","rev-parse","HEAD"]:
+            return mock.Mock(returncode=0,stdout=CERTIFIED_KERNEL_RUNNER_HEAD+"\n",stderr="")
+        out=Path(cmd[cmd.index("--out")+1])
+        out.write_text(json.dumps({"admission":{"status":"admitted"},"runtime":{"status":"completed"}}),encoding="utf-8")
+        return mock.Mock(returncode=0,stdout="",stderr="")
+
+    with mock.patch("repo_intelligence.kernel_harness.subprocess.run",side_effect=fake_run):
+        receipt=invoke_kernel_binding(_binding(),kernel_root=tmp_path,execute=True)
+
+    assert "--execute" in calls[1]
+    assert receipt["execution_requested"] is True