root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(FN-4746): complete Step 4 — document wake trigger diagnostics

Browse Source 
Fusion-Task-Id: FN-4746
Fusion-Task-Lineage: 04107d0d-4319-4270-8480-7a98341a966d
This commit is contained in:
Fusion (runfusion.ai)
2026-05-16 09:21:31 -07:00
committed by gsxdsm
parent de714b8880
commit 0121a09060
2 changed files with 14 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
AGENTS.md
View File

@@ -538,7 +538,8 @@ When debugging agent execution issues (agents stuck on "starting"), check these
10. **`[auto-claim-snapshot] rebuild generated=N reason=<ttl|invalidate>`** — Confirms project-wide auto-claim snapshot rebuild cadence
11. **`[auto-claim-prompt] agent=<id> chars=<n> count=<n>`** — Tracks rendered no-task candidate section size
12. **`[prompt-size] prompt-size { agentId, role, runId, template, systemChars, execChars, totalChars, isNoTaskRun }`** — Per-heartbeat prompt-size audit record
13. **`[retry-burned] retry-burned { taskId, agentId, role, category, attempt, total, breakdown }`** — Unified retry-burn telemetry and retry-cap circuit-breaker context
13. **`[wake-trigger-diagnostics] agent=<id> run=<id> triggerDetail=<wake-on-message*> source=<source> messageId=<id|none> from=<type:id|none> forced=<bool> createdAt=<iso|none> inboxUnreadCount=<n> wakeMessageStillUnread=<true|false|unknown> pendingRoomMessages=<n>`** — Correlates wake-on-message triggers with inbox snapshot state to diagnose empty-inbox false-positive wakes
14. **`[retry-burned] retry-burned { taskId, agentId, role, category, attempt, total, breakdown }`** — Unified retry-burn telemetry and retry-cap circuit-breaker context
### Semaphore Resilience

12
docs/agents.md
View File

@@ -849,6 +849,18 @@ Heartbeat prompts derive wake reason from trigger context plus current inbox sna
The Wake Delta block now includes an inbox snapshot line (`- inbox snapshot: <N> message(s)` or `- inbox snapshot: empty (already consumed)`) so agents can distinguish a true message payload from a stale wake trigger.
For `wake-on-message` / `wake-on-message-forced` runs, Wake Delta also adds:
- `- wake trigger source: message <messageId> from <fromType>:<fromId> (forced when applicable), <still unread|already consumed at snapshot>`
And engine logs emit a structured correlation line keyed by `[wake-trigger-diagnostics]` with the triggering message metadata plus snapshot counters (`inboxUnreadCount`, `wakeMessageStillUnread`, `pendingRoomMessages`).
**Debugging empty-inbox wake noise**
1. `grep "\[wake-trigger-diagnostics\]" <engine-log>`
2. Find lines where `triggerDetail=wake-on-message` (or forced variant) and `inboxUnreadCount=0 wakeMessageStillUnread=false`.
3. Correlate `messageId`, `from=`, and `run=` with the run's Wake Delta block; this indicates a false-positive wake where the trigger message had already been consumed by snapshot time.
### Default Procedure: Bound-Task Scope Discipline
The shipped default `HEARTBEAT_PROCEDURE` (in `packages/engine/src/agent-heartbeat.ts`) now requires bound-task classification on each tick: `executor-class`, `blocked`, or `coordination-class`.