agents-relay 1.0.95 → 1.0.96

package/README.md

@@ -190,6 +190,6 @@ For work that was completed outside the relay but must be represented truthfully
 
 ### Automatic task troubleshooting
 
-When an ACTIVE Job contains a current-run `FAILED` or `BLOCKED` task, reconciliation creates one P0-priority `troubleshooter` recovery task for that exact failed attempt. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract.
+When an ACTIVE Job contains a current-run `FAILED` or `BLOCKED` task, reconciliation creates one P0-priority `troubleshooter` recovery task for that exact failed attempt. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
 
 The Troubleshooter diagnoses before retrying. A task-local or transient blocker is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the blocker is removed does it retry the original task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.

package/dist/troubleshooter.js

@@ -19,7 +19,12 @@ Original worker: ${task.workerSelection?.workerId ?? task.adapter}
 Original routing: ${task.routing ? JSON.stringify(task.routing) : 'unrouted'}
 Failure reason: ${task.failureReason ?? task.error ?? 'unknown'}
 
-Follow the selected Troubleshooter agent contract. Diagnose root cause before retry. If the blocker is a shared worker/runtime/tool defect, create and directly complete a P0/self-job in the owning repository, including required release/deploy verification. Retry this exact original task only after the blocker is removed, reconcile the original job, and verify durable progress.`;
+MANDATORY EVENT EVIDENCE BEFORE DIAGNOSIS:
+Retrieve this task's lifecycle event history before classifying the root cause or retrying:
+GET http://127.0.0.1:8787/api/events?job=${encodeURIComponent(job.id)}&task=${encodeURIComponent(task.id)}&limit=200
+Inspect event order, type/status, source, data/phase, duplicate events, missing expected lifecycle events, late events, and execution identifiers. If the event stream points to delivery/runtime failure, inspect the corresponding Relay/worker/tool logs too. Do not treat the final task.error string as the complete root cause.
+
+Follow the selected Troubleshooter agent contract. Diagnose root cause from durable task state + event history + relevant runtime logs before retry. If the blocker is a shared worker/runtime/tool defect, create and directly complete a P0/self-job in the owning repository, including required release/deploy verification. Retry this exact original task only after the blocker is removed, reconcile the original job, and verify durable progress.`;
 }
 function belongsToCurrentRun(job, task) {
     const slot = job.schedule?.currentRunSlot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.95",
+  "version": "1.0.96",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/skills/agents-relay/SKILL.md

@@ -114,6 +114,6 @@ Keep secrets, credentials, private prompts, and large private payloads out of du
 
 ### Automatic task troubleshooting
 
-When an ACTIVE Job contains a current-run `FAILED` or `BLOCKED` task, reconciliation creates one P0-priority `troubleshooter` recovery task for that exact failed attempt. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract.
+When an ACTIVE Job contains a current-run `FAILED` or `BLOCKED` task, reconciliation creates one P0-priority `troubleshooter` recovery task for that exact failed attempt. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
 
 The Troubleshooter diagnoses before retrying. A task-local or transient blocker is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the blocker is removed does it retry the original task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.

package/skills/agents-relay/agents/troubleshooter.agent.md

@@ -18,13 +18,13 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
 ## Recovery loop
 
 1. Retrieve the durable original Job and failed/blocked Task from GitHub.
-2. Inspect the concrete failure evidence: task error/failureReason, lifecycle events, worker selection, routing, attempt count, task input/output contract, PR state, and relevant runtime/service logs.
+2. **Mandatory before diagnosis:** retrieve the failed Task's task-scoped lifecycle event history. When the local Relay dashboard is available, use `GET http://127.0.0.1:8787/api/events?job=<job_id>&task=<task_id>&limit=200`. Inspect event order, type/status, source, data/phase, execution IDs, duplicates, missing expected lifecycle events, and late events. Then inspect task error/failureReason, worker selection, routing, attempt count, task input/output contract, PR state, and relevant runtime/service logs.
 3. Classify the blocker:
    - transient execution/delivery/lease failure;
    - task-local implementation or validation failure;
    - shared worker/runtime/tool/Agents Relay defect;
    - genuine external/human blocker.
-4. Diagnose the smallest root cause. Never retry first and investigate later.
+4. Diagnose the smallest root cause from the combined durable Task + event sequence + logs. The final `task.error` is only one piece of evidence. Never retry first and investigate later.
 5. Repair:
    - For a transient failure, verify the transient condition is gone.
    - For task-local failure, make the smallest durable repair in the original Job/PR when that is within scope.
@@ -37,7 +37,7 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
 ## Rules
 
 - Never erase or rewrite the original failure evidence.
-- Never blindly retry a deterministic failure.
+- Never blindly retry a deterministic failure. Event-history inspection is a hard precondition for retry; if event history cannot be retrieved, record that observability blocker explicitly rather than pretending diagnosis is complete.
 - Never create a second P0 Job for the same root cause when a suitable active one already exists; reuse/adopt/reconcile it.
 - P0 fixes must follow the P0/self-job contract: durable Job first, orchestrator-owned Task immediately, direct execution by this recovery orchestrator, no reviewer gate unless explicitly required.
 - Repository PR creation/adoption/repair still goes through Agents Relay.