Agent Mesh — meshfleet.app

Auditable multi-agent coordination for OpenCode. Spawn parallel agents as independent OS processes. Route work to specialists. Let agents collaborate peer-to-peer — with witnessed receipts and quorum ratification, so you can answer: who saw this, who approved it, prove it. The core is MIT and free.

Website: meshfleet.app · Source version: 0.22.0 · npm · CI

Maintained: current source and Git tags are visible in the repository; a tag is an intent to ship and the registry is the only record of what shipped · issues answered within 48h · no download-count theater.

Project status — deliberately pre-1.0, actively maintained. Releases are intentionally infrequent (we cut versions when something is worth shipping, not on a calendar); the repo carries a monthly maintenance heartbeat and issues get a first response within 48 hours.

The boundary, as a covenant: the mechanisms are free and stay free — coordination, receipts, councils, provider-neutral advisory interfaces, and the ability to run verification are MIT, forever. Cryptographic signing and auditor-grade attestation are a separate paid layer (meshfleet-pro). Account-specific provider operations and managed policy are also outside this core. No existing core mechanism moves behind a paywall. The core neither owns nor independently controls provider-account credentials, balances, reset policy, spend authority, or external publication.

Host portability: this is an agent audit trail, OpenCode first — not an OpenCode-only idea. The core is a standard MCP server; broader host support tracks real demand.

Why Meshfleet?

OpenCode is a single-agent runtime. You talk to it, it does things. The moment you need multiple specialists running in parallel — explore, then review, then implement — you hit the 30-minute background-task timeout.

Meshfleet adds the missing layer: a fleet of agents that run in parallel, message each other, hand off work, and self-organize. As independent OS processes, not background tasks. No artificial ceiling.

The following is a source/operator-configured example, not a claim that every runtime shown ships in the current npm package:

const { fleet_id } = await callTool("spawn_fleet", {
  agents: [
    { role: "Explorer",   prompt: "Map the auth layer",    agent: "codebase-onboarding-engineer" },
    { role: "Analyst",    prompt: "Review the architecture", agent: "oracle" },
    { role: "Engineer",   prompt: "Implement JWT refresh",  agent: "backend-architect", model: "opencode-go/minimax-m3" },
    { role: "Reviewer",   prompt: "Review the resulting diff", runtime: "claude-cli", workspace_binding: "review-worktree" },
  ],
});

Four specialists. Four independent processes. They hand off, ask questions, alert on problems. You read the result.

Each OpenCode agent accepts an optional model (provider/model) selector. When set, Meshfleet persists it as the immutable request (Agent.requested_model) and launches opencode run --model <value> for that agent; the observed runtime banner lands in Agent.runtime_model, and a complete agent whose banner is missing or contradicts the request fails closed. Omitting model keeps the old argv exactly. The selector is data, not shell text, and the banner is observed evidence — not authentication, billing, provider availability, or attestation.

spawn_fleet also accepts an optional per-agent runtime. The default remains opencode-cli; non-default runtimes are available only when the operator configures them. claude-cli requires an absolute command, a configured version label, and an operator-admitted opaque workspace binding. The caller must repeat that binding as workspace_binding, and must omit OpenCode-specific agent and model selectors. minimax-cli and grok-cli are separate explicit-only text lanes. Each requires its own absolute MESHFLEET_<VENDOR>_COMMAND plus configured MESHFLEET_<VENDOR>_VERSION; accepts no model/agent selector, workspace authority, or artifact expectation; declares its outcome through a structured final-text envelope; withholds raw diagnostics; and is never an automatic failover target. The Grok adapter additionally forces the configured wrapper's source-blind text-only boundary. Each wrapper owns its own authentication; Meshfleet passes a scrubbed environment, never reads or serializes credentials, and exposes no account, credential, effective-model, quota, or availability claim. This outbound worker adapter is separate from the offline static Grok configuration translation, which launches no runtime. See the adapter contract for exact permission and evidence limits. Local smoke tests for any account remain environment-local. The separate pure recommend_route advisory may opt in to a caller-evidenced near-reset tie-break, but it never polls an account, grants provider authority, or executes a paid service.

And when an agent's action matters, Meshfleet can prove what happened. Every message writes per-recipient receipts (delivered, seen, acked). Decisions can go through councils — quorum-based ratification with required sign-offs, recorded on the same ledger. The design is a port of a bus that ran a 10+ agent fleet in production for 40 days and 18,404 messages, including quorum-ratified decisions.

Install in 30 seconds

From npm (the package is meshfleet; the agent-mesh npm name is squatted by a placeholder):

npm install -g meshfleet

Or from source:

git clone https://github.com/johnmwhitman/agent-mesh.git \
  ~/.config/opencode/mcp-servers/agent-mesh
cd ~/.config/opencode/mcp-servers/agent-mesh
npm install && npm run build

Add to ~/.config/opencode/opencode.jsonc (npm install):

{
  "mcp": {
    "meshfleet": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "meshfleet"]
    }
  }
}

For noncanonical development-only source-checkout usage (not the recommended release config):

{
  "mcp": {
    "meshfleet": {
      "type": "local",
      "enabled": true,
      "command": ["node", "~/.config/opencode/mcp-servers/agent-mesh/dist/index.js"]
    }
  }
}

Restart OpenCode. Spawn a fleet. Wiring it into your client →

Start with the published package

The published meshfleet package's no-key walkthrough is a scripted ledger demonstration: it proves that the package and inspector run, not that a model-backed worker completed a real task.

npx -y --package=meshfleet -- agent-mesh demo

That published walkthrough runs entirely against a throwaway temp ledger (nothing under ~/.config/opencode is touched) and prints its demonstration audit, then a next-step inspector command. To inspect your own configured MCP ledger later, bind the package explicitly — running the agent-mesh bin through npx without --package=meshfleet resolves npm's unrelated reserved agent-mesh@0.0.1 package, not this one:

npx -y --package=meshfleet -- agent-mesh inspect --verify

If that (or the MCP server itself) exits with CRASH ... unsupported newer storage schema version, it found a pre-existing ledger at the default path (~/.config/opencode/agent-mesh.db) written by a newer meshfleet build than the one you're running — common on a dev machine that already ran OpenCode/meshfleet, not on a fresh install. Point at a different ledger file with MESHFLEET_DB_FILE=/path/to/other.db (same variable your MCP client config can set) and it will not touch the existing file.

Source-only deterministic runtime

The newer source checkout documented on this page includes a local-demo runtime — the current Node executable running a deterministic worker. It is not in the published package. After building this source checkout, ask your MCP host to spawn with it:

spawn_fleet with agents [{ role: "scout", prompt: "Count the receipts.", runtime: "local-demo" }]

The spawn, lifecycle events, receipts, and collect_results are all real; only the worker is synthetic, and it says so in its output ("model": null, no invented text). local-demo is never used for automatic failover — a real agent that fails is never silently replaced by an echo.

Try one real, read-only task

Prerequisite: OpenCode is already installed and configured for an account you are authorized to use. Meshfleet does not create credentials, choose billing scope, or make provider calls until you ask it to spawn a worker. Through your MCP host:

1. Call spawn_fleet with agents: [{ role: "explorer", prompt: "Read this repository's README and list its three main sections. Do not edit files." }]. Omit runtime so the published default opencode-cli adapter is used.
2. Pass the returned fleet_id to collect_results, then inspect the local evidence with npx -y --package=meshfleet -- agent-mesh inspect --verify.
3. Treat complete and the local consistency report as recorded claims, not proof that the answer or code is correct. Review the worker's result yourself.

Then share voluntary first-use feedback and say whether the path was useful, not useful, or blocked, plus the first step where you got stuck. Please do not upload source code, prompts, credentials, secrets, or raw ledger files. If it helped, try the same evidence check on a different meaningful task another day; rerunning the scripted demo is not return use.

Wiring it into your client

Meshfleet is a standard stdio MCP server. The invocation is always the same — npx -y meshfleet (the meshfleet bin in package.json points at the server, dist/index.js) — only the config file around it changes per client.

Honesty labels. "Tested" means verifiable from this repo itself. Client-specific shapes below follow each client's documented config format — we haven't wired CI to every editor, so those are marked "per <client> docs — verification welcome."

Any MCP client (generic stdio) — tested: this exact shape ships in this repo as mcp.json

{
  "mcpServers": {
    "meshfleet": {
      "command": "npx",
      "args": ["-y", "meshfleet"]
    }
  }
}

OpenCode — primary host; canonical meshfleet server identity

~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "meshfleet": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "meshfleet"]
    }
  }
}

Claude Code — per Claude Code docs — verification welcome

CLI form:

claude mcp add meshfleet -- npx -y meshfleet

Or project-scoped .mcp.json at the repo root:

{
  "mcpServers": {
    "meshfleet": {
      "command": "npx",
      "args": ["-y", "meshfleet"]
    }
  }
}

Codex — same host-neutral stdio server

Configure Codex's MCP server entry with the same command and arguments:

{
  "mcpServers": {
    "meshfleet": {
      "command": "npx",
      "args": ["-y", "meshfleet"]
    }
  }
}

These Claude Code, Codex, OpenCode, and generic MCP configurations all call the same inbound stdio server. This proves client interoperability at the MCP boundary only. Workers default to OpenCode's opencode run; an operator may separately register a non-default runtime such as claude-cli. The subscribe_inbox SSE endpoint is optional acceleration; it is not required for compatibility, and clients can use get_inbox polling.

If any block above doesn't work in your client, open an issue — config rot is a bug.

Local A2A compatibility surface

The local parent process also exposes a loopback-only A2A compatibility adapter for dashboard and integration dogfooding:

GET  /.well-known/agent-card.json
POST /a2a/tasks
GET  /a2a/tasks/:task_id

The Agent Card advertises only local task submission and status. Task IDs are stored durably in the local SQLite ledger (local_a2a_tasks table), so they survive process exits and restarts within the same ledger. The adapter is protected by MESHFLEET_SSE_TOKEN (with the existing SSE auth aliases), remains bound to loopback, and does not claim public A2A ingress, remote relay, signed identity, or push notifications. Durable local task state is now provided for the local adapter. MCP stdio remains the primary control surface.

The CLI

Once Meshfleet is installed, the agent-mesh CLI (from the meshfleet npm package — bare agent-mesh on npm resolves a different reserved placeholder) gives you terminal visibility into your running fleets, and agent-mesh-dashboard gives you a live TUI. Every command below selects the meshfleet package explicitly via --package=meshfleet to avoid the squatted name.

$ npx -y --package=meshfleet -- agent-mesh inspect
3 fleets:

bc34d339-935c-4…  complete  3 agents, 3 done (34.8m)
37ae1cf2-5ce8-4…  complete  1 agents, 1 done (28.2m)
d648beb0-cfb2-4…  failed    2 agents, 2 done (27.3s)

$ npx -y --package=meshfleet -- agent-mesh inspect --metrics
Total fleets:       7
  completed:        3
  failed:           4
Total agents:       16
Success rate:       42.9%
Avg duration:       1.34s

$ npx -y --package=meshfleet -- agent-mesh inspect --events 5
TIMESTAMP            EVENT              DETAIL
──────────────────────────────────────────────────────────────────────
2026-07-02 12:40:12  agent_spawned       fleet=f-1 agent=a-1
2026-07-02 12:40:12  agent_spawned       fleet=f-1 agent=a-2
2026-07-02 12:40:12  fleet_created       fleet=f-1

$ npx -y --package=meshfleet -- agent-mesh inspect timeline f-1 --from 2026-07-02T12:40:00Z --to 2026-07-02T12:45:00Z
Local ledger timestamps in [1782996000000,1782996300000) · not authenticity, completeness, tamper evidence, authenticated provenance, or external time
TIMESTAMP            KIND                SUMMARY
──────────────────────────────────────────────────────────────────────
2026-07-02 12:40:13  message             handoff agent-a→agent-b
2026-07-02 12:40:18  receipt             ack by agent-b on 3f9c1a2b

$ npx -y --package=meshfleet -- agent-mesh inspect --follow            # or -f; add --fleet <id> to scope to one fleet
ledger: ~/.config/opencode/agent-mesh.db  · poll 400ms  · ctrl-c to stop
watching… no messages yet  (spawn a fleet or send_message from MCP)
2026-07-22 09:14:03  handoff  agent-a → agent-b  msg=3f9c1a2b  {"task":"review PR #42"}

Timeline bounds are optional digits-only epoch milliseconds, ISO dates (YYYY-MM-DD), or timezone-bearing ISO datetimes (YYYY-MM-DDTHH:mm:ss[.fraction](Z|±HH:mm)). Fractional precision is normalized to epoch milliseconds. Bounds select the half-open interval [from,to) over timestamps stored in the local ledger. Add --json for the additive timeline_window inspect envelope. An unbounded inspect timeline [fleet] keeps the original text and JSON shapes. This is read-only local-record selection, not proof of authenticity, completeness, tamper evidence, authenticated provenance, or external time.

MCP tools

Default stdio tools/list remains the compatible 40-tool catalog. Set MESHFLEET_COMPACT_CATALOG=1 to advertise a 36-tool compact catalog that omits three advisory routing tools (compile_route_candidates, recommend_route, plan_speculative_backlog) and deprecated verify_ledger_v2. Within compact mode, MESHFLEET_ROUTE_ADVISOR=1 restores the three advisory tools for a 39-tool catalog. Prefer verify_ledger plus verify_ledger_v3 for new integrations.

Fleets

Messaging & receipts

Councils (quorum ratification)

Routing & ops

Discussions (bounded two-agent negotiation)

See docs/discussions.md for the full quickstart, tool reference, and terminal-state precedence.

Default tools/list remains 40 for compatibility. Set MESHFLEET_COMPACT_CATALOG=1 for the 36-tool compact profile. In compact mode, set MESHFLEET_ROUTE_ADVISOR=1 to restore the three advisory routing tools; verify_ledger_v2 remains callable by exact name but is omitted from compact discovery.

RoutePlane catalog discovery is a separate package library and CLI, not an MCP tool: it fetches RoutePlane's fixed loopback model catalog and projects caller-owned policy into advisory candidates. Its package-library API, recommendRoutePlaneCatalog(), composes an already-fetched snapshot; the opt-in fetchAndRecommendRoutePlaneCatalog() fetches that fixed loopback catalog once before the same composition. Their evaluated and no_compiled_candidates statuses preserve catalog diagnostics separately from task exclusions and remain advisory with all effects false. Neither API deploys, publishes, selects providers, executes models, contacts providers beyond that explicit loopback catalog fetch, polls budget telemetry, or infers authority from provider labels. RoutePlane catalog boundary → docs/ROUTEPLANE-CATALOG.md

Fleetbudget ingress and observation projection are separate package surfaces, not MCP tools. The new meshfleet/fleetbudget-sanitizer library and meshfleet-fleetbudget-sanitize stdin CLI strictly validate the current unversioned fleetbudget --json byte shape against a caller-owned collection interval. They retain lane only as an opaque evidence identifier plus measured, used, total, and unit; routes, state, utilization, note, and detail are validated and erased. The CLI reads stdin and never invokes Fleetbudget, another provider process, or a route command.

Sanitized raw lanes deliberately contain no typed quota window, so even a complete or exhausted raw ceiling remains diagnostic-only: it produces WINDOW_MISSING, no observation, and no availability, exhaustion, allocation, ranking, or route authority. compileFleetBudgetObservations() still accepts caller-supplied versioned snapshots with explicit candidate bindings when a real typed quota window exists. Several candidates may share a lane ID as copied, unsplit evidence; the compiler returns observations or diagnostics, canonical provenance hashes, and all-false effects. Neither surface sums, allocates, reserves, synchronizes, executes, or authorizes. Validated window bounds flow through the route-candidate compiler without their lane/window ID. An explicit prefer_near_reset recommendation can use those bounds only after the existing final score as a tie-break; there is no default account-optimization policy. Structured collector versioning, producer-owned observation timing, and typed quota windows are required before raw measured budget can become actionable. Safe host collection and exact boundary → docs/FLEETBUDGET-OBSERVATIONS.md

plan_speculative_backlog is a separate, pure queue projection over closed, caller-supplied inputs. A task is proposed only when the caller includes opaque state: "approved" evidence; this is not MeshFleet authorization. It composes the existing recommend_route hard gates and may opt into its already-landed near-reset tie-break per task, but never treats reset urgency as a global queue priority. Candidate quality tags are declared eligibility only, not a quality measurement. Asset and video candidates require text-only or caller-attested rights material, private review, and a human release requirement. The result contains a canonical supplied-input hash only as replay evidence, has all effects false, and reports shared-candidate capacity as explicitly unmodeled: it does not execute, schedule, poll, read credentials, infer providers, bind pools, reserve capacity, spend budgets, send, publish, or establish freshness, provenance, approval, provider state, a receipt, or an execution commitment. The proposed and blocked arrays are priority-descending/task-ID-ascending, and each entry carries its zero-based queue_index in that global order. Advisory routing → docs/ADVISORY-ROUTING.md

Sanitized fleet wrapper usage is available through the separate pure meshfleet/wrapper-usage-observations package surface. It accepts only the closed, already-decoded fleet.wrapper-usage-summary/v1 object and returns a distinct accepted/groups status envelope with all effects and authorities false. It preserves routeplane-unattributed exactly and copies source rejections and aggregate counts without prompts, raw event IDs, provider or quota inference, derived rates, persistence, execution, scheduling, routing, logging activation, or MeshFleet health changes. It is not an MCP tool and is not structurally interchangeable with route-candidate observations. Wrapper usage status boundary → docs/WRAPPER-USAGE-OBSERVATIONS.md

Advisory routing → docs/ADVISORY-ROUTING.md · Fleetbudget observations → docs/FLEETBUDGET-OBSERVATIONS.md · Architecture orientation → AGENT-MESH-SPEC.md · P2P/receipts → SPEC-P2P.md · Councils → SPEC-COUNCILS.md

5 message types

64 KB payload cap. The default encoding is JSON, but payloads are strings — send whatever you want. Broadcasts (to_agent_id: "*") fan out to every fleet peer, and each recipient acks independently — the receipts ledger shows exactly who saw it.

4 collaboration patterns

• Pipeline handoff: A → B → C. Each specialist hands context to the next. No orchestrator in the loop.
• Debate consensus: A and B review the same artifact, debate via questions, converge before reporting.
• Failure recovery: C hits a blocker, broadcasts alert, peers with relevant skills respond with fixes.
• Ratified decision: a council votes on a risky action — quorum, deadline, required sign-off — and the outcome (including who stayed silent) is on the ledger.

More on the receipts wedge →

What the verifier catches — and what it can't

"Prove it" is a claim about detection, so it ships with the evidence: test/fixtures/corpus/ is a corpus of 85 deliberately falsified ledgers, each one a clean baseline plus one declared change. Results are reported in three separate buckets, never blended into a single coverage number:

That third bucket is published on purpose. The core polices internal coherence; it cannot police provenance, content binding, completeness, or absolute time. So a payload swapped after a council approved it, a ballot minted for an agent that legitimately holds a seat, a ghost agent with a coherent history, and a wholesale clock shift all verify clean — and each is committed as a fixture asserting exactly that. This is the free-core boundary as something you can run, rather than something we assert. It is also precisely the line Meshfleet Pro exists on the other side of: signatures are what make those vectors detectable, and signatures are not in this core.

Together the caught and anomaly vectors name every check the verifier can emit outside the discussion.* family, and that inventory is re-derived from source on every run — so a new check without a fixture fails the build.

Implemented versioned evidence scope

verify_ledger_v2 is an implemented MCP verifier surface. It remains on the compatible default catalog, but is deprecated and hidden from compact tools/list when MESHFLEET_COMPACT_CATALOG=1; the handler remains callable for this release. Prefer verify_ledger plus verify_ledger_v3. The existing verify_ledger, VerifyReport, VerifyFinding, agent-mesh inspect --verify, and meshfleet.inspect/v1 remain unchanged.

At tool dispatch, its handler reads the configured ledger through a dedicated read-only file snapshot and performs no ledger writes. In normal parent mode, server startup recovery or migration may initialize or change the configured ledger before any tool dispatch; those pre-dispatch effects are unchanged by v2 and are outside this handler boundary.

The MCP tool returns this envelope. The matching opt-in agent-mesh inspect --verify-v2 [file] CLI mode is implemented: it audits the supplied file, or the configured ledger, through the same dedicated read-only file snapshot. With --json it emits this same object; otherwise it emits one evidence-scope header followed by the unchanged legacy verifier text:

{
  "schema": "meshfleet.verify/v2",
  "evidence_scope": {
    "profile": "unsigned_snapshot_consistency/v1",
    "ok_means": "no_detected_internal_consistency_contradiction",
    "assurance_ceiling": "internal_consistency_of_the_unsigned_snapshot_read",
    "not_established": [
      "authorship_and_authenticated_provenance",
      "pre_read_snapshot_integrity_and_tamper_evidence",
      "content_binding",
      "completeness_and_deletion",
      "external_delivery_and_execution",
      "external_time"
    ]
  },
  "report": "the unchanged VerifyReport"
}

report.ok retains its exact current meaning: no detected internal consistency contradiction in the unsigned snapshot read (report.errors === 0). It does not establish authorship or authenticated provenance, pre-read snapshot integrity or tamper evidence, content binding, completeness or absence of deletion, external delivery or execution, or external time. The scope is generated verifier output, never caller or ledger input; it is a ceiling on what the report establishes, not a confidence score, integrity verdict, or promotion.

Implemented opt-in verifier v3 local consistency bands

verify_ledger_v3 and agent-mesh inspect --verify-v3 [file] are separate, opt-in verifier surfaces. They retain the same six-item unsigned_snapshot_consistency/v1 evidence_scope, but return a new exact four-key envelope with a detached copy of the unchanged VerifyReport:

{
  "schema": "meshfleet.verify/v3",
  "evidence_scope": {
    "profile": "unsigned_snapshot_consistency/v1",
    "ok_means": "no_detected_internal_consistency_contradiction",
    "assurance_ceiling": "internal_consistency_of_the_unsigned_snapshot_read",
    "not_established": [
      "authorship_and_authenticated_provenance",
      "pre_read_snapshot_integrity_and_tamper_evidence",
      "content_binding",
      "completeness_and_deletion",
      "external_delivery_and_execution",
      "external_time"
    ]
  },
  "report": {
    "ok": true,
    "scope": {
      "covers": "internal consistency — every receipt, flag, inbox entry, and ratification tally is supported by the ledger's own records",
      "excludes": "authenticity — there is no hash chain or signature here, so an edit that rewrites the ledger consistently is indistinguishable from honest history"
    },
    "errors": 0,
    "warnings": 0,
    "counts": { "fleets": 0, "agents": 0, "messages": 0, "receipts": 0, "ratifications": 0 },
    "findings": []
  },
  "finding_local_bands": []
}

There is exactly one local band for each report finding, in the report's existing order: error becomes local_consistency_error and warning becomes local_consistency_warning. The mapping does not sort, deduplicate, inspect check names, or score findings. An unknown or missing severity fails closed. Zero findings produce zero bands; they do not produce an undetectable finding.

The report copy and band array are frozen only for caller alias safety. They do not supply tamper evidence. The labels are severity-derived local consistency labels only, not provenance or confidence; no labels means neither authenticity nor completeness. As with v2, the handler reads through the dedicated read-only file snapshot and performs no ledger writes. verify_ledger, verify_ledger_v2, VerifyReport, existing inspect JSON, their text, their exits, ledger behavior, and sidecars remain unchanged.

What this proves about your agents — and what it doesn't

The section above is about the ledger lying. This one is about the agents lying, which no coordination record can rule out. Meshfleet records fleet coordination in a local, unsigned SQLite ledger: a structured, queryable history of who was spawned, who messaged whom, who voted, and what each agent declared about its own outcome. It is not a cryptographic logging system, it does not provide third-party attestation, and it cannot make an LLM's claims true.

Operating principle: a lead, not a receipt. Fleet output is a lead, never a receipt — nothing belongs in a report until you re-run it yourself. An orchestrator sits between autonomous execution and your decisions, so it must say where its responsibility ends: Meshfleet enforces protocol rules and surfaces candidate artifacts; verifying the work stays with your tooling and your review.

Known limits, and where each one stands

• Completion status is declared, not proven. Agents have been observed banking complete on an explanation of failure. The result contract (shipped) has every spawn declare done / refused / blocked in a result envelope, recorded as result_contract on the agent row and returned by collect_results. ok is the only value that may bank complete; refused, blocked, artifact_missing, invalid, or absent banks failed. A valid envelope is still a declaration — it is not a fabrication, effort, or quality check.
• Fabricated agent metrics. An agent can report synthetic test counts or invented "VERIFIED" claims, and the ledger records that it said so. Open, and only partially detectable; result-envelope enforcement does not solve it.
• Agent loss during crashes. collect_results reports loss explicitly (named lost_agents, a warning that appears only when something was lost). A crashing server leaves a durable journal line, and the next healthy start consumes it: interrupted rows carry a stopped_reason (server_crash | process_lost) when reconciliation can honestly attribute one. A failed row with a valid result contract and output or declared artifacts is instead listed in degraded_agents: the result was reported, but runtime status was not clean. This is delivery evidence, not proof of execution or truth. All shipped.
• Internal rule enforcement. Operational: the auditor re-derives its rules from source on every run, and a ledger asserting more than its own records support — a ratification without its votes, a receipt without its message — fails verification (the caught bucket above).

How it compares

None of them answer "who saw this, who approved it, prove it." That's the lane.

FAQ →

Architecture

src/
├── db.ts                # The withLedger transaction seam over SQLite (the write boundary)
├── core.ts              # Data layer: ledger, messages, receipts, capabilities, events
├── migrate.ts           # One-shot JSON→SQLite migration (runs once at startup)
├── ratify.ts            # Councils: quorum ratification over the receipts substrate
├── templates.ts         # Versioned fleet templates
├── routing-feedback.ts  # Outcome-informed work routing
├── health.ts            # Fleet health scoring
├── realtime.ts          # SSE push delivery (subscribe_inbox)
├── inspector.ts         # Pure formatters for CLI output
├── index.ts             # MCP server: transport + tool handlers
└── bin/
    ├── inspect.ts       # CLI: npx -y --package=meshfleet -- agent-mesh inspect
    └── dashboard.ts     # Live TUI: npx -y --package=meshfleet -- agent-mesh-dashboard

Every write goes through one function — withLedger(mutator) in db.ts — which runs the mutation inside a single SQLite BEGIN IMMEDIATE transaction. Agents are real OS processes that each boot their own agent-mesh instance on the same ledger, so writes are genuinely concurrent; SQLite (WAL + busy_timeout) provides cross-process write exclusion, so this codebase owns no locking protocol and lost-update is impossible by construction. (An earlier JSON read-modify-write store silently lost 57 of 120 receipts under a two-process test; the SQLite seam passes the same test 200/200.) Readers use a lock-free readLedger(). Pure formatters live in inspector.ts — easy to test, no I/O.

The ledger lives at ~/.config/opencode/agent-mesh.db (SQLite); the event log at ~/.config/opencode/agent-mesh.events.log (NDJSON). Override the ledger path with MESHFLEET_DB_FILE=/path/to/file.db — useful for a second install, a test ledger, or when an existing file at the default path was written by a newer/incompatible build. Dump the ledger as human-readable JSON any time with npx -y --package=meshfleet -- agent-mesh inspect --export. On first run after upgrading from a JSON ledger, the server migrates it once (validated, with a .migrated.<ts> backup kept).

Architecture orientation → · P2P messaging spec →

Requirements

• Node.js >= 20
• OpenCode CLI in $PATH (any model provider OpenCode supports)
• That's it

Background

Background: Human Out of the Loop is the book behind this portfolio.

License

The core is MIT — use it, fork it, ship it in your product. No attribution beyond the license file. (A commercial assurance layer, Meshfleet Pro, lives in a separate repo and doesn't change what's here.)

Contributing

See CONTRIBUTING.md. Bugs → issues. Security → SECURITY.md. Roadmap → ROADMAP.md.