# Harnessie

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

## Release state

Published core: Harnessie 1.5.0 on GitHub and PyPI, from signed tag v1.5.0 with provenance-verified assets and publisher attestations. Homebrew 1.4.1 and Verify Action 0.2.2/stable v0 are published and verified against core 1.4.1; their 1.5.0 bumps are in progress and pinning follows their own releases. Version 1.3.1 adds offline observation of existing run journals with cited JSON/Markdown and no model calls. 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.

Added in 1.5.0: harness identity on every result (installed version, inward-manifest digest and tool-surface digest in verify reports, run reports and a harness_identity event); tool-contract break metrics with a tool_contract live scorecard row and the first measured local brains on https://harnessie.com/brains.html; harnessie atif RUN_ID_OR_DIR [--out PATH] [--force] exports a run's or verify report's hash-chained event log as an ATIF-v1.7 trajectory.json with no model calls, refuses a broken chain, an unfinished loop or a step gap, and reports absent fields rather than inventing them; and examples running Harnessie as a Harbor verifier (exit 0 reward 1, exit 1 reward 0, exit 2 no reward file, so cannot-verify stays unscorable) and as a Harbor external agent. These are plumbing and contract results on one backend and one local model, not evidence about any brain.

Added in 1.4.1: harnessie export-aidr exports one canonical open record to AIDR 0.1.0 with recorded dissent and export-time hashes. It writes a new operator-selected file, refuses arbitration or ambiguous formatting, and leaves the original run halted. This command is included in the published 1.4.1 package.

Downstream release boundary: Homebrew and Harnessie Verify Action are separately propagated. Check NEXT.md for their verified pins before attributing the 1.5.0 surfaces or 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 verified core 1.5.0; Homebrew still carries 1.4.1 while its bump is in progress, and NEXT.md records downstream acceptance. 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 1.5.0 guide selects profile 2.0.0 and earned hosted Level 4 with zero blockers on 2026-10-06: https://github.com/snapsynapse/harnessie/blob/main/audits/release-1.5.0/guidecheck-prepublication.json. For the current 1.5.0 guide, served bytes, sidecar, DNS and repository hash match. The 1.4.1 receipt (https://github.com/snapsynapse/harnessie/blob/main/audits/release-1.4.1/guidecheck-prepublication.json) and the 1.3.1 receipt (https://github.com/snapsynapse/harnessie/blob/main/audits/release-1.3.1/guidecheck-prepublication.json) are historical evidence for different bytes.

## 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): 1.5.0 checkout review under profile 2.0.0; hosted Level 4 verified for the final bytes on 2026-10-06.
- Harbor verifier example (harnessie verify as a Harbor reward, cannot-verify stays unscorable): https://github.com/snapsynapse/harnessie/tree/main/examples/harbor-verifier
- Harbor external agent example (Harnessie loop host side, tool effects in the Harbor environment, ATIF trajectory per trial): https://github.com/snapsynapse/harnessie/tree/main/examples/harbor-agent
- ATIF export acceptance (Harbor-valid trajectory reconciled against OpenEnv's capture proxy, call counts only): https://github.com/snapsynapse/harnessie/blob/main/audits/atif-export-acceptance-2026-10-05.md
- [Offline observer](https://github.com/snapsynapse/harnessie/blob/main/OBSERVER.md): 1.3.1 journal snapshot verification and cited summaries, with output writes and no model calls.

## 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/

## Open-record export references

- Contract: https://github.com/snapsynapse/harnessie/blob/main/AIDR_EXPORT.md
- Offline mock runner, installed CLI and pinned AIDR reference-linter example: https://github.com/snapsynapse/harnessie/tree/main/examples/aidr-export