Skip to content

aiskillstore/marketplace / pending/cagdasyurekli/agy-worker

agy-worker

Unverified

Use when Codex or Claude Code should delegate repository exploration or implementation to Google Antigravity CLI (agy), then review, verify, repair, and deliver the result.

FileKindSize
README.mdmarkdown3.7 KB
SKILL.mdskill md12.5 KB
agents/openai.yamlconfig397 B
references/PROJECT_LIFECYCLE_AND_VERIFICATION.mdmarkdown25.6 KB
references/SECURITY_AND_COMPATIBILITY.mdmarkdown16.9 KB
references/TROUBLESHOOTING.mdmarkdown13.3 KB
runtime/agy-worker.shexecutablescript58.1 KB
runtime/delegation-policy.shexecutablescript293 B
runtime/doctor.shexecutablescript16.5 KB
runtime/evidence-report.shexecutablescript267 B
runtime/ground-truth.shexecutablescript2.9 KB
runtime/job.shexecutablescript266 B
runtime/model-selection.shexecutablescript262 B
runtime/qa-gate.shexecutablescript28.7 KB
runtime/schemas/delegation-policy.schema.jsonconfig2.6 KB
runtime/schemas/evidence-receipt.schema.jsonconfig2.5 KB
runtime/schemas/job-state.schema.jsonconfig3.6 KB
runtime/schemas/model-selection.schema.jsonconfig8.3 KB
runtime/schemas/worker-result.provider.schema.jsonconfig2.1 KB
runtime/schemas/worker-result.schema.jsonconfig3.0 KB
runtime/schemas/workflow-state.schema.jsonconfig3.7 KB
runtime/scripts/agy_dispatch.pyexecutablescript344.5 KB
runtime/scripts/agy_dispatch_containment.pyscript51.4 KB
runtime/scripts/agy_dispatch_verification.pyscript33.9 KB
runtime/scripts/agy_dispatch_worktree.pyscript220.6 KB
runtime/scripts/candidate_state.pyexecutablescript47.4 KB
runtime/scripts/delegation_policy.pyexecutablescript12.8 KB
runtime/scripts/evidence_receipt.pyexecutablescript52.9 KB
runtime/scripts/evidence_report.pyexecutablescript17.7 KB
runtime/scripts/job_lifecycle.pyexecutablescript89.0 KB
runtime/scripts/launch_authority.pyscript27.4 KB
runtime/scripts/model_selection.pyexecutablescript38.8 KB
runtime/scripts/transmission_preview.pyexecutablescript744 B
runtime/scripts/validate-envelope.pyexecutablescript6.5 KB
runtime/scripts/workflow.pyexecutablescript89.2 KB
runtime/verify-job.shexecutablescript261 B
runtime/workflow.shexecutablescript239 B
scripts/resolve-pipeline.shexecutablescript5.9 KB
skill-report.jsonconfig552.7 KB

runtime/scripts/agy_dispatch_containment.py

View on GitHub
#!/usr/bin/env python3
"""macOS OS containment for selected-content and self-verification launches.

The dispatcher remains responsible for deciding whether a launch is scoped and
for binding the provider selection.  This module owns only the native launch
envelope: an owner-private profile, private provider state, a per-attempt temp
directory, and identity-safe process-group termination.

``sandbox-exec`` is a deprecated macOS interface.  The implementation therefore
binds the Darwin build and launcher bytes and fails closed everywhere else.  A
caller must re-run :func:`confirm_contained_launch` immediately before ``Popen``.

This primitive binds the stage directory, not its contents. The trusted dispatcher
must supply a freshly copied, no-hardlink stage and rebind its complete approved
manifest before launch. A pre-existing hardlink inside an allowed directory still
names the outside inode. It must also launch with DEVNULL stdin, private pipes for
stdout/stderr, close_fds=True and no pass_fds: an inherited open descriptor is not
revoked by a pathname sandbox. Neither prerequisite is proved by directory binding.
"""

from __future__ import annotations

import ctypes
import dataclasses
import hashlib
import json
import os
from pathlib import Path
import platform
import plistlib
import posixpath
import pwd
import signal
import stat
import subprocess
import sys
import time
from typing import Mapping, Sequence, cast
import uuid


SANDBOX_EXEC = Path("/usr/bin/sandbox-exec")
MAX_EXECUTABLE_BYTES = 512 * 1024 * 1024
MAX_PROFILE_BYTES = 64 * 1024
DEDICATED_KEYCHAIN_NAME = "agy-worker-provider.keychain-db"
KEYCHAIN_SETUP_DOC = "references/TROUBLESHOOTING.md (Dedicated agy keychain for native isolation)"
KEYCHAIN_STATUS_DEADLINE_SECONDS = 5
EXIT_NATIVE_HOST_UNAVAILABLE = 27
MAX_GROUP_MEMBERS = 4096
PROCESS_GROUP_CLEANUP_SCOPE = "bound-process-group-only"
ROLE_PROVIDER = "provider"
ROLE_SELF_VERIFY = "self-verify"
NETWORK_DENY_ALL = "deny-all"
NETWORK_PROVIDER_TLS = "provider-tls"
GRANT_PROFILE_BASELINE = "baseline"
GRANT_PROFILE_A = "A"
GRANT_PROFILE_B = "B"
GRANT_PROFILE_AB = "AB"
# Only new command/preview construction reads this policy choice. Legacy callers
# retain the literal baseline defaults on render and prepare.
NEW_NATIVE_GRANT_PROFILE = "baseline"
_GRANT_PROFILES = frozenset({
    GRANT_PROFILE_BASELINE, GRANT_PROFILE_A, GRANT_PROFILE_B, GRANT_PROFILE_AB,
})
_ROLES = frozenset({ROLE_PROVIDER, ROLE_SELF_VERIFY})
_PROC_PIDTBSDINFO = 3
_MAXCOMLEN = 16


# SecKeychainGetStatus reports kSecUnlockStateStatus (1) without ever prompting.
_KEYCHAIN_STATUS_PROBE = """
import ctypes, sys
framework = "/System/Library/Frameworks/"
sec = ctypes.CDLL(framework + "Security.framework/Security")
cf = ctypes.CDLL(framework + "CoreFoundation.framework/CoreFoundation")
sec.SecKeychainOpen.argtypes = [ctypes.c_char_p, ctypes.c_void_p]
sec.SecKeychainOpen.restype = ctypes.c_int32
sec.SecKeychainGetStatus.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
sec.SecKeychainGetStatus.restype = ctypes.c_int32
cf.CFRelease.argtypes = [ctypes.c_void_p]
ref, status = ctypes.c_void_p(), ctypes.c_uint32()
if sec.SecKeychainOpen(sys.argv[1].encode(), ctypes.byref(ref)) != 0 or not ref.value:
    raise SystemExit(1)
try:
    if sec.SecKeychainGetStatus(ref, ctypes.byref(status)) != 0:
        raise SystemExit(1)
finally:
    cf.CFRelease(ref)
print("unlocked" if status.value & 1 else "locked")
"""


class ContainmentError(RuntimeError):
    """The scoped native launch boundary could not be established exactly."""


class KeychainUnavailableError(ContainmentError):
    """The dedicated Keychain is missing or locked; the message is actionable."""


@dataclasses.dataclass(frozen=True)
class FileBinding:
    path: str
    device: int
    inode: int
    uid: int
    gid: int
    mode: int
    nlink: int
    size: int
    mtime_ns: int
    ctime_ns: int
    sha256: str | None


@dataclasses.dataclass(frozen=True)
class DirectoryBinding:
    path: str
    device: int
    inode: int
    uid: int
    gid: int
    mode: int
    nlink: int


@dataclasses.dataclass(frozen=True)
class KeychainBinding:
    """Metadata-only identity for the database used by Security.framework."""

    path: str
    device: int
    inode: int
    uid: int
    mode: int


@dataclasses.dataclass(frozen=True)
class ProcessIdentity:
    pid: int
    parent_pid: int
    process_group: int
    session_id: int
    uid: int
    start_seconds: int
    start_microseconds: int


@dataclasses.dataclass(frozen=True)
class PreparedContainedLaunch:
    role: str
    network_policy: str
    grant_profile: str
    darwin_release: str
    darwin_version: str
    launcher: FileBinding
    target: FileBinding
    profile: FileBinding
    read_only_inputs: tuple[FileBinding, ...]
    keychain: KeychainBinding | None
    keychain_preferences: FileBinding | None
    provider_settings: FileBinding | None
    stage: DirectoryBinding
    private_home: DirectoryBinding
    attempt_tmp: DirectoryBinding
    target_argv: tuple[str, ...]
    environment: tuple[tuple[str, str], ...]
    allow_keychain: bool


@dataclasses.dataclass(frozen=True)
class ConfirmedContainedLaunch:
    argv: tuple[str, ...]
    executable: str
    cwd: str
    environment: dict[str, str]


class _ProcBsdInfo(ctypes.Structure):
    _fields_ = [
        ("pbi_flags", ctypes.c_uint32),
        ("pbi_status", ctypes.c_uint32),
        ("pbi_xstatus", ctypes.c_uint32),
        ("pbi_pid", ctypes.c_uint32),
        ("pbi_ppid", ctypes.c_uint32),
        ("pbi_uid", ctypes.c_uint32),
        ("pbi_gid", ctypes.c_uint32),
        ("pbi_ruid", ctypes.c_uint32),
        ("pbi_rgid", ctypes.c_uint32),
        ("pbi_svuid", ctypes.c_uint32),
        ("pbi_svgid", ctypes.c_uint32),
        ("rfu_1", ctypes.c_uint32),
        ("pbi_comm", ctypes.c_char * _MAXCOMLEN),
        ("pbi_name", ctypes.c_char * (2 * _MAXCOMLEN)),
        ("pbi_nfiles", ctypes.c_uint32),
        ("pbi_pgid", ctypes.c_uint32),
        ("pbi_pjobc", ctypes.c_uint32),
        ("e_tdev", ctypes.c_uint32),
        ("e_tpgid", ctypes.c_uint32),
        ("pbi_nice", ctypes.c_int32),
        ("pbi_start_tvsec", ctypes.c_uint64),
        ("pbi_start_tvusec", ctypes.c_uint64),
    ]


def require_supported_host() -> None:
    """Reject unsupported hosts even when no check has been selected."""
    if sys.platform != "darwin" or platform.system() != "Darwin":
        raise ContainmentError("native launch containment requires macOS")


def _canonical_existing(path: str | Path) -> Path:
    candidate = Path(os.fsdecode(path))
    if not candidate.is_absolute() or "\0" in str(candidate):
        raise ContainmentError("containment path must be canonical and absolute")
    if Path(os.path.realpath(candidate)) != candidate:
        raise ContainmentError("containment path must not contain aliases")
    return candidate


def _read_hash(descriptor: int, limit: int) -> str:
    digest = hashlib.sha256()
    size = 0
    os.lseek(descriptor, 0, os.SEEK_SET)
    while True:
        chunk = os.read(descriptor, 1024 * 1024)
        if not chunk:
            break
        size += len(chunk)
        if size > limit:
            raise ContainmentError("containment executable or profile exceeds its byte limit")
        digest.update(chunk)
    return digest.hexdigest()


def _bind_file(
    path: str | Path, *, modes: set[int], executable: bool = False,
    limit: int = MAX_EXECUTABLE_BYTES, require_single_link: bool = True,
) -> FileBinding:
    candidate = _canonical_existing(path)
    nofollow = getattr(os, "O_NOFOLLOW", 0)
    try:
        named = os.lstat(candidate)
        descriptor = os.open(candidate, os.O_RDONLY | nofollow)
    except OSError as exc:
        raise ContainmentError("containment file is unavailable") from exc
    try:
        before = os.fstat(descriptor)
        mode = stat.S_IMODE(before.st_mode)
        identity = (
            before.st_dev, before.st_ino, before.st_uid, before.st_gid,
            before.st_mode, before.st_nlink, before.st_size,
            before.st_mtime_ns, before.st_ctime_ns,
        )
        named_identity = (
            named.st_dev, named.st_ino, named.st_uid, named.st_gid,
            named.st_mode, named.st_nlink, named.st_size,
            named.st_mtime_ns, named.st_ctime_ns,
        )
        if (
            not stat.S_ISREG(before.st_mode)
            or before.st_uid not in {0, os.getuid()}
            or (require_single_link and before.st_nlink != 1)
            or (not require_single_link and before.st_nlink < 1)
            or mode not in modes
            or identity != named_identity
            or (executable and mode & 0o111 == 0)
        ):
            raise ContainmentError("containment file authority is invalid")
        content_sha = _read_hash(descriptor, limit)
        after = os.fstat(descriptor)
        after_identity = (
            after.st_dev, after.st_ino, after.st_uid, after.st_gid,
            after.st_mode, after.st_nlink, after.st_size,
            after.st_mtime_ns, after.st_ctime_ns,
        )
        if after_identity != identity or os.lstat(candidate) != after:
            raise ContainmentError("containment file changed during binding")
        return FileBinding(
            str(candidate), before.st_dev, before.st_ino, before.st_uid,
            before.st_gid, mode, before.st_nlink, before.st_size,
            before.st_mtime_ns, before.st_ctime_ns, content_sha,
        )
    finally:
        os.close(descriptor)


def _bind_keychain(path: str | Path) -> KeychainBinding:
    """Bind the dedicated Keychain by metadata without opening its database."""
    candidate = _canonical_existing(path)
    try:
        before = os.lstat(candidate)
        after = os.lstat(candidate)
    except OSError as exc:
        raise ContainmentError("native provider authentication is unavailable") from exc
    mode = stat.S_IMODE(before.st_mode)
    stable_identity = lambda item: (
        item.st_dev, item.st_ino, item.st_uid,
        stat.S_IFMT(item.st_mode), stat.S_IMODE(item.st_mode),
    )
    if (
        stable_identity(before) != stable_identity(after)
        or stat.S_ISLNK(before.st_mode)
        or not stat.S_ISREG(before.st_mode)
        or before.st_uid != os.getuid()
        or mode & 0o022
    ):
        raise ContainmentError("native provider authentication is unavailable")
    return KeychainBinding(
        str(candidate), before.st_dev, before.st_ino, before.st_uid, mode,
    )


def dedicated_keychain_path() -> Path:
    """Return the only Keychain native isolation may use, under the passwd-resolved HOME."""
    try:
        owner_home = _canonical_existing(pwd.getpwuid(os.getuid()).pw_dir)
        owner = os.lstat(owner_home)
    except (ContainmentError, OSError, KeyError) as exc:
        raise ContainmentError("native provider authentication is unavailable") from exc
    if not stat.S_ISDIR(owner.st_mode) or owner.st_uid != os.getuid():
        raise ContainmentError("native provider authentication is unavailable")
    return owner_home / "Library" / "Keychains" / DEDICATED_KEYCHAIN_NAME


def _keychain_is_unlocked(path: str) -> bool:
    """Read the lock state without UI: a locked lookup would otherwise hang on a dialog."""
    try:
        completed = subprocess.run(
            [sys.executable, "-I", "-S", "-B", "-c", _KEYCHAIN_STATUS_PROBE, path],
            stdin=subprocess.DEVNULL, capture_output=True, check=False,
            timeout=KEYCHAIN_STATUS_DEADLINE_SECONDS,
            env={"PATH": "/usr/bin:/bin", "LANG": "C", "LC_ALL": "C"},
        )
    except (OSError, subprocess.TimeoutExpired) as exc:
        raise KeychainUnavailableError(
            f"cannot read the lock state of {path} within {KEYCHAIN_STATUS_DEADLINE_SECONDS}s"
        ) from exc
    if completed.returncode == 0 and completed.stdout in {b"locked\n", b"unlocked\n"}:
        return completed.stdout == b"unlocked\n"
    raise KeychainUnavailableError(f"cannot read the lock state of {path}")


def _require_unlocked(path: str) -> None:
    if not _keychain_is_unlocked(path):
        raise KeychainUnavailableError(
            f"the dedicated agy keychain {path} is locked; unlock it with: "
            f"security unlock-keychain ~/Library/Keychains/{DEDICATED_KEYCHAIN_NAME}"
        )


def _dedicated_keychain() -> KeychainBinding:
    """Bind the dedicated Keychain, failing closed when it is missing, unsafe or locked."""
    path = dedicated_keychain_path()
    if not os.path.lexists(path):
        raise KeychainUnavailableError(
            f"native isolation needs the dedicated agy keychain {path}, which does not "
            f"exist; create it once as described in {KEYCHAIN_SETUP_DOC}"
        )
    try:
        binding = _bind_keychain(path)
    except ContainmentError as exc:
        raise KeychainUnavailableError(
            f"the dedicated agy keychain {path} must be a regular file you own "
            "without group or other write access"
        ) from exc
    _require_unlocked(binding.path)
    return binding


def _bind_directory(path: str | Path) -> DirectoryBinding:
    candidate = _canonical_existing(path)
    nofollow = getattr(os, "O_NOFOLLOW", 0)
    directory = getattr(os, "O_DIRECTORY", 0)
    try:
        named = os.lstat(candidate)
        descriptor = os.open(candidate, os.O_RDONLY | nofollow | directory)
    except OSError as exc:
        raise ContainmentError("containment directory is unavailable") from exc
    try:
        current = os.fstat(descriptor)
        if (
            not stat.S_ISDIR(current.st_mode)
            or stat.S_ISLNK(named.st_mode)
            or current.st_uid != os.getuid()
            or stat.S_IMODE(current.st_mode) != 0o700
            or (
                current.st_dev, current.st_ino, current.st_uid,
                current.st_gid, current.st_mode, current.st_nlink
            ) != (
                named.st_dev, named.st_ino, named.st_uid,
                named.st_gid, named.st_mode, named.st_nlink
            )
        ):
            raise ContainmentError("containment directory authority is invalid")
        return DirectoryBinding(
            str(candidate), current.st_dev, current.st_ino, current.st_uid,
            current.st_gid, stat.S_IMODE(current.st_mode), current.st_nlink,
        )
    finally:
        os.close(descriptor)


def _ensure_private_directory(path: Path, *, existing_ok: bool) -> DirectoryBinding:
    try:
        os.mkdir(path, 0o700)
    except FileExistsError:
        if not existing_ok:
            raise ContainmentError("per-attempt containment directory already exists")  # noqa: B904 -- preserve existing exception context and public diagnostics
    except OSError as exc:
        raise ContainmentError("cannot create containment directory") from exc
    try:
        os.chmod(path, 0o700, follow_symlinks=False)
    except OSError as exc:
        raise ContainmentError("cannot normalize containment directory") from exc
    return _bind_directory(path)


def _publish_profile(path: Path, payload: bytes) -> FileBinding:
    if not payload or len(payload) > MAX_PROFILE_BYTES:
        raise ContainmentError("containment profile has invalid size")
    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
    try:
        descriptor = os.open(path, flags, 0o600)
    except OSError as exc:
        raise ContainmentError("cannot create containment profile") from exc
    try:
        view = memoryview(payload)
        while view:
            written = os.write(descriptor, view)
            if written <= 0:
                raise ContainmentError("cannot write containment profile")
            view = view[written:]
        os.fsync(descriptor)
        os.fchmod(descriptor, 0o400)
    finally:
        os.close(descriptor)
    return _bind_file(path, modes={0o400}, limit=MAX_PROFILE_BYTES)


def _publish_private_file(path: Path, payload: bytes) -> FileBinding:
    """Publish a small owner-private internal artifact without replacement."""
    if not payload or len(payload) > MAX_PROFILE_BYTES:
        raise ContainmentError("native provider authentication is unavailable")
    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
    try:
        descriptor = os.open(path, flags, 0o600)
    except OSError as exc:
        raise ContainmentError("native provider authentication is unavailable") from exc
    try:
        try:
            view = memoryview(payload)
            while view:
                written = os.write(descriptor, view)
                if written <= 0:
                    raise ContainmentError("native provider authentication is unavailable")
                view = view[written:]
            os.fsync(descriptor)
            os.fchmod(descriptor, 0o600)
        except OSError as exc:
            raise ContainmentError("native provider authentication is unavailable") from exc
    finally:
        try:
            os.close(descriptor)
        except OSError as exc:
            raise ContainmentError("native provider authentication is unavailable") from exc
    return _bind_file(path, modes={0o600}, limit=MAX_PROFILE_BYTES)


def _default_keychain_preferences_payload(keychain: KeychainBinding) -> bytes:
    """Create the minimal private DefaultKeychain preference from Security's GUID."""
    try:
        framework = ctypes.CDLL("/System/Library/Frameworks/Security.framework/Security")
        guid = (ctypes.c_ubyte * 16).in_dll(framework, "gGuidAppleCSPDL")
        value = {
            "DefaultKeychain": [{
                "GUID": "{" + str(uuid.UUID(bytes=bytes(guid))).upper() + "}",
                "SubserviceId": 0,
                "SubserviceType": 6,
                "MajorVersion": 0,
                "MinorVersion": 0,
                "DbName": keychain.path,
            }],
        }
        return plistlib.dumps(value, fmt=plistlib.FMT_XML, sort_keys=True)
    except (AttributeError, OSError, ValueError) as exc:
        raise ContainmentError("native provider authentication is unavailable") from exc


def _file_binding_record(binding: FileBinding) -> bytes:
    return (json.dumps(dataclasses.asdict(binding), sort_keys=True, separators=(",", ":")) + "\n").encode("ascii")


def _load_file_binding_record(path: Path) -> FileBinding:
    try:
        sidecar = _bind_file(path, modes={0o600}, limit=MAX_PROFILE_BYTES)
        descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
        try:
            raw = os.read(descriptor, MAX_PROFILE_BYTES + 1)
        finally:
            os.close(descriptor)
        if len(raw) > MAX_PROFILE_BYTES:
            raise ValueError("sidecar too large")
        value = json.loads(raw.decode("ascii", "strict"))
        if set(value) != {field.name for field in dataclasses.fields(FileBinding)}:
            raise ValueError("sidecar schema")
        binding = FileBinding(**value)
        if not isinstance(binding.path, str) or not binding.path.startswith("/"):
            raise ValueError("sidecar path")
        # Bind after read: sidecar bytes and identity must be stable.
        if _bind_file(path, modes={0o600}, limit=MAX_PROFILE_BYTES) != sidecar:
            raise ValueError("sidecar changed")
        return binding
    except (ContainmentError, OSError, UnicodeError, ValueError, TypeError, json.JSONDecodeError) as exc:
        raise ContainmentError("native provider authentication is unavailable") from exc


def _prepare_keychain_preferences(
    job: Path, home: Path, keychain: KeychainBinding,
) -> FileBinding:
    """Create once, then only reuse the exact private preference identity."""
    preferences_dir = home / "Library" / "Preferences"
    _ensure_private_directory(home / "Library", existing_ok=True)
    _ensure_private_directory(preferences_dir, existing_ok=True)
    preferences = preferences_dir / "com.apple.security.plist"
    sidecar = job / ".provider-keychain-preferences.binding"
    payload = _default_keychain_preferences_payload(keychain)
    if os.path.lexists(sidecar):
        prior = _load_file_binding_record(sidecar)
        try:
            current = _bind_file(preferences, modes={0o600}, limit=MAX_PROFILE_BYTES)
        except ContainmentError as exc:
            raise ContainmentError("native provider authentication is unavailable") from exc
        if current != prior or current.sha256 != hashlib.sha256(payload).hexdigest():
            raise ContainmentError("native provider authentication is unavailable")
        return current
    if os.path.lexists(preferences):
        raise ContainmentError("native provider authentication is unavailable")
    created = _publish_private_file(preferences, payload)
    try:
        _publish_private_file(sidecar, _file_binding_record(created))
    except ContainmentError:
        # Never overwrite or accept a partly-created preference without its
        # protected identity record on a later repair attempt.
        raise
    return created


def _validate_provider_write_selectors(
    selectors: Sequence[Mapping[str, str]],
) -> tuple[tuple[str, str], ...]:
    """Accept only the closed, already-validated scope selector shape."""
    if isinstance(selectors, (str, bytes)):
        raise ContainmentError("native provider permission settings are unavailable")
    result: list[tuple[str, str]] = []
    previous: str | None = None
    forbidden = frozenset("()[]{}*?\\\"'")
    for entry in selectors:
        if not isinstance(entry, Mapping) or set(entry) != {"kind", "path"}:
            raise ContainmentError("native provider permission settings are unavailable")
        kind, path = entry["kind"], entry["path"]
        if (
            kind not in {"file", "tree"}
            or not isinstance(path, str)
            or not path
            or path.startswith("/")
            or path.endswith("/")
            or "\x00" in path
            or any(character in forbidden for character in path)
        ):
            raise ContainmentError("native provider permission settings are unavailable")
        normalized = posixpath.normpath(path)
        parts = normalized.split("/")
        if (
            normalized != path
            or normalized in {"", ".", ".."}
            or normalized.startswith("../")
            or any(part in {"", ".", "..", ".git", ".agy-worker-control"} for part in parts)
            or previous is not None and path <= previous
        ):
            raise ContainmentError("native provider permission settings are unavailable")
        previous = path
        result.append((kind, path))
    return tuple(result)


def _provider_settings_payload(
    job: Path, max_cycles: int, selectors: tuple[tuple[str, str], ...],
) -> bytes:
    if type(max_cycles) is not int or not 1 <= max_cycles <= 5:
        raise ContainmentError("native provider permission settings are unavailable")
    forbidden = frozenset("()[]{}*?\\\"'")

    def rule_target(path: Path) -> str:
        value = str(path)
        if (
            not path.is_absolute()
            or "\x00" in value
            or "\r" in value
            or "\n" in value
            or any(character in forbidden for character in value)
        ):
            raise ContainmentError("native provider permission settings are unavailable")
        return value

    job_target = rule_target(job)
    if Path(os.path.realpath(job_target)) != job:
        raise ContainmentError("native provider permission settings are unavailable")
    allowed: list[str] = []
    for cycle in range(1, max_cycles + 1):
        stage = job / f"stage-{cycle:03d}"
        allowed.append(f"read_file({rule_target(stage)})")
        allowed.extend(
            f"write_file({rule_target(stage / path)})" for _kind, path in selectors
        )
    payload = json.dumps(
        {"permissions": {"allow": allowed}},
        sort_keys=True, separators=(",", ":"),
    ).encode("utf-8")
    if not payload or len(payload) > MAX_PROFILE_BYTES:
        raise ContainmentError("native provider permission settings are unavailable")
    return payload


def _prepare_provider_settings(
    job: Path, home: Path, max_cycles: int,
    selectors: tuple[tuple[str, str], ...],
) -> FileBinding:
    """Create once and then exactly rebind the private provider policy."""
    settings_parent = home / ".gemini" / "antigravity-cli"
    _ensure_private_directory(home / ".gemini", existing_ok=True)
    _ensure_private_directory(settings_parent, existing_ok=True)
    settings = settings_parent / "settings.json"
    sidecar = job / ".provider-antigravity-settings.binding"
    payload = _provider_settings_payload(job, max_cycles, selectors)
    if os.path.lexists(sidecar):
        prior = _load_file_binding_record(sidecar)
        try:
            current = _bind_file(settings, modes={0o600}, limit=MAX_PROFILE_BYTES)
        except ContainmentError as exc:
            raise ContainmentError("native provider permission settings are unavailable") from exc
        if current != prior or current.sha256 != hashlib.sha256(payload).hexdigest():
            raise ContainmentError("native provider permission settings are unavailable")
        return current
    if os.path.lexists(settings):
        raise ContainmentError("native provider permission settings are unavailable")
    created = _publish_private_file(settings, payload)
    _publish_private_file(sidecar, _file_binding_record(created))
    return created


def _scheme_string(value: str) -> str:
    if "\0" in value:
        raise ContainmentError("sandbox profile value contains NUL")
    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
    escaped = escaped.replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
    return f'"{escaped}"'


def _validate_grant_profile(
    grant_profile: str, role: str, network_policy: str, allow_keychain: bool,
) -> None:
    if type(grant_profile) is not str or grant_profile not in _GRANT_PROFILES:
        raise ContainmentError("native grant profile is invalid")
    if role != ROLE_PROVIDER and grant_profile != GRANT_PROFILE_BASELINE:
        raise ContainmentError("only provider launches may select native grants")
    if grant_profile in {GRANT_PROFILE_A, GRANT_PROFILE_AB} and not allow_keychain:
        raise ContainmentError("native grant profile requires provider keychain")
    if grant_profile in {GRANT_PROFILE_B, GRANT_PROFILE_AB} and network_policy != NETWORK_PROVIDER_TLS:
        raise ContainmentError("native grant profile requires provider TLS")


def render_profile(
    *, target_executable: str, role: str, network_policy: str,
    allow_keychain: bool, read_only_inputs: Sequence[str] = (),
    keychain_path: str | None = None, provider_settings_path: str | None = None,
    grant_profile: str = "baseline",
) -> bytes:
    """Render the fixed default-deny profile; dynamic paths use ``-D`` params."""
    if role not in _ROLES:
        raise ContainmentError("containment role is invalid")
    if network_policy not in {NETWORK_DENY_ALL, NETWORK_PROVIDER_TLS}:
        raise ContainmentError("containment network policy is invalid")
    if network_policy == NETWORK_PROVIDER_TLS and role != ROLE_PROVIDER:
        raise ContainmentError("only provider launches may use provider TLS")
    if role != ROLE_PROVIDER and allow_keychain:
        raise ContainmentError("only provider launches may access the keychain")
    _validate_grant_profile(grant_profile, role, network_policy, allow_keychain)
    if (allow_keychain and (
        not isinstance(keychain_path, str) or not keychain_path.startswith("/")
    )) or (not allow_keychain and keychain_path is not None):
        raise ContainmentError("containment keychain input is invalid")
    if provider_settings_path is not None and (
        not allow_keychain
        or not isinstance(provider_settings_path, str)
        or not provider_settings_path.startswith("/")
    ):
        raise ContainmentError("containment provider settings input is invalid")
    if provider_settings_path is not None:
        settings = Path(provider_settings_path)
        if (
            str(settings) != provider_settings_path
            or ".." in settings.parts
            or settings.parts[-3:] != (".gemini", "antigravity-cli", "settings.json")
            or settings.parents[2] == Path("/")
        ):
            raise ContainmentError("containment provider settings input is invalid")
    if len(read_only_inputs) > 8 or any(
        not isinstance(path, str) or not path.startswith("/") for path in read_only_inputs
    ):
        raise ContainmentError("containment read-only inputs are invalid")
    runtime_reads = ""
    if read_only_inputs:
        runtime_reads = "\n(allow file-read*\n" + "".join(
            f"  (literal {_scheme_string(path)})\n" for path in read_only_inputs
        ) + ")\n"
    provider_parent_metadata = ""
    if role == ROLE_PROVIDER:
        # Core Foundation needs the executable directory's metadata to build
        # its main bundle and SSL policy. Keep contents and exec helpers denied.
        provider_parent_metadata = f"""
(with-filter (process-path {_scheme_string(target_executable)})
  (allow file-read-metadata file-test-existence
    (literal {_scheme_string(str(Path(target_executable).parent))}))
  ; SQLite resolves every ancestor before opening its private conversation DB.
  (allow file-read-metadata (path-ancestors (param "HOME"))))
"""
    keychain = ""
    if allow_keychain:
        # A fork retains the target image and its exact service authority. An
        # exec normally loses that authority; /usr/bin/security is the sole
        # Keychain-helper exception and inherits every other profile boundary.
        direct_keychain = f"""(with-filter (process-path {_scheme_string(target_executable)})
  (allow mach-lookup
    (global-name "com.apple.SecurityServer")
    (global-name "com.apple.securityd.xpc")
    (global-name "com.apple.securityd.general")
    (global-name "com.apple.trustd")
    (global-name "com.apple.trustd.agent")))
"""
        helper_keychain = f"""(with-filter (process-path {_scheme_string("/usr/bin/security")})
  (allow mach-lookup
    (global-name "com.apple.SecurityServer")
    (global-name "com.apple.securityd.xpc")
    (global-name "com.apple.securityd.general")
    (global-name "com.apple.trustd")
    (global-name "com.apple.trustd.agent"))
  (allow file-read*
    (literal {_scheme_string(cast(str, keychain_path))})))
"""
        keychain = "\n"
        if grant_profile not in {GRANT_PROFILE_A, GRANT_PROFILE_AB}:
            keychain += direct_keychain
        keychain += helper_keychain
    network = ""
    if network_policy == NETWORK_PROVIDER_TLS:
        # Apple's localhost token was qualified against owned IPv4, IPv6, and
        # interface-local listeners. This is a process/port boundary, not a
        # recipient allowlist or proof that the connection uses TLS. For local
        # listeners it also permits wildcard binds; the exact provider image is
        # trusted to request its advertised localhost endpoint.
        network = f"""
(with-filter (process-path {_scheme_string(target_executable)})
  (allow network-outbound
    (require-all (remote tcp "*:443")
      (require-not (remote ip "localhost:*"))))
  (allow network-outbound (literal "/private/var/run/mDNSResponder"))
"""
        if grant_profile not in {GRANT_PROFILE_B, GRANT_PROFILE_AB}:
            network += '  (allow network-bind network-inbound (local tcp "localhost:*"))\n'
        network += """  (allow mach-lookup (global-name "com.apple.mDNSResponder")))
(deny network-outbound (remote ip "localhost:*"))
"""
    provider_settings = ""
    if provider_settings_path is not None:
        # Protect the directory entries as well as the leaf: replacing an
        # ancestor otherwise changes which policy the same pathname names.
        # Literal rules keep mutable logs and state below these parents writable.
        settings = Path(provider_settings_path)
        provider_settings = f"""
(deny file-write*
  (literal (param "HOME"))
  (literal {_scheme_string(str(settings.parent.parent))})
  (literal {_scheme_string(str(settings.parent))}))
(deny file-write*
  (literal {_scheme_string(provider_settings_path)}))
"""
    profile_text = f"""(version 1)
(deny default)
(import "dyld-support.sb")

; Fork/exec is required for ordinary build tools.  Every exec inherits this
; profile.  Darwin implements setsid/setpgid without a process-info-setcontrol
; hook, so explicitly deny those two syscalls while leaving fork available.
(allow syscall*)
(allow mach-bootstrap)
(deny syscall-unix
  (syscall-number SYS_setsid)
  (syscall-number SYS_setpgid))
(allow process-fork)
(allow process-exec
  (literal (param "TARGET"))
  (subpath (param "STAGE"))
  (subpath "/bin")
  (subpath "/usr/bin")
  (subpath "/Library/Developer/CommandLineTools"))
(allow process-info-pidinfo (target self))
(allow sysctl-read)

(allow file-read* file-map-executable
  (literal (param "TARGET"))
  (subpath (param "STAGE"))
  (subpath (param "HOME"))
  (subpath (param "TMPDIR"))
  (subpath "/bin")
  (subpath "/usr/bin")
  (subpath "/usr/lib")
  (subpath "/usr/share")
  (subpath "/System")
  (subpath "/Library/Apple")
  (subpath "/Library/Developer/CommandLineTools")
  (subpath "/private/var/db/timezone")
  (literal "/")
  (literal "/dev/null")
  (literal "/dev/zero")
  (literal "/dev/random")
  (literal "/dev/urandom")
  (literal "/etc/resolv.conf")
  (literal "/private/etc/resolv.conf")
  (literal "/private/var/run/resolv.conf"))
(allow file-read-metadata file-test-existence
  (path-ancestors "/Library/Developer/CommandLineTools")
  (literal "/var")
  (literal "/private/var/select")
  (literal "/private/var/select/developer_dir")
  (literal "/private/var/select/sh"))
(allow file-write-data
  (literal "/dev/null")
  (literal "/dev/zero")
  (subpath "/dev/fd"))
(allow file-read* file-write*
  (subpath (param "STAGE"))
  (subpath (param "HOME"))
  (subpath (param "TMPDIR")))

{runtime_reads}{provider_parent_metadata}{keychain}{network}{provider_settings}"""
    return profile_text.encode("utf-8")


def _bind_target(path: str | Path) -> FileBinding:
    binding = _bind_file(
        path, modes={0o700, 0o750, 0o755}, executable=True,
        require_single_link=False,
    )
    if binding.uid != 0 and binding.nlink != 1:
        raise ContainmentError("user-owned containment target has multiple links")
    return binding


def prepare_contained_launch(
    *,
    role: str,
    network_policy: str,
    job_dir: str | Path,
    attempt: int,
    stage_dir: str | Path,
    target_executable: str | Path,
    target_argv: Sequence[str],
    child_environment: Mapping[str, str],
    allow_keychain: bool = False,
    read_only_inputs: Sequence[str | Path] = (),
    provider_max_cycles: int | None = None,
    provider_write_selectors: Sequence[Mapping[str, str]] = (),
    grant_profile: str = "baseline",
) -> PreparedContainedLaunch:
    """Create and bind one native selected-content launch envelope."""
    require_supported_host()
    if role not in _ROLES:
        raise ContainmentError("containment role is invalid")
    if network_policy not in {NETWORK_DENY_ALL, NETWORK_PROVIDER_TLS}:
        raise ContainmentError("containment network policy is invalid")
    if network_policy == NETWORK_PROVIDER_TLS and role != ROLE_PROVIDER:
        raise ContainmentError("only provider launches may use provider TLS")
    if role != ROLE_PROVIDER and allow_keychain:
        raise ContainmentError("only provider launches may access the keychain")
    _validate_grant_profile(grant_profile, role, network_policy, allow_keychain)
    if allow_keychain and provider_max_cycles is None:
        raise ContainmentError("native provider permission settings are unavailable")
    if not allow_keychain and (
        provider_max_cycles is not None or tuple(provider_write_selectors)
    ):
        raise ContainmentError("containment provider settings are invalid")
    if type(attempt) is not int or not 1 <= attempt <= 999:
        raise ContainmentError("containment attempt is invalid")
    if not target_argv or any(
        not isinstance(value, str) or "\0" in value for value in target_argv
    ):
        raise ContainmentError("containment target argv is invalid")
    if any(
        not isinstance(key, str) or not isinstance(value, str)
        or not key or "=" in key or "\0" in key or "\0" in value
        for key, value in child_environment.items()
    ):
        raise ContainmentError("child environment is invalid")
    job = _canonical_existing(job_dir)
    job_binding = _bind_directory(job)
    stage = _bind_directory(stage_dir)
    if Path(stage.path).parent != Path(job_binding.path):
        raise ContainmentError("scoped stage must be an immediate job child")
    if allow_keychain and Path(stage.path) != Path(job_binding.path) / f"stage-{attempt:03d}":
        raise ContainmentError("native provider permission settings are unavailable")
    launcher = _bind_file(SANDBOX_EXEC, modes={0o755}, executable=True)
    target = _bind_target(target_executable)
    if target_argv[0] != target.path:
        raise ContainmentError("containment target argv does not name the bound executable")
    if len(read_only_inputs) > 8:
        raise ContainmentError("too many containment read-only inputs")
    bound_inputs = tuple(
        _bind_file(
            path, modes={0o400, 0o444, 0o600, 0o644},
            limit=MAX_PROFILE_BYTES,
        )
        for path in read_only_inputs
    )
    if len({item.path for item in bound_inputs}) != len(bound_inputs):
        raise ContainmentError("containment read-only inputs are repeated")
    stem = "provider" if role == ROLE_PROVIDER else "self-verify"
    keychain: KeychainBinding | None = None
    keychain_preferences: FileBinding | None = None
    provider_settings: FileBinding | None = None
    if allow_keychain:
        try:
            assert provider_max_cycles is not None
            selectors = _validate_provider_write_selectors(provider_write_selectors)
            if type(provider_max_cycles) is not int or not attempt <= provider_max_cycles <= 5:
                raise ContainmentError("native provider permission settings are unavailable")
        except ContainmentError as exc:
            raise ContainmentError("native provider permission settings are unavailable") from exc
        try:
            # Before any provider HOME exists: a missing or locked keychain leaves the job untouched.
            keychain = _dedicated_keychain()
        except KeychainUnavailableError:
            raise
        except ContainmentError as exc:
            raise ContainmentError("native provider authentication is unavailable") from exc
    home = _ensure_private_directory(job / f"{stem}-home", existing_ok=True)
    if allow_keychain:
        assert provider_max_cycles is not None
        try:
            keychain_preferences = _prepare_keychain_preferences(
                job, Path(home.path), cast(KeychainBinding, keychain),
            )
        except ContainmentError as exc:
            raise ContainmentError("native provider authentication is unavailable") from exc
        try:
            provider_settings = _prepare_provider_settings(
                job, Path(home.path), provider_max_cycles, selectors,
            )
            # Creating the private preference subtree changes the directory's
            # link count; bind the final provider HOME, not an earlier shape.
            home = _bind_directory(home.path)
        except ContainmentError as exc:
            raise ContainmentError("native provider permission settings are unavailable") from exc
    attempt_tmp = _ensure_private_directory(
        job / f"{stem}-tmp-{attempt:03d}", existing_ok=False,
    )
    profile_payload = render_profile(
        target_executable=target.path,
        role=role,
        network_policy=network_policy,
        allow_keychain=allow_keychain,
        read_only_inputs=tuple(item.path for item in bound_inputs),
        keychain_path=keychain.path if keychain is not None else None,
        provider_settings_path=(
            provider_settings.path if provider_settings is not None else None
        ),
        grant_profile=grant_profile,
    )
    profile_binding = _publish_profile(
        job / f"{stem}-sandbox-{attempt:03d}.sb", profile_payload,
    )
    if role == ROLE_SELF_VERIFY:
        environment = {
            "PATH": "/usr/bin:/bin",
            "LANG": "C",
            "LC_ALL": "C",
            "TERM": "dumb",
            "NO_COLOR": "1",
        }
    else:
        environment = dict(child_environment)
    environment.update({
        "HOME": home.path,
        "TMPDIR": attempt_tmp.path,
        "XDG_CACHE_HOME": str(Path(home.path) / ".cache"),
        "XDG_CONFIG_HOME": str(Path(home.path) / ".config"),
        "XDG_DATA_HOME": str(Path(home.path) / ".local" / "share"),
        "XDG_STATE_HOME": str(Path(home.path) / ".local" / "state"),
    })
    return PreparedContainedLaunch(
        role, network_policy, grant_profile, platform.release(), platform.version(), launcher,
        target, profile_binding, bound_inputs, keychain, keychain_preferences, provider_settings,
        stage, home, attempt_tmp, tuple(target_argv),
        tuple(sorted(environment.items())), bool(allow_keychain),
    )


def confirm_contained_launch(
    prepared: PreparedContainedLaunch,
) -> ConfirmedContainedLaunch:
    """Revalidate every native authority immediately before caller ``Popen``."""
    require_supported_host()
    if (platform.release(), platform.version()) != (
        prepared.darwin_release, prepared.darwin_version,
    ):
        raise ContainmentError("Darwin build changed before scoped launch")
    if _bind_file(prepared.launcher.path, modes={0o755}, executable=True) != prepared.launcher:
        raise ContainmentError("sandbox launcher changed before scoped launch")
    if _bind_file(
        prepared.target.path, modes={0o700, 0o750, 0o755}, executable=True,
        require_single_link=False,
    ) != prepared.target:
        raise ContainmentError("target executable changed before contained launch")
    if _bind_file(
        prepared.profile.path, modes={0o400}, limit=MAX_PROFILE_BYTES,
    ) != prepared.profile:
        raise ContainmentError("sandbox profile changed before scoped launch")
    expected_profile = render_profile(
        target_executable=prepared.target.path,
        role=prepared.role,
        network_policy=prepared.network_policy,
        allow_keychain=prepared.allow_keychain,
        read_only_inputs=tuple(item.path for item in prepared.read_only_inputs),
        keychain_path=prepared.keychain.path if prepared.keychain is not None else None,
        provider_settings_path=(
            prepared.provider_settings.path if prepared.provider_settings is not None else None
        ),
        grant_profile=prepared.grant_profile,
    )
    if hashlib.sha256(expected_profile).hexdigest() != prepared.profile.sha256:
        raise ContainmentError("native grant profile changed before scoped launch")
    if any(
        _bind_file(
            item.path, modes={0o400, 0o444, 0o600, 0o644},
            limit=MAX_PROFILE_BYTES,
        ) != item
        for item in prepared.read_only_inputs
    ):
        raise ContainmentError("containment read-only input changed before launch")
    if prepared.allow_keychain:
        if prepared.keychain is None or prepared.keychain_preferences is None:
            raise ContainmentError("native provider authentication is unavailable")
        if _bind_keychain(prepared.keychain.path) != prepared.keychain:
            raise ContainmentError("native provider authentication is unavailable")
        _require_unlocked(prepared.keychain.path)
        if _bind_file(
            prepared.keychain_preferences.path, modes={0o600}, limit=MAX_PROFILE_BYTES,
        ) != prepared.keychain_preferences:
            raise ContainmentError("native provider authentication is unavailable")
        try:
            if prepared.provider_settings is None or _bind_file(
                prepared.provider_settings.path, modes={0o600}, limit=MAX_PROFILE_BYTES,
            ) != prepared.provider_settings:
                raise ContainmentError("native provider permission settings are unavailable")
        except ContainmentError as exc:
            raise ContainmentError("native provider permission settings are unavailable") from exc
    elif (
        prepared.keychain is not None or prepared.keychain_preferences is not None
        or prepared.provider_settings is not None
    ):
        raise ContainmentError("native provider authentication is unavailable")
    if _bind_directory(prepared.stage.path) != prepared.stage:
        raise ContainmentError("scoped stage changed before launch")
    if _bind_directory(prepared.private_home.path) != prepared.private_home:
        raise ContainmentError("private HOME changed before launch")
    if _bind_directory(prepared.attempt_tmp.path) != prepared.attempt_tmp:
        raise ContainmentError("private provider TMPDIR changed before launch")
    argv = (
        prepared.launcher.path,
        "-f", prepared.profile.path,
        "-D", f"TARGET={prepared.target.path}",
        "-D", f"STAGE={prepared.stage.path}",
        "-D", f"HOME={prepared.private_home.path}",
        "-D", f"TMPDIR={prepared.attempt_tmp.path}",
        prepared.target.path,
        *prepared.target_argv[1:],
    )
    return ConfirmedContainedLaunch(
        argv, prepared.launcher.path, prepared.stage.path,
        dict(prepared.environment),
    )


def _libproc() -> ctypes.CDLL:
    require_supported_host()
    library = ctypes.CDLL("/usr/lib/libproc.dylib", use_errno=True)
    library.proc_pidinfo.argtypes = [
        ctypes.c_int, ctypes.c_int, ctypes.c_uint64,
        ctypes.c_void_p, ctypes.c_int,
    ]
    library.proc_pidinfo.restype = ctypes.c_int
    library.proc_listpgrppids.argtypes = [ctypes.c_int, ctypes.c_void_p, ctypes.c_int]
    library.proc_listpgrppids.restype = ctypes.c_int
    return library


def capture_process_identity(pid: int) -> ProcessIdentity:
    """Bind a Darwin PID to kernel start time, owner, group, and session."""
    if type(pid) is not int or pid <= 1:
        raise ContainmentError("provider PID is invalid")
    info = _ProcBsdInfo()
    library = _libproc()
    size = library.proc_pidinfo(
        pid, _PROC_PIDTBSDINFO, 0, ctypes.byref(info), ctypes.sizeof(info),
    )
    if size != ctypes.sizeof(info) or int(info.pbi_pid) != pid:
        raise ContainmentError("provider process identity is unavailable")
    try:
        session_id = os.getsid(pid)
    except OSError as exc:
        raise ContainmentError("provider process session is unavailable") from exc
    return ProcessIdentity(
        pid, int(info.pbi_ppid), int(info.pbi_pgid), session_id,
        int(info.pbi_uid), int(info.pbi_start_tvsec), int(info.pbi_start_tvusec),
    )


def bind_new_process_group(pid: int) -> ProcessIdentity:
    """Bind the session leader created by ``Popen(start_new_session=True)``."""
    identity = capture_process_identity(pid)
    if (
        identity.uid != os.getuid()
        or identity.process_group != pid
        or identity.session_id != pid
    ):
        raise ContainmentError("provider process is not a new bound session leader")
    return identity


def _process_group_members(process_group: int) -> tuple[int, ...]:
    library = _libproc()
    capacity = 64
    while capacity <= MAX_GROUP_MEMBERS:
        values = (ctypes.c_int * capacity)()
        size = library.proc_listpgrppids(
            process_group, ctypes.byref(values), ctypes.sizeof(values),
        )
        if size < 0:
            raise ContainmentError("provider process group is unavailable")
        # Unlike proc_pidinfo(), proc_listpgrppids() returns a PID count.
        count = size
        if count < capacity:
            return tuple(sorted({int(values[index]) for index in range(count) if values[index] > 1}))
        capacity *= 2
    raise ContainmentError("provider process group exceeds the cleanup bound")


def _bind_group_members(root: ProcessIdentity) -> tuple[ProcessIdentity, ...]:
    # A member may exit after proc_listpgrppids() reports it but before its
    # identity is queried. Re-list that race; never treat an unbound PID as a
    # group member and never signal until one complete pass is stable.
    for _attempt in range(32):
        members: list[ProcessIdentity] = []
        retry = False
        for pid in _process_group_members(root.process_group):
            try:
                current = capture_process_identity(pid)
            except ContainmentError:
                retry = True
                break
            if (
                current.uid != root.uid
                or current.process_group != root.process_group
                or current.session_id != root.session_id
                or (current.start_seconds, current.start_microseconds)
                < (root.start_seconds, root.start_microseconds)
            ):
                raise ContainmentError("contained process group identity drifted")
            members.append(current)
        if retry:
            time.sleep(0.005)
            continue
        live_root = next((item for item in members if item.pid == root.pid), None)
        if live_root is not None and live_root != root:
            raise ContainmentError("contained root PID was reused")
        return tuple(members)
    raise ContainmentError("contained process group changed during binding")


def process_group_is_quiescent(root: ProcessIdentity) -> bool:
    """Return true when the bound group is empty, without a lineage claim.

    A child can create another session through posix_spawn attributes even
    though direct setsid/setpgid syscalls are denied. Such a child retains this
    Seatbelt profile but is outside this process-group cleanup primitive.
    """
    return not _bind_group_members(root)


def terminate_bound_process_group(
    root: ProcessIdentity, number: int = signal.SIGKILL,
) -> tuple[ProcessIdentity, ...]:
    """Signal only members of the exact new session rooted at ``root``.

    Direct ``setsid`` and ``setpgid`` syscalls are denied, but posix_spawn
    session/group attributes are a confirmed bypass. This function covers only
    processes still in the bound group. It binds and re-checks every current
    member before ``killpg``; a PID-reused or unrelated group is rejected
    instead of signalled. Escaped descendants retain filesystem/network
    containment but are outside this cleanup primitive.
    """
    if number not in {signal.SIGTERM, signal.SIGKILL}:
        raise ContainmentError("cleanup signal is invalid")
    members = _bind_group_members(root)
    if not members:
        return ()
    # A surviving member with the bound session ID proves this is still the
    # original session even if its leader has already exited.
    for item in members:
        if capture_process_identity(item.pid) != item:
            raise ContainmentError("provider process changed before cleanup")
    try:
        os.killpg(root.process_group, number)
    except ProcessLookupError:
        return ()
    except OSError as exc:
        raise ContainmentError("provider process-group cleanup failed") from exc
    return members


def write_login_preferences(home: Path) -> None:
    """Point an empty private HOME at the dedicated Keychain for the one-time sign-in."""
    keychain = _dedicated_keychain()
    preferences = home / "Library" / "Preferences"
    _ensure_private_directory(home / "Library", existing_ok=True)
    _ensure_private_directory(preferences, existing_ok=True)
    _publish_private_file(
        preferences / "com.apple.security.plist",
        _default_keychain_preferences_payload(keychain),
    )


def main(argv: Sequence[str]) -> int:
    """Shell entry: ``keychain-preflight`` or ``keychain-login-home PRIVATE_HOME``."""
    try:
        require_supported_host()
        if list(argv) == ["keychain-preflight"]:
            _dedicated_keychain()
        elif len(argv) == 2 and argv[0] == "keychain-login-home":
            write_login_preferences(Path(argv[1]))
        else:
            print("usage: keychain-preflight | keychain-login-home PRIVATE_HOME", file=sys.stderr)
            return 64
    except ContainmentError as exc:
        print(f"agy-worker: {exc}", file=sys.stderr)
        return EXIT_NATIVE_HOST_UNAVAILABLE
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall