Granary Harness — Secure GitOps Orchestration & Containment

A secure, GitOps-native multi-agent orchestration loop and zero-trust containment framework. Grounded in the academic CAID (Centralized Asynchronous Isolated Delegation) paradigm, Granary coordinates multi-agent fleets asynchronously using private GitHub PRs as an immutable blackboard communications bus—fully isolated by local sandboxing boundaries, credential filters, and an MCP gateway.

🚀 Day-0 Quickstart (Run the MVP Demo)

Granary is packaged to be extremely lightweight (<5MB) and runs in any terminal in under 30 seconds.

1. Installation & Environment Setup

Clone the repository and install dependencies in editable development mode:

make setup

2. View Security & Governance Status Dashboard

Run bare granary (or granary status) to view a beautifully formatted terminal dashboard showing active directory sandboxes, registered agent capabilities, loaded self-healing hooks, and MCP gateway policies:

.venv/bin/granary

3. Run the Secure Blackboard Loop Demo (CAID)

Execute our E2E GitOps loop simulation to see how agents coordinate asynchronously, how file containment jails block unauthorized traversal attempts, how Helix-style self-healing auto-hooks are dynamically compiled on exceptions, and how SEDM/TierMem memory evolution consolidates records on success:

.venv/bin/python bin/granary-loop-demo.py

Key Features

• Asynchronous GitOps Coordination (CAID): Standardizes multi-agent software engineering workflows over Git branches and PRs (as in arXiv:2603.21489), sequentially merging worker commits and resolving workspace conflicts natively.
• Helix-style "Gene Map" Auto-Hooks: Intercepts, trace-fingerprints, and registers dynamic recovery hooks on sandbox failures, shielding future loops in under 1ms without LLM overhead.
• SEDM/TierMem Memory Evolution: Promotes probation records to active memory via "Verified Write-Back" upon successful PR merges, or quarantines them on task exceptions.
• Operating Constitution: Enforces a strict, declarative, five-tier (T0-T4) blast-radius boundary limit for filesystem, LOC edits, token budgets, and path overrides via agent-constitution.yaml.
• Dynamic JIT Privilege Elevation: Implements AgentAssertionToken (AAT) with agent_owner and agent_trust_score claims, alongside RFC 8693 token exchange payloads and RFC 9449 DPoP sender-constraining validation.
• Egress & Tunneling Control (ShieldNet): Shannon entropy monitoring and rate limiting over DNS queries to identify exfiltration channels and active tunneling attempts.
• MCP Trust Gateway: High-fidelity Model Context Protocol tool interceptors, risk-based gating, and human-in-the-loop approvals.

Project Structure

granary-harness/
├── granary/                # Core security modules
│   ├── __init__.py         # Public API (39 fully exported modules)
│   ├── identity.py         # AAT Claims, signatures, and DPoP validation
│   ├── constitution.py     # Operating Constitution and YAML parser
│   ├── readiness.py        # Pre-launch checklists & cold rollbacks
│   ├── adversa.py          # Adversa offline red-teaming
│   ├── mcp_security.py     # MCP tool risk gateways
│   ├── shieldnet.py        # DNS entropy network egress
│   ├── attestation.py      # Nitro enclave attestation
│   └── ...                 # Sandboxing, rollups, self-healing, otel
├── tests/                  # Standalone unittest suites
│   └── test_granary_*.py   # 192 Granary unit tests
├── docs/                   # Governance & policy contracts
│   ├── gtm/                # Competitive positioning & matrices
│   ├── agent-constitution.yaml
│   ├── governance-cadence.md
│   └── planning_merge_verification.md
├── pyproject.toml          # Package configuration
├── CLAUDE.md               # Code standards & run commands
└── AGENTS.md               # Autonomous onboarding reference

Setup & Task Automation

Granary includes a standardized local task runner using the project Makefile:

• Set up standalone environment: Create .venv and install the package in editable development mode:

  make setup
  

• Run the unit test suite: Run all 192 Granary tests with verbose reporting:

  make test
  

• Package compiling: Compile the project into distributable wheel (.whl) and sdist (.tar.gz) archives:

  make build
  

• Pristine cleaning: Recursively clean caches, bytecode, and packaging/environment folders:

  make clean
  

Command-Line Interface (CLI)

The administrative utility is registered natively upon installation as the executable granary.

1. Constitution Validation

Validate the syntax and autonomy tiers of a declarative agent constitution YAML file:

granary validate-constitution --path docs/agent-constitution.yaml

2. Merkle Audit Ledger Management

• Export Chain: Export a mock, cryptographically chained, and redacted compliance ledger:

  granary admin ledger export --work-unit-id "wu_92e8a10f-3a21" --output "./forensics_export.json"
  

• Verify Chain Integrity: Scan, recalculate Merkle roots, and verify HSM-signatures over an exported ledger file:

  granary admin ledger verify-chain --input "./forensics_export.json"
  

Running Unit Tests

Unit tests are written using Python's built-in, zero-dependency unittest module.

To run the Granary test suite (192 tests) with no regressions:

Legacy Living-NN trees (core/, gfo-server-v3/, etc.) are documented in legacy/README.md and are not part of the PyPI package.

python -m unittest discover -s tests -p "test_granary_*.py" -v

MCP Gateway (Cursor / Claude)

Granary exposes a stdio MCP server that wraps McpTrustGateway for live agent sessions.

Setup

make setup   # installs granary-harness[mcp]

Cursor configuration

This repo ships .cursor/mcp.json. After setup, restart Cursor or reload MCP servers. You should see granary-gateway with four tools:

Run manually:

granary-mcp

Optional custom policy JSON via GRANARY_MCP_POLICY=/path/to/policy.json.

Publishing to PyPI

See docs/PYPI_RELEASE.md for build, twine check, TestPyPI, and production upload steps.

make build
make publish-check