Lockfile and State

AgentMesh persists state across three surfaces with different lifecycles:

Surface	Location	Committed?	Purpose
Repository	agentmesh.lock, .ai/, AGENTS.md	Yes	Shared resolved state
Repository (gitignored)	.claude/settings.local.json, .codex/hooks.json	No	Per-machine hooks
Machine cache	~/.cache/agentmesh/<repo-hash>/	N/A	Integrity, queue, conflicts

agentmesh.lock

A YAML file at the repo root — modeled on Cargo.lock or pnpm-lock.yaml. Generated by AgentMesh, committed to git, reviewed in PRs.

Top-level shape:

version: 1
schema: 1

entities:
  skill:security-review:
    type: skill
    locations:
      .ai: skills/security-review/SKILL.md
      .claude: skills/security-review/SKILL.md
      .codex: skills/security-review/SKILL.md
    canonical_sha256: abc123…
    emitted_native_sha256:
      .ai: abc123…
      .claude: abc123…
      .codex: abc123…

adapters:
  claude:
    mode: bundled
    protocol_version: 1
    entities: [instructions, skill, subagent]
  codex:
    mode: bundled
    protocol_version: 1
    entities: [instructions, skill, subagent]

Key fields per entity

Field	Purpose
canonical_sha256	Hash of canonical form — ancestor for three-way merge
emitted_native_sha256	Per-location hash of bytes AgentMesh last wrote (post-translation)
pending_conflict_resolution	Set after tiebreaker; cleared by ack or restore
lineage	How the entity entered the canonical model
overrides (top-level)	Opt-in per-runtime field divergence

Do not edit agentmesh.lock by hand. Use agentmesh reconcile-lock for git merge conflicts.

agentmesh.config.yaml

Optional user-edited intent file. Every key is optional — a project with no config file runs full bidirectional sync with defaults.

See Configuration for the full schema.

AgentMesh creates this file only if absent during init; it never modifies it afterward.

Machine-local cache

Located at ~/.cache/agentmesh/<repo-hash>/ (platform equivalents on macOS/Windows):

File / directory	Purpose
integrity.json	Pinned binary path + sha256
hook-ownership.json	Which hook entries AgentMesh installed
pending-syncs/	Drainer queue
conflicts/	Archived losing versions from auto-resolved conflicts
watcher.pid	Watcher daemon process ID
*.lock	Advisory locks for concurrent sync

Never commit cache contents. Each machine has its own cache.

Git merge conflicts

When agentmesh.lock has a textual merge conflict:

agentmesh reconcile-lock
git diff agentmesh.lock   # review
git add agentmesh.lock && git commit

The command merges entity entries from both sides, re-scans the filesystem, and writes a clean lockfile. It does not auto-commit.

Schema compatibility

• Read backward: older AgentMesh reads newer lockfiles until schema version exceeds support
• No read forward: running an old binary on a newer schema produces a clear upgrade error (exit code 4)

Related

• Repository Setup — what to commit
• CI Integration — verifying lockfile in pipelines
• Sync Engine — when the lockfile updates