FirstMate: agent crews, durable evidence and delivery authority
FirstMate architecture: durable wake events are not proof of a healthy worker
Trace task state, semantic busy verdicts and generation-bound wake handling without confusing a visible terminal with a completed or recoverable task.
What you will learn
- The backend endpoint is only one observation
- Bind events to the incarnation that produced them
- Escalation needs evidence and restrained action
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
- Endpoint existence and semantic worker state are separate.
- Stale events must not govern a new incarnation.
- Unknown state calls for inspection, not a fabricated verdict.
The backend endpoint is only one observation
The runtime backend creates and addresses task endpoints, captures bounded output and supports lifecycle operations. The agent adapter contributes semantic activity information. These are different layers: a terminal may remain open after an agent dies, and an apparently quiet agent may be waiting on a long-running tool.
The architecture specifies busy, idle, unknown and dead verdicts together with the source of the observation. Missing, malformed, stale or unverified semantic state becomes unknown, not idle or busy. At this revision Codex and standalone Kimi remain unknown behind explicit probes until their semantic source is live-verified.
Bind events to the incarnation that produced them
A lifecycle record belongs to an incarnation token minted when task wiring is armed. An event from an earlier incarnation must not update the new worker. This is the same general distributed-systems problem as a late response arriving after a retry: matching the task name alone is insufficient to establish freshness.
The watcher and wake queue address another distinction: endpoint liveness does not establish queue-consumption liveness. The architecture describes durable wake rows and progress-based observation. A parent observing a local secondmate’s queue should not take over its consumption or rewrite its rows simply because progress is delayed.
Escalation needs evidence and restrained action
A stuck-looking worker can still be writing its worktree. The documented supervisor combines state and bounded inspection rather than treating CPU, modification time or silence as a universal busy signal. A wedge notification calls for inspection, not an automatic interrupt or restart that could discard active work.
Draw a recovery record with task identity, incarnation, observation source, queue progress and the next authorized action. Leave unknown fields unknown. We inspected the documented architecture but did not execute the watcher or reproduce adapter-specific recovery, so this explanation is not a runtime reliability measurement.
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
Record task and incarnation together.
- 2
Retain the source of each state observation.
- 3
Inspect queue progress separately from terminal liveness.
- 4
Escalate with evidence before destructive recovery.
Copy-ready example
{
"example": true,
"taskId": "scout-demo",
"incarnation": "generation-2",
"verdict": "unknown",
"observationSource": "missing semantic record",
"nextAction": "inspect",
"restartAuthorized": false
}Frequently asked questions
Can an old turn-ended file prove the worker is idle?
No. The architecture treats it as a wake notification, not authoritative current state.
Does a wedge signal authorize restarting a worker?
No. It requests closer inspection; recovery still needs an authorized action.
Sources
- FirstMate / docs/architecture.mdSource checked 2026-09-14
- FirstMate / docs/configuration.mdSource checked 2026-09-14