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

> Understand Firstmate harness supervision protocols for Claude Grok and Pi. Learn about stop-hook background-notification and extension-owned background wakes for efficient sequence management.

- Repository: [Kun Chen/firstmate](https://github.com/kunchenguid/firstmate)
- Tags: deep-dive
- Published: 2026-08-13

---

**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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-watch-arm.sh) directly

```bash

# 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`](https://github.com/kunchenguid/firstmate/blob/main/docs/supervision-protocols/grok.md), Grok spawns a background task that executes [`bin/fm-watch-arm.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-watch-arm.sh) and notifies Firstmate upon completion.

### Core Steps

1. Drain the durable wake queue: [`bin/fm-wake-drain.sh`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/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.

```bash

# 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`](https://github.com/kunchenguid/firstmate/blob/main/docs/supervision-protocols/pi.md).

### Core Steps

1. Drain the wake queue: [`bin/fm-wake-drain.sh`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-session-start.sh).
2. Re-arm the watcher: `fm_watch_arm_pi`.
3. **Never** invoke [`bin/fm-watch-arm.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-watch-arm.sh) directly for Pi recovery.

```bash

# 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`](https://github.com/kunchenguid/firstmate/blob/main/docs/watcher-continuity.md) and the turn-end guard specifications.

### Drain-First Execution

Every turn must begin by draining the durable wake queue:

```bash
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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/docs/supervision-protocols/claude.md) | Claude stop-hook supervision specification |
| [`docs/supervision-protocols/grok.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/supervision-protocols/grok.md) | Grok background-notify supervision |
| [`docs/supervision-protocols/pi.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/supervision-protocols/pi.md) | Pi extension-owned supervision |
| [`docs/watcher-continuity.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/watcher-continuity.md) | Arm-layer successor and clean-close contracts |
| [`docs/turnend-guard.md`](https://github.com/kunchenguid/firstmate/blob/main/docs/turnend-guard.md) | Turn-end guard implementation for all harnesses |
| [`bin/fm-wake-drain.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-wake-drain.sh) | Drains the durable wake queue |
| [`bin/fm-watch-arm.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-watch-arm.sh) | Core watcher arm wrapper (used by all harnesses) |
| [`bin/fm-turnend-guard.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-turnend-guard.sh) | Guard script with flags `--claude`, `--grok`, `--pi` |
| [`bin/fm-claude-stop-autoarm.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-claude-stop-autoarm.sh) | Automatic arm for Claude's Stop hook |
| [`bin/fm-turnend-guard-grok.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-turnend-guard-grok.sh) | Grok-specific guard logic |
| [`bin/fm-arm-pretool-check.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-arm-pretool-check.sh) | Pre-tool validation preventing manual background operators |
| [`bin/fm-session-start.sh`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-session-start.sh) for recovery.
- All harnesses require running [`bin/fm-wake-drain.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-wake-drain.sh) before processing and executing the exact `WAKE_ACK_REQUIRED` acknowledgment command.
- The [`bin/fm-arm-pretool-check.sh`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/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`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-session-start.sh), then re-arm the watcher using `fm_watch_arm_pi`. Never invoke [`bin/fm-watch-arm.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-watch-arm.sh) directly for Pi recovery, as this bypasses the extension's process management.