📚 AI 工程与智能体教程站

English

简体中文

English

简体中文

Chapter 11 · Zero-Token Event-Driven Supervision: Watcher and Turn-End Guard ​

Chapter goals: Understand how FirstMate replaces manual babysitting with "zero-token event-driven supervision" — the bash watcher sleeps on standby, the turn-end guard catches blind stops, and auto-reconcile resumes after restart.

11.1 Why "Zero-Token" Supervision Is Needed ​

Imagine a common scenario: you've dispatched three parallel tasks to the fleet, then go do something else. Who watches those tasks?

The traditional approach is polling: every few minutes ask the agent "is the task done?" This has two致命缺陷:

text
Cost of polling:

1. Token waste: each question consumes one LLM call,
   even though most of the time the answer is "still running"
2. Slow reaction: anomalies between polls can only wait to be discovered

FirstMate flips this model entirely. The official架构文档 describes:

A zero-token bash watcher sleeps on the fleet, classifies detected wakes in bash, and wakes the first mate only when something is actionable.

The keyword is zero-token: the watcher itself is a纯 bash script that consumes no LLM calls at all. It持续 observes the session backend (tmux windows etc.) status signals, distinguishing "events worth disturbing the captain" from "benign noise" — only the former triggers a真实 firstmate round.

11.2 Watcher Working Mechanism: Sleep, Classify, Wake ​

The core script is bin/fm-watch.sh. Its loop logic概括为 three steps:

text
┌─────────────────────────────────────────────────┐
│  1. SLEEP    Sleep on the fleet, listening for status signals  │
│  2. CLASSIFY Classify wake events in bash                    │
│     ├─ actionable → write to queue and exit, wake firstmate  │
│     └─ benign     → absorb and keep sleeping                 │
│  3. WAKE     firstmate is roused to process the backlog      │
└─────────────────────────────────────────────────┘

What counts as an "actionable wake"? The official docs list the main categories:

text
Actionable wakes include:
- captain-related status signals
- verbless signals where the crewmate cannot prove still-working
- authenticated check outputs (e.g., PR merge polling, Relay mentions)
- stale panes where the crewmate cannot prove still-working
- declared external waits that have timed out
- heartbeat backstop hits

Benign noise absorbed:
- routine watcher polling
- supervision no-ops
- absorbed benign wakes

The key工程细节 is the persistent wake queue. Actionable events are not dropped直接 into the conversation; they are first written to the disk-based state/.wake-queue:

text
state/
├── .wake-queue          # Persistent queue of actionable events
├── .watch-triage.log    # Debug log of absorbed benign wakes
└── .watch-cycle-exits.log  # Watcher lifecycle records

This design ensures: even if the watcher or the processing round is interrupted中途, the queue record is not lost; the next cycle resumes from disk. Additionally, each time events are presented to the captain, a fleet-wide OPEN DECISIONS block is attached, ensuring earlier unresolved decisions that were "swamped" by later logs持续浮出水面 until explicitly resolved.

11.3接入 Per Primary Harness ​

The watcher needs the primary harness to cooperate to "wake" the firstmate — different harnesses provide不同的钩子机制. FirstMate has适配 for each validated primary harness:

Harness接入 Mechanism
Claude Codetracked Stop hook (asyncRewake), tokenless re-arm loop
Grokbackground-notify wake cycle
Pi / pi-signedtracked primary watcher extension (.pi/extensions/*.ts)
Cursor Agent CLIproject-level .cursor/hooks.json stop hook, docked on watcher
Codexbounded foreground checkpoints
OpenCodeTUI plugin

Take Claude Code as an example: it registers two Stop hooks in .claude/settings.json:

json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "bin/fm-turnend-guard.sh --claude" },

The first hook is the turn-end guard (see below); the second is the watcher re-arm.

11.4 Turn-End Guard: The Blind-Stop Safety Net ​

Even with a watcher, there's a edge case: the watcher might miss a termination signal, or the harness might stop without notifying. The turn-end guard (bin/fm-turnend-guard.sh) is the fallback — it runs at the end of each agent turn and checks whether the fleet state is consistent.

If the guard detects an inconsistency (e.g., a crewmate window is dead but not recorded as dead), it raises an alert and optionally triggers a手动 reconcile. This is the "blind-stop" safety net — ensuring the fleet never silently停摆.

11.5 Restart Reconciliation ​

After a harness restart, the firstmate runs a reconciliation pass: it checks all known crewmates against the actual session backend state,marks missing ones as dead, and re-queues any unresolved wakes. This ensures the fleet状态 is一致 after any disruption.

11.6 Chapter Summary ​

  • Zero-token watcher: a纯 bash script that sleeps on the fleet, classifies events, and only wakes firstmate for actionable events;
  • Persistent wake queue: actionable events are written to state/.wake-queue before processing, surviving interruptions;
  • Turn-end guard: runs at the end of each turn as a blind-stop safety net;
  • Restart reconciliation: after harness restart, the firstmate reconciles fleet state and re-queues unresolved events.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the watcher in FirstMate?

2. What is stored in state/.wake-queue?

3. What does the turn-end guard do?

4. What happens to unresolved wakes after a harness restart?

🛠️ Hands-On Exercises ​

  1. Read bin/fm-watch.sh and trace the sleep-classify-wake loop; identify where the actionable/benign classification happens.
  2. Trigger a wake event (e.g., kill a crewmate's tmux pane); observe the .wake-queue file being written; then restart the harness and verify the event is processed.
  3. Read the turn-end guard script (bin/fm-turnend-guard.sh); identify what consistency checks it performs and what alerts it raises.

Supervision understood. Next, built-in skills: /ahoy, /bearings, /afk, /stow, /updatefirstmate.