FirstMate: agent crews, durable evidence and delivery authority
Read FirstMate merge-authority code: identity-bound receipts are not merge permission
Follow authority resolution, six-line persistence and identity-checked consumption, including the limits of an isolated JavaScript teaching model.
What you will learn
- Begin with the helper’s declared boundary
- Persistence binds the receipt to a particular request
- Retirement must not remove a replacement receipt
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
- The authority resolver is not the complete merge gate.
- Receipts bind historical classification to a canonical request.
- Cleanup also needs identity checks to avoid removing replacements.
Begin with the helper’s declared boundary
The header of bin/fm-merge-authority-lib.sh says the resolver authorizes nothing by itself. The merge path owns the actual gate and persists authority after the forge accepts the request. The six-line record contains a format marker, provider, host, repository path, request number and authority classification.
The resolver distinguishes attended, yolo and away-grant classifications. A missing away record resolves to attended; an existing but unreadable record fails. With a valid away record, the task metadata’s yolo setting or an exact task grant determines the classification. Do not reinterpret attended as a bypass of live checks or user instructions.
Persistence binds the receipt to a particular request
The persistence function validates the task, state directory and current request identity before writing. It acquires a record lock, creates a private temporary file in the state directory, writes the six lines, checks the file and replaces the destination. Its helper calls enforce additional file constraints that our standalone teaching model does not implement.
record_matches rejects an incorrect format, unsupported authority, identity mismatch or extra line. The read function defaults to external and consumes only a matching receipt under the record lock. This prevents a later poll from inventing historical authority from whatever away policy happens to exist at polling time.
Retirement must not remove a replacement receipt
remove_if_matches compares the canonical request, authority and recorded file identity before removing a receipt. Matching only the task name would risk deleting a newer record written after a reader’s observation. This source-level precaution illustrates why cleanup is part of correctness rather than incidental housekeeping.
Our JavaScript model tests six-line parsing and exact request matching with synthetic strings. It deliberately excludes shell imports, filesystem permissions, locks, forge calls and authorization resolution. Passing it demonstrates the teaching model’s invariants only; it neither executes the upstream shell nor proves that concurrent production merges are safe.
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
Read the source header before tracing helper functions.
- 2
Follow resolve, persist, read and retirement separately.
- 3
Test malformed and mismatched receipts with synthetic data.
- 4
Keep model coverage separate from shell and live-forge coverage.
Copy-ready example
// Teaching model only: not the upstream merge gate.
const sameRequest = (a, b) =>
["provider", "host", "path", "number"]
.every(key => a[key] === b[key]);
// Filesystem identity and lock checks remain separate.Frequently asked questions
Does a valid receipt authorize a new merge?
No. It records classification for a particular accepted request; the actual merge gate has other checks.
Did this review execute upstream merge scripts?
No. Only the separate JavaScript teaching model was executed, without filesystem or forge operations.
Sources
- FirstMate / bin/fm-merge-authority-lib.shSource checked 2026-09-14
- FirstMate / docs/architecture.mdSource checked 2026-09-14