Skip to content

richfrem/agent-plugins-skills / plugins/agent-agentic-os/.apm/skills/running-control-plane

running-control-plane

Flagged

CRITICAL INTAKE GATEWAY: use at the start of any non-trivial engineering task, feature, refactor, multi-file bugfix, work package or new idea, including requests to explore, brainstorm, build, fix or change something, before planning or code changes. Enforces read-only discovery, 1-3 structured questions with defaults, control-plane registration and the immutable four-pillar TASK_SPEC.md. Also runs the rest of the control plane: health ("run health check", "check os metrics", "system monitor", event bus, locks, memory, "is my signing identity ready" status check), transition simulation ("dry run transition", "simulate transition", "check edge X -> Y"), worktree selection, and gating on/off ("disable the control plane", "turn off the push guard", "stop gating my commits"). Not for project setup or key creation (use setting-up-agentic-os) or improving skills (use improving-skills-in-lab).

FileKindSize
SKILL.mdskill md5.4 KB
evals/evals.jsonconfig8.3 KB
references/acceptance-criteria.mdmarkdown4.0 KB
references/agentic-os-skill-map.mdmarkdown2.3 KB
references/architecture/architecture.mdmarkdown2.4 KB
references/architecture/context-folder-patterns.mdmarkdown3.3 KB
references/architecture/vision.mdmarkdown56.6 KB
references/cheap-agent-transition-simulation.mdmarkdown6.1 KB
references/control-plane-architecture.mdmarkdown9.0 KB
references/control-plane-rebuild-recovery.mdmarkdown6.2 KB
references/control-plane-simulation-protocol.mdmarkdown5.7 KB
references/diagrams/agentic-os-memory-subsystem.mmdother1.4 KB
references/diagrams/architecture-overview.mmdother3.1 KB
references/diagrams/control-plane-architecture.mermaidother6.3 KB
references/diagrams/control-plane-lifecycle-hardened-with-ciba-rar.mermaidother4.5 KB
references/diagrams/control-plane-pipeline-happy-path.mermaidother5.0 KB
references/diagrams/control-plane-pipeline.mermaidother9.3 KB
references/diagrams/event-bus-architecture.mmdother2.4 KB
references/diagrams/increment-b-human-only-transition-ssh-signing.mermaidother5.3 KB
references/edge-matrix.mdmarkdown13.3 KB
references/fallback-tree.mdmarkdown2.9 KB
references/health-detailed-reference.mdmarkdown7.1 KB
references/healthy-transcript.mdmarkdown3.8 KB
references/implementation-ledger-contract.mdmarkdown851 B
references/intake-detailed-reference.mdmarkdown3.1 KB
references/modes/health.mdmarkdown3.4 KB
references/modes/intake.mdmarkdown3.8 KB
references/modes/mode.mdmarkdown5.8 KB
references/modes/simulator.mdmarkdown6.2 KB
references/modes/worktree.mdmarkdown2.9 KB
references/multi-round-external-review-protocol.mdmarkdown2.6 KB
references/worktree-reconciliation-and-multi-worktree-practices.mdmarkdown5.8 KB
requirements-dev.inother741 B
requirements-dev.txtmarkdown603 B
requirements.inother196 B
requirements.txtmanifest202 B
scripts/agent_control.pyscript97.7 KB
scripts/audit_map_debt.pyscript6.1 KB
scripts/capability_probe.pyscript6.4 KB
scripts/check_plan_links.pyscript1.8 KB
scripts/control_plane/__init__.pyscript842 B
scripts/control_plane/adapters.pyscript144.9 KB
scripts/control_plane/approver_policy.pyscript20.0 KB
scripts/control_plane/baseline_transition_report.pyscript4.0 KB
scripts/control_plane/constants.pyscript13.5 KB
scripts/control_plane/coordinator.pyscript57.3 KB
scripts/control_plane/edge_matrix.pyscript3.1 KB
scripts/control_plane/gate1_approval.pyscript10.7 KB
scripts/control_plane/gate_evidence.pyscript9.9 KB
scripts/control_plane/identity_layout.pyscript2.9 KB
scripts/control_plane/identity_setup.pyscript11.0 KB
scripts/control_plane/implementation.pyscript3.7 KB
scripts/control_plane/implementation_loop.pyscript11.3 KB
scripts/control_plane/inspection.pyscript3.9 KB
scripts/control_plane/installation_probe.pyscript5.7 KB
scripts/control_plane/isolation_check.pyscript14.0 KB
scripts/control_plane/measurement.pyscript39.1 KB
scripts/control_plane/pipeline_simulator.pyscript30.0 KB
scripts/control_plane/policy.pyscript32.5 KB
scripts/control_plane/ports.pyscript20.3 KB
scripts/control_plane/proof_edges.pyscript4.6 KB
scripts/control_plane/proof_policy.pyscript2.2 KB
scripts/control_plane/receipt_provenance.pyscript4.7 KB
scripts/control_plane/registry.pyscript32.9 KB
scripts/control_plane/review_options.pyscript8.2 KB
scripts/control_plane/review_selection.pyscript3.2 KB
scripts/control_plane/run_transition_simulation.pyscript12.0 KB
scripts/control_plane/signing_selftest.pyscript6.8 KB
scripts/control_plane/simulation_identity.pyscript10.4 KB
scripts/control_plane/snapshot.pyscript10.8 KB
scripts/control_plane/ssh_signing.pyscript21.8 KB
scripts/control_plane/state_machine.pyscript5.8 KB
scripts/control_plane/transition_request.pyscript19.5 KB
scripts/control_plane/transition_simulation_cases.pyscript24.6 KB
scripts/control_plane/transition_templates.yamlconfig159.1 KB
scripts/control_plane/tty_signer.pyscript3.0 KB
scripts/control_plane/wrappers/__init__.pyscript24 B
scripts/control_plane/wrappers/record_interview_question.pyscript8.0 KB
scripts/control_plane/wrappers/record_retrospective.pyscript2.3 KB
scripts/control_plane/wrappers/run_exit_verification.pyscript6.4 KB
scripts/control_plane/wrappers/run_verify_exit_bundle.pyscript5.4 KB
scripts/control_plane/wrappers/write_plan_document.pyscript9.6 KB
scripts/control_plane_hooks.pyscript10.5 KB
scripts/control_plane_mode.pyscript12.0 KB
scripts/distill_playbook.pyexecutablescript9.9 KB
scripts/evolution_state.pyscript29.4 KB
scripts/export_upstream_pr.pyscript4.4 KB
scripts/interview_spec_engine.pyscript9.1 KB
scripts/kernel.pyscript14.6 KB
scripts/pre-commit-evolution-guardexecutablescript3.7 KB
scripts/pre-commit-pipeline-guardexecutablescript13.6 KB
scripts/pre-push-review-guardexecutablescript10.5 KB
scripts/record_trace.pyscript7.2 KB
scripts/smoke_test.pyexecutablescript22.6 KB
scripts/test_capability_probe.pyscript3.9 KB
scripts/test_worktree_manager.pyscript2.8 KB
scripts/verify_evolution_receipt.pyscript7.5 KB
scripts/verify_gate_evidence.pyscript1.6 KB
scripts/worktree_manager.pyscript3.0 KB
tests/conftest.pyscript7.7 KB
tests/helpers/__init__.pyscript0 B
tests/helpers/control_plane_fixtures.pyscript2.6 KB
tests/helpers/control_plane_repo.pyscript4.0 KB
tests/helpers/gate1_fixtures.pyscript5.8 KB
tests/helpers/human_signer.pyscript7.3 KB
tests/helpers/implementation_ledger.pyscript1.1 KB
tests/interview_helpers.pyscript5.2 KB
tests/test_actionable_rollback.pyscript2.2 KB
tests/test_agent_control.pyscript190.6 KB
tests/test_agent_control_gate_characterization.pyscript14.7 KB
tests/test_approve_transition.pyscript10.5 KB
tests/test_approver_identity_guidance.pyscript3.4 KB
tests/test_approver_isolation.pyscript12.3 KB
tests/test_audit_map_debt.pyscript4.7 KB
tests/test_authorized_actor_enforcement.pyscript22.9 KB
tests/test_background_document_priority.pyscript924 B
tests/test_check_plan_links.pyscript1.1 KB
tests/test_content_snapshot.pyscript11.8 KB
tests/test_control_plane_architecture_diagram_contract.pyscript9.0 KB
tests/test_control_plane_architecture_overview_contract.pyscript2.1 KB
tests/test_control_plane_critic_review.pyscript3.1 KB
tests/test_control_plane_crypto_adapter.pyscript5.0 KB
tests/test_control_plane_delegation_contract.pyscript5.7 KB
tests/test_control_plane_facade_composition.pyscript15.9 KB
tests/test_control_plane_filesystem_adapter.pyscript4.9 KB
tests/test_control_plane_hooks.pyscript7.3 KB
tests/test_control_plane_interview_guidance.pyscript3.8 KB
tests/test_control_plane_measurement_contract.pyscript28.0 KB
tests/test_control_plane_mode.pyscript7.5 KB
tests/test_control_plane_mode_guards.pyscript3.5 KB
tests/test_control_plane_model_catalog_adapter.pyscript9.2 KB
tests/test_control_plane_pipeline_diagram_contract.pyscript2.3 KB
tests/test_control_plane_pipeline_simulator.pyscript7.5 KB
tests/test_control_plane_policy.pyscript13.0 KB
tests/test_control_plane_ports.pyscript3.2 KB
tests/test_control_plane_reset_transition.pyscript13.6 KB
tests/test_control_plane_schema_rebuild_atomicity.pyscript20.0 KB
tests/test_control_plane_simulation_protocol_contract.pyscript959 B
tests/test_control_plane_sqlite_persistence_adapter.pyscript5.5 KB
tests/test_control_plane_state_machine.pyscript15.2 KB
tests/test_control_plane_trigger_enforcement.pyscript14.6 KB
tests/test_control_plane_worktree_sharing.pyscript4.5 KB
tests/test_domain_namespaces.pyscript6.7 KB
tests/test_done_closure_proof.pyscript6.9 KB
tests/test_draft_plan_interactive_outline_gap.pyscript2.2 KB
tests/test_dual_identity_onboarding.pyscript7.3 KB
tests/test_edge_matrix.pyscript3.2 KB
tests/test_ensure_schema_fastpath.pyscript4.4 KB
tests/test_evolution_guards.pyscript14.9 KB
tests/test_evolution_scripts.pyscript55.3 KB
tests/test_gate1_guidance.pyscript1.8 KB
tests/test_gate3_code_acceptance.pyscript13.5 KB
tests/test_graph_state_machine.pyscript16.0 KB
tests/test_guidance_readiness.pyscript2.2 KB
tests/test_health_check_signing_status.pyscript3.5 KB
tests/test_human_decision_trigger_enforcement.pyscript37.3 KB
tests/test_human_only_wiring.pyscript22.3 KB
tests/test_human_signer_isolation.pyscript4.0 KB
tests/test_identity_verification_readiness.pyscript5.8 KB
tests/test_implementation_ledger.pyscript3.4 KB
tests/test_implementation_loop.pyscript6.9 KB
tests/test_implementation_runtime_bridge.pyscript2.6 KB
tests/test_init_agentic_os_scaffolding.pyscript10.0 KB
tests/test_init_respects_control_plane_mode.pyscript4.3 KB
tests/test_inspect_verbs.pyscript3.6 KB
tests/test_installation_probe.pyscript3.1 KB
tests/test_intake_scenarios.pyscript7.2 KB
tests/test_interview_plan_outline.pyscript2.8 KB
tests/test_isolation_check.pyscript12.5 KB
tests/test_isolation_setup_docs.pyscript2.7 KB
tests/test_kernel_security.pyscript4.0 KB
tests/test_legacy_input_fallback.pyscript6.0 KB
tests/test_list_review_options.pyscript3.1 KB
tests/test_multi_agent_bundle_gate.pyscript5.5 KB
tests/test_one_approver_per_pipeline.pyscript15.8 KB
tests/test_os_init_dual_identity.pyscript3.9 KB
tests/test_os_init_identity_bootstrap.pyscript8.8 KB
tests/test_os_init_identity_status.pyscript3.9 KB
tests/test_os_init_single_instruction_file.pyscript7.3 KB
tests/test_p00_live_baseline.pyscript10.2 KB
tests/test_p01_intake_persistence.pyscript6.7 KB
tests/test_post_run_metrics_protocol.pyscript3.3 KB
tests/test_pre_commit_pipeline_guard.pyscript29.1 KB
tests/test_pre_push_review_guard.pyscript5.7 KB
tests/test_receipt_provenance.pyscript6.6 KB
tests/test_retrospective_pipeline.pyscript5.3 KB
tests/test_review_option_menus.pyscript6.6 KB
tests/test_review_selection.pyscript8.2 KB
tests/test_round3_fixes.pyscript8.3 KB
tests/test_rules_compliance.pyscript1.3 KB
tests/test_run_transition_simulation_formatting.pyscript1.7 KB
tests/test_run_verify_exit_bundle.pyscript10.2 KB
tests/test_setup_ciba_identity.pyscript11.2 KB
tests/test_signed_approval_human_receipt.pyscript3.9 KB
tests/test_signing_mechanics_selftest.pyscript6.9 KB
tests/test_signing_skill_selfcontained.pyscript3.4 KB
tests/test_skip_receipt_guidance.pyscript2.7 KB
tests/test_ssh_signing.pyscript23.9 KB
tests/test_strategy_artifacts.pyscript21.8 KB
tests/test_transition_answer_normalization.pyscript1.1 KB

scripts/control_plane/isolation_check.py

View on GitHub
#!/usr/bin/env python3
"""
control_plane/isolation_check.py
================================

Purpose:
    Fail-closed isolation preflight for Gate 1 (AWAITING_APPROVAL -> APPROVED) of
    auth-ciba-increment-b (issue #639, task T1). Human decision D4: the security
    boundary is that the trust anchors and signing material are human-owned and
    agent-inaccessible: `allowed_signers`, `allowed_signers_selftest`, the private
    signing keys, and the challenge directory. The SQLite control-plane DB is
    deliberately NOT checked; the agent must keep writing it for ordinary
    transitions (residual risk documented in the spec).

    All evidence comes from `lstat`/`fstat` and uids, never from an environment
    variable or a config string: the agent controls its own environment but cannot
    `chown`. Symlinks are rejected at every path component, every ancestor
    directory is checked for agent write access, and `open_protected_readonly`
    gives callers a file descriptor that is verified once (`O_NOFOLLOW` + `fstat`)
    and can be held across a transaction.

Key Input Dependencies:
    - Python stdlib only (os, stat, pwd, grp, dataclasses)
    - The paths of allowed_signers, allowed_signers_selftest, the challenge
      directory and optional private key files (supplied by the caller)
    - The configured agent identity (default `agentic-os-local-agent`), injectable
      for tests: name, uid and gids

Key Functions:
    - check_isolation() -- run the whole preflight; returns an IsolationResult that
      lists EVERY failure (never stops at the first).
    - open_protected_readonly() -- open a file `O_NOFOLLOW`, verify owner/mode from
      the descriptor, return the fd.
    - _check_chain() -- walk a path from `/`, rejecting symlinks and agent-writable
      ancestor directories.
    - _check_file(), _check_dir() -- final-component checks (type, owner, mode).
    - _resolve_agent_identity() -- uid/gids from injected values or from pwd/grp.
    - _agent_can_write_dir() -- whether the agent identity can modify a directory.

Failure codes:
    IDENTITY_UNRESOLVED, EUID_IS_AGENT, SSH_AUTH_SOCK_SET, PATH_MISSING,
    SYMLINK_COMPONENT, NOT_REGULAR_FILE, NOT_DIRECTORY, NOT_OWNED_BY_HUMAN,
    OWNED_BY_AGENT, BAD_MODE, ANCESTOR_AGENT_WRITABLE, CHALLENGE_DIR_HAS_SYMLINK

Usage:
    result = check_isolation(allowed_signers=..., allowed_signers_selftest=...,
                             challenge_dir=..., key_paths=[...])
    if not result.ok:
        for f in result.failures: print(f.code, f.path, f.message)
"""

import errno
import os
import stat
import sys
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Dict, Iterable, List, Mapping, Optional, Set, Tuple, Union

try:  # pwd/grp are POSIX-only; Windows resolves identity differently (documented)
    import grp
    import pwd
except ImportError:  # pragma: no cover
    grp = None  # type: ignore[assignment]
    pwd = None  # type: ignore[assignment]

DEFAULT_AGENT_NAME = "agentic-os-local-agent"
SSH_AUTH_SOCK = "SSH_AUTH_SOCK"
SIGNERS_MODE = 0o600
CHALLENGE_DIR_MODE = 0o700

PathLike = Union[str, "os.PathLike[str]"]


class IsolationError(Exception):
    """Raised by open_protected_readonly() when a file fails verification."""


@dataclass(frozen=True)
class IsolationFailure:
    """One failed isolation check."""

    code: str
    path: Optional[str]
    message: str


@dataclass(frozen=True)
class IsolationResult:
    """Outcome of the preflight. `ok` is True only when `failures` is empty."""

    ok: bool
    failures: Tuple[IsolationFailure, ...]
    evidence: Dict[str, Any] = field(default_factory=dict)


# External comment: resolve the agent's uid and gids (injected values win; otherwise pwd/grp).
def _resolve_agent_identity(
    agent_name: str, agent_uid: Optional[int], agent_gids: Optional[Set[int]]
) -> Tuple[Optional[int], Set[int]]:
    """Return (uid or None when unresolvable, gids). Never guesses a uid."""
    gids: Set[int] = set(agent_gids) if agent_gids is not None else set()
    uid = agent_uid
    if pwd is not None and uid is None:
        try:
            entry = pwd.getpwnam(agent_name)
            uid = entry.pw_uid
            if agent_gids is None:
                gids.add(entry.pw_gid)
        except KeyError:
            uid = None
    if agent_gids is None and pwd is not None and grp is not None and uid is not None:
        try:
            entry = pwd.getpwuid(uid)
            gids.add(entry.pw_gid)
            gids.update(g.gr_gid for g in grp.getgrall() if entry.pw_name in g.gr_mem)
        except KeyError:
            pass
    return uid, gids


# External comment: can the agent identity modify entries of this directory?
def _agent_can_write_dir(st: os.stat_result, agent_uid: int, agent_gids: Set[int]) -> bool:
    """True if the agent owns the directory or has group/other write access.

    An other-writable directory with the sticky bit is not counted: sticky stops
    non-owners from renaming or deleting entries they do not own."""
    mode = stat.S_IMODE(st.st_mode)
    if st.st_uid == agent_uid:
        return True
    if mode & 0o020 and st.st_gid in agent_gids:
        return True
    if mode & 0o002 and not mode & stat.S_ISVTX:
        return True
    return False


# External comment: walk `/` down to the path; reject symlinks and agent-writable ancestors.
def _check_chain(
    path: Path, agent_uid: Optional[int], agent_gids: Set[int], failures: List[IsolationFailure]
) -> Optional[os.stat_result]:
    """Return lstat of the final component, or None when it cannot be inspected.

    Appends PATH_MISSING / SYMLINK_COMPONENT / ANCESTOR_AGENT_WRITABLE failures."""
    absolute = Path(os.path.abspath(path))
    parts = absolute.parts
    current = Path(parts[0])
    final_stat: Optional[os.stat_result] = None
    for index, part in enumerate(parts[1:], start=1):
        current = current / part
        last = index == len(parts) - 1
        try:
            st = os.lstat(current)
        except FileNotFoundError:
            failures.append(IsolationFailure("PATH_MISSING", str(absolute), f"{current} does not exist"))
            return None
        except OSError as exc:
            failures.append(IsolationFailure("PATH_MISSING", str(absolute), f"cannot lstat {current}: {exc}"))
            return None
        if stat.S_ISLNK(st.st_mode):
            failures.append(
                IsolationFailure("SYMLINK_COMPONENT", str(absolute), f"{current} is a symlink; pass the real path")
            )
            return None
        if last:
            final_stat = st
        elif stat.S_ISDIR(st.st_mode) and agent_uid is not None:
            if _agent_can_write_dir(st, agent_uid, agent_gids):
                failures.append(
                    IsolationFailure(
                        "ANCESTOR_AGENT_WRITABLE", str(absolute), f"ancestor {current} is writable by the agent identity"
                    )
                )
    return final_stat


# External comment: owner checks shared by every protected artifact.
def _check_owner(
    st: os.stat_result, path: Path, euid: int, agent_uid: Optional[int], failures: List[IsolationFailure]
) -> None:
    if not hasattr(os, "geteuid") and sys.platform.startswith("win"):
        # On Windows, st.st_uid is dummy (0) and POSIX ownership does not apply
        return
    if st.st_uid != euid:
        failures.append(
            IsolationFailure("NOT_OWNED_BY_HUMAN", str(path), f"owner uid {st.st_uid} is not the human uid {euid}")
        )
    if agent_uid is not None and st.st_uid == agent_uid:
        failures.append(IsolationFailure("OWNED_BY_AGENT", str(path), "owned by the agent uid"))


# External comment: regular file, human-owned, and the required mode (exact or no group/other bits).
def _check_file(
    path: Path,
    euid: int,
    agent_uid: Optional[int],
    agent_gids: Set[int],
    exact_mode: Optional[int],
    failures: List[IsolationFailure],
) -> None:
    st = _check_chain(path, agent_uid, agent_gids, failures)
    if st is None:
        return
    if not stat.S_ISREG(st.st_mode):
        failures.append(IsolationFailure("NOT_REGULAR_FILE", str(path), "not a regular file"))
        return
    _check_owner(st, path, euid, agent_uid, failures)
    mode = stat.S_IMODE(st.st_mode)
    if exact_mode is not None and mode != exact_mode:
        failures.append(IsolationFailure("BAD_MODE", str(path), f"mode {mode:04o}, required {exact_mode:04o}"))
    elif exact_mode is None and mode & 0o077:
        failures.append(IsolationFailure("BAD_MODE", str(path), f"mode {mode:04o} grants group/other access"))


# External comment: challenge directory: human-owned 0700, a real directory, no symlink entries.
def _check_dir(
    path: Path, euid: int, agent_uid: Optional[int], agent_gids: Set[int], failures: List[IsolationFailure]
) -> None:
    st = _check_chain(path, agent_uid, agent_gids, failures)
    if st is None:
        return
    if not stat.S_ISDIR(st.st_mode):
        failures.append(IsolationFailure("NOT_DIRECTORY", str(path), "not a directory"))
        return
    _check_owner(st, path, euid, agent_uid, failures)
    mode = stat.S_IMODE(st.st_mode)
    if mode != CHALLENGE_DIR_MODE:
        failures.append(IsolationFailure("BAD_MODE", str(path), f"mode {mode:04o}, required {CHALLENGE_DIR_MODE:04o}"))
    try:
        with os.scandir(path) as entries:
            for entry in entries:
                if entry.is_symlink():
                    failures.append(
                        IsolationFailure("CHALLENGE_DIR_HAS_SYMLINK", str(path), f"{entry.name} is a symlink")
                    )
    except OSError as exc:
        failures.append(IsolationFailure("PATH_MISSING", str(path), f"cannot list challenge dir: {exc}"))


def check_isolation(
    *,
    allowed_signers: PathLike,
    allowed_signers_selftest: PathLike,
    challenge_dir: PathLike,
    key_paths: Iterable[PathLike] = (),
    agent_name: str = DEFAULT_AGENT_NAME,
    agent_uid: Optional[int] = None,
    agent_gids: Optional[Set[int]] = None,
    euid: Optional[int] = None,
    environ: Optional[Mapping[str, str]] = None,
) -> IsolationResult:
    """Run the fail-closed preflight for the process that verifies/commits Gate 1.

    Fails closed on: an unresolvable agent identity, euid equal to the agent uid,
    `SSH_AUTH_SOCK` present, and any of the protected artifacts failing its
    ownership/mode/symlink/ancestor checks. The DB is intentionally not inspected.
    Every failure is reported. Container/sandbox markers are evidence only."""
    failures: List[IsolationFailure] = []
    if sys.platform.startswith("win") and euid is None:
        failures.append(
            IsolationFailure(
                "WINDOWS_ISOLATION_UNSUPPORTED",
                None,
                "Windows: account and folder-permission isolation is not auto-detected; follow references/isolation-setup.md",
            )
        )
    human_uid = (os.geteuid() if hasattr(os, "geteuid") else 0) if euid is None else euid
    env = os.environ if environ is None else environ

    resolved_uid, gids = _resolve_agent_identity(agent_name, agent_uid, agent_gids)
    if resolved_uid is None:
        if not sys.platform.startswith("win"):
            failures.append(
                IsolationFailure(
                    "IDENTITY_UNRESOLVED",
                    None,
                    f"cannot resolve agent account '{agent_name}'; create it per references/isolation-setup.md",
                )
            )
    elif human_uid == resolved_uid:
        failures.append(
            IsolationFailure("EUID_IS_AGENT", None, "the verifying process runs as the agent uid")
        )
    if SSH_AUTH_SOCK in env:
        failures.append(
            IsolationFailure("SSH_AUTH_SOCK_SET", None, "SSH_AUTH_SOCK is set in the verifying process")
        )

    for signers in (Path(allowed_signers), Path(allowed_signers_selftest)):
        _check_file(signers, human_uid, resolved_uid, gids, SIGNERS_MODE, failures)
    _check_dir(Path(challenge_dir), human_uid, resolved_uid, gids, failures)
    for key in key_paths:
        _check_file(Path(key), human_uid, resolved_uid, gids, None, failures)

    evidence = {
        "agent_name": agent_name,
        "agent_uid": resolved_uid,
        "euid": human_uid,
        "markers": {"dockerenv": os.path.exists("/.dockerenv"), "container_env": "container" in env},
    }
    return IsolationResult(ok=not failures, failures=tuple(failures), evidence=evidence)


def open_protected_readonly(
    path: PathLike,
    *,
    expected_mode: Optional[int] = None,
    expected_uid: Optional[int] = None,
    forbidden_mode_bits: int = 0,
) -> int:
    """Open `path` read-only with O_NOFOLLOW and verify it from the descriptor.

    Returns the fd (the caller closes it and may hold it across a transaction).
    Raises IsolationError for a symlink, a non-regular file, a wrong owner, a wrong
    mode, or any mode bit in `forbidden_mode_bits` (e.g. 0o022 for group/other write). Verification uses fstat on the opened descriptor, so a swap after
    the check cannot change what was verified."""
    uid = (os.geteuid() if hasattr(os, "geteuid") else 0) if expected_uid is None else expected_uid
    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_CLOEXEC", 0)
    try:
        fd = os.open(path, flags)
    except OSError as exc:
        reason = "is a symlink" if exc.errno in (errno.ELOOP, errno.EMLINK) else f"cannot be opened: {exc}"
        raise IsolationError(f"{path} {reason}") from exc
    try:
        st = os.fstat(fd)
        if not stat.S_ISREG(st.st_mode):
            raise IsolationError(f"{path} is not a regular file")
        if (hasattr(os, "geteuid") or expected_uid is not None) and st.st_uid != uid:
            raise IsolationError(f"{path} owner uid {st.st_uid} is not the expected uid {uid}")
        mode = stat.S_IMODE(st.st_mode)
        if not sys.platform.startswith("win"):
            if expected_mode is not None and mode != expected_mode:
                raise IsolationError(f"{path} mode {mode:04o}, required {expected_mode:04o}")
            if mode & forbidden_mode_bits:
                raise IsolationError(f"{path} mode {mode:04o} has forbidden bits {forbidden_mode_bits:04o}")
    except IsolationError:
        os.close(fd)
        raise
    return fd
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: 471kUpdated Claude CodeCodexUnverifiedInstall
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