---
status: resolved
parent: "[[005-pi-subagents-firstmate-and-related-tools-research]]"
blocked-by: []
tags:
  - ticket/research
---

# Firstmate reusable patterns research

## Question

Which specific Firstmate patterns could be useful for neutral Pi subagents, especially around Herdr pane identity, lifecycle tracking, supervision, recovery, worktree isolation, and keeping orchestration policy separate from mechanism?

## Resolution

## Findings

Firstmate treats exact Herdr pane identity as authoritative and treats labels and focus as non-authoritative.
Its Herdr placement logic uses injected `HERDR_PANE_ID`, socket/session verification, and live Herdr reads of pane to tab to workspace.
If parent identity is stale, cross-session, missing socket identity, or inconsistent, spawn refuses before creating a worker.
Citation: `/tmp/firstmate-research/firstmate/docs/herdr-backend.md` and `bin/backends/herdr.sh`.

Firstmate distinguishes selection signals from authority signals.
`HERDR_ENV=1` can select the Herdr backend, but pane and socket identity are required to prove launcher ancestry.
Citation: `/tmp/firstmate-research/firstmate/bin/fm-backend.sh` and `bin/backends/herdr.sh`.

Firstmate persists endpoint IDs rather than labels.
Task metadata records Herdr session, workspace, tab, and pane identifiers, while labels support discovery or recovery but not destructive authority.
Citation: `/tmp/firstmate-research/firstmate/docs/herdr-backend.md` and `AGENTS.md`.

Firstmate treats lifecycle logs as events, not truth.
Status files are append-only wake history, while current state is recomputed from structured semantic sources.
Missing or stale busy signals become `unknown`, not idle.
Citation: `/tmp/firstmate-research/firstmate/AGENTS.md` and `docs/architecture.md`.

Firstmate uses durable queues and incarnation-bound records for supervision.
Actionable watcher events are appended before detector state advances, and lifecycle events are bound to tokens minted when wiring is armed so old events cannot update new incarnations.
Citation: `/tmp/firstmate-research/firstmate/docs/architecture.md`.

Firstmate uses recovery-grade liveness states.
Herdr panes are mapped to states such as alive, dead, missing, and unreadable.
Restart sweeps relaunch only confirmed dead or missing targets and preserve ambiguous or unreadable cases.
Citation: `/tmp/firstmate-research/firstmate/docs/herdr-backend.md` and `AGENTS.md`.

Firstmate asserts isolation before launch.
Ship and scout spawns refuse unless the task path is a real git worktree root distinct from the primary checkout.
Secondmates use persistent homes as durable identity for recovery.
Citation: `/tmp/firstmate-research/firstmate/bin/fm-spawn.sh`, `docs/architecture.md`, and secondmate lifecycle tests.

Firstmate separates policy from mechanism through backend adapters and single-owner scripts.
`bin/fm-backend.sh` dispatches backend-neutral operations, `bin/backends/herdr.sh` owns Herdr mechanics, and harness-specific supervision prose is selected by `bin/fm-supervision-instructions.sh` from per-harness protocol docs.
Citation: `/tmp/firstmate-research/firstmate/bin/fm-backend.sh`, `bin/backends/herdr.sh`, and `bin/fm-supervision-instructions.sh`.

## Implications

Useful patterns for neutral Pi subagents are: exact host endpoint identity, durable lifecycle events separate from current truth, unknown-preserving recovery, incarnation tokens, host adapters, and policy-free mechanism boundaries.

Patterns that should remain optional are worktree isolation, persistent homes, PR workflow, and supervision daemon behavior.
Those belong to higher-level orchestration policy, not the neutral subagent primitive.

A Herdr adapter for Pi subagents should persist pane/session identifiers, refuse ambiguous recovery, avoid label authority, and treat host presentation as an adapter rather than as the subagent's semantic identity.
