82 lines
3.2 KiB
Markdown
82 lines
3.2 KiB
Markdown
# Subagent Delivery Watchdog State Shape
|
|
|
|
This directory is reserved for file-backed state used by the subagent delivery watchdog.
|
|
|
|
## Purpose
|
|
|
|
The watchdog tracks whether a subagent dispatch has a matching completion receipt and whether the main thread has enough evidence to classify the run state without guessing.
|
|
|
|
This task defines the **state JSON shape only**. It does **not** implement receipt write logic, status recomputation, recovery behavior, or live integration.
|
|
|
|
## Suggested file model
|
|
|
|
One JSON document per dispatched subagent run.
|
|
|
|
Example path pattern:
|
|
|
|
- `state/subagent-delivery-watchdog/<runId>.json`
|
|
|
|
## State JSON shape
|
|
|
|
```json
|
|
{
|
|
"runId": "run_2026_04_24_abc123",
|
|
"childSessionKey": "agent:engineering:subagent:cd236af1-7d4a-4f4e-bccd-04e4f9a96c02",
|
|
"dispatchAt": "2026-04-24T10:40:00+08:00",
|
|
"expectedBy": "2026-04-24T10:50:00+08:00",
|
|
"completionReceivedAt": null,
|
|
"forwardedToMain": false,
|
|
"resultSource": null,
|
|
"status": "active",
|
|
"statusUpdatedAt": "2026-04-24T10:40:00+08:00",
|
|
"statusReason": "Dispatch receipt exists and SLA has not been crossed.",
|
|
"recoveryAction": null,
|
|
"recoveryAttemptCount": 0,
|
|
"lastRecoveryAt": null,
|
|
"notes": []
|
|
}
|
|
```
|
|
|
|
## Receipt fields
|
|
|
|
### Dispatch receipt fields
|
|
|
|
- `runId`: unique identifier for the dispatched subagent run.
|
|
- `childSessionKey`: session key or stable child-session identifier used to correlate the run.
|
|
- `dispatchAt`: ISO-8601 timestamp for when the subagent was dispatched.
|
|
- `expectedBy`: ISO-8601 timestamp for the watchdog SLA / expected completion deadline.
|
|
|
|
### Completion receipt fields
|
|
|
|
- `completionReceivedAt`: ISO-8601 timestamp for when a completion receipt was observed by the owner thread; `null` if not yet observed.
|
|
- `forwardedToMain`: boolean indicating whether the completion/result was confirmed forwarded back to the main thread.
|
|
- `resultSource`: source label for the result evidence, for example `completion_event`, `history_fetch`, or `manual_recovery`; `null` if no completion evidence exists yet.
|
|
|
|
## Status fields
|
|
|
|
- `status`: current watchdog classification. Expected values include:
|
|
- `active`
|
|
- `suspect_delivery_failure`
|
|
- `done_but_not_forwarded`
|
|
- `completed`
|
|
- `recovered`
|
|
- `blocked`
|
|
- `statusUpdatedAt`: ISO-8601 timestamp of the latest status evaluation/update.
|
|
- `statusReason`: short human-readable explanation for why the current status was assigned.
|
|
|
|
## Optional supporting fields
|
|
|
|
These fields are not a substitute for the required receipt/status fields, but they can support later tasks safely.
|
|
|
|
- `recoveryAction`: pending or last recovery decision, if any.
|
|
- `recoveryAttemptCount`: number of recovery attempts already made.
|
|
- `lastRecoveryAt`: ISO-8601 timestamp of the last recovery attempt.
|
|
- `notes`: append-only diagnostic notes.
|
|
|
|
## Constraints
|
|
|
|
- Receipt fields and status fields must remain explicit in stored state.
|
|
- `completionReceivedAt`, `resultSource`, and recovery-related fields may be `null` before any completion signal exists.
|
|
- `forwardedToMain` should remain `false` until the return path to the main thread is actually confirmed.
|
|
- Status must be derived from evidence; later implementation should not infer success without a receipt or equivalent recovery proof.
|