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/simulation_identity.py

View on GitHub
"""
control_plane/simulation_identity.py
====================================

Purpose:
    The agent's simulation identity, kept apart from the human's production identity. Real work
    is approved only with the human's key, enrolled in <repo>/context/identity/allowed_signers
    (set up by the human with setup_ciba_identity.py). Simulations run in
    <repo>/context/simulation/simulation_control_plane.db and are approved only with the agent's
    simulation key, which lives in its own folder and trust file:
        <repo>/context/simulation/identity/simulation_key(.pub)
        <repo>/context/simulation/identity/allowed_signers(_selftest)
    The agent may create and use this identity (it is the agent's own key, passphrase-less by
    design). Creating it never writes the human's production trust file; reruns reuse the key and
    only ever add enrollment lines. A key registered here is refused on real work even if someone
    relabels it as a human in the production trust file (approver_policy).

    Also reports readiness for the three parts of the setup separately (human approval,
    simulation, isolation of the agent from the human's trust files), on macOS, Linux and Windows.

Key Input Dependencies:
    - ssh-keygen (OpenSSH 8.1+) to generate the simulation key
    - control_plane.identity_layout, identity_setup (human status, per-OS account commands), isolation_check
    - control_plane.gate1_approval (show_challenge / approve_transition, used by SimulationSigner)

Key Functions:
    - simulation_root() / simulation_db_path() / simulation_layout() -- where simulations and their identity live
    - ensure_identity_at() / ensure_simulation_identity() -- create or reuse the simulation key and enroll it additively
    - simulation_key_fingerprints() -- fingerprints registered as simulation keys for a repository
    - dual_identity_status() -- human / simulation / isolation readiness, reported separately
    - SimulationSigner -- signs a simulation database's gates with the simulation key

Usage:
    from control_plane.simulation_identity import ensure_simulation_identity, simulation_db_path
    PipelineSimulator(simulation_db_path(repo)).run_standard_happy_path(task)  # signs with the simulation key
"""

import os
import subprocess
import sys
from pathlib import Path
from typing import Any, Dict, Set

from control_plane.approver_policy import AGENT_SIMULATION_PRINCIPAL, SIMULATION_DB_NAME, enrolled_keys, key_fingerprint
from control_plane.identity_layout import IdentityLayout, default_layout
from control_plane.ssh_signing import SELFTEST_NAMESPACE, SIGN_NAMESPACE

SIMULATION_KEY_NAME = "simulation_key"


# <repo>/context/simulation: simulations never share a file with real work
def simulation_root(repo_root: Any) -> Path:
    """Return <repo>/context/simulation."""
    return Path(repo_root) / "context" / "simulation"


def simulation_db_path(repo_root: Any) -> Path:
    """Return <repo>/context/simulation/simulation_control_plane.db."""
    return simulation_root(repo_root) / SIMULATION_DB_NAME


def simulation_layout(repo_root: Any) -> IdentityLayout:
    """Return the simulation identity layout: <repo>/context/simulation/identity."""
    return IdentityLayout(root=simulation_root(repo_root) / "identity")


def _append_line(path: Path, line: str) -> None:
    """Append `line` to a trust file unless already present (additive, never rewrites), owner-only on POSIX."""
    existing = path.read_text(encoding="utf-8") if path.exists() else ""
    if line not in existing.splitlines():
        with open(path, "a", encoding="utf-8") as f:
            f.write(("" if not existing or existing.endswith("\n") else "\n") + line + "\n")
    if os.name == "posix":
        os.chmod(path, 0o600)


# Create or reuse a simulation key in an identity folder; enroll it additively there only
def ensure_identity_at(identity_root: Any) -> Dict[str, Any]:
    """Return {'key', 'fingerprint', 'created', 'layout'} for the simulation identity in identity_root."""
    layout = IdentityLayout(root=Path(identity_root))
    for directory in (layout.root, layout.challenge_dir):
        directory.mkdir(parents=True, exist_ok=True)
        if os.name == "posix":
            os.chmod(directory, 0o700)
    key = layout.root / SIMULATION_KEY_NAME
    created = False
    if not key.exists():
        subprocess.run(
            ["ssh-keygen", "-q", "-t", "ed25519", "-N", "", "-C", "agentic-os-simulation", "-f", str(key)],
            check=True, capture_output=True,
        )
        created = True
    key_type, key_b64 = Path(str(key) + ".pub").read_text(encoding="utf-8").split()[:2]
    for path, namespace in ((layout.allowed_signers, SIGN_NAMESPACE), (layout.allowed_signers_selftest, SELFTEST_NAMESPACE)):
        _append_line(path, f'{AGENT_SIMULATION_PRINCIPAL} namespaces="{namespace}" {key_type} {key_b64}')
    return {"key": key, "fingerprint": key_fingerprint(key_b64), "created": created, "layout": layout}


# The repository's simulation identity: <repo>/context/simulation/identity
def ensure_simulation_identity(repo_root: Any) -> Dict[str, Any]:
    """Create or reuse the repository's simulation key; never writes the production trust file."""
    return ensure_identity_at(simulation_layout(repo_root).root)


# Keys registered as simulation keys for the repository that owns a database
def simulation_key_fingerprints(repo_root: Any) -> Set[str]:
    """Return the fingerprints enrolled in <repo>/context/simulation/identity/allowed_signers."""
    anchor = simulation_layout(repo_root).allowed_signers
    if not anchor.exists():
        return set()
    return {k.fingerprint for k in enrolled_keys(anchor)}


def _isolation_status() -> Dict[str, Any]:
    """Report whether the agent runs as its own OS account (per platform), with the human's setup commands."""
    from control_plane.identity_setup import privileged_account_commands
    from control_plane.isolation_check import DEFAULT_AGENT_NAME, _resolve_agent_identity

    if sys.platform.startswith("win"):
        return {
            "ready": False,
            "detail": "Windows: account and folder-permission isolation is not auto-detected. Run the agent as a separate "
                      "account and deny it write access to context/identity (see references/isolation-setup.md).",
            "commands": privileged_account_commands(),
        }
    uid, _ = _resolve_agent_identity(DEFAULT_AGENT_NAME, None, None)
    if uid is None:
        return {
            "ready": False,
            "detail": f"No '{DEFAULT_AGENT_NAME}' account: the agent runs as you and could edit your trust files. "
                      "Separation of approvals is enforced for normal use, not against a hostile agent, until you create it.",
            "commands": privileged_account_commands(),
        }
    if hasattr(os, "geteuid") and uid == os.geteuid():
        return {"ready": False, "detail": f"This process runs as the agent account '{DEFAULT_AGENT_NAME}'; run the status as yourself.", "commands": []}
    return {
        "ready": False,
        "account_present": True,
        "detail": f"Agent account '{DEFAULT_AGENT_NAME}' exists (uid {uid}), but account existence does not "
                  "verify the agent runtime or protected-file permissions. Confirm the agent actually runs under "
                  "that account and run the human signing isolation preflight before claiming isolation.",
        "commands": [],
    }


# Human approval / simulation / isolation readiness, never collapsed into one "ready"
def dual_identity_status(repo_root: Any) -> Dict[str, Dict[str, Any]]:
    """Return {'human', 'simulation', 'isolation'} readiness for a repository. Never writes."""
    production = default_layout(repo_root).allowed_signers
    human_keys = [k for k in enrolled_keys(production) if AGENT_SIMULATION_PRINCIPAL not in k.principals] if production.exists() else []
    sim_prints = simulation_key_fingerprints(repo_root)
    relabelled = sorted(k.fingerprint for k in human_keys if k.fingerprint in sim_prints)
    human = {
        "ready": bool(human_keys) and not relabelled,
        "keys": [k.fingerprint for k in human_keys],
        "detail": ("Relabelled simulation key(s) found in the production trust file: " + ", ".join(relabelled)) if relabelled
        else ("Human key(s) enrolled." if human_keys else "No human key enrolled: the human runs setup_ciba_identity.py."),
    }
    sim_key = simulation_layout(repo_root).root / SIMULATION_KEY_NAME
    simulation = {
        "ready": sim_key.exists() and bool(sim_prints),
        "keys": sorted(sim_prints),
        "database": str(simulation_db_path(repo_root)),
        "detail": "Simulation identity ready." if sim_key.exists() and sim_prints else "No simulation identity yet (os-control-init creates it).",
    }
    return {"human": human, "simulation": simulation, "isolation": _isolation_status()}


class SimulationSigner:
    """Signs a simulation database's cryptographic gates with the simulation key kept next to it
    (<db dir>/identity; for <repo>/context/simulation/simulation_control_plane.db that is the
    repository's simulation identity). That trust file is the agent's own by design, so the
    human-anchor isolation preflight does not apply to it; it never touches the human's identity."""

    def __init__(self, identity_root: Path) -> None:
        """Use the simulation identity kept in `identity_root` (created on first use)."""
        self.identity_root = Path(identity_root)

    def __call__(self, cp: Any, request_id: int) -> Any:
        """Sign and commit one pending gate request with the simulation key; return the TransitionRecord."""
        import io

        from control_plane.gate1_approval import approve_transition, show_challenge
        from control_plane.ssh_signing import sign_command

        identity = ensure_identity_at(self.identity_root)
        layout = identity["layout"]
        uid = os.geteuid() if hasattr(os, "geteuid") else 0
        not_this_process = {"agent_name": "agentic-os-simulation-none", "agent_uid": uid + 4242, "agent_gids": set()}
        challenge = show_challenge(cp, request_id, layout=layout, key_hint=str(identity["key"]), agent_identity=not_this_process, out=io.StringIO())
        sig = Path(str(challenge) + ".sig")
        if sig.exists():
            sig.unlink()
        subprocess.run(sign_command(str(identity["key"]), challenge), check=True, capture_output=True)
        return approve_transition(cp, request_id, layout=layout, principal=AGENT_SIMULATION_PRINCIPAL, agent_identity=not_this_process, out=io.StringIO())
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