3.8 KiB
status, parent, blocked-by, tags
| status | parent | blocked-by | tags | |
|---|---|---|---|---|
| resolved | 005-pi-subagents-firstmate-and-related-tools-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.