devlyn-cli 3.1.0 → 3.1.2

package/config/skills/_shared/platform-support.py

@@ -0,0 +1,370 @@
+#!/usr/bin/env python3
+"""Native lock, argv, process and UTF-8 boundaries shared by harness callers."""
+from __future__ import annotations
+
+import contextlib
+import errno
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import signal
+import stat
+import subprocess
+import sys
+import time
+
+
+def configure_utf8():
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="strict")
+
+
+def open_stdin(path):
+    fd = os.open(path, os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NONBLOCK", 0))
+    if not stat.S_ISREG(os.fstat(fd).st_mode):
+        os.close(fd)
+        raise ValueError(f"stdin file is not a regular file: {path}")
+    return os.fdopen(fd, "rb")
+
+
+@contextlib.contextmanager
+def file_lock(path, *, blocking=False):
+    with Path(path).open("a+b") as handle:
+        if os.name == "nt":
+            import msvcrt
+            while True:
+                handle.seek(0)
+                try:
+                    msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+                    break
+                except OSError as exc:
+                    # CRT maps ERROR_LOCK_VIOLATION to EACCES (winerror may be absent).
+                    contended = exc.errno == errno.EACCES and getattr(exc, "winerror", None) in (None, 33)
+                    if not contended:
+                        raise
+                    if not blocking:
+                        raise BlockingIOError(errno.EAGAIN, "lock occupied", str(path)) from exc
+                    time.sleep(0.05)
+            try:
+                yield
+            finally:
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB))
+            try:
+                yield
+            finally:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+def native_argv(argv):
+    """Resolve supported npm engine shims to their package's Node bin, never cmd /c."""
+    if os.name != "nt":
+        return list(argv)
+    binary = shutil.which(argv[0])
+    if binary is None:
+        raise FileNotFoundError(f"executable unavailable: {argv[0]}")
+    shim = Path(binary)
+    if shim.suffix.lower() not in {".cmd", ".bat"}:
+        return [binary, *argv[1:]]
+    packages = {"codex": "@openai/codex", "claude": "@anthropic-ai/claude-code"}
+    package = packages.get(shim.stem.lower())
+    if shim.suffix.lower() != ".cmd" or package is None:
+        raise OSError(f"unsupported native command shim: {shim}")
+    root = (shim.parent.parent if shim.parent.name == ".bin" else shim.parent / "node_modules") / package
+    try:
+        manifest = json.loads((root / "package.json").read_text(encoding="utf-8"))
+    except (ValueError, UnicodeError) as exc:
+        raise OSError(f"invalid npm engine manifest: {shim}") from exc
+    if not isinstance(manifest, dict):
+        raise OSError(f"invalid npm engine manifest: {shim}")
+    entry = manifest.get("bin")
+    entry = entry.get(shim.stem.lower()) if isinstance(entry, dict) else entry
+    if manifest.get("name") != package or not isinstance(entry, str):
+        raise OSError(f"invalid npm engine bin: {shim}")
+    target = (root / entry).resolve(strict=True)
+    if not target.is_relative_to(root.resolve()) or target.suffix not in {".js", ".cjs", ".mjs"}:
+        raise OSError(f"unsupported npm engine bin: {target}")
+    raw = shim.read_text(encoding="utf-8")
+    matches = re.findall(r'"%_prog%"\s+"%dp0%\\([^"\r\n]+)"\s+%\*', raw)
+    if len(matches) != 1 or (shim.parent / matches[0]).resolve() != target:
+        raise OSError(f"unrecognized npm engine shim: {shim}")
+    node = shim.parent / "node.exe"
+    binary = str(node) if node.is_file() else shutil.which("node.exe")
+    if binary is None:
+        raise FileNotFoundError(f"node.exe unavailable for {shim}")
+    return [binary, str(target), *argv[1:]]
+
+
+def system_exit_code(code):
+    # CPython SystemExit uses signed C long (32 bits on Windows), unlike DWORD.
+    return code - 0x100000000 if os.name == "nt" and code >= 0x80000000 else code
+
+
+if os.name == "nt":
+    import ctypes
+    from ctypes import wintypes
+    import msvcrt
+
+    class _BasicLimits(ctypes.Structure):
+        _fields_ = [("PerProcessUserTimeLimit", ctypes.c_longlong),
+                    ("PerJobUserTimeLimit", ctypes.c_longlong),
+                    ("LimitFlags", wintypes.DWORD),
+                    ("MinimumWorkingSetSize", ctypes.c_size_t),
+                    ("MaximumWorkingSetSize", ctypes.c_size_t),
+                    ("ActiveProcessLimit", wintypes.DWORD),
+                    ("Affinity", ctypes.c_size_t),
+                    ("PriorityClass", wintypes.DWORD),
+                    ("SchedulingClass", wintypes.DWORD)]
+
+    class _ExtendedLimits(ctypes.Structure):
+        _fields_ = [("BasicLimitInformation", _BasicLimits),
+                    ("IoInfo", ctypes.c_ulonglong * 6),
+                    ("ProcessMemoryLimit", ctypes.c_size_t),
+                    ("JobMemoryLimit", ctypes.c_size_t),
+                    ("PeakProcessMemoryUsed", ctypes.c_size_t),
+                    ("PeakJobMemoryUsed", ctypes.c_size_t)]
+
+    class _JobProcessIds(ctypes.Structure):
+        _fields_ = [("NumberOfAssignedProcesses", wintypes.DWORD),
+                    ("NumberOfProcessIdsInList", wintypes.DWORD),
+                    ("ProcessIdList", ctypes.c_size_t * 1)]
+
+    def _checked(result, function, _args):
+        if not result:
+            error = ctypes.get_last_error()
+            raise ctypes.WinError(error, f"{function.__name__}: {ctypes.FormatError(error)}")
+        return result
+
+    _kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+    for _name, _args, _result in (
+        ("CreateJobObjectW", [ctypes.c_void_p, wintypes.LPCWSTR], wintypes.HANDLE),
+        ("SetInformationJobObject", [wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD], wintypes.BOOL),
+        ("QueryInformationJobObject", [wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD, ctypes.c_void_p], wintypes.BOOL),
+        ("AssignProcessToJobObject", [wintypes.HANDLE, wintypes.HANDLE], wintypes.BOOL),
+        ("TerminateJobObject", [wintypes.HANDLE, wintypes.UINT], wintypes.BOOL),
+        ("OpenProcess", [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD], wintypes.HANDLE),
+        ("IsProcessInJob", [wintypes.HANDLE, wintypes.HANDLE, ctypes.POINTER(wintypes.BOOL)], wintypes.BOOL),
+        ("GetCurrentProcess", [], wintypes.HANDLE),
+        ("DuplicateHandle", [wintypes.HANDLE, wintypes.HANDLE, wintypes.HANDLE, ctypes.POINTER(wintypes.HANDLE), wintypes.DWORD, wintypes.BOOL, wintypes.DWORD], wintypes.BOOL),
+        ("CloseHandle", [wintypes.HANDLE], wintypes.BOOL),
+        ("PeekNamedPipe", [wintypes.HANDLE, ctypes.c_void_p, wintypes.DWORD, ctypes.c_void_p, ctypes.POINTER(wintypes.DWORD), ctypes.c_void_p], wintypes.BOOL),
+    ):
+        _function = getattr(_kernel, _name)
+        _function.argtypes, _function.restype, _function.errcheck = _args, _result, _checked
+
+    _kernel.WaitForSingleObject.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+    _kernel.WaitForSingleObject.restype = wintypes.DWORD  # WAIT_OBJECT_0 is successful zero, not BOOL.
+
+    def _read_control(fd, count):
+        deadline = time.monotonic() + 10
+        data = b""
+        while len(data) < count:
+            available = wintypes.DWORD()
+            _kernel.PeekNamedPipe(msvcrt.get_osfhandle(fd), None, 0, None, ctypes.byref(available), None)
+            if available.value:
+                data += os.read(fd, min(count - len(data), available.value))
+            elif time.monotonic() >= deadline:
+                raise OSError("Windows job launch handshake timed out")
+            else:
+                time.sleep(0.01)
+        return data
+
+    class _WindowsJob:
+        def __init__(self):
+            self.handle = None
+            self.child = None
+            self.creating = False
+            self.interrupted_signal = None
+
+        def start(self, argv, stdin):
+            self.handle = _kernel.CreateJobObjectW(None, None)
+            limits = _ExtendedLimits()
+            limits.BasicLimitInformation.LimitFlags = 0x2000  # KILL_ON_JOB_CLOSE; no breakaway.
+            _kernel.SetInformationJobObject(self.handle, 9, ctypes.byref(limits), ctypes.sizeof(limits))
+            with contextlib.ExitStack() as controls, contextlib.ExitStack() as inherited_handles:
+                inherited_job = wintypes.HANDLE()
+                current = _kernel.GetCurrentProcess()
+                _kernel.DuplicateHandle(current, self.handle, current, ctypes.byref(inherited_job), 0, True, 2)
+                inherited_handles.callback(_kernel.CloseHandle, inherited_job)
+                ready_read, ready_write = os.pipe()
+                controls.callback(os.close, ready_read); inherited_handles.callback(os.close, ready_write)
+                allow_read, allow_write = os.pipe()
+                inherited_handles.callback(os.close, allow_read); controls.callback(os.close, allow_write)
+                inherited = [inherited_job.value, msvcrt.get_osfhandle(ready_write), msvcrt.get_osfhandle(allow_read)]
+                for handle in inherited[1:]:
+                    os.set_handle_inheritable(handle, True)
+                startup = subprocess.STARTUPINFO()
+                startup.lpAttributeList = {"handle_list": inherited}
+                command = [sys.executable, "-I", "-S", str(Path(__file__).resolve()), "--job-bootstrap",
+                           str(inherited[0]), str(inherited[2]), str(inherited[1]), *argv]
+                # Retain the Popen object even if __init__ raises after native creation.
+                self.child = subprocess.Popen.__new__(subprocess.Popen)
+                self.creating = True
+                try:
+                    self.child.__init__(command, stdin=stdin, startupinfo=startup, close_fds=True)
+                finally:
+                    self.creating = False
+                if self.interrupted_signal is not None:
+                    raise SystemExit(128 + self.interrupted_signal)
+                inherited_handles.close()
+                if _read_control(ready_read, 1) != b"R":
+                    raise OSError("Windows job enrollment did not report ready")
+                os.write(allow_write, b"G")
+                self.target_pid = int.from_bytes(_read_control(ready_read, 4), "little")
+            return self.child
+
+        def terminate(self):
+            try:
+                # Stop startup first so no new enrollment/dispatch can race job quiescence.
+                if self.child is not None and getattr(self.child, "_child_created", False):
+                    try:
+                        if self.child.poll() is None:
+                            self.child.kill()
+                        self.child.wait(timeout=5)
+                    finally:
+                        self.child._handle.Close()
+            finally:
+                if self.handle is not None:
+                    with contextlib.ExitStack() as handles:
+                        handles.callback(_kernel.CloseHandle, self.handle)
+                        limits = _ExtendedLimits()  # Zero ActiveProcessLimit: no freed slot admits a new child.
+                        limits.BasicLimitInformation.LimitFlags = 0x2008  # KILL_ON_JOB_CLOSE | ACTIVE_PROCESS.
+                        _kernel.SetInformationJobObject(self.handle, 9, ctypes.byref(limits), ctypes.sizeof(limits))
+                        capacity = 1
+                        while True:
+                            buffer = ctypes.create_string_buffer(_JobProcessIds.ProcessIdList.offset + capacity * ctypes.sizeof(ctypes.c_size_t))
+                            ids = _JobProcessIds.from_buffer(buffer)
+                            try:
+                                _kernel.QueryInformationJobObject(self.handle, 3, buffer, len(buffer), None)
+                                break
+                            except OSError as exc:
+                                if exc.winerror != 234:  # ERROR_MORE_DATA: never accept a partial list.
+                                    raise
+                                capacity = max(capacity * 2, ids.NumberOfAssignedProcesses)
+                        members = []
+                        pids = (ctypes.c_size_t * ids.NumberOfProcessIdsInList).from_buffer(buffer, _JobProcessIds.ProcessIdList.offset)
+                        for pid in pids:
+                            try:
+                                process = _kernel.OpenProcess(0x101000, False, pid)  # SYNCHRONIZE | QUERY_LIMITED_INFORMATION.
+                            except OSError as exc:
+                                if exc.winerror == 87:  # Already gone; other open failures remain visible.
+                                    continue
+                                raise
+                            handles.callback(_kernel.CloseHandle, process)
+                            member = wintypes.BOOL()
+                            _kernel.IsProcessInJob(process, self.handle, ctypes.byref(member))
+                            if member.value:  # A reused PID in another job is not our process identity.
+                                members.append((pid, process))
+                        # Natural exits before capture do not prove pending I/O or historical object finalization.
+                        _kernel.TerminateJobObject(self.handle, 1)
+                        deadline = time.monotonic() + 5
+                        for pid, process in members:
+                            remaining = max(0, int((deadline - time.monotonic()) * 1000))
+                            result = _kernel.WaitForSingleObject(process, remaining)
+                            if result == 258:  # WAIT_TIMEOUT.
+                                raise OSError(f"Windows job teardown timed out waiting for process {pid}")
+                            if result == 0xFFFFFFFF:  # WAIT_FAILED.
+                                error = ctypes.get_last_error()
+                                raise ctypes.WinError(error, f"WaitForSingleObject: {ctypes.FormatError(error)}")
+                            if result != 0:
+                                raise OSError(f"WaitForSingleObject: unexpected result {result} for process {pid}")
+
+    def _job_bootstrap(argv):
+        job, allow, ready = map(int, argv[:3])
+        with contextlib.ExitStack() as handles:
+            allow_fd = msvcrt.open_osfhandle(allow, os.O_RDONLY | os.O_BINARY)
+            handles.callback(os.close, allow_fd)
+            ready_fd = msvcrt.open_osfhandle(ready, os.O_WRONLY | os.O_BINARY)
+            handles.callback(os.close, ready_fd)
+            try:
+                _kernel.AssignProcessToJobObject(job, _kernel.GetCurrentProcess())
+            finally:
+                _kernel.CloseHandle(job)
+            os.write(ready_fd, b"R")
+            if _read_control(allow_fd, 1) != b"G":
+                raise OSError("Windows job launch was not authorized")
+            with subprocess.Popen(argv[3:], stdin=sys.stdin.buffer, close_fds=True) as target:
+                os.write(ready_fd, target.pid.to_bytes(4, "little"))
+                return target.wait()
+
+
+def terminate_tree(child, job=None):
+    if job is not None:
+        job.terminate()
+        return
+    try:
+        os.killpg(child.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        child.wait()
+        return
+    # Reap the leader and retain the grace period for its surviving descendants.
+    deadline = time.monotonic() + 5
+    try:
+        child.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        pass  # The leader also needs the final group KILL below.
+    time.sleep(max(0, deadline - time.monotonic()))
+    try:
+        os.killpg(child.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass  # Every member already exited during the grace period.
+    child.wait()
+
+
+def run_process(argv, stdin, seconds, *, heartbeat=0):
+    child = None
+    job = _WindowsJob() if os.name == "nt" else None
+    previous = {}
+
+    def interrupted(signum, _frame):
+        # CPython stores the native handle only after CreateProcess's finally block.
+        if job is not None and job.creating:
+            job.interrupted_signal = signum
+            return
+        raise SystemExit(128 + signum)
+
+    try:
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            previous[sig] = signal.signal(sig, interrupted)
+        child = job.start(argv, stdin) if job is not None else subprocess.Popen(argv, stdin=stdin, start_new_session=True)
+        started = time.monotonic()
+        next_heartbeat = started + heartbeat
+        if heartbeat:
+            print(f"[codex-monitored] codex pid={job.target_pid if job is not None else child.pid}", file=sys.stderr, flush=True)
+        while True:
+            try:
+                return child.wait(timeout=0.1)
+            except subprocess.TimeoutExpired:
+                now = time.monotonic()
+                if seconds and now - started >= seconds:
+                    if heartbeat:
+                        print(f"[codex-monitored] timeout: elapsed={int(now-started)}s limit={seconds}s", file=sys.stderr, flush=True)
+                    return 124
+                if heartbeat and now >= next_heartbeat:
+                    print(f"[codex-monitored] heartbeat: elapsed={int(now-started)}s", file=sys.stderr, flush=True)
+                    next_heartbeat = now + heartbeat
+    finally:
+        try:
+            if job is not None or child is not None:
+                terminate_tree(child, job)
+        finally:
+            for sig, handler in previous.items():
+                signal.signal(sig, handler)
+
+
+if __name__ == "__main__" and os.name == "nt":
+    configure_utf8()
+    try:
+        if sys.argv[1:2] != ["--job-bootstrap"]:
+            raise ValueError("expected internal Windows job bootstrap")
+        code = _job_bootstrap(sys.argv[2:])
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        code = 2
+    raise SystemExit(system_exit_code(code))

package/config/skills/_shared/process-evidence.py

@@ -2,6 +2,7 @@
 """Capture and validate run-scoped process evidence without third-party dependencies."""
 from __future__ import annotations
 
+import runpy
 import argparse
 import hashlib
 import json
@@ -184,7 +185,7 @@ def _source_expected_path(work: pathlib.Path, state: dict) -> pathlib.Path | Non
     if not isinstance(spec_path, str) or not spec_path:
         raise EvidenceError("state.source.spec_path is missing")
     spec_rel = _safe_relative_path(spec_path, "state.source.spec_path")
-    expected = work.joinpath(*spec_rel.parts).with_suffix(".expected.json")
+    expected = work.joinpath(*spec_rel.parts).with_name("spec.expected.json")
     try:
         expected.resolve().relative_to(work.resolve())
     except (OSError, ValueError) as exc:
@@ -358,7 +359,7 @@ def capture_process(
     started = time.monotonic()
     try:
         proc = subprocess.run(
-            item.get("cmd") if "cmd" in item else item["argv"],
+            item.get("cmd") if "cmd" in item else runpy.run_path(pathlib.Path(__file__).with_name("platform-support.py"))["native_argv"](item["argv"]),
             cwd=work, shell="cmd" in item, capture_output=True,
             timeout=item["timeout_sec"], check=False,
         )
@@ -374,7 +375,7 @@ def capture_process(
         outcome = {"kind": "timeout", "exit_code": None, "signal": None}
     except OSError as exc:
         stdout = b""
-        stderr = os.fsencode(str(exc))
+        stderr = str(exc).encode("utf-8")
         outcome = {"kind": "spawn_error", "exit_code": None, "signal": None}
     return _append_entry(
         work, manifest_path, run_id, phase, round_, item["id"], _execution(item),
@@ -681,6 +682,21 @@ def self_test() -> int:
             "cmd": "printf raw-out; printf raw-err >&2; exit 7",
             "exit_code": 7, "stdout_contains": ["raw-outraw-err"],
         })
+        spec_dir = work / "docs"
+        spec_dir.mkdir()
+        (spec_dir / "X.md").write_text("# Named spec\n", encoding="utf-8")
+        expected = spec_dir / "spec.expected.json"
+        expected.write_text(json.dumps({
+            "process_evidence": [obligation],
+            "verification_commands": [{"cmd": "printf required"}],
+        }), encoding="utf-8")
+        (spec_dir / "X.expected.json").write_text("{}\n", encoding="utf-8")
+        named_state = {**state, "source": {"type": "spec", "spec_path": "docs/X.md"}}
+        assert declared_obligations(work, named_state, "implement") == [obligation]
+        assert mechanical_evidence_required(work, named_state)
+        expected.unlink()
+        assert declared_obligations(work, named_state, "implement") == []
+        assert not mechanical_evidence_required(work, named_state)
         entry = capture_process(work, manifest, state["run_id"], "implement", 0, obligation)
         assert entry["expectation_met"]
         assert (manifest.parent / "red-first.stdout").read_bytes() == b"raw-out"
@@ -906,4 +922,5 @@ def main() -> int:
 
 
 if __name__ == "__main__":
+    runpy.run_path(str(pathlib.Path(__file__).with_name("platform-support.py")))["configure_utf8"]()
     raise SystemExit(main())