Supervision Protocols for Firstmate Harnesses: Claude, Grok, and Pi Explained

Firstmate runs a single live supervision cycle owned by the active harness, with Claude using a stop-hook model, Grok using background-notification, and Pi using extension-owned background wakes, each requiring specific drain-acknowledge-arm sequences.

The kunchenguid/firstmate repository implements distinct supervision protocols for firstmate harnesses to manage the lifecycle of watcher processes across different LLM runtimes. Understanding these harness-specific mechanisms is essential for maintaining reliable turn-based execution and proper process recovery.

Claude Harness Supervision Protocol (Stop-Hook-Owned)

The Claude harness implements stop-hook-owned supervision. According to the source code in docs/supervision-protocols/claude.md, the Claude "Stop" hook automatically arms a watcher at each turn-end, eliminating the need for manual arm invocations during normal operation.

Core Steps

Every Claude supervision cycle follows this sequence:

1. Drain the wake queue using bin/fm-wake-drain.sh to clear any pending notifications.
2. Process all wakes, then execute the WAKE_ACK_REQUIRED command printed by the turn-end guard.
3. Allow the Stop hook (bin/fm-claude-stop-autoarm.sh) to re-arm the watcher automatically.

Recovery and Guard Mechanisms

The turn-end guard at bin/fm-turnend-guard.sh --claude validates the watcher’s PID and beacon. If the watcher fails to auto-arm, the guard reports a watcher auto-arm FAILED notice.

When this occurs:

• Inspect the registration (typically located in ~/.firstmate/…)
• Do not start a manual arm loop or invoke bin/fm-watch-arm.sh directly

# Standard Claude flow - no manual arm needed

bin/fm-wake-drain.sh

# Process wakes, then run the ack command printed by:

bin/fm-turnend-guard.sh --claude

# Stop hook handles: bin/fm-claude-stop-autoarm.sh

Grok Harness Supervision Protocol (Background-Notify)

The Grok harness uses a background-notify supervision model. As implemented in docs/supervision-protocols/grok.md, Grok spawns a background task that executes bin/fm-watch-arm.sh and notifies Firstmate upon completion.

Core Steps

1. Drain the durable wake queue: bin/fm-wake-drain.sh.
2. Handle all wakes and acknowledge using the printed WAKE_ACK_REQUIRED command.
3. Start the background arm using Grok's specific terminal command pattern.

Recovery and Guard Mechanisms

The primary guard bin/fm-turnend-guard-grok.sh monitors for watcher: FAILED … lines in the output. On failure, you must re-arm the background task; normal completion operates silently without additional intervention.

# First-time arm for Grok (background execution)

run_terminal_command background:true \
  '[ -f __FM_X_MODE_ENV_SH__ ] && . __FM_X_MODE_ENV_SH__; exec bin/fm-watch-arm.sh'

# Standard cycle

bin/fm-wake-drain.sh

# Acknowledge with the command from the guard output

bin/fm-turnend-guard-grok.sh

Pi Harness Supervision Protocol (Extension-Owned)

The Pi harness (supporting pi or pi-signed extensions) follows an extension-owned background wake model. The Pi extensions launch a dedicated arm function fm_watch_arm_pi that wraps bin/fm-watch-arm.sh --restart, as specified in docs/supervision-protocols/pi.md.

Core Steps

1. Drain the wake queue: bin/fm-wake-drain.sh.
2. Acknowledge wakes with the WAKE_ACK_REQUIRED command.
3. The Pi extension automatically calls fm_watch_arm_pi for the first cycle; subsequent cycles attach to the same child process.

Recovery and Guard Mechanisms

The Pi-specific turn-end guard (__FM_PI_TURNEND_EXT__) ensures the extension has loaded correctly. If the extension reports a missing or failed cycle:

1. Reclaim the session lock: bin/fm-session-start.sh.
2. Re-arm the watcher: fm_watch_arm_pi.
3. Never invoke bin/fm-watch-arm.sh directly for Pi recovery.

# First cycle (extension-owned)

fm_watch_arm_pi

# If extension reports missing cycle:

bin/fm-session-start.sh
fm_watch_arm_pi  # Wrapper for bin/fm-watch-arm.sh --restart

Shared Safety Contracts Across All Harnesses

All three supervision protocols for firstmate harnesses enforce common safety contracts defined in docs/watcher-continuity.md and the turn-end guard specifications.

Drain-First Execution

Every turn must begin by draining the durable wake queue:

bin/fm-wake-drain.sh

Idempotent Acknowledgment

You must run the exact --ack-through command printed as WAKE_ACK_REQUIRED before the turn ends. This guarantees idempotent handling of queued wakes across Claude, Grok, and Pi.

No Manual Background Operators

Launching a watcher with shell background operators (&) is explicitly blocked by the pre-tool check in bin/fm-arm-pretool-check.sh. Always use harness-specific arm mechanisms.

Watcher Continuity Markers

Any watcher: started … or watcher: attached … line confirms a live cycle. Conversely, watcher: FAILED … signals that the supervision stack is down and requires re-arming according to harness-specific recovery protocols.

Key Implementation Files

The supervision architecture relies on these critical files in the kunchenguid/firstmate repository:

File	Role
docs/supervision-protocols/claude.md	Claude stop-hook supervision specification
docs/supervision-protocols/grok.md	Grok background-notify supervision
docs/supervision-protocols/pi.md	Pi extension-owned supervision
docs/watcher-continuity.md	Arm-layer successor and clean-close contracts
docs/turnend-guard.md	Turn-end guard implementation for all harnesses
bin/fm-wake-drain.sh	Drains the durable wake queue
bin/fm-watch-arm.sh	Core watcher arm wrapper (used by all harnesses)
bin/fm-turnend-guard.sh	Guard script with flags --claude, --grok, --pi
bin/fm-claude-stop-autoarm.sh	Automatic arm for Claude's Stop hook
bin/fm-turnend-guard-grok.sh	Grok-specific guard logic
bin/fm-arm-pretool-check.sh	Pre-tool validation preventing manual background operators
bin/fm-session-start.sh	Session lock reclamation for Pi recovery
__FM_PI_TURNEND_EXT__	Pi extension file for turn-end guarding
__FM_PI_EXT__	Pi extension file that owns the arm cycle

Summary

• Claude uses stop-hook-owned supervision where bin/fm-claude-stop-autoarm.sh handles re-arming automatically; manual arm loops are prohibited.
• Grok employs background-notify supervision requiring explicit background task spawning and monitoring via bin/fm-turnend-guard-grok.sh.
• Pi relies on extension-owned supervision through fm_watch_arm_pi, with session lock management via bin/fm-session-start.sh for recovery.
• All harnesses require running bin/fm-wake-drain.sh before processing and executing the exact WAKE_ACK_REQUIRED acknowledgment command.
• The bin/fm-arm-pretool-check.sh enforces the prohibition against manual background operators (&) across all protocols.

Frequently Asked Questions

What is the first step in every Firstmate supervision cycle?

Every cycle begins with draining the durable wake queue using bin/fm-wake-drain.sh. This step is mandatory across Claude, Grok, and Pi harnesses to ensure no pending wakes interfere with the current turn's execution.

Why can't I use shell background operators to start watchers?

The pre-tool check implemented in bin/fm-arm-pretool-check.sh explicitly blocks attempts to launch watchers using shell background operators (&). This restriction ensures that harness-specific protocols maintain proper process ownership and signal handling required for reliable supervision.

How does Claude's supervision differ from Grok's?

Claude uses a stop-hook-owned model where bin/fm-claude-stop-autoarm.sh automatically re-arms the watcher at turn-end without manual intervention. Grok uses a background-notify model that requires explicitly spawning a background task with run_terminal_command and monitoring completion through bin/fm-turnend-guard-grok.sh.

What should I do if the Pi extension reports a missing cycle?

If the Pi extension (__FM_PI_EXT__) reports a missing or failed cycle, first reclaim the session lock by running bin/fm-session-start.sh, then re-arm the watcher using fm_watch_arm_pi. Never invoke bin/fm-watch-arm.sh directly for Pi recovery, as this bypasses the extension's process management.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}