FerryCat

FerryCat: Contract-Driven Cross-Host AI Agent Handoff Bus

English • 中文

FerryCat (ferrycat) is a lightweight, deterministic cross-host AI agent handoff, code review, and verification harness built on the Model Context Protocol (MCP) and Node.js built-in node:sqlite (WAL mode).

Purpose-built to safely bridge isolated desktop IDE agent hosts (such as Google Antigravity, WorkBuddy, Claude Code, and Cursor) across separate OS processes—enabling Actor-Critic evaluation loops, static analysis gates, and SWE-bench-style patch verification without context drift or blind reviews on stale files.

📖 Deep Dive: Why I Started Building FerryCat: When Two AI Coding Hosts Live on the Same Desktop

---

Quick Glance (See It in 60s)

No IDE setup or config file edits required. Watch the entire deterministic loop execute inside an isolated sandbox in ~2 seconds:

npx ferrycat demo

⚡ FerryCat Zero-Config Sandbox Demo ⚡

✔ [1/4] Contract Dispatched Locked: src/calc.ts (sha256: ce3ba9a5...bc5d) ✔ [2/4] Contract Claimed Lease: 7424261d-9a3f-4a86-a7ff-de278c273e96 ✔ [3/4] Execution & Check Heartbeat 1 renewal | CHANGES_REQUESTED (loose equality caught) ✔ [4/4] Contract Completed TOCTOU: 0 dirty files | Status: COMPLETED (elapsed: 2.1s) 🎉 End-to-end multi-agent handoff verified successfully!

> 💡 Real benchmark: spins up an isolated child-process sandbox, triggers 1 real lease renewal, and runs a static analysis & verification gate that catches loose equality at `src/calc.ts:6`. Options (`--keep` / `--json` / `--no-color`) detailed in [Quickstart §0](#0-see-what-it-actually-does-first-ferrycat-demo).

---

Core Pain Points & Engineering Solutions

While the official MCP Tasks specification (2025-11 / 2026-07) addresses long-running operations within a single `Client ↔ Server` connection, it does not solve cross-host collaboration on a developer workstation:

1. `stdio` Process Isolation: Desktop IDEs spawn local MCP servers as independent child processes with isolated memory spaces and distinct Node.js runtimes.
2. Silent Blind Reviews on Stale Code (`Stale Context`): When handing off a task from Host A to Host B, unushed IDE buffers, branch switches, or mid-review edits cause the receiving agent to audit outdated code and produce plausible but invalid conclusions.
3. Context Window Bloat: Pasting hundreds of lines of source code across chat windows duplicates token consumption on both ends.
4. Unstructured Handoff Outputs: Free-form prose responses lack deterministic schema enforcement, making downstream consumption unreliable and prone to infinite retry loops.

FerryCat resolves these failure modes through a human-scheduled, contract-driven SQLite WAL bus:

[Developer]             [Host A: Antigravity]            [~/.ferrycat/mesh.db]            [Host B: WorkBuddy]

| | | |-- Read local files | | |<-- fulfill_contract() --------|-- Re-verify SHA-256 | | | (Validate Ajv JSON Schema | & submit JSON | | | -> status = COMPLETED) |

---

Key Architectural Pillars

1. Deterministic 7-State Machine

Every state transition is bound to an explicit SQL transaction with optimistic concurrency control (changes === 1), eliminating phantom or dangling states:

                  dispatch_contract()

│ ▼ ┌───────────┐ │ SUBMITTED │ (Queue TTL: default 1800s) └─────┬─────┘ │ poll_next_task() ┌────────────────┼────────────────┐ │ (Queue TTL) │ (Hash Match) │ (Missing / Size Diff / SHA-256 Mismatch) ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────────┐ │ TIMED_OUT │ │ CLAIMED │ │ POINTER_STALE │ (Terminal: Rejects blind review) └───────────┘ └─────┬─────┘ └───────────────┘ ▲ │ (Exec TTL: default 300s) │ fulfill_contract() │ ┌────────────────┼────────────────┬────────────────┐ └──┤ (Exec TTL) │ (Schema Valid) │ (Retries > 2) │ (Mid-Review File Edit) │ ▼ ▼ ▼ │ ┌───────────┐ ┌───────────────────┐ ┌───────────────┐ └──────────│ COMPLETED │ │ VALIDATION_FAILED │ │ POINTER_STALE │ └───────────┘ └───────────────────┘ └───────────────┘

*Note on POINTER_STALE vs. SELF_CONTAINED Patch Mode (FC-202)*: POINTER_STALE is terminal whenever on-disk pointer files mismatch the dispatched SHA-256 baseline, except when a read-only contract (code_review / architecture_audit) attaches a verified unified git_patch (--patch-file) that satisfies all three gates: every declared file block carries at least one @@ hunk with real +/- content (EMPTY_PATCH_HUNKS / EMPTY_PATCH_CONTENT otherwise), and the touched paths cover every pointer file (PATCH_DOES_NOT_COVER_POINTERS otherwise). In that SELF_CONTAINED mode, poll_next_task returns patch_mode: "SELF_CONTAINED" with an explicit workspace_warning instructing the reviewer to inspect git_patch rather than stale on-disk files.

Holder-side lifecycle controls on a CLAIMED contract (all require agent_id === target_agent):

2. Full-File SHA-256 Fingerprinting, Pre-Flight Verify & TOCTOU Soft-Failure Buffering (ADR-0004)

• Dispatch Snapshot: dispatch_contract reads target files on disk, recording byte size, full-file sha256 (64 hex chars), first_line, and last_line. If a file was modified within the last 3 seconds, a warning is emitted to alert the requester of potential unsaved IDE buffers.
• Claim Verification: poll_next_task verifies Existence -> Byte Size -> Full-File SHA-256 (never rejecting on mtime_ms alone to tolerate no-op IDE saves). On mismatch, it waits 150ms asynchronously (non-blocking, FC-203) and retries once to rule out transient IDE flushes before marking the contract POINTER_STALE — unless the contract is a read-only review/audit carrying a verified unified git_patch covering all pointer files (SELF_CONTAINED patch mode, FC-202), in which case it claims with an explicit workspace_warning and records __verified_on_disk__: "NO" and __unverified_pointers__ in verified_sha256.
• Pre-Flight Verify (`verify_contract`): A strictly read-only check allowing workers or scripts to audit pointer health (valid: true vs valid: false with dirty files list) before submitting.
• TOCTOU Soft-Failure Buffering: fulfill_contract checks on-disk pointer fingerprints. If dirty pointers are detected:
• Strike 1 returns RETRY_NEEDED, leaves the contract CLAIMED, renews the execution window, and lists dirty files with recovery instructions (git stash / git checkout -- ).
• Strike 2 transitions to terminal POINTER_STALE and saves the full submitted review payload into salvaged_result_json so review effort is never lost.
• TOCTOU Race Narrowing: While no file-based system can eliminate the microsecond race between reading disk bytes and committing a database row, FerryCat's dual-verification (at poll and at fulfill) drastically narrows the TOCTOU window from minutes of blind review down to the sub-millisecond atomic SQL transition boundary.

3. Bounded Schema Validation (RETRY_NEEDED $\le 2$)

• Outputs are validated against the contract's JSON Schema via cached Ajv validators, with errors flattened into concise single-line paths (e.g., ["/passed: must be boolean"]).
• Up to 2 validation failures return RETRY_NEEDED while keeping the contract CLAIMED for immediate self-correction (each rejection also renews the execution window); a 3rd failure transitions the contract to terminal VALIDATION_FAILED.

4. Dual-Stage TTL & Read-Before-Write Sweeping

• Separates queue_ttl_sec (default 1800s for SUBMITTED) from exec_ttl_sec (measured from claimed_at), preventing tasks claimed late in the queue window from timing out prematurely during execution.
• exec_ttl_sec defaults are tiered by task_type: code_review / architecture_audit → 1800s (deep reasoning or human-in-the-loop), implementation / test_generation → 300s. An explicit exec_ttl_sec always wins.
• poll_next_task executes a lock-free SELECT COUNT(*) pro