FirstMate: agent crews, durable evidence and delivery authority
Build a read-only FirstMate evidence dashboard before adding automation
Design a learning project that displays task identities, observation sources and merge receipts without turning a status view into an unauthorized control plane.
What you will learn
- Start with an evidence view, not command buttons
- Reuse the identity lesson without claiming full compatibility
- Test the display’s refusal to invent certainty
Before you start
- Git worktrees and pull-request basics
- Understanding of terminal agents and credential scope
Define a delivery contract and inspect state and authority evidence without claiming untested runtime guarantees.
Key takeaways
- A read-only evidence view should preserve unknown states.
- Synthetic receipt tests do not validate live-home parsing.
- Control actions require a separate authorization design.
Start with an evidence view, not command buttons
A useful learning extension is a local read-only dashboard for synthetic task records. Display task identity, incarnation, endpoint observation, semantic verdict and the last consumed wake evidence. This is our proposal, not a feature claimed to ship in FirstMate or a statement of its roadmap.
Avoid a single green status derived from terminal existence. Show unknown observations and their age, and distinguish a report ready for review from a delivered change. For merge activity, display accepted, queued, landed and unconfirmed as separate observations when supported by evidence. Do not infer a missing transition.
Reuse the identity lesson without claiming full compatibility
The companion JavaScript teaching model parses the authority helper’s six-line shape and matches the canonical request tuple. Feed it synthetic matching and mismatching receipts to make stale attribution visible. The model is intentionally not a file reader or a validator of FirstMate’s complete private-state schema.
A real integration would need versioned parsers, safe path handling, snapshot consistency and access control before reading sensitive homes. It would also need to respect producers’ locking contracts. Do not point this learning prototype at a live fleet simply because its synthetic tests pass.
Test the display’s refusal to invent certainty
Exercise an old incarnation, missing semantic record, mismatched request number and accepted-but-unconfirmed merge. The view should retain the original observation and explain why a conclusion is unavailable. A future control button would require separate authorization and lifecycle design; it must not appear as an incidental convenience in a read-only viewer.
Static tables and a two-dimensional SVG are sufficient for these relationships. A Three.js fleet scene could be an optional presentation later, but critical evidence must remain accessible as text without animation. The first milestone is faithful state interpretation, not a more elaborate visual impression of progress.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Create synthetic task and receipt records.
- 2
Render identity, observation source and uncertainty separately.
- 3
Test stale and contradictory observations.
- 4
Keep any future mutation interface out of the first milestone.
Copy-ready example
{
"proposal": true,
"input": "synthetic snapshot",
"mode": "read-only",
"unknownVisible": true,
"liveHomeAccess": false,
"commandButtons": false
}Frequently asked questions
Is this dashboard already included upstream?
No. It is a proposed learning extension described in this series.
Does the teaching model safely parse an entire live home?
No. It handles synthetic receipt strings and does not implement filesystem, locking or complete state-schema checks.
Sources
- FirstMate / docs/architecture.mdSource checked 2026-09-14
- FirstMate / docs/configuration.mdSource checked 2026-09-14
- FirstMate / bin/fm-merge-authority-lib.shSource checked 2026-09-14