ferrycat 0.4.0 → 0.5.0

package/README.md

@@ -13,8 +13,8 @@
 [![Glama](https://img.shields.io/badge/Glama-MCP_Server-18181b?style=flat)](https://glama.ai/mcp/servers/GuoBug/FerryCat)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-> **FerryCat** (`ferrycat`) is a lightweight, deterministic cross-host AI agent handoff and code review bus 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 without context drift or blind reviews on stale files.
+> **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.
 
 <p align="center">
   <img src="https://guobug.github.io/assets/images/flowchart-ferrycat-cross-host-demand-and-workflow-en.svg" alt="FerryCat Architecture and Workflow" width="960" />
@@ -24,6 +24,26 @@
 
 ---
 
+## 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:
+
+```bash
+npx ferrycat demo
+```
+
+```text
+⚡ 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:
@@ -87,6 +107,8 @@ Every state transition is bound to an explicit SQL transaction with optimistic c
                     └───────────┘   └───────────────────┘ └───────────────┘
 ```
 
+> *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`):
 
 | Call | Transition | Guard rails |
@@ -97,7 +119,7 @@ Holder-side lifecycle controls on a `CLAIMED` contract (all require `agent_id ==
 
 ### 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` and retries once to rule out transient IDE flushes before marking the contract `POINTER_STALE`.
+- **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 -- <file>`).
@@ -135,7 +157,7 @@ Holder-side lifecycle controls on a `CLAIMED` contract (all require `agent_id ==
 
 ## Controlled Daemon & Declarative Handlers (ADR-0005)
 
-FerryCat provides a controlled daemon mode governed by SQLite microsecond CAS leases on `daemon_locks` and declarative scripts defined in `ferrycat.config.json`:
+FerryCat provides a controlled daemon mode governed by SQLite microsecond CAS leases on `daemon_locks` and declarative scripts defined in `ferrycat.config.json` (ideal for binding static analysis gates like `tsc` / `eslint` / AST checks or automated test suites like `Jest` / `Vitest` / `Pytest` as deterministic verification workers):
 
 ```bash
 # Run a single dispatch cycle with declared handlers
@@ -143,8 +165,13 @@ ferrycat-cli daemon --config ./ferrycat.config.json --once
 
 # Start continuous daemon loop
 ferrycat-cli daemon --config ./ferrycat.config.json
+
+# Inspect lease ownership + write-ahead journal health (read-only)
+ferrycat-cli daemon --status
 ```
 
+`daemon --status` reports `journal_degraded` / `last_journal_error` / `journal_path` / `journal_entries` alongside lease ownership, so a silently unwritable write-ahead journal (which would disarm crash recovery) is visible instead of failing mute.
+
 Example `ferrycat.config.json`:
 ```json
 {
@@ -210,7 +237,7 @@ Sandbox: /tmp/ferrycat-demo-c5iK6V
 
 ### 1. Recommended: Zero-Install MCP Mounting (via npx)
 
-No local clone or manual compilation required. Mount directly into your IDE's MCP configuration using `npx -y ferrycat`:
+No local clone or manual compilation required. Run `npx ferrycat init --yes` to auto-detect installed hosts (Antigravity, WorkBuddy, Cursor, VS Code, Windsurf, Claude Desktop, Claude Code) and safely merge the `ferrycat` server entry (with backup and JSONC protection), or mount manually into your IDE's MCP configuration using `npx -y ferrycat`:
 
 #### Antigravity Configuration
 Edit `%USERPROFILE%\.gemini\antigravity\mcp_config.json` (or `~/.gemini/antigravity/mcp_config.json` on macOS/Linux):
@@ -288,7 +315,25 @@ npx ferrycat verify <CONTRACT_ID>
 Poll the queue, claim tasks, and execute local review/test scripts with automatic failure closure:
 ```bash
 # Safely run a script upon task arrival (no shell quotation hazards)
-npx ferrycat worker --agent codex --mode=exec --exec-file ./scripts/review.sh
+npx ferrycat worker --agent codex --mode=exec --exec-file ./scripts/review.sh --delivery envelope
+# See docs/examples/ for dispatch.example.json, fulfill.example.json, and handler.example.cjs templates.
+```
+
+### 4. Zero-Config Sandbox Walkthrough (demo)
+Run the self-contained multi-agent lifecycle simulation without configuring an MCP server:
+```bash
+npx ferrycat demo
+```
+Options (`--keep` to retain SQLite for manual inspection, `--json` for CI assertions) detailed in [Quickstart §0](#0-see-what-it-actually-does-first-ferrycat-demo).
+
+### 5. Production Controlled Daemon (daemon, ADR-0005)
+Run the headless orchestration daemon coordinating background workers via atomic CAS leases and declarative script bindings:
+```bash
+# Launch daemon using project-local declarative configuration
+npx ferrycat daemon --config ./ferrycat.config.json
+
+# Run single poll/dispatch iteration for a targeted agent and exit
+npx ferrycat daemon --agent workbuddy --once
 ```
 
 ---
@@ -297,20 +342,22 @@ npx ferrycat worker --agent codex --mode=exec --exec-file ./scripts/review.sh
 
 | Tool Name | Role | Transactional Behavior |
 | :--- | :--- | :--- |
-| **`dispatch_contract`** | Requester | Enforces path blacklist $\to$ computes full-file SHA-256 & line bounds $\to$ inserts `SUBMITTED`. |
-| **`poll_next_task`** | Worker | Sweeps expired TTLs (read-before-write) $\to$ claims via `changes === 1` (`CLAIMED`) $\to$ verifies disk SHA-256 (or marks `POINTER_STALE`). |
+| **`dispatch_contract`** | Requester | Enforces path blacklist $\to$ computes full-file SHA-256 & line bounds (plus optional unified `git_patch` / `--patch-file` validation covering pointers, FC-202) $\to$ inserts `SUBMITTED`. |
+| **`poll_next_task`** | Worker | Sweeps expired TTLs (read-before-write) $\to$ claims via `changes === 1` (`CLAIMED`) $\to$ verifies disk SHA-256 with async 150ms retry (FC-203) or falls back to `SELF_CONTAINED` patch mode with `workspace_warning` (otherwise marks `POINTER_STALE`). |
 | **`fulfill_contract`** | Worker | Re-verifies SHA-256 (TOCTOU guard) $\to$ validates Ajv JSON Schema ($\le 2$ retries via `RETRY_NEEDED`, 3rd marks `VALIDATION_FAILED`) $\to$ marks `COMPLETED`. |
 | **`release_contract`** | Worker (holder) | Hands a `CLAIMED` contract back to the queue tail as `SUBMITTED`. `retry_count` is preserved (contract-level circuit breaker); `extend_count` is reset. Max 3 releases; refused once past the absolute lifetime deadline. |
 | **`extend_ttl`** | Worker (holder) | Heartbeat: restarts the execution window (`claimed_at = now`), max 5 renewals and bounded total lifetime. |
 | **`fail_contract`** | Worker (holder) | Marks a `CLAIMED` contract terminal `FAILED` with a mandatory `reason`. |
 | **`verify_contract`** | Worker / Any (Read-Only) | Pre-flight check: validates on-disk pointer files against the baseline SHA-256 without mutating contract state (ADR-0004). |
-| **`inspect_mesh_state`** | Any (Read-Only) | Pure read-only query of contract states, outputs, and dynamic `is_logically_expired` flags. |
+| **`inspect_mesh_state`** | Any (Read-Only) | Pure read-only query of contract states, outputs, `patch_sha256` / `patch_bytes` (opt-in `include_patch: true`), and dynamic `is_logically_expired` flags. |
 
 > 💡 **Architecture Decision Records & Engineering Verification**:
 > - [ADR-0001: Cross-Host SQLite WAL Bus & Human-Scheduled Poll Model](docs/adr/0001-cross-host-sqlite-wal-and-poll-model.md) (Why `node:sqlite` WAL + `poll_next_task` instead of 60s Blocking Hold or single-connection MCP Tasks)
 > - [ADR-0002: Full-File SHA-256 Fingerprinting, TOCTOU Guard & Cross-Model Audit](docs/adr/0002-fingerprint-toctou-and-cross-model-audit.md) (Stale-context prevention and real-world cross-host verification records)
 > - [ADR-0003: GUI Sandbox vs CLI Process Hybrid Layering Architecture & Wake-Up Boundaries](docs/adr/0003-gui-cli-hybrid-architecture.md) (Desktop HITL approval vs in-house CLI dual-channel autonomy)
-> - [ADR-0004: Separation of Review and Mutation (SRM), TOCTOU Soft-Failure Buffering & Immutable Baseline Protocol](docs/adr/0004-review-mutation-separation-and-toctou-buffer.md) (How to prevent review abortion from concurrent or well-intended reviewer edits)
+> - [ADR-0004: Separation of Review and Mutation (SRM), TOCTOU Soft-Failure Buffering & Immutable Baseline Protocol](docs/adr/0004-review-mutation-separation-and-toctou-buffer.md) (How to prevent review abortion from concurrent or well-intended reviewer edits; live mesh case: contract `fc_1793098036393_aea8bb9b`)
+> - [ADR-0005: Controlled Daemon, Atomic CAS Micro-Leases & Safe Execution Boundaries](docs/adr/0005-controlled-daemon-and-process-supervision.md) (Microsecond atomic CAS leases on `daemon_locks` and declarative whitelist handler enforcement)
+> - [ADR-0006: Dual-Track TOCTOU Semantics & Post-Mutation SHA-256 Fulfillment](docs/adr/0006-dual-track-mutation-fulfillment.md) (Why `implementation` / `test_generation` tasks commit post-mutation SHA-256 into `verified_sha256` while preserving pre-mutation baselines in `pointers`; live mesh case: `fc_1793100801409_4eedf544`)
 > - [FerryCat Requirements Backlog & Roadmap](docs/roadmap.md)
 
 ---

package/README_zh.md

@@ -13,8 +13,8 @@
 [![Glama](https://img.shields.io/badge/Glama-MCP_Server-18181b?style=flat)](https://glama.ai/mcp/servers/GuoBug/FerryCat)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-> **FerryCat** (`ferrycat`) 是一个基于 Model Context Protocol (MCP) 与 Node.js 内置 `node:sqlite`（WAL 并发模式）构建的轻量级、确定性跨宿主 AI Agent 工单交接与交叉评审总线。  
-> 专为解决单机桌面环境下不同 IDE 宿主（如 Google Antigravity、WorkBuddy、Claude Code、Cursor）因进程物理隔离导致的上下文割裂、未落盘代码静默盲审与非结构化交付痛点而设计。
+> **FerryCat** (`ferrycat`) 是一个基于 Model Context Protocol (MCP) 与 Node.js 内置 `node:sqlite`（WAL 并发模式）构建的轻量级、确定性跨宿主 AI Agent 工单交接、交叉评审与评测验证底座（Verification Harness）。  
+> 专为解决单机桌面环境下不同 IDE 宿主（如 Google Antigravity、WorkBuddy、Claude Code、Cursor）因进程物理隔离导致的上下文割裂、未落盘代码静默盲审与非结构化交付痛点而设计，支持构建 Actor-Critic 双智能体评测、静态分析守卫（Static Analysis Gate）与 SWE-bench 风格的补丁验证流水线。
 
 <p align="center">
   <img src="https://guobug.github.io/assets/images/flowchart-ferrycat-cross-host-demand-and-workflow.svg" alt="FerryCat 跨宿主契约摆渡全景" width="960" />
@@ -24,6 +24,26 @@
 
 ---
 
+## 60 秒看懂它 (Quick Glance)
+
+无需安装配置任何 IDE，无需修改配置文件，一条命令在系统临时目录跑通完整沙箱闭环：
+
+```bash
+npx ferrycat demo
+```
+
+```text
+⚡ 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!
+```
+> 💡 实测数据：2 秒真实拉起独立子进程沙箱、真实心跳续约 1 次、通过静态分析与验证守卫真实检出 `src/calc.ts:6` 的松散相等缺陷。详细参数（`--keep` / `--json` / `--no-color`）与底层机制见 [快速上手 §0](#0-先用一条命令看它到底是什么ferrycat-demo)。
+
+---
+
 ## 核心痛点与工程解法
 
 MCP 官方的 `Tasks` 规范（2025-11 / 2026-07）解决的是**单条 `Client ↔ Server` 连接内部**的长耗时任务状态跟踪，但无法解决桌面端跨宿主协同的四个物理难题：
@@ -87,6 +107,8 @@ MCP 官方的 `Tasks` 规范（2025-11 / 2026-07）解决的是**单条 `Client
                     └───────────┘   └───────────────────┘ └───────────────┘
 ```
 
+> *关于 `POINTER_STALE` 与 `SELF_CONTAINED` 补丁模式的边界说明 (FC-202)*：当磁盘文件与派单基线 SHA-256 不一致时，工单默认流转至终态 `POINTER_STALE`；**唯一例外**是只读审查类任务（`code_review` / `architecture_audit`）附带了同时通过三重闸门的统一差异补丁（`git_patch` / `--patch-file`）：每个声明文件块必须含至少一个带真实 `+`/`-` 内容的 `@@` hunk（否则 `EMPTY_PATCH_HUNKS` / `EMPTY_PATCH_CONTENT`），且补丁触及路径必须覆盖全部指针文件（否则 `PATCH_DOES_NOT_COVER_POINTERS`）。在此 `SELF_CONTAINED` 模式下，`poll_next_task` 返回 `patch_mode: "SELF_CONTAINED"` 及显式告警 `workspace_warning`，指示审查方以 `git_patch` 为准，且交单后 `verified_sha256` 显式标记 `__verified_on_disk__: "NO"` 与 `__unverified_pointers__`。
+
 持单方对 `CLAIMED` 工单的生命周期控制（均要求 `agent_id === target_agent`）：
 
 | 调用 | 状态流转 | 护栏 |
@@ -97,7 +119,7 @@ MCP 官方的 `Tasks` 规范（2025-11 / 2026-07）解决的是**单条 `Client
 
 ### 2. 全文件 SHA-256 指纹校验、预检与 TOCTOU 软失败缓冲 (ADR-0004)
 - **派单快照**：`dispatch_contract` 读取磁盘文件，记录字节数 `size`、全文件 `sha256`（64 位 hex）以及非空首末行 `first_line` / `last_line`。若文件在最近 3 秒内刚被修改，返回 `warning` 提醒确认 IDE 缓冲区已落盘。
-- **领单核验**：`poll_next_task` 严格按 `存在性 -> 字节数 size -> 全文件 sha256` 顺序核验（绝不以 `mtime` 单独判死刑，避免 IDE 无变更保存导致误杀）。若不一致，等待 `150ms` 重试一次排除瞬态写入，仍不一致则直接置为终态 `POINTER_STALE`。
+- **领单核验**：`poll_next_task` 严格按 `存在性 -> 字节数 size -> 全文件 sha256` 顺序核验（绝不以 `mtime` 单独判死刑，避免 IDE 无变更保存导致误杀）。若不一致，异步等待 `150ms` 重试一次（非阻塞，FC-203）排除瞬态写入；若仍不一致，除附带完整覆盖指针的 `git_patch` 只读任务降级为 `SELF_CONTAINED` 模式（附带 `workspace_warning`）外，其余直接置为终态 `POINTER_STALE`。
 - **只读预检 (`verify_contract`)**：纯只读命令，允许 Worker 或外部脚本在交单前核验指针健康度（返回 `valid: true/false` 与脏文件清单），不消耗工单状态。
 - **TOCTOU 软失败缓冲**：`fulfill_contract` 在交单时二次核验全文件指纹。若检测到脏指针：
   - **第 1 次超标（Strike 1）**：返回 `RETRY_NEEDED`，工单保持 `CLAIMED` 并自动续期执行窗口，返回脏文件清单与抢救指引（`git stash` / `git checkout -- <file>`）。
@@ -135,7 +157,7 @@ MCP 官方的 `Tasks` 规范（2025-11 / 2026-07）解决的是**单条 `Client
 
 ## 守护进程与声明式处理 (Controlled Daemon, ADR-0005)
 
-FerryCat 支持受控后台守护进程，通过 SQLite 微事务 CAS 租约锁实现多进程安全抢占与故障转移，并强制通过 `ferrycat.config.json` 静态绑定脚本处理器：
+FerryCat 支持受控后台守护进程，通过 SQLite 微事务 CAS 租约锁实现多进程安全抢占与故障转移，并强制通过 `ferrycat.config.json` 静态绑定脚本处理器（非常适合挂载 `tsc` / `eslint` / AST 静态分析守卫，或接入 `Jest` / `Vitest` / `Pytest` 自动化测试套件作为确定性验证 Worker）：
 
 ```bash
 # 单次轮询分发并执行已声明的处理脚本
@@ -143,6 +165,8 @@ ferrycat-cli daemon --config ./ferrycat.config.json --once
 
 # 启动后台守护主循环
 ferrycat-cli daemon --config ./ferrycat.config.json
+# 只读查询租约归属与预写日志健康度
+ferrycat-cli daemon --status
 ```
 
 配置文件形态示例（`ferrycat.config.json`）：
@@ -209,7 +233,7 @@ Sandbox: C:\Users\...\Temp\ferrycat-demo-c5iK6V
 
 ### 1. 推荐：零配置免安装挂载 (npx)
 
-无需手动克隆仓库或本地编译，直接在各 IDE 宿主的 MCP 配置文件中声明（基于全局或 `npx -y ferrycat`）：
+无需手动克隆仓库或本地编译。推荐直接运行 `npx ferrycat init --yes` 自动探测本机已安装的 IDE 宿主（Antigravity、WorkBuddy、Cursor、VS Code、Windsurf、Claude Desktop、Claude Code）并安全合并注入配置（自带原文件备份与 JSONC 注释保护），或在各 IDE 宿主的 MCP 配置文件中手动声明（基于全局或 `npx -y ferrycat`）：
 
 #### Antigravity 宿主配置
 编辑 `%USERPROFILE%\.gemini\antigravity\mcp_config.json`（macOS/Linux 为 `~/.gemini/antigravity/mcp_config.json`）：
@@ -287,7 +311,25 @@ npx ferrycat verify <CONTRACT_ID>
 监听契约队列并直接拉起本地脚本执行（支持安全脚本执行与非零退出自动熔断为 `FAILED`）：
 ```bash
 # 启动常驻 Worker 监听并自动执行指定脚本（无 Shell 注入风险）
-npx ferrycat worker --agent codex --mode=exec --exec-file ./scripts/review.sh
+npx ferrycat worker --agent codex --mode=exec --exec-file ./scripts/review.sh --delivery envelope
+# 标准载荷与 Handler 范例模板见 docs/examples/（dispatch.example.json / fulfill.example.json / handler.example.cjs）
+```
+
+### 4. 零配置一键沙箱演练 (demo)
+在系统临时目录中构建沙箱，验证两端 Agent 派单、认领、心跳保活与交单的完整流转：
+```bash
+npx ferrycat demo
+```
+完整参数（`--keep` 保留 SQLite 供手动 inspect、`--json` 供 CI 断言等）见 [快速上手 §0](#0-先用一条命令看它到底是什么ferrycat-demo)。
+
+### 5. 受控常驻守护进程（daemon，ADR-0005）
+脱离前台控制台，基于 SQLite WAL 短事务原子 CAS 租约与声明式配置自动拉起白名单脚本，无人值守但严格受控：
+```bash
+# 依据当前目录 ferrycat.config.json 启动常驻守护中枢
+npx ferrycat daemon --config ./ferrycat.config.json
+
+# 指定监听单一 Agent 且仅处理一次工单后退出（适合轻量调度）
+npx ferrycat daemon --agent workbuddy --once
 ```
 
 ---
@@ -296,20 +338,22 @@ npx ferrycat worker --agent codex --mode=exec --exec-file ./scripts/review.sh
 
 | 工具名 | 调用角色 | 职责与事务行为 |
 | :--- | :--- | :--- |
-| **`dispatch_contract`** | 发起方 (Requester) | 校验路径黑名单 $\to$ 计算全文件 SHA-256 与首末行快照 $\to$ 写入 `SUBMITTED`。 |
-| **`poll_next_task`** | 接收方 (Worker) | 先读后写清理超时工单 $\to$ `changes === 1` 原子抢占为 `CLAIMED` $\to$ 校验文件指纹（不匹配则置为 `POINTER_STALE`）。 |
+| **`dispatch_contract`** | 发起方 (Requester) | 校验路径黑名单 $\to$ 计算全文件 SHA-256 与首末行快照（以及可选的 `git_patch` / `--patch-file` 统一补丁及指针覆盖校验，FC-202）$\to$ 写入 `SUBMITTED`。 |
+| **`poll_next_task`** | 接收方 (Worker) | 先读后写清理超时工单 $\to$ `changes === 1` 原子抢占为 `CLAIMED` $\to$ 校验文件指纹（含 150ms 异步重试 FC-203；只读任务附带完整覆盖指针的 `git_patch` 时进入 `SELF_CONTAINED` 模式并返回 `workspace_warning`，否则置为 `POINTER_STALE`）。 |
 | **`verify_contract`** | 接收方 / 任意方 (Read-Only) | 只读预检：校验磁盘文件指纹与基线是否一致，不变更任何状态（ADR-0004）。 |
 | **`fulfill_contract`** | 接收方 (Worker) | 二次复核文件指纹（TOCTOU 软失败缓冲：Strike 1 返回 `RETRY_NEEDED`，Strike 2 置为 `POINTER_STALE` 并在 `salvaged_result` 抢救产出）$\to$ 校验 Ajv JSON Schema $\to$ 通过则置为 `COMPLETED`。 |
 | **`release_contract`** | 持单方 (Worker) | 将 `CLAIMED` 工单退回队尾重新置为 `SUBMITTED`。保留 `retry_count`（工单级熔断配额），清零 `extend_count`。最多退回 3 次；超出绝对生命期上限时拒绝。 |
 | **`extend_ttl`** | 持单方 (Worker) | 心跳续期：重置执行窗口（`claimed_at = now`），最多 5 次，总生命周期有上限。 |
 | **`fail_contract`** | 持单方 (Worker) | 携带必填 `reason` 将 `CLAIMED` 工单置为终态 `FAILED`。 |
-| **`inspect_mesh_state`** | 任意方 (Read-Only) | 纯只读查询工单状态、结构化产出与错误原因，动态计算 `is_logically_expired`。 |
+| **`inspect_mesh_state`** | 任意方 (Read-Only) | 纯只读查询工单状态、结构化产出、`patch_sha256` / `patch_bytes`（可通过 `include_patch: true` 显式读取补丁正文）与错误原因，动态计算 `is_logically_expired`。 |
 
 > 💡 **架构决策记录 (ADR) 与工程验证沉淀**：
 > - [ADR-0001: 采用跨宿主 SQLite WAL 总线与人工调度即时轮询模型](docs/adr/0001-cross-host-sqlite-wal-and-poll-model_zh.md)（为什么采用 `node:sqlite` WAL + `poll_next_task`，而非 60s 长轮询挂起或单连接 MCP Tasks）
 > - [ADR-0002: 全文件 SHA-256 指纹防盲审、TOCTOU 闭合与跨宿主多模型实测记录](docs/adr/0002-fingerprint-toctou-and-cross-model-audit_zh.md)（指针陈旧防护设计与 3 模型真实互审复盘记录）
 > - [ADR-0003: GUI 沙箱与 CLI 进程混合分层架构、唤醒边界与双通道 Worker 选型](docs/adr/0003-gui-cli-hybrid-architecture_zh.md)（桌面人在回路审批闸 vs 自研 CLI 双通道自治）
-> - [ADR-0004: 审议分离协议、TOCTOU 软失败缓冲与审查期不可变基线规范](docs/adr/0004-review-mutation-separation-and-toctou-buffer_zh.md)（如何彻底规避审查者“边审边修”或并发写入引发的工单报废）
+> - [ADR-0004: 审议分离协议、TOCTOU 软失败缓冲与审查期不可变基线规范](docs/adr/0004-review-mutation-separation-and-toctou-buffer_zh.md)（如何彻底规避审查者“边审边修”或并发写入引发的工单报废；真实案例见 2026-10-27 真实总线工单 `fc_1793098036393_aea8bb9b` 漂移拦截）
+> - [ADR-0005: 受控守护进程、短事务 CAS 租约与安全执行边界](docs/adr/0005-controlled-daemon-and-process-supervision_zh.md)（微秒级原子 CAS 租约如何防死锁、声明式 handler 如何将任意 Shell 注入面彻底收敛）
+> - [ADR-0006: 读写双轨 TOCTOU 语义与变更型任务双哈希交单存证协议](docs/adr/0006-dual-track-mutation-fulfillment_zh.md)（为什么 `implementation` / `test_generation` 任务在 `pointers` 保留修改前基线并在 `verified_sha256` 落库修改后产物哈希；实战案例：`fc_1793100801409_4eedf544`）
 > - [FerryCat 演进路线图 (Roadmap)](docs/roadmap_zh.md)
 
 ---

package/bin/ferrycat.js

@@ -12,6 +12,7 @@ if (major < 22 || (major === 22 && minor < 5)) {
 
 const CLI_SUBCOMMANDS = new Set([
   'demo',
+  'init',
   'dispatch',
   'poll',
   'verify',

package/dist/cli.js

@@ -6,6 +6,7 @@ import { ZodError } from 'zod';
 import { expandTilde, FerryCatEngine } from './engine.js';
 import { FerryCatDaemon } from './daemon.js';
 import { runDemo } from './demo.js';
+import { runInit } from './init.js';
 import { executeTaskAndFulfill, terminateActiveChildrenSync, } from './supervisor.js';
 import { DispatchContractSchema, ExtendTtlSchema, FailContractSchema, FulfillContractSchema, InspectMeshStateSchema, PollNextTaskSchema, ReleaseContractSchema, VerifyContractSchema, WorkerCommandSchema, } from './schemas.js';
 function loadPackageVersion() {
@@ -37,6 +38,7 @@ Commands:
   worker      Run background watcher, single-shot claim, or automated script execution
   daemon      Run multi-tenant production daemon with CAS micro-lease and declarative handlers (ADR-0005)
   demo        Zero-config sandbox walkthrough of the full contract lifecycle (no MCP setup needed)
+  init        Detect installed MCP hosts (Antigravity, WorkBuddy, Cursor, VS Code, ...) and add FerryCat to them
 
 Common Options:
   --agent <id>              Agent identity (overrides AGENT_NAME env var)
@@ -58,16 +60,18 @@ Examples:
   # 4. Run worker in explicit mode (watch | claim | exec) with quote-free --exec-file
   ferrycat-cli worker --agent workbuddy --mode=exec --once --exec-file ./scripts/review.js`;
 const SUBCOMMAND_HELP = {
-    dispatch: `Usage: ferrycat-cli dispatch [--agent <requester>] [--file <path|->] ['{...}']
+    dispatch: `Usage: ferrycat-cli dispatch [--agent <requester>] [--patch-file <path>] [--file <path|->] ['{...}']
 
 Dispatches a new contract and computes full-file SHA-256 fingerprints for all pointer files.
 
 Options:
-  --agent <id>        Requester agent identifier (overrides requester_agent in payload)
-  --file <path | ->   JSON payload file path, or "-" to read from stdin
+  --agent <id>          Requester agent identifier (overrides requester_agent in payload)
+  --patch-file <path>   Optional unified git diff file path to attach as self-contained git_patch (FC-202)
+  --file <path | ->     JSON payload file path, or "-" to read from stdin
 
 Examples:
   ferrycat-cli dispatch --file dispatch.json
+  ferrycat-cli dispatch --file dispatch.json --patch-file changes.patch
   cat dispatch.json | ferrycat-cli dispatch --agent antigravity -`,
     poll: `Usage: ferrycat-cli poll [--agent <worker_id>]
 
@@ -159,7 +163,7 @@ Options:
 Examples:
   ferrycat-cli inspect --target workbuddy --status ACTIVE
   ferrycat-cli inspect --id fc_123 --json`,
-    worker: `Usage: ferrycat-cli worker [--agent <id>] [--mode <watch|claim|exec>] [--once] [--interval <ms>] [--exec <cmd>] [--exec-file <script>]
+    worker: `Usage: ferrycat-cli worker [--agent <id>] [--mode <watch|claim|exec>] [--once] [--interval <ms>] [--exec <cmd>] [--exec-file <script>] [--pass-env <NAME>] [--delivery <auto|envelope>]
 
 Runs the FerryCat CLI worker in watcher, single-claim, or automated execution mode.
 
@@ -173,12 +177,23 @@ Options:
   --interval <ms>           Polling interval in milliseconds for persistent loop (>= 100, default: 1000)
   --exec-file <script>      Recommended: script file (.js/.mjs/.cjs/.ts/.ps1/.sh) executed directly via execFile without shell interpolation
   --exec <cmd>              Shell command to run on claim (UNSAFE: executes via system shell, contract JSON piped via stdin)
+  --pass-env <NAME>         Forward an extra host env var into the child (repeatable)
+  --delivery <auto|envelope>
+                            How child stdout becomes the deliverable (REQ-ENG-04):
+                              auto:     {"ferrycat_delivery":{...}} envelope, or a JSON object with
+                                        result_summary / structured_output, or plain text (default)
+                              envelope: only the ferrycat_delivery envelope is accepted; anything
+                                        else marks the contract FAILED (stdout is salvaged)
+
+Delivery envelope (one stdout line, other lines are treated as logs):
+  {"ferrycat_delivery":{"result_summary":"...","structured_output":{...}}}
 
 Examples:
   ferrycat-cli worker --agent workbuddy --mode=watch
   ferrycat-cli worker --agent workbuddy --mode=claim
-  ferrycat-cli worker --agent workbuddy --mode=exec --once --exec-file ./worker-handler.js`,
-    daemon: `Usage: ferrycat-cli daemon [--config <path>] [--agent <id>] [--once] [--lease-ttl <sec>] [--interval <ms>]
+  ferrycat-cli worker --agent workbuddy --mode=exec --once --exec-file ./worker-handler.js
+  ferrycat-cli worker --agent workbuddy --mode=exec --exec-file ./handler.js --delivery envelope`,
+    daemon: `Usage: ferrycat-cli daemon [--config <path>] [--agent <id>] [--once] [--status] [--lease-ttl <sec>] [--interval <ms>]
 
 Runs the FerryCat production daemon (ADR-0005). Coordinates background workers using short-transaction
 CAS leases on the daemon_locks table and executes declarative scripts defined in ferrycat.config.json.
@@ -187,13 +202,16 @@ Options:
   --config <path>           Path to ferrycat.config.json (defaults to ./ferrycat.config.json or ~/.ferrycat/config.json)
   --agent <id>              Optional target agent filter (overrides config defaults)
   --once                    Run a single dispatch cycle and exit
+  --status                  Print lease ownership and write-ahead journal health (journal_degraded,
+                            last_journal_error, journal_path, entries) as JSON, then exit. Read-only.
   --lease-ttl <sec>         Daemon CAS lease TTL in seconds (default: 30)
   --interval <ms>           Poll interval in milliseconds (default: 1000)
   --no-notify               Disable console notices
 
 Examples:
   ferrycat-cli daemon --config ./ferrycat.config.json
-  ferrycat-cli daemon --agent workbuddy --once`,
+  ferrycat-cli daemon --agent workbuddy --once
+  ferrycat-cli daemon --status`,
     demo: `Usage: ferrycat-cli demo [--json] [--keep] [--no-color]
 
 Runs a complete contract lifecycle (dispatch -> claim -> supervised execution -> TOCTOU
@@ -211,6 +229,45 @@ Examples:
   ferrycat-cli demo
   ferrycat-cli demo --json
   ferrycat-cli demo --keep`,
+    init: `Usage: ferrycat-cli init [--client <id>]... [--agent <name>] [--config-path <file>] [--local] [--yes] [--dry-run] [--force] [--list] [--server-name <key>] [--json]
+
+Detects locally installed MCP hosts and merges a "ferrycat" stdio server entry
+({"command":"npx","args":["-y","ferrycat"],"env":{"AGENT_NAME":"<host>"}}) into each host's
+MCP config file. Each host gets its own AGENT_NAME so contracts can be routed between them.
+
+Supported hosts (--client ids):
+  antigravity     ~/.gemini/antigravity/mcp_config.json
+  workbuddy       ~/.workbuddy/.mcp.json (or ~/.workbuddy/mcp.json if already present)
+  cursor          ~/.cursor/mcp.json
+  vscode          <AppData>/Code/User/mcp.json        ("servers" format, type: stdio)
+  windsurf        ~/.codeium/windsurf/mcp_config.json
+  claude-desktop  <AppData>/Claude/claude_desktop_config.json
+  claude-code     ./.mcp.json (project scope, current directory)
+
+Safety:
+  - Unparseable configs (comments / broken JSON) are never rewritten; the snippet is printed instead.
+  - An existing, different "ferrycat" entry is kept unless --force is given.
+  - Existing files are backed up as <file>.ferrycat-bak-<timestamp> before writing.
+  - In a non-interactive shell without --yes, init only prints the plan (dry run).
+
+Options:
+  --client <id>         Only configure these hosts (repeatable or comma-separated). Hosts that
+                        are not detected are configured only when named explicitly.
+  --agent <name>        Override AGENT_NAME for all selected hosts (default: the host id)
+  --config-path <file>  Override target config file path (requires a single --client)
+  --local               Point at this checkout's local dist/index.js instead of npx -y ferrycat
+  --yes, -y             Apply without per-host confirmation
+  --dry-run             Show what would change without writing
+  --force               Replace an existing, different "ferrycat" entry
+  --list                Only print detection results
+  --server-name <key>   MCP server key to write (default: ferrycat)
+  --json                Emit the structured result
+
+Examples:
+  ferrycat-cli init
+  ferrycat-cli init --list
+  ferrycat-cli init --client workbuddy --client antigravity --yes
+  ferrycat-cli init --client cursor --agent cursor-reviewer --dry-run`,
 };
 function stripBom(content) {
     return content.replace(/^\uFEFF/, '');
@@ -373,7 +430,16 @@ function parseArgs(argv) {
             flagOverrides.claim_token = requireFlagValue(token, rest[++i]);
         }
         else if (token === '--status') {
-            flagOverrides.status = requireFlagValue('--status', rest[++i]);
+            // Dual purpose: `inspect --status <STATUS>` filters by contract status, while
+            // `daemon --status` is a bare boolean that prints lease + journal health.
+            const next = rest[i + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                flagOverrides.status = next;
+                i += 1;
+            }
+            else {
+                flagOverrides.status = true;
+            }
         }
         else if (token === '--reason') {
             flagOverrides.reason = requireFlagValue('--reason', rest[++i]);
@@ -381,6 +447,14 @@ function parseArgs(argv) {
         else if (token === '--summary') {
             flagOverrides.result_summary = requireFlagValue('--summary', rest[++i]);
         }
+        else if (token === '--patch-file') {
+            const patchPath = requireFlagValue('--patch-file', rest[++i]);
+            const resolvedPatch = path.resolve(expandTilde(patchPath));
+            if (!fs.existsSync(resolvedPatch)) {
+                throw new Error(`Patch file not found: "${patchPath}" (resolved: "${resolvedPatch}").`);
+            }
+            flagOverrides.git_patch = fs.readFileSync(resolvedPatch, 'utf8');
+        }
         else if (token === '--limit') {
             const rawLimit = requireFlagValue('--limit', rest[++i]);
             const num = Number(rawLimit);
@@ -427,6 +501,40 @@ function parseArgs(argv) {
             }
             flagOverrides.exec_file = scriptPath;
         }
+        else if (token === '--client') {
+            const clientId = requireFlagValue('--client', rest[++i]).trim();
+            const existing = flagOverrides.clients ?? [];
+            existing.push(...clientId.split(',').map((c) => c.trim()).filter(Boolean));
+            flagOverrides.clients = existing;
+        }
+        else if (token === '--server-name') {
+            flagOverrides.server_name = requireFlagValue('--server-name', rest[++i]).trim();
+        }
+        else if (token === '--config-path') {
+            flagOverrides.config_path = requireFlagValue('--config-path', rest[++i]).trim();
+        }
+        else if (token === '--local') {
+            flagOverrides.local = true;
+        }
+        else if (token === '--yes' || token === '-y') {
+            flagOverrides.yes = true;
+        }
+        else if (token === '--dry-run') {
+            flagOverrides.dry_run = true;
+        }
+        else if (token === '--force') {
+            flagOverrides.force = true;
+        }
+        else if (token === '--list') {
+            flagOverrides.list = true;
+        }
+        else if (token === '--delivery') {
+            const mode = requireFlagValue('--delivery', rest[++i]).trim();
+            if (mode !== 'auto' && mode !== 'envelope') {
+                throw new Error(`Invalid --delivery "${mode}": expected "auto" or "envelope".`);
+            }
+            flagOverrides.delivery = mode;
+        }
         else if (token === '--pass-env') {
             const varName = requireFlagValue('--pass-env', rest[++i]).trim();
             if (!varName) {
@@ -567,7 +675,7 @@ async function runWorkerLoop(engine, agentId, intervalMs, spec) {
     while (running) {
         try {
             if (hasExec) {
-                const pollRes = engine.pollNextTask({ agent_id: resolvedAgent });
+                const pollRes = await engine.pollNextTask({ agent_id: resolvedAgent });
                 if (pollRes.has_task && pollRes.contract) {
                     console.log(JSON.stringify({
                         event: 'TASK_CLAIMED',
@@ -794,7 +902,7 @@ async function main() {
             }
             case 'poll': {
                 engine = new FerryCatEngine();
-                output = engine.pollNextTask(PollNextTaskSchema.parse(data));
+                output = await engine.pollNextTask(PollNextTaskSchema.parse(data));
                 console.log(JSON.stringify(output, null, 2));
                 break;
             }
@@ -881,10 +989,11 @@ async function main() {
                     execCmd: validated.exec,
                     execFile: validated.exec_file,
                     passEnv: validated.pass_env,
+                    delivery: validated.delivery,
                 };
                 engine = new FerryCatEngine();
                 if (effectiveOnce) {
-                    const pollRes = engine.pollNextTask({ agent_id: resolvedAgent });
+                    const pollRes = await engine.pollNextTask({ agent_id: resolvedAgent });
                     if (!pollRes.has_task || !pollRes.contract) {
                         // Preserve engine's specific poll status/message/stale_error (fixes G8)
                         output = {
@@ -924,6 +1033,7 @@ async function main() {
                 const configPath = data.config;
                 const targetAgent = data.target_agent ?? data.agent_id;
                 const once = Boolean(data.once);
+                const wantStatus = Boolean(data.status);
                 const leaseTtl = data.lease_ttl_sec ? Number(data.lease_ttl_sec) : undefined;
                 const intervalMs = data.interval_ms ? Number(data.interval_ms) : undefined;
                 const notify = data.notify !== false;
@@ -934,11 +1044,18 @@ async function main() {
                     pollIntervalMs: intervalMs,
                     notify,
                 });
-                if (once) {
+                if (wantStatus) {
+                    // R7: read-only inspection of lease ownership + write-ahead journal health.
+                    const status = daemon.getStatus();
+                    daemon.engine.close();
+                    console.log(JSON.stringify({ ok: true, daemon_status: status }, null, 2));
+                }
+                else if (once) {
                     const res = await daemon.pollAndDispatchOnce();
+                    const status = daemon.getStatus();
                     daemon.releaseLease();
                     daemon.engine.close();
-                    output = { ok: true, daemon_once: res };
+                    output = { ok: true, daemon_once: res, journal_degraded: status.journal_degraded };
                     console.log(JSON.stringify(output, null, 2));
                 }
                 else {
@@ -948,6 +1065,32 @@ async function main() {
                 }
                 break;
             }
+            case 'init': {
+                const serverName = data.server_name;
+                if (serverName !== undefined && !/^[A-Za-z0-9_.-]{1,64}$/.test(serverName)) {
+                    throw new Error(`Invalid --server-name "${serverName}": use 1-64 chars of [A-Za-z0-9_.-].`);
+                }
+                const initResult = await runInit({
+                    clients: data.clients,
+                    agent: data.agent_id,
+                    serverName,
+                    configPath: data.config_path,
+                    local: Boolean(data.local),
+                    yes: Boolean(data.yes),
+                    dryRun: Boolean(data.dry_run),
+                    force: Boolean(data.force),
+                    list: Boolean(data.list),
+                    json: parsed.format === 'json',
+                    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                });
+                if (parsed.format === 'json') {
+                    console.log(JSON.stringify(initResult, null, 2));
+                }
+                if (!initResult.ok) {
+                    process.exitCode = 1;
+                }
+                break;
+            }
             case 'demo': {
                 const demoResult = await runDemo({
                     json: parsed.format === 'json',
@@ -963,7 +1106,7 @@ async function main() {
                 break;
             }
             default:
-                throw new Error(`Unknown subcommand "${command}". Supported commands: dispatch, poll, verify, fulfill, release, extend, fail, inspect, worker, daemon, demo. Run "ferrycat-cli --help" for usage.`);
+                throw new Error(`Unknown subcommand "${command}". Supported commands: dispatch, poll, verify, fulfill, release, extend, fail, inspect, worker, daemon, demo, init. Run "ferrycat-cli --help" for usage.`);
         }
     }
     catch (err) {