agents-relay 2.0.108 → 2.0.109

package/dist/cli-support.js

@@ -247,6 +247,13 @@ export async function publishTaskUnblocked(bus, job, taskId, reason) { if (!bus)
 catch (error) {
     process.stderr.write(`warning: unblock event unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
 } }
+export async function publishTaskBlocked(bus, job, taskId, reason, data) { if (!bus)
+    return; try {
+    await bus.publish(eventFor(job.id, taskId, null, 'task.blocked', 'blocked', `Task ${taskId} blocked: ${reason}`, 'orchestrator', { repository: job.repository, prNumber: job.prNumber, reason, ...data }));
+}
+catch (error) {
+    process.stderr.write(`warning: block event unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+} }
 export async function publishDependentUnblocked(bus, targets, reason) { if (!bus)
     return; for (const target of targets) {
     try {

package/dist/cli-unblock.js

@@ -1,9 +1,18 @@
 import { arg, publishTaskUnblocked, publishWake, saveLocal, withEventBus } from './cli-support.js';
 import { isEffectivelyBlocked, unblockAutonomousTasks, unblockTask } from './unblock.js';
+import { resumeTroubleshooter } from './task-recovery.js';
 export async function runTaskUnblockCommand(args, store, job, task, localFile) {
     const reason = arg(args, '--reason');
-    if (!reason.trim())
-        throw new Error('task unblock requires --reason');
+    const response = arg(args, '--response');
+    if (!reason.trim() && !response.trim())
+        throw new Error('task unblock requires --reason or --response');
+    if (task.agentName === 'troubleshooter' && task.escalation?.status === 'pending' && response.trim()) {
+        const result = await resumeTroubleshooter(store, job.id, task.id, response);
+        await saveLocal(localFile, result.job);
+        await withEventBus(args, async (bus) => { await publishTaskUnblocked(bus, result.job, task.id, reason || 'Human response recorded'); await publishWake(bus, result.job, task.id, 'Troubleshooter resumed after human response'); });
+        console.log(JSON.stringify({ taskId: task.id, resumed: true, task: result.task }, null, 2));
+        return;
+    }
     const result = await unblockTask({ store, job, task, trigger: { source: 'cli', reason } });
     const refreshed = await store.load(job.id);
     await saveLocal(localFile, refreshed);

package/dist/cli.js

@@ -41,6 +41,7 @@ import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg,
 export { SERVICE_DEFAULTS, eventBus, executionMode, chatGptTabClosePolicy } from './cli-support.js';
 import { workerTaskFromArgs } from './cli-worker-task.js';
 import { taskExecutionContext } from './task-context.js';
+import { requestTroubleshooterEscalation, resumeTroubleshooter } from './task-recovery.js';
 import { pauseJob, resumeJob } from './job-pause.js';
 export { ensureManagedGitHubJob } from './cli-job-create.js';
 async function runManagedTaskCommand(action, args) {
@@ -69,7 +70,7 @@ async function runManagedTaskCommand(action, args) {
     console.log(JSON.stringify(task, null, 2));
 }
 async function runTaskCommand(action, args) {
-    if (!['create', 'update', 'show', 'context', 'comment', 'comments', 'list', 'retry', 'recover', 'unblock', 'cancel', 'supersede'].includes(action))
+    if (!['create', 'update', 'show', 'context', 'comment', 'comments', 'list', 'retry', 'recover', 'unblock', 'escalate', 'resume-troubleshooter', 'cancel', 'supersede'].includes(action))
         throw new Error(usage);
     const managed = !arg(args, '--file') && Boolean(arg(args, '--repo') && arg(args, '--id'));
     if (managed) {
@@ -142,9 +143,24 @@ async function runTaskCommand(action, args) {
             if (!taskId)
                 throw new Error('task unblock requires --task-id');
             const reason = arg(args, '--reason');
-            if (!reason.trim())
-                throw new Error('task unblock requires --reason');
-            const job = await relayControlCommand(args, { command: 'task.unblock', jobId, taskId, reason });
+            const response = arg(args, '--response');
+            if (!reason.trim() && !response.trim())
+                throw new Error('task unblock requires --reason or --response');
+            const job = await relayControlCommand(args, { command: 'task.unblock', jobId, taskId, reason, ...(response.trim() ? { response } : {}) });
+            console.log(JSON.stringify(job.tasks.find(item => item.id === taskId), null, 2));
+            return;
+        }
+        if (action === 'escalate') {
+            if (!taskId)
+                throw new Error('task escalate requires --task-id');
+            const job = await relayControlCommand(args, { command: 'task.escalate', jobId, taskId, requiredAction: arg(args, '--required-action'), resolutionCondition: arg(args, '--resolution-condition'), context: arg(args, '--context') });
+            console.log(JSON.stringify(job.tasks.find(item => item.id === taskId), null, 2));
+            return;
+        }
+        if (action === 'resume-troubleshooter') {
+            if (!taskId)
+                throw new Error('task resume-troubleshooter requires --task-id');
+            const job = await relayControlCommand(args, { command: 'task.resume-troubleshooter', jobId, taskId, response: arg(args, '--response') });
             console.log(JSON.stringify(job.tasks.find(item => item.id === taskId), null, 2));
             return;
         }
@@ -235,6 +251,18 @@ async function runTaskCommand(action, args) {
         await runTaskUnblockCommand(args, store, job, task, localFile);
         return;
     }
+    if (action === 'escalate') {
+        const result = await requestTroubleshooterEscalation(store, job.id, id, { requiredAction: arg(args, '--required-action'), resolutionCondition: arg(args, '--resolution-condition'), context: arg(args, '--context') });
+        await saveLocal(localFile, result.job);
+        console.log(JSON.stringify(result.task, null, 2));
+        return;
+    }
+    if (action === 'resume-troubleshooter') {
+        const result = await resumeTroubleshooter(store, job.id, id, arg(args, '--response'));
+        await saveLocal(localFile, result.job);
+        console.log(JSON.stringify(result.task, null, 2));
+        return;
+    }
     if (action === 'retry' || action === 'recover' || action === 'cancel') {
         let outputJob = job;
         let outputTask = task;

package/dist/managed-worker-input.js

@@ -68,8 +68,8 @@ ${task.adapter === 'chatgpt' ? `Because ChatGPT execution continues asynchronous
 Before returning or allowing the worker process to exit, you MUST publish exactly one canonical terminal event:
 - task.completed only after the declared output is durable;
 - task.failed for implementation, tool, command, test, patch, commit, push, runtime, or other execution failure that prevents completion;
-- task.blocked only when genuine human/external action is required;
-- task.cancelled only when execution was cancelled.
+- task.completed or task.failed is the only agent terminal result. Relay owns task.blocked/task.unblocked lifecycle transitions; never publish task.blocked for a recovery request;
+- Relay-owned cancellation is not an agent terminal result; if execution cannot continue, publish task.failed.
 
 If any execution step fails and you cannot continue, publish task.failed with the concrete reason BEFORE exiting.
 Never exit after task.started without publishing exactly one terminal task event.

package/dist/reconciler.js

@@ -80,6 +80,9 @@ export class Reconciler extends ReconcilerReviewBase {
         this.reconciling = true;
         try {
             const job = await this.store.load(jobId);
+            for (const live of [...this.live.values()])
+                if (live.jobId === jobId && job.tasks.some(task => task.id === live.taskId && task.state === 'BLOCKED'))
+                    this.cancelExecutionGeneration(jobId, live.taskId, live.executionId);
             const previousState = job.state;
             const lifecycleFingerprint = (value) => `${value.state}|${value.tasks.map(task => `${task.id}:${task.state}`).join(',')}`;
             const beforeFingerprint = lifecycleFingerprint(job);

package/dist/relayd-control.js

@@ -3,7 +3,9 @@ import { InMemoryStore } from './store.js';
 import { openLocalManagedStore } from './local-managed-store.js';
 import { relayStoreDirectory } from './relay-store.js';
 import { normalizeThreadId } from './reviewer-thread.js';
+import { publishTaskBlocked } from './cli-support.js';
 import { supersedeCancelledTask } from './task-actions.js';
+import { requestTroubleshooterEscalation, resumeTroubleshooter } from './task-recovery.js';
 import { adoptExistingPullRequestJob } from './cli-job-create.js';
 export function createWorkspaceControl(deps) {
     const { client, trusted, noGitHub, repositories, refreshAll, requireLocalJobBinding, makeReconciler, concurrency, pool, bus, isEffectivelyBlocked, unblockAutonomousTasks, unblockTask, publishTaskUnblocked, dispatchTaskAction, registerBlockerDependency, discoverAgents, ensureManagedGitHubJob } = deps;
@@ -166,12 +168,36 @@ export function createWorkspaceControl(deps) {
             const task = job.tasks.find((item) => item.id === taskId);
             if (!task)
                 throw new Error(`Task ${taskId} not found`);
+            if (task.agentName === 'troubleshooter' && task.escalation?.status === 'pending' && typeof body.response === 'string') {
+                const resumed = await resumeTroubleshooter(store, jobId, taskId, body.response);
+                await publishTaskUnblocked(bus, resumed.job, taskId, reason || 'Human response recorded');
+                await pool.reconcileLocalJob(jobId, 'control.task.unblock.troubleshooter');
+                return await store.load(jobId);
+            }
             await unblockTask({ store, job, task, trigger: { source: 'cli', reason } });
             const refreshed = await store.load(jobId);
             await publishTaskUnblocked(bus, refreshed, taskId, reason);
             await pool.reconcileLocalJob(jobId, 'control.task.unblock');
             return await store.load(jobId);
         }
+        if (command === 'task.escalate') {
+            const recoveryTaskId = typeof body.taskId === 'string' ? body.taskId : '';
+            const requiredAction = typeof body.requiredAction === 'string' ? body.requiredAction : '';
+            const resolutionCondition = typeof body.resolutionCondition === 'string' ? body.resolutionCondition : '';
+            const context = typeof body.context === 'string' ? body.context : '';
+            const result = await requestTroubleshooterEscalation(store, jobId, recoveryTaskId, { requiredAction, resolutionCondition, context });
+            await publishTaskBlocked(bus, result.job, recoveryTaskId, requiredAction, { escalationId: result.escalation.id, originalTaskId: result.escalation.originalTaskId });
+            await pool.reconcileLocalJob(jobId, 'control.task.escalate');
+            return await store.load(jobId);
+        }
+        if (command === 'task.resume-troubleshooter') {
+            const recoveryTaskId = typeof body.taskId === 'string' ? body.taskId : '';
+            const response = typeof body.response === 'string' ? body.response : '';
+            const resumed = await resumeTroubleshooter(store, jobId, recoveryTaskId, response);
+            await publishTaskUnblocked(bus, resumed.job, recoveryTaskId, 'Human response recorded');
+            await pool.reconcileLocalJob(jobId, 'control.task.resume-troubleshooter');
+            return await store.load(jobId);
+        }
         if (command === 'review.request') {
             if (job.state === 'CANCELLED' || job.state === 'COMPLETED')
                 throw new Error('Cannot request review for terminal Job');

package/dist/review-terminal-normalization.js

@@ -18,6 +18,10 @@ export function normalizeReviewerTerminalEvent(event) {
     const head = [outcome.head_sha, outcome.headSha, review.head_sha, review.headSha,
         data.head_sha, data.headSha]
         .find(value => typeof value === 'string' && value.length > 0);
+    // A unified task.completed review must carry its immutable target explicitly;
+    // native legacy review events may still use the task-bound fallback.
+    if (!head)
+        return null;
     const existingFindings = outcome.blocking_findings ?? outcome.blockingFindings;
     const findings = existingFindings ?? (Array.isArray(data.findings) ? data.findings : undefined);
     return { ...event, type, data: { ...data, outcome: {

package/dist/task-recovery.js

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import { tryTransitionTaskEvent } from './scheduler.js';
+import { dispatchTaskResolutionSync, materializeResolution } from './workflow/task-resolution.js';
+function activeRecovery(job, original) {
+    return job.tasks.find(task => task.agentName === 'troubleshooter'
+        && task.parentTaskId === original.id
+        && ['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED'].includes(task.state));
+}
+function clearExecution(task) {
+    task.leaseOwner = null;
+    task.leaseExpiresAt = null;
+    task.executionId = null;
+}
+function validateRequest(request) {
+    if (!request.requiredAction.trim())
+        throw new Error('Escalation requires a concrete required action');
+    if (!request.resolutionCondition.trim())
+        throw new Error('Escalation requires a resolution condition');
+    if (!request.context.trim())
+        throw new Error('Escalation requires diagnostic context');
+}
+/** Relay-owned escalation: the recovery Task, never the failed original, becomes BLOCKED. */
+export async function requestTroubleshooterEscalation(store, jobId, recoveryTaskId, request, now = new Date().toISOString()) {
+    validateRequest(request);
+    let result;
+    const apply = (job) => {
+        const recovery = job.tasks.find(task => task.id === recoveryTaskId);
+        if (!recovery || recovery.agentName !== 'troubleshooter' || !recovery.parentTaskId)
+            throw new Error(`Task ${recoveryTaskId} is not a Troubleshooter recovery`);
+        if (job.state === 'CANCELLED' || job.state === 'COMPLETED')
+            throw new Error(`Job ${job.id} is terminal`);
+        const original = job.tasks.find(task => task.id === recovery.parentTaskId);
+        if (!original || original.state !== 'FAILED')
+            throw new Error(`Troubleshooter ${recoveryTaskId} has no current FAILED original Task`);
+        if (recovery.escalation?.status === 'pending' && recovery.state === 'BLOCKED') {
+            result = { task: structuredClone(recovery), escalation: structuredClone(recovery.escalation), duplicate: true };
+            return job;
+        }
+        if (!['QUEUED', 'RUNNING'].includes(recovery.state))
+            throw new Error(`Troubleshooter ${recoveryTaskId} cannot escalate from ${recovery.state}`);
+        const proposal = { path: 'escalation_gate', targetTaskId: original.id, rootCause: request.context.trim(), solution: request.requiredAction.trim() };
+        const decision = dispatchTaskResolutionSync(original, proposal, 'troubleshooter', {
+            createEscalationGate: () => { original.resolution = materializeResolution(original, proposal, 'troubleshooter', now); },
+        });
+        if (!decision.accepted)
+            throw new Error(`Task resolution graph rejected escalation for ${original.id}`);
+        if (!tryTransitionTaskEvent(recovery, 'task.blocked').accepted)
+            throw new Error(`Troubleshooter ${recoveryTaskId} cannot be blocked`);
+        const escalation = {
+            id: randomUUID(), originalTaskId: original.id, originalExecutionId: original.executionId ?? undefined,
+            recoveryExecutionId: recovery.executionId ?? undefined, requiredAction: request.requiredAction.trim(),
+            resolutionCondition: request.resolutionCondition.trim(), context: request.context.trim(), status: 'pending',
+            requestedAt: now, notification: request.notification ?? null,
+        };
+        recovery.escalation = escalation;
+        recovery.error = `Waiting for human action: ${escalation.requiredAction}`;
+        recovery.failureReason = 'human_action_required';
+        clearExecution(recovery);
+        recovery.updatedAt = now;
+        result = { task: structuredClone(recovery), escalation, duplicate: false };
+        job.updatedAt = now;
+        return job;
+    };
+    const job = store.mutateJob ? await store.mutateJob(jobId, apply) : await store.load(jobId).then(async (current) => { apply(current); for (const task of current.tasks)
+        await store.saveTask(task); await store.saveJob(current); return current; });
+    if (!result)
+        throw new Error('Escalation did not produce a durable result');
+    return { job, ...result };
+}
+/** Authorized human response; only a blocked Troubleshooter may be resumed. */
+export async function resumeTroubleshooter(store, jobId, recoveryTaskId, response, now = new Date().toISOString()) {
+    if (!response.trim())
+        throw new Error('Troubleshooter response is required');
+    let updated;
+    const apply = (job) => {
+        const task = job.tasks.find(item => item.id === recoveryTaskId);
+        if (!task || task.agentName !== 'troubleshooter' || !task.escalation)
+            throw new Error(`Task ${recoveryTaskId} is not a Troubleshooter escalation`);
+        if (task.escalation.status !== 'pending')
+            throw new Error(`Escalation ${task.escalation.id} already has a response`);
+        if (task.state !== 'BLOCKED')
+            throw new Error(`Task ${recoveryTaskId} is not a blocked Troubleshooter escalation`);
+        if (!tryTransitionTaskEvent(task, 'task.unblocked', { autonomousJob: false }).accepted)
+            throw new Error(`Troubleshooter ${recoveryTaskId} cannot be resumed`);
+        task.escalation = { ...task.escalation, status: 'responded', response: response.trim(), respondedAt: now };
+        task.input += `\n\n## Human response (${now})\n${response.trim()}\n\nRe-validate the original failure against this response. Required resolution condition: ${task.escalation.resolutionCondition}`;
+        task.result = null;
+        task.error = null;
+        task.failureReason = undefined;
+        clearExecution(task);
+        task.updatedAt = now;
+        updated = structuredClone(task);
+        job.updatedAt = now;
+        return job;
+    };
+    const job = store.mutateJob ? await store.mutateJob(jobId, apply) : await store.load(jobId).then(async (current) => { apply(current); for (const task of current.tasks)
+        await store.saveTask(task); await store.saveJob(current); return current; });
+    if (!updated)
+        throw new Error('Troubleshooter was not resumed');
+    return { job, task: updated };
+}
+export function hasPendingTroubleshooterEscalation(job, original) {
+    const recovery = activeRecovery(job, original);
+    return recovery?.state === 'BLOCKED' && recovery.escalation?.status === 'pending';
+}

package/dist/unblock.js

@@ -1,7 +1,12 @@
 import { applyTaskUnblockRetrySnapshot } from './task-actions.js';
 import { tryTransitionTaskEvent } from './scheduler.js';
 import { dispatchAuthoritativeUnblock } from './workflow/authoritative-unblock-v2.js';
+import { hasPendingTroubleshooterEscalation } from './task-recovery.js';
 export function isEffectivelyBlocked(task) { return task.kind !== 'planner' && task.state === 'BLOCKED'; }
+function assertNoPendingHumanEscalation(tasks) {
+    if (tasks.some(task => task.agentName === 'troubleshooter' && task.escalation?.status === 'pending'))
+        throw new Error('Blocked Troubleshooter requires an authorized human response; use task unblock --response');
+}
 function baselineFor(task) {
     return task.blockedBaseline ?? { blockedAt: task.updatedAt, reason: task.error ?? undefined };
 }
@@ -59,6 +64,7 @@ export async function unblockAutonomousTasks(options) {
     const tasks = options.tasks.filter(isEffectivelyBlocked);
     if (tasks.length === 0)
         throw new Error('No effective BLOCKED work task is available to unblock');
+    assertNoPendingHumanEscalation(tasks);
     const now = options.now ?? new Date().toISOString();
     const currentHeadSha = await store.headSha?.() ?? job.headSha ?? null;
     const facts = unblockFacts(job, tasks, currentHeadSha, trigger.reason);
@@ -95,6 +101,10 @@ export async function unblockAutonomousTasks(options) {
 export async function unblockTask(options) {
     if (!isEffectivelyBlocked(options.task))
         throw new Error(`Task ${options.task.id} is not an effective BLOCKED work task`);
+    assertNoPendingHumanEscalation([options.task]);
+    if (options.task.agentName !== 'troubleshooter' && hasPendingTroubleshooterEscalation(options.job, options.task)) {
+        throw new Error(`Task ${options.task.id} cannot be directly unblocked while its Troubleshooter is awaiting human action`);
+    }
     let result;
     const decision = await dispatchAuthoritativeUnblock(options.job.executionMode === 'autonomous', async (actionId) => {
         if (actionId === 'unblock.replan') {

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "agents-relay",
-  "version": "2.0.108",
+  "version": "2.0.109",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lalalic/agents-relay.git"
+  },
   "type": "module",
   "bin": {
     "agents-relay": "dist/cli.js",

package/skills/agents-relay/SKILL.md

@@ -9,6 +9,8 @@ Use Agents Relay when an orchestrator needs durable delegated work that survives
 
 ## Required shared contract
 
+For unified agent terminal events and role-specific results, see `contracts/event-contract.md` and `contracts/task-recovery-flows.md`.
+
 Before creating, planning, reviewing, or managing a job/task, read and follow `contracts/task-job-contract.md`. This is the canonical producer/runtime protocol for story size, lifecycle events, review, and auto-merge.
 
 ## Core task contract
@@ -39,7 +41,7 @@ Agents Relay may launch a Codex process or submit a one-shot ChatGPT browser tas
 A running agent MUST use the canonical Neo `events-bus` protocol and publish exactly one correlated terminal event before stopping:
 - `task.completed` after the declared output is durable;
 - `task.failed` when the task cannot complete;
-- `task.blocked` when external or human action is required.
+- Progress is optional; `task.blocked` and `task.unblocked` are Relay-owned lifecycle facts, never agent terminal events.
 
 Event publishing is not an Agents Relay CLI responsibility. Sandboxed Codex and hosted ChatGPT workers use the federated `events__publish` MCP tool from `events-bus`; direct non-sandbox local workers may use the caller-provided `NEO_EVENTS_EMIT`. Agents Relay subscribes to the canonical `neo.events.job.<job_id>.>` stream and maps terminal events into durable task state. Relay resolves its native NATS endpoint and subject prefix from the canonical events-bus runtime configuration (with explicit Relay CLI flags remaining authoritative). The same runtime configuration supplies the events-bus HTTP API used for replay/history. Relay and its dashboard must not read the events-bus private history file or maintain a second event-history backend.
 
@@ -48,7 +50,7 @@ The event must carry the exact durable `job_id` and `task_id`. Progress events a
 Agents Relay maps those terminal events to durable state:
 - `task.completed` → `SUCCEEDED`
 - `task.failed` → `FAILED`
-- `task.blocked` → `BLOCKED`
+Relay may authoritatively move a Task to `BLOCKED` for an external condition and may resume it only through an authorized unblock operation. A human response resumes the blocked Troubleshooter, not the failed original Task.
 
 A model-backed task must not launch without an event bus. If no terminal event arrives before the task timeout, Relay records an explicit timeout failure. A Codex process exit or ChatGPT submission receipt alone never changes the task to a terminal state.
 

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

@@ -22,3 +22,6 @@ identity supplied by Relay for every lifecycle event.
 Run the most relevant tests and checks for the change. Do not claim completion
 without durable implementation evidence, validation results, and a concise
 summary of changed files and remaining risks.
+
+Use only `task.completed` or `task.failed` as the terminal agent event;
+block/unblock decisions belong to Relay. See `../contracts/event-contract.md`.

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

@@ -16,3 +16,14 @@ Reconstruct all material acceptance requirements from the durable Job objective
 ## Review Decision
 
 Return a concrete approved, changes-required or blocked verdict tied to the declared immutable target, with attributed findings, severity and remediation steps. Do not alter artifacts, generate approvals on behalf of users, or perform publication, merges or external actions. Relay owns the review lifecycle and Task/Job completion.
+
+## Unified execution event
+
+After completing the review, publish **`task.completed`**, including `data.verdict`
+(`approved`, `changes-required`, or `blocked`), the **exact immutable**
+`data.head_sha`, and actionable `data.findings` for changes required. A
+negative verdict is a successful review, not `task.failed`. If review
+execution fails and no sound verdict can be produced, publish `task.failed`.
+Never emit `review.*` as the agent's terminal event. The event source must
+match the execution identity supplied by Relay. See
+`../contracts/event-contract.md`.

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

@@ -29,8 +29,8 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
    - 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.
    - For a shared platform/runtime defect, first create or reuse the owning blocker P0/self-job. If it can be completed inside this recovery execution, fix/verify it and retry the original Task. If it cannot be completed now, register the original Task with `agents-relay blocker add` on that blocker Job and finish this Troubleshooter task; do not stay running while waiting for another Job.
-   - For a suspected genuine human/external blocker, do not publish `task.blocked` and do not branch on Neo's result yourself. Invoke `agents-relay escalation` with the original intent, blocker, and relevant context. If the recovery context defines a preferred way to contact the user, pass that description through `--on-needs-user` or `--on-needs-user-file`; Relay must not hard-code a channel. The canonical `workflow/escalation.mmd` graph invokes Neo escalation and owns the `resolved` / `failed` / `needs_user` decision. Follow the graph-selected outcome: resume recovery, preserve technical-failure evidence, or publish `task.blocked` with the exact returned user action and notification evidence.
-6. For an immediate repair, only after the blocker is removed run `agents-relay task retry` for the original Task and reconcile its Job. For deferred repair, rely on the durable blocker relation: merge-mode blockers wake matching dependents after merge; release/deploy/runtime blockers use `--resolution verified` and `agents-relay blocker resolve` only after verification.
+   - For a suspected genuine human/external blocker, do not publish `task.blocked` and do not branch on Neo's result yourself. Invoke `agents-relay escalation` with the original intent, blocker, and relevant context. The canonical graph owns the `resolved`, `failed`, and `needs_user` outcomes. When it returns `needs_user`, call Relay's `task escalate` operation with the concrete required action, resolution condition, and diagnostic context. Relay records the escalation and blocks this Troubleshooter; no worker remains running while waiting.
+6. For an immediate repair, only after the blocker is removed run `agents-relay task recover` for the original Task with this Troubleshooter's recovery Task ID and reconcile its Job. An authorized human response resumes this same Troubleshooter with its diagnostic context; verify the action before requesting original-task recovery. For deferred repair, rely on the durable blocker relation: merge-mode blockers wake matching dependents after merge; release/deploy/runtime blockers use `--resolution verified` and `agents-relay blocker resolve` only after verification.
 7. Verify durable evidence that the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
 8. Publish this Troubleshooter Task's terminal event only after the recovery outcome is durable.
 

package/skills/agents-relay/contracts/event-contract.md

@@ -0,0 +1,30 @@
+# Agents Relay Unified Task Event Contract
+
+**Scope:** Relay-specific event meaning and validation. This does **not** define Events Bus transport. The bus only handles generic event identity, type, timestamp, routing as needed, and opaque `data`. No Events Bus change is required when Relay adds agent roles or payload fields.
+
+## Producer contract
+
+Every Implementation, Reviewer, and Troubleshooter execution publishes `task.started`, optional `task.progress` or `task.heartbeat`, then **exactly one** agent terminal event:
+
+- `task.completed`: assigned responsibility finished and its role-specific output is durable, regardless of whether a reviewed artifact passed.
+- `task.failed`: assigned responsibility could not be fulfilled; include failure phase, reason, and evidence in `data`.
+
+`task.blocked` and `task.unblocked` are **Relay-owned lifecycle facts**, not agent terminal outcomes. Transport acceptance is not proof Relay accepted the transition. Every lifecycle event must use the exact Job, Task, and execution source identity provided by Relay; stale/duplicate execution events cannot change current state.
+
+## Role-specific completed data
+
+| Role | `task.completed.data` | Relay action |
+| --- | --- | --- |
+| Implementation | Evidence of output/artifact, validation, and summary as required by the Task | Persist Task success and continue dependencies/review |
+| Reviewer | `verdict` (`approved`, `changes-required`, or `blocked`), exact immutable `head_sha`, actionable `findings` as necessary | Validate current immutable review target and apply verdict; defects are a successful Reviewer execution, not `task.failed` |
+| Troubleshooter | Recovery action and durable evidence of verified original Task retry, blocker-Job handoff, or other authorized recovery | Complete recovery Task only; original Task state changes through separately authorized Relay operations |
+
+A Reviewer must **not** publish unstructured `task.completed`: missing verdict or immutable head is invalid. Relay normalizes an authenticated structured Reviewer terminal event into its internal Review decision; native `review.*` events may be accepted for backward compatibility.
+
+## Troubleshooter human escalation
+
+Only a real user action merits escalation. Troubleshooter invokes the Relay escalation operation, specifying the required action, resolution condition, and diagnostic context. Relay durably records the human action and blocks **the Troubleshooter Task**, leaving the original failed Task `FAILED`. This is a Relay state transition, not a third agent terminal event.
+
+When the human responds, the **Troubleshooter Task** is authoritatively unblocked and resumed with its prior context plus the response. Troubleshooter independently verifies resolution, requests an authorized original Task recovery, and only then publishes its own `task.completed`. If unresolved, it continues diagnosis or escalates again; human assertion alone is not technical verification.
+
+See [task-recovery-flows.md](task-recovery-flows.md) for unified architecture, overall flow, failure recovery, and post-blocked resumption.

package/skills/agents-relay/contracts/task-recovery-flows.md

@@ -0,0 +1,135 @@
+# Task Failure Recovery and Human Escalation — Agreed Target Design
+
+**Status:** Design agreement; not an assertion of current implementation. This document describes two flows. Existing runtime, workflow graphs, and agent instructions may need changes to conform.
+
+## Principles and ownership
+
+- **Events Bus is neutral.** Its generic event envelope consists of event identity, type, time, and opaque client-defined data (plus any transport metadata needed by the bus). It must not understand Relay Jobs, Tasks, roles, or verdicts.
+- **One agent Task event contract** applies to Implementation, Reviewer, and Troubleshooter: optional progress, then exactly one agent terminal event, `task.completed` or `task.failed`. Role-specific results belong in `data`. A review with findings is a *completed* review, not a failed agent execution.
+- **`task.blocked` and `task.unblocked` are authoritative Relay lifecycle transitions**, not ordinary agent terminal events. A human may authorize unblocking a Troubleshooter but does not directly unblock the failed original Task.
+- **Troubleshooter owns diagnosis and recovery decisions.** It chooses technical repair/retry, blocker-Job dependency, or human escalation. There is no separate Escalator agent.
+- **Relay owns transitions and dispatch.** Troubleshooter requests authorized operations; the reconciler/engine validates and durably applies them. An event arriving over the bus is not proof its transition was applied.
+- Preserve the original failure, exact execution correlation, evidence, and idempotency throughout retries and resumes.
+
+## Unified architecture
+
+All three agent roles publish through the **same Task event contract**. Events Bus treats `data` as opaque; Relay interprets role-specific results and alone changes durable Task/Job state.
+
+```mermaid
+flowchart TD
+    I["Implementation"] --> U["Unified Task events"]
+    V["Reviewer"] --> U
+    T["Troubleshooter"] --> U
+    U --> B["Neutral Events Bus"]
+    B --> C["Relay event consumer"]
+    C --> S["Validate execution identity and role-specific data"]
+    S --> W["Relay workflow engine / reconciler"]
+    W --> D[("Durable Task and Job state")]
+    W --> R["Execution / recovery / human-interaction operations"]
+```
+
+- Agents publish `task.completed` or `task.failed` as terminal execution outcomes; Reviewer verdicts and Troubleshooter recovery evidence are results inside `data`.
+- `task.blocked` / `task.unblocked` describe Relay-authorized state changes, not a third agent terminal outcome.
+- Transport does not interpret verdicts, execution IDs, blocker relations, or recovery decisions.
+
+## Overall flow — Task outcome and recovery branches
+
+This captures the overall decision tree in the accompanying design screenshot, with the **human-action branch corrected** to the agreed ownership: Relay blocks the **Troubleshooter Task**, not the original failed Task.
+
+```mermaid
+flowchart TD
+    A["Worker / Reviewer"] --> B{"Task outcome"}
+    B -->|Success| C["task.completed"]
+    B -->|Failure| D["task.failed"]
+    D --> E["Relay dispatches Troubleshooter"]
+    E --> F{"Recovery decision"}
+    F -->|Technical recovery| G["Fix and verify; request retry"]
+    G --> H["Original Task resumes"]
+    F -->|Other Job required| I["Create/link blocker Job"]
+    I --> J["Dependency resolution"]
+    J --> K["Original Task resumes after verification"]
+    F -->|Human required| L["Troubleshooter requests escalation"]
+    L --> M["Relay records human action and blocks TROUBLESHOOTER"]
+    M --> N["Wait for human action"]
+    N --> O["Human unblocks TROUBLESHOOTER"]
+    O --> P["Troubleshooter resumes; verifies result"]
+    P --> Q{"Problem resolved?"}
+    Q -->|Yes| R["Relay retries original Task"]
+    Q -->|No| F
+    R --> S["Original Task resumes"]
+```
+
+The original Task remains `FAILED` while its Troubleshooter is blocked for a human action. Technical and dependent-Job paths may close the Troubleshooter Task after durable recovery or handoff; the human-action path resumes that same recovery responsibility after authorized unblock.
+
+## Flow 1 — Failure → Troubleshooter → Recovery
+
+```mermaid
+flowchart TD
+    A["Implementation / Reviewer task.failed"] --> B["Relay records failure and dispatches Troubleshooter"]
+    B --> C["Troubleshooter inspects events, Task, logs; diagnoses cause"]
+    C --> D{"Selected resolution"}
+    D -->|Repairable now| E["Repair / verify technical cause"]
+    E --> F["Request original Task retry"]
+    D -->|Needs another Job| G["Create or reuse blocker Job; register dependency"]
+    G --> H["Troubleshooter completes after durable registration"]
+    D -->|Requires real user action| I["Enter Flow 2: human escalation"]
+    F --> J["Relay validates and requeues original Task"]
+    J --> K["Troubleshooter completes after durable recovery evidence"]
+```
+
+1. Original agent reports `task.failed` with useful diagnostic `data`; Relay durably records `FAILED`.
+2. Reconciler starts a correlated Troubleshooter Task. Troubleshooter examines durable Task history and technical evidence before choosing a resolution.
+3. For a technical remedy, Troubleshooter repairs/validates, requests authorized retry, confirms the original Task requeued, and completes **its own** Task.
+4. For a blocker Job, Troubleshooter registers a durable dependency, then completes **its own** Task; the dependency mechanism later wakes the original Task after verified resolution.
+5. Only a **real user action** calls for human escalation (Flow 2). Missing credentials that can be found or configured automatically, crashes, and retries are Troubleshooter work, not escalation.
+6. If Troubleshooter itself encounters an unrecoverable execution failure, it emits `task.failed`; Relay handles that failure without discarding original context.
+
+## Flow 2 — Human Escalation → Blocked Troubleshooter → Human Unblock → Original Task Recovery
+
+```mermaid
+flowchart TD
+    A["Troubleshooter determines real human action is required"] --> B["Troubleshooter triggers escalation request"]
+    B --> C["Relay durably records required action, context, and escalation ID"]
+    C --> D["Relay marks TROUBLESHOOTER Task BLOCKED"]
+    D --> E["Human acts and submits response"]
+    E --> F["Human authorizes unblock of TROUBLESHOOTER"]
+    F --> G["Relay validates authorization, records response, resumes Troubleshooter"]
+    G --> H["Troubleshooter verifies action and re-diagnoses"]
+    H --> I{"Original failure now recoverable?"}
+    I -->|Yes| J["Troubleshooter requests original Task unblock/retry"]
+    J --> K["Relay validates and requeues original Task"]
+    K --> L["Troubleshooter task.completed"]
+    I -->|No, still needs user| B
+    I -->|No, technical issue| M["Continue Flow 1 recovery"]
+    M --> H
+```
+
+1. **Troubleshooter** selects escalation as its recovery resolution and requests a concrete user action. Escalation is an interaction mechanism, **not a second problem-solving agent**.
+2. Relay durably records the escalation ID, original failed Task/execution, Troubleshooter Task/execution, required human action, resolution condition, communication evidence/status, and audit trail; then it authoritatively moves the **Troubleshooter Task** to `BLOCKED`. The original Task stays `FAILED` (pending recovery), not `BLOCKED` merely because the Troubleshooter awaits a human.
+3. While awaiting human action, no Troubleshooter execution continues running. Notification failures and duplicate requests must not silently create orphaned BLOCKED Tasks.
+4. Human performs the requested action and explicitly unblocks the **Troubleshooter** through an authorized Relay operation. Relay stores the response and resumes Troubleshooter with its previous diagnostic context.
+5. Troubleshooter validates whether the action resolved the problem. Human saying “done” is evidence, not by itself proof of technical resolution (unless the requested action was itself an authoritative approval).
+6. If resolved, Troubleshooter requests Relay to unblock/retry the **original Task**, verifies the durable transition, then emits `task.completed` for its own Task. If unresolved, it continues technical diagnosis or initiates another recorded escalation.
+7. Relay guards against stale execution IDs, cancelled/superseded Tasks, duplicate human responses, and paused Jobs. No old response may resurrect obsolete work.
+
+## Event contract versus state transitions
+
+| Actor | Action | Meaning |
+| --- | --- | --- |
+| Implementation / Reviewer | `task.completed` | Assigned work finished; Reviewer verdict is in `data` |
+| Implementation / Reviewer | `task.failed` | Execution could not fulfill assigned work |
+| Troubleshooter | `task.completed` | Technical recovery verified, or durable blocker-Job handoff established |
+| Troubleshooter | `task.failed` | Troubleshooter execution failed |
+| Troubleshooter | Escalation request (Relay operation) | Request a specific real human action; does **not** complete its own Task |
+| Relay | Block / unblock Troubleshooter | Authoritative lifecycle actions before/after human interaction |
+| Relay | Retry / unblock original Task | Authorized transition **only after** Troubleshooter establishes recovery |
+| Events Bus | Transport generic events | No knowledge of task roles, blocker semantics, or response structure |
+
+`BLOCKED` is a durable Task state and `task.blocked` may be published by Relay as a state-change fact; it is **not** an agent-selected terminal outcome. Human unblocking resumes the blocked Troubleshooter Task rather than terminating or re-creating its recovery responsibility.
+
+## Required follow-up implementation alignment
+
+- Align `skills/agents-relay/SKILL.md` and role instructions with the two agent terminal events; remove agent-directed `task.blocked` emission.
+- Align escalation graph, CLI, reconciler, and unblock commands so human intervention blocks **Troubleshooter**, not the original failed Task; preserve the original failure and correlated recovery context.
+- Ensure the blocked Troubleshooter can resume after an authorized human unblock rather than being treated as a finished terminal execution.
+- Add integrated checks: technical retry, blocker-Job handoff, human request/block, human unblock/resume, failed verification/re-escalation, stale/duplicate responses, and correct original-Task retry.