# Harnessie

A brain-agnostic multi-agent harness. The harness structure carries the quality floor; the model carries the ceiling.

## Release state

Stable core release: Harnessie 1.2.0 on PyPI. It accepts raw verification criteria or v1 evidence bundles and provides structured required-claim verdicts under the fail-closed 0/1/2 verifier exit contract.

Downstream release boundary: Homebrew and Harnessie Verify Action are separately propagated. Check NEXT.md for their verified pins before attributing the 1.2.0 evidence-bundle contract to those install surfaces.

## What it is

An orchestrator decomposes a goal into task packets with acceptance criteria and out-of-scope fences. Cheap workers execute those packets inside a jailed workspace with allowlisted tools, owning the files they create. Every worker phase exits through a gate that runs deterministic checks first, then an independent fresh-context verifier that never sees the worker's reasoning and fails closed. Contested decisions fan out to an adversarial panel whose positions and objections land in a decision record only a human may arbitrate. Everything is journaled, budgeted, resumable, and hash-chain audited. Models are swapped by editing one YAML file; the gates, jails, budgets, ownership rules, and audit log are the same underneath any brain.

## Key concepts

- Roles: orchestrator (decompose and integrate), worker (execute, own files), verifier (judge in fresh context, fail closed).
- Consent: task packets are offers; side-effecting tools unlock only after a worker accepts.
- Gates: deterministic checks plus an independent verifier between every phase.
- Harnessie's Golden Rule for agent work: Read together. Write only what you own.
- Ownership lanes: direct cross-lane writes are refused; child processes receive agent-specific read-only overlays; operator lanes are locked; declared overlapping parallel writes refuse before dispatch.
- Shipped in 1.1.0: harnessie ownership PATH --agent AGENT [--json] explains a ledger decision without mutating it. The zero-model collision proof lives at https://github.com/snapsynapse/harnessie/tree/main/examples/ownership-collision
- Brain-agnostic routing: task classes map to model tiers in config/models.yaml.
- Governance: contested decisions produce AIDR-style records with human-only arbitration.
- Audit: a hash-chained event log; harnessie audit re-verifies it and renders one timeline.
- Security: role permissions, consent lock, workspace jail, admitted OS sandbox (Seatbelt/bubblewrap/firejail; Docker for base confinement only), injection quarantine, secret scrubbing, structured refusals.

## Install

pip install harnessie; also available through pipx or uv tool install. PyPI carries core 1.2.0. Homebrew and Harnessie Verify Action are separately propagated downstreams. The guided mock run makes no provider call and spends no model money, but installation and scaffolding do use the package index and local filesystem. An AI-assisted review path exists at https://harnessie.com/.well-known/assistant-guide.txt; verify it, report the achieved level and SHA-256, and get explicit human approval before any action. The current 1.2.0 guide is repository-pinned but awaits its external DNS and hosted-verifier re-anchor; the hosted 1.1.0 GuideCheck receipt remains dated historical evidence only.

## Key files

- Landing page: https://harnessie.com/
- Repository: https://github.com/snapsynapse/harnessie
- Quickstart (no shell fluency assumed): https://harnessie.com/quickstart.html
- Getting started: https://harnessie.com/getting-started.html
- Modes (the ease-and-safety ladder: five run modes, what is real at each, human-only arbitration across all): https://harnessie.com/ladder.html
- User guide: https://harnessie.com/guide.html
- Agent file ownership (Harnessie's Golden Rule, enforcement, boundaries, and proof): https://harnessie.com/agent-file-ownership.html
- Compare (where Harnessie fits among agent frameworks and guardrail tools): https://harnessie.com/compare.html
- Ringer adoption (verify agent-produced changes through Ringer's exit-code check contract): https://harnessie.com/ringer.html
- Architecture: https://github.com/snapsynapse/harnessie/blob/main/ARCHITECTURE.md
- Governance: https://github.com/snapsynapse/harnessie/blob/main/GOVERNANCE.md
- Security model: https://github.com/snapsynapse/harnessie/blob/main/SECURITY.md
- Brains receipt (models proven under the harness): https://harnessie.com/brains.html
- Threat model (falsifiable claims table): https://harnessie.com/threat-model.html
- Stable v1 workflow schema: https://harnessie.com/schemas/v1/workflow.schema.json
- Schema compatibility contract: https://github.com/snapsynapse/harnessie/blob/main/SCHEMA_COMPATIBILITY.md
- Plugin contract: https://github.com/snapsynapse/harnessie/blob/main/PLUGIN_CONTRACT.md
- [Assistant Guide](https://harnessie.com/.well-known/assistant-guide.txt): bounded, human-verifiable 1.2.0 guide for reviewing a Harnessie checkout before authorizing a run; repository and served bytes agree with the sidecar, while external DNS and hosted verification remain pending. Historical 1.1.0 receipt: https://github.com/snapsynapse/harnessie/blob/main/audits/guidecheck-live-result-2026-08-21-v1.1.0.json

## Support and machine handoff

- Agent capability and boundary declaration: https://harnessie.com/agents.json
- Local CLI interface manifest (not a hosted API): https://harnessie.com/api/v1/index.json
- Machine-readable release history: https://harnessie.com/changelog.json
- Contact support or report a bug: https://github.com/snapsynapse/harnessie/issues
- Report a vulnerability privately: https://github.com/snapsynapse/harnessie/security/advisories/new
- Security contact contract: https://harnessie.com/.well-known/security.txt

## Related

- Anthropic, Patterns and problems in emerging multiagent systems: https://anthropic.com/research/multiagent-systems
- HardGuard25 (human-safe identifiers): https://hardguard25.com/
- Graceful Boundaries (refusal grammar): https://gracefulboundaries.dev/
- AI Decision Records (AIDR): https://aidr.work/