63 lines
3.8 KiB
Markdown
63 lines
3.8 KiB
Markdown
---
|
|
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.
|