fix: coordinate concurrent local writes

CHANGELOG.md

@@ -8,9 +8,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ### Fixed
 
-- Serialize concurrent gateway edge mutations through a token-checked lease stored in
-  SQLite. The coordinator recovers an expired crashed-writer lease without releasing a
-  newer owner, and keeps gateway calls outside the local write boundary.
+- Serialize concurrent gateway edge and local-authority mutations through a
+  token-checked lease stored in SQLite. The coordinator recovers an expired
+  crashed-writer lease without releasing a newer owner, and keeps gateway calls
+  outside the local write boundary.
 
 ## [0.6.2] - 2026-07-21
 

CLAUDE.md

@@ -109,7 +109,7 @@ Sync triggers:
 - Immutable publisher delivery policy owns delivery mode, retry limits, and backoff. Cancel and requeue are publisher-only. Requeue resets cycle attempt but not lifetime attempt. Consumer `maxAttempts` and `retryPolicy` inputs are validated and ignored for one compatibility release.
 - Exact idempotent replay deduplicates. Changed content under an existing idempotency key fails.
 - Historical direct-database rows are handled only by migration and reconciliation commands. The normal remote path uses the authenticated gateway.
-- Local and edge SQLite files use WAL, owner-only modes where supported, and bounded busy waits. Initialization and schema upgrade use a 15-second minimum retry window; normal operations retain the configured timeout. Windows verifies the private parent and main database before open, then applies explicit sidecar ACLs after WAL setup and the serialized schema transaction. Replacement during one ACL check still fails.
+- Local and edge SQLite files use WAL, owner-only modes where supported, and bounded busy waits. Each file-backed store has a durable token-checked write lease that serializes mutations across independent processes, expires after a crash, and never covers gateway I/O. Initialization and schema upgrade use a 15-second minimum retry window; normal operations retain the configured timeout. Windows verifies the private parent and main database before open, then applies explicit sidecar ACLs after WAL setup and the serialized schema transaction. Replacement during one ACL check still fails.
 - Host-adapter manifests and installers inject identity per installed client. The v1 manifest field named `runtime` is a compatibility key for the installation target. It does not mean a live process. Installers do not write one identity into shared config.
 - The `codex` adapter configures the profile shared by the Codex CLI and the Codex surface in the ChatGPT desktop app. Claude Code and Claude Desktop use separate adapters and registrations.
 - `AGENT_BRIDGE_INSTANCE` is an optional caller-supplied stable consumer key. Supported installers generate and persist it; direct clients may manage it themselves. The gateway does not bind it to an installer registration. Unless `AGENT_BRIDGE_CURSOR` is explicit, the key selects cursor storage. It also selects leases and instance presence. Without a key or explicit cursor path, cursor storage uses `default`. Lease ownership falls back to the principal, and presence is unavailable. It is not a PID or session. Per-process presence must be additive.

README.md

@@ -246,8 +246,9 @@ for its relationship to MCP, A2A, agmsg, brokers, and agent runtimes.
 
 - Node.js 22.23.1 or newer.
 - SQLite 3.51.3 or newer for local and edge storage. The supported Node version includes it.
-- Concurrent local and edge initialization may wait up to 15 seconds for schema work;
-  normal database operations retain their configured busy timeout.
+- Concurrent local and edge initialization may wait up to 15 seconds for schema work.
+  File-backed local and edge stores serialize mutations with a durable token-checked
+  lease, so independently launched MCP clients do not contend as SQLite writers.
 - PostgreSQL 15, 16, 17, or 18 for gateway mode. New PostgreSQL majors fail the
   migration prerequisite and live readiness checks until their catalog digest is
   certified.

docs/architecture-v2.md

@@ -82,6 +82,12 @@ SQLite WAL provides local-only operation, a durable outbox, an inbox cache, curs
 
 The gateway outbox queues immutable message publication. Receipt and lease mutations still require the remote authority because replaying them after ownership or identity changes can settle the wrong work.
 
+Every file-backed local authority and gateway edge database has a durable, token-checked
+write lease. It serializes mutations across independently launched MCP processes,
+expires after a crash, and is released only by its current token holder. The lease
+covers local transactions, never gateway calls. This keeps one shared local database
+correct without a daemon or per-client replicas.
+
 Long-lived gateway MCP clients own a cancellable transport loop that replays publications and refreshes the inbox cache with bounded exponential backoff. It is transport maintenance, not agent monitoring. Manual MCP and CLI sync use the same replay path. A publication timeout after the gateway may have committed remains queued under its stable idempotency key. A retry resolves to the original immutable message instead of publishing a duplicate.
 
 Local initialization must be idempotent. Concurrent initialization and schema upgrade

docs/troubleshooting.md

@@ -81,18 +81,18 @@ Queued sends retain their idempotency keys. Long-lived MCP clients retry them, a
 `agent-bridge sync` triggers the same bounded replay manually. Claims, lease changes,
 delivery settlement, presence, and read-receipt writes still require the gateway.
 
-## Local edge database is locked
+## Shared SQLite database is locked
 
 Gateway clients share an owner-private local edge database for their outbox and inbox
-cache. Several active MCP processes may use that database at once. Agent Bridge stores
-one token-checked, short-lived write lease in that database. The lease serializes local
-mutations, survives a crashed process, and is never held while a client calls the
-gateway.
-
-If an older installed executable reports `fatal local edge failure: database is locked`,
-upgrade the package and restart only the affected MCP host. Do not delete
-`edge.sqlite3` or its `-wal` or `-shm` sidecars while clients are running. Those files
-carry durable queued work and may be open in another session.
+cache. Local-mode clients can also share a local-authority database. Several active MCP
+processes may use either database at once. Agent Bridge stores one token-checked,
+short-lived write lease in each database. The lease serializes local mutations,
+survives a crashed process, and is never held while a client calls the gateway.
+
+If an older installed executable reports `database is locked`, upgrade the package and
+restart only the affected MCP host. Do not delete `bridge.sqlite3`, `edge.sqlite3`, or
+their `-wal` or `-shm` sidecars while clients are running. Those files carry durable
+state and may be open in another session.
 
 Use `lsof` to identify the host before restarting it. Multiple Codex task processes are
 normal. A stale child is one whose parent host has exited, not simply one that has been