ferrycat 0.3.1 → 0.3.3

package/README.md

@@ -5,6 +5,8 @@
   <a href="README_zh.md">中文</a>
 </p>
 
+[![npm version](https://img.shields.io/npm/v/ferrycat.svg?style=flat&color=cb3837&logo=npm)](https://www.npmjs.com/package/ferrycat)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-Active-10b981?style=flat)](https://registry.modelcontextprotocol.io/v0/servers?search=ferrycat)
 [![Node.js Version](https://img.shields.io/badge/Node.js-22.5%2B-339933?style=flat&logo=nodedotjs)](https://nodejs.org/)
 [![Native Addons](https://img.shields.io/badge/Native_Addons-0_(node%3Asqlite)-success?style=flat)]()
 [![Protocol](https://img.shields.io/badge/Protocol-MCP_Stdio-orange?style=flat)](https://modelcontextprotocol.io/)
@@ -15,7 +17,7 @@
 > 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.
 
 <p align="center">
-  <img src="https://guobug.github.io/assets/images/flowchart-ferrycat-cross-host-demand-and-workflow.svg" alt="FerryCat Architecture and Workflow" width="960" />
+  <img src="https://guobug.github.io/assets/images/flowchart-ferrycat-cross-host-demand-and-workflow-en.svg" alt="FerryCat Architecture and Workflow" width="960" />
 </p>
 
 > 📖 **Deep Dive**: [Why I Started Building FerryCat: When Two AI Coding Hosts Live on the Same Desktop](https://guobug.github.io/posts/2026/10/22/why-we-built-ferrycat-cross-host-agent-review-bus/)
@@ -118,6 +120,7 @@ Holder-side lifecycle controls on a `CLAIMED` contract (all require `agent_id ==
 ### 6. Threat Model & Security Assumptions (Local Workstation IPC)
 - **Assumed Trust Environment**: FerryCat is intentionally designed as a **Trusted Local Workstation Bus** bridging isolated IDE hosts operating under the **same OS user account**. Callers and workers share the local file system (`workspace_root`) and SQLite database (`~/.ferrycat/mesh.db`).
 - **Defense Scope**: Path containment (`assertSafePointerPath`) and sensitive file pattern filters prevent unintentional workspace escapes, symlink traversals, or accidental leakage of credentials/secret files during handoffs.
+- **Daemon Execution Surface**: In daemon mode (`ferrycat-cli daemon`), handler scripts are invoked directly via `execFile`. Write permissions to `ferrycat.config.json` or handler script paths are equivalent to host execution privileges (ADR-0005 §2.2). Keep configurations local and version-controlled.
 - **Out of Scope (Non-Goals)**: FerryCat does **not** provide adversarial sandboxing, multi-tenant isolation, or network authorization against malicious local processes or adversarial agents spoofing `AGENT_NAME`.
 
 ---
@@ -126,32 +129,61 @@ Holder-side lifecycle controls on a `CLAIMED` contract (all require `agent_id ==
 
 1. **Disjoint File Systems**: FerryCat offloads context by file reference; both hosts must share access to the same local `workspace_root`.
 2. **Trivial Single-Turn Queries**: Each cross-host handoff involves 3 explicit human window switches (~15–25s overhead).
-3. **Unattended Background Pipelines**: Desktop IDE hosts follow a request-response model and cannot be woken up asynchronously by an idle MCP server. For unattended multi-step pipelines, use a standalone DAG workflow engine such as [PatchCat](https://github.com/GuoBug/ai-prompt-orchestrator).
+3. **Multi-Step Dynamic DAG Pipelines**: FerryCat's background daemon (`ferrycat-cli daemon`, ADR-0005) manages single-step contract dispatch and supervised worker lifecycles; for complex multi-step branching DAG orchestrations, use dedicated DAG workflow engines such as [PatchCat](https://github.com/GuoBug/ai-prompt-orchestrator).
 
 ---
 
-## Quickstart
+## 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`:
 
-### 1. Build & Verify
 ```bash
-git clone https://github.com/GuoBug/FerryCat.git
-cd FerryCat
-npm install
-npm run build
-npm test
+# Run a single dispatch cycle with declared handlers
+ferrycat-cli daemon --config ./ferrycat.config.json --once
+
+# Start continuous daemon loop
+ferrycat-cli daemon --config ./ferrycat.config.json
+```
+
+Example `ferrycat.config.json`:
+```json
+{
+  "version": 1,
+  "daemon": {
+    "poll_interval_ms": 1000,
+    "lease_ttl_sec": 30,
+    "heartbeat_interval_ms": 10000,
+    "notify": true
+  },
+  "agents": {
+    "workbuddy": {
+      "handlers": {
+        "code_review": {
+          "exec_file": "./scripts/review-handler.js",
+          "pass_env": ["CUSTOM_ANALYZER_PATH"]
+        }
+      }
+    }
+  }
+}
 ```
 
-### 2. Mount in Antigravity
+---
+
+## Quickstart
+
+### 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`:
+
+#### Antigravity Configuration
 Edit `%USERPROFILE%\.gemini\antigravity\mcp_config.json` (or `~/.gemini/antigravity/mcp_config.json` on macOS/Linux):
 ```json
 {
   "mcpServers": {
     "ferrycat": {
-      "command": "node",
-      "args": [
-        "--experimental-sqlite",
-        "F:/git/FerryCat/dist/index.js"
-      ],
+      "command": "npx",
+      "args": ["-y", "ferrycat"],
       "env": {
         "AGENT_NAME": "antigravity"
       }
@@ -160,17 +192,14 @@ Edit `%USERPROFILE%\.gemini\antigravity\mcp_config.json` (or `~/.gemini/antigrav
 }
 ```
 
-### 3. Mount in WorkBuddy / Claude Code / Cursor
+#### WorkBuddy / Claude Code / Cursor / Codex Configuration
 Configure the target host's MCP settings with its respective `AGENT_NAME`:
 ```json
 {
   "mcpServers": {
     "ferrycat": {
-      "command": "node",
-      "args": [
-        "--experimental-sqlite",
-        "F:/git/FerryCat/dist/index.js"
-      ],
+      "command": "npx",
+      "args": ["-y", "ferrycat"],
       "env": {
         "AGENT_NAME": "workbuddy"
       }
@@ -178,7 +207,53 @@ Configure the target host's MCP settings with its respective `AGENT_NAME`:
   }
 }
 ```
-> **Note**: Both MCP Stdio and direct CLI invocation (`ferrycat-cli <dispatch|poll|verify|fulfill|release|extend|fail|inspect|worker>`) share the same SQLite WAL database at `~/.ferrycat/mesh.db` and the same Zod validation schemas. CLI supports `--help` tree, stdin payloads (`--file -` or `-`), `verify` pre-flight check, `inspect` ASCII table formatting (`--target <agent>`), `worker --mode=watch|claim|exec` and direct script execution via `--exec-file <script>`. In `worker --exec` mode, a non-zero exit of the child command closes the contract as `FAILED` instead of leaving it `CLAIMED` until the TTL sweep.
+
+### 2. Global Installation & Source Build
+
+- **Global CLI Installation**:
+  ```bash
+  npm install -g ferrycat
+  ```
+  Then simply set `"command": "ferrycat"` in your MCP config.
+- **Local Source Build (For Contributors)**:
+  ```bash
+  git clone https://github.com/GuoBug/FerryCat.git
+  cd FerryCat
+  npm install
+  npm run build
+  npm test
+  ```
+  Mount using your local path:
+  `"command": "node"`, `"args": ["--experimental-sqlite", "/path/to/FerryCat/dist/index.js"]`.
+
+---
+
+## First-Class CLI Experience (`ferrycat-cli`)
+
+Beyond serving as an in-IDE MCP Server, FerryCat provides a first-class CLI utility (`ferrycat-cli` or `npx ferrycat-cli`). Sharing the same `~/.ferrycat/mesh.db` SQLite WAL database and Zod validation contracts, the CLI allows developers to inspect mesh health, verify working tree safety, and hook into automated CI/Git scripts without leaving their terminal:
+
+### 1. Terminal Visual Inspection (ASCII Status Table)
+Inspect all cross-host handoffs and error reasons formatted as an ASCII table:
+```bash
+# View all contracts in an ASCII table
+npx ferrycat-cli inspect
+
+# Filter by target agent (e.g., only tasks for antigravity)
+npx ferrycat-cli inspect --target antigravity
+```
+
+### 2. Pre-Flight Verification (Auditing Before Mutation)
+Audit on-disk pointer file integrity against the contract's baseline SHA-256 before committing review work (ADR-0004), eliminating false-positive deliveries:
+```bash
+npx ferrycat-cli verify <CONTRACT_ID>
+```
+
+### 3. Local CI & Headless Worker Execution
+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-cli worker --agent codex --mode=exec --exec-file ./scripts/review.sh
+```
 
 ---
 

package/README_zh.md

@@ -5,6 +5,8 @@
   <b>中文</b>
 </p>
 
+[![npm version](https://img.shields.io/npm/v/ferrycat.svg?style=flat&color=cb3837&logo=npm)](https://www.npmjs.com/package/ferrycat)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-Active-10b981?style=flat)](https://registry.modelcontextprotocol.io/v0/servers?search=ferrycat)
 [![Node.js Version](https://img.shields.io/badge/Node.js-22.5%2B-339933?style=flat&logo=nodedotjs)](https://nodejs.org/)
 [![Native Addons](https://img.shields.io/badge/Native_Addons-0_(node%3Asqlite)-success?style=flat)]()
 [![Protocol](https://img.shields.io/badge/Protocol-MCP_Stdio-orange?style=flat)](https://modelcontextprotocol.io/)
@@ -118,6 +120,7 @@ MCP 官方的 `Tasks` 规范（2025-11 / 2026-07）解决的是**单条 `Client
 ### 6. 威胁模型与安全边界声明 (同机同用户受信 IPC)
 - **环境信任假设**：FerryCat 定位为**面向同机同操作系统用户的跨宿主 AI 开发者协作总线**。所有 IDE 宿主与 Worker 均运行在同一本地用户权限下，共享本地工作区（`workspace_root`）与本地 SQLite 文件（`~/.ferrycat/mesh.db`）。
 - **防护范畴**：双端路径防逃逸（`assertSafePointerPath`）与敏感文件模式黑名单旨在防范跨宿主误触敏感配置（如 `.env`、SSH 密钥）、软链接越界与无意识的目录逃逸。
+- **守护进程执行面**：在守护进程模式（`ferrycat-cli daemon`）下，处理脚本通过 `execFile` 直接执行。`ferrycat.config.json` 或处理脚本所在目录的写权限等价于宿主代码执行权限（详见 ADR-0005 §2.2），请确保配置文件置于本地受信任路径。
 - **非防护目标**：FerryCat **不作为**面向不受信外部网络、多租户强隔离或恶意本地进程伪造 `AGENT_NAME` 的零信任安全网关。
 
 ---
@@ -126,34 +129,61 @@ MCP 官方的 `Tasks` 规范（2025-11 / 2026-07）解决的是**单条 `Client
 
 1. **两端不共享同一本地文件系统**：FerryCat 依赖按引用传递文件指针（Context Offloading by Reference），要求双方能访问同一份 `workspace_root`。
 2. **单轮简单问答即可解决的任务**：每次跨宿主交接需要 3 次人工窗口切换（约 15~25 秒操作开销），简单问题直接在单个 IDE 内完成即可。
-3. **需要无人值守全自动流水线的场景**：桌面 IDE 宿主受限于请求-响应模型，无法在空闲时被 MCP 服务端主动推流唤醒；若需无人值守编排，请使用独立的 DAG 状态机工作流引擎（如 [PatchCat](https://github.com/GuoBug/ai-prompt-orchestrator)）。
+3. **跨步骤复杂有向图编排**：FerryCat 的守护进程（`ferrycat-cli daemon`）负责同机多 Agent 之间的单步契约分发与进程生命周期托管；若需跨多步骤的复杂动态 DAG 有向无环图分支编排，请使用专门的工作流引擎（如 [PatchCat](https://github.com/GuoBug/ai-prompt-orchestrator)）。
 
 ---
 
-## 快速上手
+## 守护进程与声明式处理 (Controlled Daemon, ADR-0005)
+
+FerryCat 支持受控后台守护进程，通过 SQLite 微事务 CAS 租约锁实现多进程安全抢占与故障转移，并强制通过 `ferrycat.config.json` 静态绑定脚本处理器：
 
-### 1. 安装与编译测试
 ```bash
-git clone https://github.com/GuoBug/FerryCat.git
-cd FerryCat
-npm install
-npm run build
-npm test
+# 单次轮询分发并执行已声明的处理脚本
+ferrycat-cli daemon --config ./ferrycat.config.json --once
+
+# 启动后台守护主循环
+ferrycat-cli daemon --config ./ferrycat.config.json
 ```
 
-> **关于 `--experimental-sqlite`**：启动参数中恒定携带 `--experimental-sqlite`，以同时兼容 Node 22.12 LTS（需 flag）与 Node 22.22+ / Node 24+（原生免 flag，携带亦不报错），实现零原生 C++ 编译依赖。
+配置文件形态示例（`ferrycat.config.json`）：
+```json
+{
+  "version": 1,
+  "daemon": {
+    "poll_interval_ms": 1000,
+    "lease_ttl_sec": 30,
+    "heartbeat_interval_ms": 10000,
+    "notify": true
+  },
+  "agents": {
+    "workbuddy": {
+      "handlers": {
+        "code_review": {
+          "exec_file": "./scripts/review-handler.js",
+          "pass_env": ["CUSTOM_ANALYZER_PATH"]
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 快速上手 (Quickstart)
 
-### 2. Antigravity 侧挂载
+### 1. 推荐：零配置免安装挂载 (npx)
+
+无需手动克隆仓库或本地编译，直接在各 IDE 宿主的 MCP 配置文件中声明（基于全局或 `npx -y ferrycat`）：
+
+#### Antigravity 宿主配置
 编辑 `%USERPROFILE%\.gemini\antigravity\mcp_config.json`（macOS/Linux 为 `~/.gemini/antigravity/mcp_config.json`）：
 ```json
 {
   "mcpServers": {
     "ferrycat": {
-      "command": "node",
-      "args": [
-        "--experimental-sqlite",
-        "F:/git/FerryCat/dist/index.js"
-      ],
+      "command": "npx",
+      "args": ["-y", "ferrycat"],
       "env": {
         "AGENT_NAME": "antigravity"
       }
@@ -162,17 +192,14 @@ npm test
 }
 ```
 
-### 3. WorkBuddy / Claude Code / Cursor 侧挂载
-在目标宿主的 MCP 配置文件中添加对应 `AGENT_NAME`：
+#### WorkBuddy / Claude Code / Cursor / Codex 宿主配置
+在目标宿主的 MCP 配置文件中指定对应 `AGENT_NAME` 即可：
 ```json
 {
   "mcpServers": {
     "ferrycat": {
-      "command": "node",
-      "args": [
-        "--experimental-sqlite",
-        "F:/git/FerryCat/dist/index.js"
-      ],
+      "command": "npx",
+      "args": ["-y", "ferrycat"],
       "env": {
         "AGENT_NAME": "workbuddy"
       }
@@ -180,7 +207,53 @@ npm test
   }
 }
 ```
-> **注**：MCP `stdio` 模式与 CLI 直接调用模式（`ferrycat-cli <dispatch|poll|verify|fulfill|release|extend|fail|inspect|worker>`）共享同一份 `~/.ferrycat/mesh.db` 数据库与同一套 Zod 参数校验契约。CLI 提供全量 `--help` 树、stdin 管道输入（`--file -` 或 `-`）、`verify` 只读预检、`inspect` ASCII 表格输出（支持 `--target <agent>` 过滤）、`worker --mode=watch|claim|exec` 以及 `--exec-file <script>` 无转义直接执行脚本。在 `worker --exec` 模式下子进程非零退出时，工单会被直接置为 `FAILED`，不再挂在 `CLAIMED` 等超时。
+
+### 2. 全局安装或本地源码模式
+
+- **全局 CLI 安装**：
+  ```bash
+  npm install -g ferrycat
+  ```
+  在 MCP 配置文件中直接指定 `"command": "ferrycat"` 即可。
+- **本地源码编译（适合贡献者二次开发）**：
+  ```bash
+  git clone https://github.com/GuoBug/FerryCat.git
+  cd FerryCat
+  npm install
+  npm run build
+  npm test
+  ```
+  本地调试时可将配置中的 `command` 与 `args` 设为：
+  `"command": "node"`, `"args": ["--experimental-sqlite", "/path/to/FerryCat/dist/index.js"]`。
+
+---
+
+## 一级入口：CLI 极速总线与自动化调度 (`ferrycat-cli`)
+
+除了作为 MCP Server 嵌入在 IDE 内部供大模型自主调用外，FerryCat 原生提供一级命令行工具 **`ferrycat-cli`**（可通过全局安装或直接运行 `npx ferrycat-cli`）。它与 MCP 共享同一份 `~/.ferrycat/mesh.db` 数据库与 Zod 校验契约，无需切换 IDE 窗口即可在终端直观排查链路、接入 Git Hook 或自动化 CI：
+
+### 1. 终端可视化监控（ASCII 状态总线）
+实时打印工单流转状态、执行租约与报错信息，无需打开数据库查看：
+```bash
+# 查看全局工单 ASCII 终端表格
+npx ferrycat-cli inspect
+
+# 按接收方过滤（例如仅查看 target 为 antigravity 的工单）
+npx ferrycat-cli inspect --target antigravity
+```
+
+### 2. 交付前只读预检（Pre-Flight Verify）
+在正式交付前，无需变更契约状态即可安全核验磁盘文件指针一致性，杜绝因未落盘修改导致的假阳性交付：
+```bash
+npx ferrycat-cli verify <CONTRACT_ID>
+```
+
+### 3. 本地 CI 与自动化 Worker 执行
+监听契约队列并直接拉起本地脚本执行（支持安全脚本执行与非零退出自动熔断为 `FAILED`）：
+```bash
+# 启动常驻 Worker 监听并自动执行指定脚本（无 Shell 注入风险）
+npx ferrycat-cli worker --agent codex --mode=exec --exec-file ./scripts/review.sh
+```
 
 ---
 

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import { exec, execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ZodError } from 'zod';
 import { expandTilde, FerryCatEngine } from './engine.js';
+import { FerryCatDaemon } from './daemon.js';
+import { executeTaskAndFulfill, terminateActiveChildrenSync, } from './supervisor.js';
 import { DispatchContractSchema, ExtendTtlSchema, FailContractSchema, FulfillContractSchema, InspectMeshStateSchema, PollNextTaskSchema, ReleaseContractSchema, VerifyContractSchema, WorkerCommandSchema, } from './schemas.js';
 function loadPackageVersion() {
     try {
@@ -33,6 +34,7 @@ Commands:
   fail        Explicitly mark a CLAIMED contract you hold as terminal FAILED with reason
   inspect     Query contracts (renders concise table by default; pass --json for raw JSON)
   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)
 
 Common Options:
   --agent <id>              Agent identity (overrides AGENT_NAME env var)
@@ -174,6 +176,22 @@ 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>]
+
+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.
+
+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
+  --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`,
 };
 function stripBom(content) {
     return content.replace(/^\uFEFF/, '');
@@ -384,6 +402,28 @@ function parseArgs(argv) {
             }
             flagOverrides.exec_file = scriptPath;
         }
+        else if (token === '--pass-env') {
+            const varName = requireFlagValue('--pass-env', rest[++i]).trim();
+            if (!varName) {
+                throw new Error('Invalid --pass-env value: variable name cannot be empty.');
+            }
+            const existing = flagOverrides.pass_env ?? [];
+            existing.push(varName);
+            flagOverrides.pass_env = existing;
+        }
+        else if (token === '--config' || token === '-c') {
+            flagOverrides.config = requireFlagValue(token, rest[++i]);
+        }
+        else if (token === '--lease-ttl') {
+            const ttl = Number(requireFlagValue('--lease-ttl', rest[++i]));
+            if (!Number.isInteger(ttl) || ttl < 5) {
+                throw new Error('Invalid --lease-ttl: must be an integer >= 5 seconds.');
+            }
+            flagOverrides.lease_ttl_sec = ttl;
+        }
+        else if (token === '--no-notify') {
+            flagOverrides.notify = false;
+        }
         else if (token === '--format') {
             const fmt = requireFlagValue('--format', rest[++i]).trim().toLowerCase();
             if (fmt !== 'table' && fmt !== 'json') {
@@ -461,149 +501,6 @@ function interruptibleSleep(ms, signal) {
         signal.addEventListener('abort', onAbort, { once: true });
     });
 }
-function spawnExecTarget(spec, options, callback) {
-    if (spec.execFile) {
-        const resolvedScript = path.resolve(expandTilde(spec.execFile));
-        const ext = path.extname(resolvedScript).toLowerCase();
-        if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
-            return execFile(process.execPath, [resolvedScript], options, callback);
-        }
-        if (ext === '.ts') {
-            return execFile(process.execPath, ['--import', 'tsx', resolvedScript], options, callback);
-        }
-        if (ext === '.ps1') {
-            return execFile('powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', resolvedScript], options, callback);
-        }
-        if (ext === '.sh') {
-            return execFile('sh', [resolvedScript], options, callback);
-        }
-        return execFile(resolvedScript, [], options, callback);
-    }
-    return exec(spec.execCmd, options, callback);
-}
-async function executeTaskAndFulfill(engine, contract, spec) {
-    return new Promise((resolve) => {
-        const childEnv = {
-            ...process.env,
-            FERRYCAT_CONTRACT_ID: contract.contract_id,
-            FERRYCAT_TASK_TYPE: contract.task_type,
-            FERRYCAT_WORKSPACE_ROOT: contract.workspace_root,
-            FERRYCAT_TARGET_AGENT: contract.target_agent,
-            FERRYCAT_CLAIM_TOKEN: contract.claim_token ?? '',
-        };
-        const timeoutMs = Math.max(10000, contract.exec_ttl_sec * 1000);
-        const maxBuffer = 10 * 1024 * 1024;
-        const label = spec.execFile ?? spec.execCmd ?? 'exec';
-        const child = spawnExecTarget(spec, { env: childEnv, timeout: timeoutMs, maxBuffer }, (err, stdout, stderr) => {
-            if (err) {
-                const execErr = err;
-                const execError = `External exec command failed with code ${execErr.code ?? 1}${execErr.killed ? ' (killed after exec timeout)' : ''}: ${stderr || execErr.message}`;
-                let contractStatus;
-                try {
-                    contractStatus = engine.failContract({
-                        contract_id: contract.contract_id,
-                        agent_id: contract.target_agent,
-                        claim_token: contract.claim_token,
-                        reason: execError.slice(0, 2000),
-                    }).status;
-                }
-                catch (failErr) {
-                    contractStatus = `UNCHANGED (${failErr instanceof Error ? failErr.message : String(failErr)})`;
-                }
-                return resolve({
-                    ok: false,
-                    status: 'EXEC_FAILED',
-                    error: execError,
-                    contract_status: contractStatus,
-                });
-            }
-            let structuredOutput;
-            let resultSummary = stripBom(stdout).trim();
-            try {
-                const parsed = JSON.parse(resultSummary);
-                if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
-                    if (parsed.structured_output && typeof parsed.structured_output === 'object') {
-                        structuredOutput = parsed.structured_output;
-                    }
-                    else {
-                        structuredOutput = parsed;
-                    }
-                    if (parsed.result_summary && typeof parsed.result_summary === 'string') {
-                        resultSummary = parsed.result_summary;
-                    }
-                }
-            }
-            catch {
-                // Plain text stdout, fallback to result_summary
-            }
-            const boundedSummary = (resultSummary || `Completed via automated worker exec: ${label}`).slice(0, 20000);
-            try {
-                const validatedFulfillInput = FulfillContractSchema.parse({
-                    contract_id: contract.contract_id,
-                    agent_id: contract.target_agent,
-                    claim_token: contract.claim_token,
-                    result_summary: boundedSummary,
-                    structured_output: structuredOutput,
-                });
-                let fulfillRes = engine.fulfillContract(validatedFulfillInput);
-                // If RETRY_NEEDED occurs in automated exec (schema retry vs TOCTOU strike 1):
-                if (fulfillRes.status === 'RETRY_NEEDED') {
-                    // RETRY_NEEDED has two distinct causes with incompatible retry semantics:
-                    //   (a) schema validation failure -> retry_count increments, so retrying the
-                    //       same payload until the breaker trips is the intended behavior.
-                    //   (b) TOCTOU dirty pointers     -> retry_count does NOT move. The on-disk
-                    //       baseline cannot heal between two consecutive calls, so retrying only
-                    //       burns the single ADR-0004 strike and forces a terminal POINTER_STALE
-                    //       with nobody in the loop to restore the files. Never auto-retry it.
-                    const isToctouRejection = (fulfillRes.toctou_strike ?? 0) > 0 && (fulfillRes.retry_count ?? 0) === 0;
-                    if (isToctouRejection) {
-                        resolve({
-                            ok: false,
-                            status: 'TOCTOU_RESCUE_REQUIRED',
-                            fulfill_result: fulfillRes,
-                            error: 'Automated exec mutated pointer files. The contract stays CLAIMED with a renewed execution window. Restore the files (git stash / git checkout) and re-run, or deliver edits via structured_output.fixes instead of writing to the workspace.',
-                        });
-                        return;
-                    }
-                    const maxAttempts = (fulfillRes.max_retries ?? 2) + 1;
-                    for (let i = fulfillRes.retry_count ?? 1; i < maxAttempts; i++) {
-                        fulfillRes = engine.fulfillContract(validatedFulfillInput);
-                        if (fulfillRes.status !== 'RETRY_NEEDED')
-                            break;
-                    }
-                }
-                resolve({ ok: fulfillRes.ok, status: fulfillRes.status, fulfill_result: fulfillRes });
-            }
-            catch (fulfillErr) {
-                const fulfillError = fulfillErr instanceof Error ? fulfillErr.message : String(fulfillErr);
-                let contractStatus;
-                try {
-                    contractStatus = engine.failContract({
-                        contract_id: contract.contract_id,
-                        agent_id: contract.target_agent,
-                        reason: `FULFILL_ERROR: ${fulfillError}`.slice(0, 2000),
-                    }).status;
-                }
-                catch {
-                    contractStatus = undefined;
-                }
-                resolve({
-                    ok: false,
-                    status: 'FULFILL_ERROR',
-                    error: fulfillError,
-                    contract_status: contractStatus,
-                });
-            }
-        });
-        if (child.stdin) {
-            child.stdin.on('error', () => {
-                // Child process exited without consuming stdin, ignore EPIPE
-            });
-            child.stdin.write(JSON.stringify(contract));
-            child.stdin.end();
-        }
-    });
-}
 async function runWorkerLoop(engine, agentId, intervalMs, spec) {
     const resolvedAgent = resolveWorkerIdentity(agentId);
     const abortController = new AbortController();
@@ -625,9 +522,10 @@ async function runWorkerLoop(engine, agentId, intervalMs, spec) {
     const stopHandler = () => {
         sigintCount++;
         if (sigintCount >= 2) {
+            terminateActiveChildrenSync();
             console.error(JSON.stringify({
                 status: 'WORKER_FORCE_EXIT',
-                message: 'Second interrupt received, exiting immediately.',
+                message: 'Second interrupt received, terminated active child process trees and exiting immediately.',
             }));
             process.exit(130);
         }
@@ -957,6 +855,7 @@ async function main() {
                 const execSpec = {
                     execCmd: validated.exec,
                     execFile: validated.exec_file,
+                    passEnv: validated.pass_env,
                 };
                 engine = new FerryCatEngine();
                 if (effectiveOnce) {
@@ -996,8 +895,36 @@ async function main() {
                 }
                 break;
             }
+            case 'daemon': {
+                const configPath = data.config;
+                const targetAgent = data.target_agent ?? data.agent_id;
+                const once = Boolean(data.once);
+                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;
+                const daemon = new FerryCatDaemon({
+                    configPath,
+                    targetAgent,
+                    leaseTtlSec: leaseTtl,
+                    pollIntervalMs: intervalMs,
+                    notify,
+                });
+                if (once) {
+                    const res = await daemon.pollAndDispatchOnce();
+                    daemon.releaseLease();
+                    daemon.engine.close();
+                    output = { ok: true, daemon_once: res };
+                    console.log(JSON.stringify(output, null, 2));
+                }
+                else {
+                    await daemon.start();
+                    // Keep active process alive until signal
+                    await new Promise(() => { });
+                }
+                break;
+            }
             default:
-                throw new Error(`Unknown subcommand "${command}". Supported commands: dispatch, poll, verify, fulfill, release, extend, fail, inspect, worker. Run "ferrycat-cli --help" for usage.`);
+                throw new Error(`Unknown subcommand "${command}". Supported commands: dispatch, poll, verify, fulfill, release, extend, fail, inspect, worker, daemon. Run "ferrycat-cli --help" for usage.`);
         }
     }
     catch (err) {