@andespindola/crow-skills 0.40.0 → 0.41.0

package/skills/crow-mcp-maker/scripts/engines.py

@@ -0,0 +1,732 @@
+#!/usr/bin/env python3
+"""Explicit isolated upstream runtimes; stdlib manager, NOT a security sandbox.
+
+status never executes third-party code. setup requires --yes; run never installs.
+All upstream arguments after -- pass unchanged. Native TUI needs --interactive.
+Private stdout artifacts retain complete upstream output (possibly sensitive).
+Operational reports never include argv, environment, raw stdout or raw stderr.
+"""
+import argparse
+import base64
+import contextlib
+import functools
+import hashlib
+import json
+import math
+import os
+from pathlib import Path, PurePosixPath
+import selectors
+import signal
+import stat
+import subprocess
+import sys
+import tarfile
+import time
+import threading
+import urllib.request
+import uuid
+
+SCHEMA = 'crow-maker-runtime/1'
+MAX_ARCHIVE = 64 * 1024 * 1024
+MAX_EXTRACTED = 256 * 1024 * 1024
+MAX_OUTPUT = 64 * 1024 * 1024
+SPECS = {
+    'skill-scanner': {
+        'kind': 'python', 'repository': 'cisco-ai-defense/skill-scanner',
+        'extras': ['google', 'bedrock', 'vertex', 'azure', 'all'],
+        'commit': 'c558c421157c546ec417cf23778ce81a3a8f35fd',
+        'url': 'https://api.github.com/repos/cisco-ai-defense/skill-scanner/tarball/c558c421157c546ec417cf23778ce81a3a8f35fd',
+        'sha256': 'aa747556f5179aa213f49c897549052c8b13f0744b78b335921e377774ed3e5f',
+        'distribution': 'cisco-ai-skill-scanner', 'version': '0.0.0+git.c558c421157c',
+        'versionMeaning': 'Synthetic source version, not an upstream release version.',
+        'entrypoints': {'skill-scanner': 'venv/bin/skill-scanner',
+                        'skill-scanner-api': 'venv/bin/skill-scanner-api',
+                        'skill-scanner-pre-commit': 'venv/bin/skill-scanner-pre-commit'}},
+    'mcp-scanner': {
+        'kind': 'python', 'repository': 'cisco-ai-defense/mcp-scanner',
+        'extras': ['js', 'go', 'java', 'kotlin', 'csharp', 'ruby', 'rust', 'php', 'all-languages'],
+        'commit': '9ff8fc84b792aae315a838cf4e37b40ef46a0293',
+        'url': 'https://api.github.com/repos/cisco-ai-defense/mcp-scanner/tarball/9ff8fc84b792aae315a838cf4e37b40ef46a0293',
+        'sha256': '8f32cf61afbb74f9d60292f1e059fd79eeaefd99572a7bb9624471ec2c252aaf',
+        'distribution': 'cisco-ai-mcp-scanner', 'version': '4.8.7',
+        'entrypoints': {'mcp-scanner': 'venv/bin/mcp-scanner', 'mcp-scanner-api': 'venv/bin/mcp-scanner-api'}},
+    'inspector': {
+        'kind': 'npm', 'repository': 'modelcontextprotocol/inspector', 'extras': [],
+        'commit': '488c30d9d16e4993bc548ad298eb7450f5125c93',
+        'sourceArchiveSha256': '2f3b60cd98e500d2934581ffe7c81c4588e02c3d2742bee6d34c1b5d415500fe',
+        'url': 'https://registry.npmjs.org/@modelcontextprotocol/inspector/-/inspector-2.15.0.tgz',
+        'integrity': 'sha512-TWdX2oJNVTan3B0/0YLpVJWbeuuii3cgDnc7uIwAiCQ9q7QMvZuQrapkQXOC2MKsmyNWj0tplWjza3IolBU+wA==',
+        'distribution': '@modelcontextprotocol/inspector', 'version': '2.15.0',
+        'entrypoints': {'inspector': 'npm/node_modules/@modelcontextprotocol/inspector/clients/launcher/build/index.js',
+                        'mcp-inspector': 'npm/node_modules/@modelcontextprotocol/inspector/clients/launcher/build/index.js',
+                        'mcpdo': 'npm/node_modules/@modelcontextprotocol/inspector/clients/mcpdo/build/mcp-bin.js'}},
+}
+
+
+class RuntimeErrorSafe(Exception):
+    def __init__(self, code):
+        super().__init__(code)
+        self.code = code
+
+
+class OperationCancelled(BaseException):
+    """Cancellation crosses setup cleanup before becoming a structured result."""
+    def __init__(self, signum):
+        self.signum = int(signum)
+
+
+def _cancel_result(signum, engine=None):
+    result = {'schema': SCHEMA, 'state': 'cancelled', 'cancelled': True,
+              'signal': signal.Signals(signum).name, 'signalNumber': signum,
+              'exitCode': 128 + signum, 'timedOut': False, 'ready': False}
+    if engine is not None:
+        result['engine'] = engine
+    return result
+
+
+class _SignalGuard:
+    def __init__(self):
+        self.deferred = False
+        self.pending = None
+
+    def handler(self, signum, frame):
+        # Do not raise between fork and assignment of the Popen object: that
+        # would orphan a newly created process before its owner can clean it.
+        if self.deferred:
+            self.pending = signum
+        else:
+            raise OperationCancelled(signum)
+
+    @contextlib.contextmanager
+    def deferred_signals(self):
+        self.deferred = True
+        try:
+            yield
+        finally:
+            self.deferred = False
+            if self.pending is not None:
+                signum, self.pending = self.pending, None
+                raise OperationCancelled(signum)
+
+
+@contextlib.contextmanager
+def _termination_scope():
+    """Only main-thread operations temporarily own SIGTERM; always restore it.
+
+    Worker-thread calls cannot replace process signal handlers. Their embedding
+    main thread remains responsible for cancellation policy; no global handler
+    is installed or leaked by those calls.
+    """
+    guard = _SignalGuard()
+    installed = threading.current_thread() is threading.main_thread()
+    previous = signal.getsignal(signal.SIGTERM) if installed else None
+    if installed:
+        signal.signal(signal.SIGTERM, guard.handler)
+    try:
+        yield guard
+    finally:
+        if installed:
+            signal.signal(signal.SIGTERM, previous)
+
+
+def _cancellable(function):
+    @functools.wraps(function)
+    def wrapped(engine, *args, **kwargs):
+        with _termination_scope():
+            try:
+                return function(engine, *args, **kwargs)
+            except OperationCancelled as cancelled:
+                return _cancel_result(cancelled.signum, engine)
+            except KeyboardInterrupt:
+                return _cancel_result(signal.SIGINT, engine)
+    return wrapped
+
+
+def _json(value):
+    return json.dumps(value, sort_keys=True, ensure_ascii=True, allow_nan=False).encode()
+
+
+def _digest(raw):
+    return hashlib.sha256(raw).hexdigest()
+
+
+def _open(path, directory=False):
+    """No-follow each absolute component; never accept special-file reads."""
+    if not hasattr(os, 'O_NOFOLLOW') or not hasattr(os, 'O_DIRECTORY'):
+        raise RuntimeErrorSafe('posix-no-follow-required')
+    path = Path(os.path.abspath(path))
+    fd = os.open(path.anchor, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        for i, part in enumerate(path.parts[1:]):
+            final = i == len(path.parts[1:]) - 1
+            flags = os.O_RDONLY | os.O_NOFOLLOW | getattr(os, 'O_NONBLOCK', 0)
+            if not final or directory:
+                flags |= os.O_DIRECTORY
+            new = os.open(part, flags, dir_fd=fd)
+            os.close(fd)
+            fd = new
+        return fd
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def _read(path, limit):
+    fd = _open(path)
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise RuntimeErrorSafe('regular-file-required')
+        chunks, left = [], limit + 1
+        while left:
+            chunk = os.read(fd, min(65536, left))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            left -= len(chunk)
+        raw = b''.join(chunks)
+        if len(raw) > limit:
+            raise RuntimeErrorSafe('file-byte-limit')
+        return raw
+    finally:
+        os.close(fd)
+
+
+def _private_dir(path, create=False):
+    path = Path(os.path.abspath(path))
+    if create:
+        parent = _open(path.parent, True)
+        try:
+            try:
+                os.mkdir(path.name, 0o700, dir_fd=parent)
+            except FileExistsError:
+                pass
+        finally:
+            os.close(parent)
+    fd = _open(path, True)
+    try:
+        info = os.fstat(fd)
+        if info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) & 0o077:
+            raise RuntimeErrorSafe('runtime-directory-must-be-owned-and-private')
+    finally:
+        os.close(fd)
+    return path
+
+
+def _atomic(path, raw):
+    fd = _open(Path(path).parent, True)
+    temp = '.write-' + uuid.uuid4().hex
+    try:
+        child = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=fd)
+        with os.fdopen(child, 'wb') as stream:
+            stream.write(raw)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temp, Path(path).name, src_dir_fd=fd, dst_dir_fd=fd)
+    finally:
+        try:
+            os.unlink(temp, dir_fd=fd)
+        except FileNotFoundError:
+            pass
+        os.close(fd)
+
+
+def _source_identity(spec):
+    if spec['kind'] == 'npm':
+        return {'installedDistribution': {key: spec[key] for key in ('distribution', 'version', 'integrity')},
+                'reviewedSource': {key: spec[key] for key in ('repository', 'commit', 'sourceArchiveSha256')},
+                'distributionToReviewedCommitMapping': 'Unverified: registry metadata supplies no gitHead; matching version is not commit proof.'}
+    return {key: spec[key] for key in ('repository', 'commit', 'sha256', 'sourceArchiveSha256', 'integrity', 'distribution', 'version') if key in spec}
+
+
+def _verify_archive(raw, spec):
+    if spec['kind'] == 'python':
+        valid = _digest(raw) == spec['sha256']
+    else:
+        valid = 'sha512-' + base64.b64encode(hashlib.sha512(raw).digest()).decode() == spec['integrity']
+    if not valid:
+        raise RuntimeErrorSafe('archive-hash-mismatch')
+
+
+def _download(url, timeout=120):
+    deadline = time.monotonic() + timeout
+    request = urllib.request.Request(url, headers={'User-Agent': 'crow-maker-runtime/1'})
+    with urllib.request.urlopen(request, timeout=min(30, timeout)) as response:
+        if not response.geturl().startswith('https://'):
+            raise RuntimeErrorSafe('insecure-download-redirect')
+        chunks, count = [], 0
+        while True:
+            if time.monotonic() >= deadline:
+                raise RuntimeErrorSafe('download-timeout')
+            chunk = response.read(65536)
+            if not chunk:
+                break
+            count += len(chunk)
+            if count > MAX_ARCHIVE:
+                raise RuntimeErrorSafe('archive-byte-limit')
+            chunks.append(chunk)
+        return b''.join(chunks)
+
+
+def _extract(archive, destination):
+    """Validate entire tar before writes: no links, devices, escapes or duplicates."""
+    parent_fd = _open(destination.parent, True)
+    try:
+        try:
+            os.mkdir(destination.name, 0o700, dir_fd=parent_fd)
+        except FileExistsError:
+            raise RuntimeErrorSafe('extraction-destination-must-be-new') from None
+    finally:
+        os.close(parent_fd)
+    _private_dir(destination)
+    with tarfile.open(archive, 'r:gz') as tar:
+        members, seen, total, roots = [], set(), 0, set()
+        for member in tar:
+            path = PurePosixPath(member.name)
+            if (not member.name or path.is_absolute() or '..' in path.parts or
+                    '\\' in member.name or ':' in member.name or
+                    not (member.isfile() or member.isdir()) or member.name in seen):
+                raise RuntimeErrorSafe('unsafe-archive-member')
+            if not path.parts or path.parts[0] in ('.', ''):
+                raise RuntimeErrorSafe('unsafe-archive-member')
+            roots.add(path.parts[0])
+            seen.add(member.name)
+            total += member.size
+            if len(seen) > 30000 or total > MAX_EXTRACTED or member.size > MAX_ARCHIVE:
+                raise RuntimeErrorSafe('archive-extraction-limit')
+            members.append(member)
+        if len(roots) != 1:
+            raise RuntimeErrorSafe('archive-must-have-single-source-root')
+        for member in members:
+            target = destination.joinpath(*PurePosixPath(member.name).parts)
+            # Destination was created by us and archive cannot introduce symlinks.
+            if member.isdir():
+                target.mkdir(mode=0o700, parents=True, exist_ok=True)
+            else:
+                target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+                descriptor = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o700 if member.mode & 0o111 else 0o600)
+                with os.fdopen(descriptor, 'wb') as output, tar.extractfile(member) as source:
+                    left = member.size
+                    while left:
+                        chunk = source.read(min(65536, left))
+                        if not chunk:
+                            raise RuntimeErrorSafe('archive-truncated-member')
+                        output.write(chunk)
+                        left -= len(chunk)
+        return destination / next(iter(roots))
+
+
+def _redact_stderr(raw, argv, environment):
+    # Never record argv/environment. Redact known credential values if a tool
+    # repeats them on stderr; stdout is an explicitly private raw result artifact.
+    candidates = []
+    for key, value in environment.items():
+        if any(word in key.upper() for word in ('TOKEN', 'SECRET', 'PASSWORD', 'API_KEY', 'AUTHORIZATION')) and len(value) >= 4:
+            candidates.append(value)
+    for i, value in enumerate(argv):
+        if value.startswith('-') and any(word in value.lower() for word in ('token', 'password', 'secret', 'api-key', 'authorization', 'header')):
+            if '=' in value:
+                candidates.append(value.split('=', 1)[1])
+            elif i + 1 < len(argv):
+                candidates.append(argv[i + 1])
+    for value in sorted(set(candidates), key=len, reverse=True):
+        if value:
+            raw = raw.replace(value.encode(), b'[REDACTED]')
+    return raw
+
+
+def _kill_group_impl(process):
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    try:
+        process.wait(timeout=2)
+    except subprocess.TimeoutExpired:
+        pass
+    # Kill the group even if its leader already exited on TERM.
+    try:
+        os.killpg(process.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    process.wait()
+
+
+def _kill_group(process):
+    # A repeated SIGTERM must not interrupt the TERM -> grace -> KILL cleanup
+    # and leave a TERM-ignoring child alive. Deliver it only after cleanup.
+    with _termination_scope() as guard:
+        with guard.deferred_signals():
+            _kill_group_impl(process)
+
+
+def _invoke_impl(argv, home, timeout, environment=None, interactive=False, cwd=None, guard=None):
+    if not math.isfinite(timeout) or timeout <= 0 or timeout > 86400:
+        raise RuntimeErrorSafe('timeout-must-be-finite-positive-at-most-one-day')
+    env = os.environ.copy() if environment is None else environment
+    working_directory = home if cwd is None else cwd
+    logs = _private_dir(home / 'logs', True)
+    stem = uuid.uuid4().hex
+    output_path, error_path = logs / (stem + '.stdout'), logs / (stem + '.stderr')
+    start = time.monotonic()
+    if interactive:
+        process = None
+        try:
+            with guard.deferred_signals():
+                process = subprocess.Popen(argv, cwd=working_directory, env=env, shell=False, start_new_session=True)
+            code = process.wait(timeout=timeout)
+            return {'returnCode': code, 'timedOut': False, 'stdoutRef': None, 'stderrRef': None, 'interactive': True}
+        except subprocess.TimeoutExpired:
+            return {'returnCode': 124, 'timedOut': True, 'stdoutRef': None, 'stderrRef': None, 'interactive': True}
+        finally:
+            if process is not None:
+                _kill_group(process)
+    output_fd = os.open(output_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
+    error_fd = os.open(error_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
+    capture = bytearray()
+    stderr_chunks = []
+    truncated, timed_out, totals = False, False, {'out': 0, 'err': 0}
+    process = None
+    try:
+        with guard.deferred_signals():
+            process = subprocess.Popen(argv, cwd=working_directory, env=env, stdin=subprocess.DEVNULL,
+                                       stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                                       shell=False, start_new_session=True)
+        selector = selectors.DefaultSelector()
+        selector.register(process.stdout, selectors.EVENT_READ, 'out')
+        selector.register(process.stderr, selectors.EVENT_READ, 'err')
+        try:
+            while selector.get_map():
+                if time.monotonic() - start >= timeout:
+                    timed_out = True
+                    _kill_group(process)
+                    break
+                for key, _ in selector.select(timeout=min(.1, timeout)):
+                    raw = os.read(key.fileobj.fileno(), 65536)
+                    if not raw:
+                        selector.unregister(key.fileobj)
+                        continue
+                    kind = key.data
+                    remaining = max(0, MAX_OUTPUT - totals[kind])
+                    if len(raw) > remaining:
+                        truncated = True
+                    kept = raw[:remaining]
+                    totals[kind] += len(raw)
+                    if kind == 'out':
+                        offset = 0
+                        while offset < len(kept):
+                            offset += os.write(output_fd, kept[offset:])
+                        if len(capture) < 8*1024*1024:
+                            capture.extend(kept[:8*1024*1024-len(capture)])
+                    else:
+                        # Stderr chunks are private and known credential values
+                        # are scrubbed. Arbitrary unknown secrets remain possible.
+                        stderr_chunks.append(kept)
+            if not timed_out:
+                try:
+                    process.wait(timeout=max(.001, timeout - (time.monotonic()-start)))
+                except subprocess.TimeoutExpired:
+                    timed_out = True
+                    _kill_group(process)
+            if not timed_out:
+                _kill_group(process)
+            scrubbed = _redact_stderr(b''.join(stderr_chunks), argv, env)
+            offset = 0
+            while offset < len(scrubbed):
+                offset += os.write(error_fd, scrubbed[offset:])
+        finally:
+            selector.close()
+            process.stdout.close()
+            process.stderr.close()
+    except BaseException as failure:
+        if process is not None:
+            _kill_group(process)
+            for stream in (process.stdout, process.stderr):
+                if stream is not None and not stream.closed:
+                    stream.close()
+        if isinstance(failure, (OperationCancelled, KeyboardInterrupt)):
+            failure.stdout_ref = 'logs/' + output_path.name
+            failure.stderr_ref = 'logs/' + error_path.name
+        raise
+    finally:
+        os.close(output_fd)
+        os.close(error_fd)
+    return {'returnCode': 124 if timed_out else process.returncode, 'timedOut': timed_out,
+            'outputTruncated': truncated, 'stdoutRef': 'logs/' + output_path.name,
+            'stderrRef': 'logs/' + error_path.name, '_stdout': bytes(capture)}
+
+
+def _invoke(argv, home, timeout, environment=None, interactive=False, cwd=None):
+    with _termination_scope() as guard:
+        try:
+            return _invoke_impl(argv, home, timeout, environment, interactive, cwd, guard)
+        except OperationCancelled as cancelled:
+            result = _cancel_result(cancelled.signum)
+            refs = (getattr(cancelled, 'stdout_ref', None), getattr(cancelled, 'stderr_ref', None))
+        except KeyboardInterrupt as cancelled:
+            result = _cancel_result(signal.SIGINT)
+            refs = (getattr(cancelled, 'stdout_ref', None), getattr(cancelled, 'stderr_ref', None))
+        result.update({'returnCode': result['exitCode'], 'stdoutRef': refs[0], 'stderrRef': refs[1],
+                       'outputTruncated': False, 'interactive': interactive, '_stdout': b''})
+        return result
+
+
+def _public_result(result):
+    return {key: value for key, value in result.items() if not key.startswith('_')}
+
+
+def _install_env(home):
+    env = {key: value for key, value in os.environ.items() if key in ('PATH', 'SYSTEMROOT', 'LANG', 'LC_ALL', 'SSL_CERT_FILE', 'SSL_CERT_DIR')}
+    for name in ('home', 'tmp', 'cache'):
+        _private_dir(home / name, True)
+    # npm rejects loading one path twice as both user and global config.
+    # Separate owned empty files also prevent reading the caller's npmrc.
+    user_config, global_config = home / 'npm-user.npmrc', home / 'npm-global.npmrc'
+    _atomic(user_config, b'')
+    _atomic(global_config, b'')
+    env.update({'HOME': str(home / 'home'), 'TMPDIR': str(home / 'tmp'),
+                'PIP_CONFIG_FILE': os.devnull, 'PIP_DISABLE_PIP_VERSION_CHECK': '1',
+                'PIP_CACHE_DIR': str(home / 'cache'), 'PYTHONNOUSERSITE': '1',
+                'npm_config_cache': str(home / 'cache'), 'npm_config_userconfig': str(user_config),
+                'npm_config_globalconfig': str(global_config), 'npm_config_audit': 'false',
+                'npm_config_fund': 'false'})
+    return env
+
+
+def _checked(argv, home, timeout, env):
+    result = _invoke(argv, home, timeout, environment=env)
+    if result.get('cancelled'):
+        raise OperationCancelled(result['signalNumber'])
+    if result['returnCode'] != 0 or result.get('outputTruncated'):
+        raise RuntimeErrorSafe('installer-or-verification-command-failed-see-private-logs')
+    return result
+
+
+def _installed_version(home, spec):
+    if spec['kind'] == 'npm':
+        data = json.loads(_read(home / 'npm/node_modules/@modelcontextprotocol/inspector/package.json', 1024*1024))
+        if data.get('name') != spec['distribution']:
+            raise RuntimeErrorSafe('installed-package-name-mismatch')
+        return data.get('version')
+    site = home / 'venv/lib'
+    # Static metadata reads: status does not start Python or import packages.
+    versions = []
+    for library in site.iterdir():
+        if not library.name.startswith('python') or library.is_symlink():
+            continue
+        packages = library / 'site-packages'
+        if not packages.is_dir() or packages.is_symlink():
+            continue
+        for item in packages.iterdir():
+            if item.name.endswith('.dist-info') and not item.is_symlink():
+                metadata = _read(item / 'METADATA', 2*1024*1024).decode('utf-8')
+                name, version = None, None
+                for line in metadata.splitlines():
+                    if line.startswith('Name: '): name = line[6:].strip()
+                    if line.startswith('Version: '): version = line[9:].strip()
+                    if name and version: break
+                if name and name.lower().replace('_', '-') == spec['distribution']:
+                    versions.append(version)
+    if len(versions) != 1:
+        raise RuntimeErrorSafe('installed-package-metadata-missing-or-ambiguous')
+    return versions[0]
+
+
+def status(engine, runtime_root):
+    spec = SPECS[engine]
+    root = Path(os.path.abspath(runtime_root))
+    result = {'schema': SCHEMA, 'engine': engine, 'installed': False,
+              'configured': False, 'verified': False, 'ready': False,
+              'configurationScope': 'Runtime environment and extras only.',
+              'providerConfiguration': 'not-checked', 'providerCredentialsVerified': False,
+              'source': _source_identity(spec), 'availableExtras': spec['extras'], 'exitCode': 1,
+              'verificationScope': 'Pinned source identity, installed target version, entrypoint hashes and resolved-inventory hash; not all dependency file contents.',
+              'limitations': ['Installed dependencies are resolved and recorded, not fully transitive hash-locked.',
+                  'Status does not execute third-party code or validate provider credentials, networking or every upstream mode.']}
+    try:
+        _private_dir(root)
+        home = _private_dir(root / engine)
+        result['installed'] = True
+        marker = json.loads(_read(home / 'READY.json', 2*1024*1024))
+        if (marker.get('schema') != SCHEMA or marker.get('state') != 'complete' or
+                marker.get('source') != _source_identity(spec)):
+            raise RuntimeErrorSafe('marker-identity-or-state-mismatch')
+        extras = marker.get('extras', [])
+        if not isinstance(extras, list) or any(value not in spec['extras'] for value in extras):
+            raise RuntimeErrorSafe('marker-extras-invalid')
+        result['configured'] = True
+        result['configuredExtras'] = extras
+        if _installed_version(home, spec) != spec['version']:
+            raise RuntimeErrorSafe('installed-version-mismatch')
+        if _digest(_read(home / 'resolved-inventory.json', 16*1024*1024)) != marker['inventorySha256']:
+            raise RuntimeErrorSafe('inventory-changed')
+        expected = set(spec['entrypoints'].values())
+        if set(marker.get('entrypointSha256', {})) != expected:
+            raise RuntimeErrorSafe('entrypoint-set-mismatch')
+        for rel, digest in marker['entrypointSha256'].items():
+            if _digest(_read(home / rel, 16*1024*1024)) != digest:
+                raise RuntimeErrorSafe('entrypoint-changed')
+        result.update({'verified': True, 'ready': True, 'exitCode': 0, 'entrypoints': sorted(spec['entrypoints'])})
+        if spec['kind'] == 'python':
+            result['runtimePython'] = str(home / 'venv/bin/python')
+    except (OSError, ValueError, KeyError, TypeError, RuntimeErrorSafe):
+        result['reason'] = 'not-installed-partial-or-verification-failed'
+    return result
+
+
+@_cancellable
+def setup(engine, runtime_root, yes=False, archive=None, timeout=1800, python=sys.executable, extras=()):
+    if not yes:
+        raise RuntimeErrorSafe('setup-requires-explicit-yes')
+    if not math.isfinite(timeout) or timeout <= 0 or timeout > 86400:
+        raise RuntimeErrorSafe('invalid-setup-timeout')
+    spec = SPECS[engine]
+    if not isinstance(extras, (list, tuple)) or not all(isinstance(value, str) and value in spec['extras'] for value in extras):
+        raise RuntimeErrorSafe('unknown-upstream-extra')
+    extras = sorted(set(extras))
+    root = _private_dir(runtime_root, True)
+    home = root / engine
+    if home.exists() or home.is_symlink():
+        current = status(engine, root)
+        if current['ready']:
+            if not set(extras).issubset(current.get('configuredExtras', [])):
+                raise RuntimeErrorSafe('additional-extras-require-new-private-runtime-root')
+            current['setup'] = 'already-ready-no-install-performed'
+            return current
+        raise RuntimeErrorSafe('partial-or-existing-runtime-use-new-private-root')
+    home = _private_dir(home, True)
+    try:
+        raw = _read(archive, MAX_ARCHIVE) if archive is not None else _download(spec['url'])
+        _verify_archive(raw, spec)
+        source_archive = home / 'source.tar.gz'
+        _atomic(source_archive, raw)
+        source = _extract(source_archive, home / 'source')
+        env = _install_env(home)
+        if spec['kind'] == 'python':
+            env['SETUPTOOLS_SCM_PRETEND_VERSION'] = spec['version']
+            _checked([str(python), '-I', '-m', 'venv', str(home / 'venv')], home, timeout, env)
+            interpreter = str(home / 'venv/bin/python')
+            _checked([interpreter, '-I', '-m', 'pip', 'install', '--disable-pip-version-check', '--no-input',
+                      '--report', str(home / 'pip-install-report.json'), str(source) + ('[' + ','.join(extras) + ']' if extras else '')], home, timeout, env)
+            inventory = _checked([interpreter, '-I', '-m', 'pip', 'list', '--format=json', '--disable-pip-version-check'], home, timeout, env)
+            parsed_inventory = json.loads(inventory['_stdout'])
+            if not isinstance(parsed_inventory, list):
+                raise RuntimeErrorSafe('invalid-resolved-inventory')
+        else:
+            package = json.loads(_read(source / 'package.json', 1024*1024))
+            if package.get('name') != spec['distribution'] or package.get('version') != spec['version']:
+                raise RuntimeErrorSafe('archive-package-version-mismatch')
+            npm = _private_dir(home / 'npm', True)
+            _checked(['npm', '--prefix', str(npm), 'install', '--ignore-scripts', '--no-audit', '--no-fund',
+                      '--save-exact', str(source_archive)], home, timeout, env)
+            inventory = _checked(['npm', '--prefix', str(npm), 'ls', '--json', '--all'], home, timeout, env)
+            parsed_inventory = json.loads(inventory['_stdout'])
+            if not isinstance(parsed_inventory, dict):
+                raise RuntimeErrorSafe('invalid-resolved-inventory')
+        if _installed_version(home, spec) != spec['version']:
+            raise RuntimeErrorSafe('installed-version-mismatch')
+        inventory_raw = _json(parsed_inventory)
+        _atomic(home / 'resolved-inventory.json', inventory_raw)
+        entries = {rel: _digest(_read(home / rel, 16*1024*1024)) for rel in set(spec['entrypoints'].values())}
+        # Only this final atomic write means ready; any preceding failure stays partial.
+        marker = {'schema': SCHEMA, 'state': 'complete', 'source': _source_identity(spec),
+                  'archiveSha256': _digest(raw), 'extras': extras, 'inventorySha256': _digest(inventory_raw),
+                  'entrypointSha256': entries, 'createdAtUnix': time.time(),
+                  'dependencyPolicy': 'Normal upstream dependency resolution isolated and inventoried; not a transitive lock guarantee.'}
+        _atomic(home / 'READY.json', _json(marker))
+        result = status(engine, root)
+        if not result['ready']:
+            raise RuntimeErrorSafe('post-setup-verification-failed')
+        result['setup'] = 'installed-and-verified-within-scope'
+        return result
+    except BaseException as failure:
+        # Retain partial state and private logs, never publish a READY marker.
+        try:
+            (home / 'READY.json').unlink(missing_ok=True)
+            _atomic(home / 'FAILED.json', _json({'schema': SCHEMA, 'state': 'partial-setup', 'source': _source_identity(spec), 'cancelled': isinstance(failure, (OperationCancelled, KeyboardInterrupt))}))
+        except OSError:
+            pass
+        raise
+
+
+@_cancellable
+def run(engine, runtime_root, args, timeout=300, entrypoint=None, interactive=False, cwd=None):
+    current = status(engine, runtime_root)
+    if not current['ready']:
+        raise RuntimeErrorSafe('engine-not-ready-run-never-installs')
+    spec = SPECS[engine]
+    entrypoint = entrypoint or engine
+    if entrypoint not in spec['entrypoints']:
+        raise RuntimeErrorSafe('unknown-engine-entrypoint')
+    if not isinstance(args, list) or not all(isinstance(arg, str) and '\x00' not in arg for arg in args):
+        raise RuntimeErrorSafe('invalid-upstream-arguments')
+    home = Path(os.path.abspath(runtime_root)) / engine
+    target = str(home / spec['entrypoints'][entrypoint])
+    command = (['node', target] if spec['kind'] == 'npm' else [target]) + args
+    working_directory = Path(os.path.abspath(os.getcwd() if cwd is None else cwd))
+    directory_fd = _open(working_directory, True)
+    os.close(directory_fd)
+    result = _invoke(command, home, timeout, interactive=interactive, cwd=working_directory)
+    return {'schema': SCHEMA, 'engine': engine, 'entrypoint': entrypoint,
+            'state': 'cancelled' if result.get('cancelled') else 'completed',
+            'cancelled': bool(result.get('cancelled')), 'signal': result.get('signal'),
+            'exitCode': 2 if result.get('outputTruncated') else result['returnCode'],
+            'execution': _public_result(result),
+            'limitations': ['Native upstream execution, not sandboxed; supplied arguments may connect to servers or invoke paid provider APIs.',
+                'Private stdout artifacts retain raw results and may contain sensitive data; do not publish them blindly.',
+                'Stderr scrubbing is best effort for known credential values, not a secret-detection guarantee.',
+                'Timeout cleanup targets the new process group; descendants that deliberately escape it are not contained.']}
+
+
+def _main_impl(argv=None):
+    tokens = list(sys.argv[1:] if argv is None else argv)
+    upstream = []
+    if '--' in tokens:
+        cut = tokens.index('--')
+        tokens, upstream = tokens[:cut], tokens[cut+1:]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('operation', choices=('status', 'setup', 'run'))
+    parser.add_argument('engine', choices=tuple(SPECS))
+    parser.add_argument('--runtime-root', required=True)
+    parser.add_argument('--yes', action='store_true')
+    parser.add_argument('--archive')
+    parser.add_argument('--python', default=sys.executable)
+    parser.add_argument('--timeout', type=float)
+    parser.add_argument('--entrypoint')
+    parser.add_argument('--interactive', action='store_true')
+    parser.add_argument('--cwd', help='Upstream working directory; defaults to the caller current directory')
+    parser.add_argument('--extras', default='', help='Explicit comma-separated declared upstream Python extras')
+    args = parser.parse_args(tokens)
+    try:
+        if upstream and args.operation != 'run':
+            raise RuntimeErrorSafe('upstream-arguments-only-valid-for-run')
+        if args.operation == 'status':
+            result = status(args.engine, args.runtime_root)
+        elif args.operation == 'setup':
+            result = setup(args.engine, args.runtime_root, args.yes, args.archive,
+                           args.timeout if args.timeout is not None else 1800, args.python,
+                           args.extras.split(',') if args.extras else [])
+        else:
+            result = run(args.engine, args.runtime_root, upstream,
+                         args.timeout if args.timeout is not None else 300,
+                         args.entrypoint, args.interactive, args.cwd)
+    except (RuntimeErrorSafe, OSError, ValueError, KeyError, TypeError, tarfile.TarError) as error:
+        result = {'schema': SCHEMA, 'engine': args.engine, 'exitCode': 2,
+                  'error': error.code if isinstance(error, RuntimeErrorSafe) else 'operational-setup-or-runtime-error'}
+    print(json.dumps(result, sort_keys=True, ensure_ascii=True, allow_nan=False))
+    return result['exitCode']
+
+
+def main(argv=None):
+    with _termination_scope():
+        try:
+            return _main_impl(argv)
+        except OperationCancelled as cancelled:
+            result = _cancel_result(cancelled.signum)
+        except KeyboardInterrupt:
+            result = _cancel_result(signal.SIGINT)
+        print(json.dumps(result, sort_keys=True, ensure_ascii=True, allow_nan=False))
+        return result['exitCode']
+
+
+if __name__ == '__main__':
+    sys.exit(main())