agents-relay 2.0.155 → 2.0.157

package/dist/types.js

@@ -5,13 +5,19 @@ export function taskOverallTimeoutMs(size, reasoning) { return storySizeTimeoutM
 export function chatGptStartAckTimeoutMs(overallTimeoutMs) { return Math.min(600000, Math.max(120000, Math.floor(overallTimeoutMs / 3))); }
 /** Normalize snapshots written before UNBLOCKED was removed from the lifecycle graph. */
 export function normalizeLegacyTaskLifecycle(task, executionMode) {
+    void executionMode;
     const legacy = task;
-    if (legacy.state !== 'UNBLOCKED')
-        return task;
-    legacy.state = executionMode === 'autonomous' ? 'DRAFT' : 'QUEUED';
-    // Preserve the historical execution count when upgrading old snapshots.
-    task.maxAttempts = Math.max(3, task.maxAttempts ?? 0, task.attempt + 1);
-    task.unblock = task.unblock ? { ...task.unblock, event: 'task.unblocked' } : undefined;
+    if (legacy.state === 'UNBLOCKED') {
+        legacy.state = task.agentName === 'troubleshooter' ? 'QUEUED' : 'FAILED';
+        task.failureReason ??= 'legacy_unblocked_task_requires_recovery';
+        task.maxAttempts = Math.max(3, task.maxAttempts ?? 0, task.attempt + 1);
+        task.unblock = task.unblock ? { ...task.unblock, event: 'task.unblocked' } : undefined;
+    }
+    if (legacy.state === 'BLOCKED' && task.kind !== 'planner' && task.agentName !== 'troubleshooter') {
+        legacy.state = 'FAILED';
+        task.failureReason ??= task.failureReason === 'worker_outcome_unknown' ? task.failureReason : 'legacy_ordinary_blocked';
+        task.error ??= 'Legacy ordinary Task was BLOCKED; preserved as FAILED pending Troubleshooter diagnosis.';
+    }
     return task;
 }
 export function assertJobLifecycleTransition(from, to) { assertV2StateTransition(jobLifecycleV2.graph, from, to, 'job'); }

package/dist/unblock.js

@@ -2,7 +2,7 @@ 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'; }
+export function isEffectivelyBlocked(task) { return task.kind !== 'planner' && task.agentName === 'troubleshooter' && 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');
@@ -32,7 +32,7 @@ function unblockFacts(job, tasks, currentHeadSha, reason) {
 }
 export function unconsumedUnblockTrigger(job) {
     const consumed = new Set((job.plans ?? []).filter(plan => plan.status === 'SUCCEEDED').flatMap(plan => plan.trigger.source === 'unblock' ? plan.trigger.taskIds ?? [] : []));
-    const tasks = job.tasks.filter(task => task.unblock && !consumed.has(task.id) && ['DRAFT', 'QUEUED', 'UNBLOCKED'].includes(task.state));
+    const tasks = job.tasks.filter(task => task.agentName !== 'troubleshooter' && task.unblock && !consumed.has(task.id) && ['DRAFT', 'QUEUED'].includes(task.state));
     if (tasks.length === 0) {
         const legacy = job.changeCycle;
         if (!legacy || legacy.consumedByPlannerTaskId)
@@ -60,43 +60,8 @@ export function unblockNeedsNewPlan(job) {
         && latest.trigger.taskIds?.some(id => pending.taskIds?.includes(id)));
 }
 export async function unblockAutonomousTasks(options) {
-    const { store, job, trigger } = 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);
-    const apply = (current) => {
-        for (const requested of tasks) {
-            const task = current.tasks.find(item => item.id === requested.id);
-            if (!task || !isEffectivelyBlocked(task))
-                throw new Error(`Task ${requested.id} changed before authoritative unblock`);
-            const baseline = baselineFor(task);
-            if (!tryTransitionTaskEvent(task, 'task.unblocked', { autonomousJob: true }).accepted)
-                throw new Error(`Task ${task.id} cannot be authoritatively unblocked`);
-            task.blockedBaseline = baseline;
-            task.unblock = { event: 'task.unblocked', at: now, source: trigger.source, reason: trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, facts, blockerJobId: trigger.blockerJobId, resolution: trigger.resolution };
-            task.updatedAt = now;
-            delete task.blockedBy;
-        }
-        current.updatedAt = now;
-    };
-    if (store.mutateJob) {
-        const committed = await store.mutateJob(job.id, current => { apply(current); return current; });
-        Object.assign(job, structuredClone(committed));
-    }
-    else {
-        apply(job);
-        for (const task of tasks)
-            await store.saveTask(task);
-    }
-    const planTrigger = unconsumedUnblockTrigger(job) ?? {
-        source: 'unblock', taskIds: tasks.map(task => task.id), reason: trigger.reason,
-        facts, currentHeadSha: currentHeadSha ?? undefined, unblockSource: trigger.source,
-    };
-    return planTrigger;
+    void options;
+    throw new Error('Ordinary Tasks cannot be authoritatively unblocked; only a blocked Troubleshooter can resume');
 }
 export async function unblockTask(options) {
     if (!isEffectivelyBlocked(options.task))
@@ -106,11 +71,7 @@ export async function unblockTask(options) {
         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') {
-            result = { replanning: true, planTrigger: await unblockAutonomousTasks({ store: options.store, job: options.job, tasks: [options.task], trigger: options.trigger, now: options.now }) };
-            return {};
-        }
+    const decision = await dispatchAuthoritativeUnblock(options.task.agentName === 'troubleshooter', async (actionId) => {
         if (actionId === 'unblock.retry') {
             const now = options.now ?? new Date().toISOString();
             const currentHeadSha = await options.store.headSha?.() ?? options.job.headSha ?? null;

package/dist/workflow/authoritative-unblock-v2.js

@@ -4,17 +4,16 @@ import { dispatchWorkflowGraph, dispatchWorkflowGraphSync } from './dispatcher.j
 const source = readFileSync(new URL('../../workflow/authoritative-unblock.mmd', import.meta.url), 'utf8');
 const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
 export const authoritativeUnblockV2 = new GraphRuntime(source, {
-    states: new Set(['blocked', 'autonomous_replan', 'fixed_retry']),
-    guards: { autonomousJob: boolGuard('autonomousJob') },
+    states: new Set(['blocked', 'troubleshooter_queued']),
+    guards: { blockedTroubleshooter: boolGuard('blockedTroubleshooter') },
     actions: {
-        'unblock.replan': { id: 'unblock.replan' },
         'unblock.retry': { id: 'unblock.retry' },
     },
     events: { 'task.authoritative_unblock': { id: 'task.authoritative_unblock' } },
 });
-export async function dispatchAuthoritativeUnblock(autonomousJob, executeAction) {
-    return dispatchWorkflowGraph(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, graphName: 'authoritative-unblock', durableFacts: { autonomousJob }, executeAction });
+export async function dispatchAuthoritativeUnblock(blockedTroubleshooter, executeAction) {
+    return dispatchWorkflowGraph(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, graphName: 'authoritative-unblock', durableFacts: { blockedTroubleshooter }, executeAction });
 }
-export function decideAuthoritativeUnblock(autonomousJob) {
-    return dispatchWorkflowGraphSync(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, graphName: 'authoritative-unblock', durableFacts: { autonomousJob } });
+export function decideAuthoritativeUnblock(blockedTroubleshooter) {
+    return dispatchWorkflowGraphSync(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, graphName: 'authoritative-unblock', durableFacts: { blockedTroubleshooter } });
 }

package/dist/workflow/contracts.js

@@ -12,6 +12,7 @@ export const WORKFLOW_EVENT_NAMES = [
     'hold',
     'lease.expired',
     'implementation.completed',
+    'interactive.waiting',
     'local.completed',
     'local.merge.requested',
     'effect.deliverLocalMerge.failed',
@@ -38,6 +39,7 @@ export const WORKFLOW_EVENT_NAMES = [
     'task.progress',
     'task.started',
     'task.unblocked',
+    'interactive.waiting',
     'watchdog.failed',
     'worker.delivery_failed',
     'worker.start_ack_failed',
@@ -70,6 +72,7 @@ export const WORKFLOW_MUTATION_NAMES = [
     'mutation.clearExecution',
     'mutation.markLeaseExpired',
     'mutation.markStartupOrphanedExhausted',
+    'mutation.markUnknownOutcome',
     'mutation.markPlannerUnavailable',
     'mutation.preparePlatformFallback',
     'mutation.quarantinePlatformFailure',

package/dist/workflow/definitions-v2.js

@@ -5,7 +5,7 @@ import { WORKFLOW_EFFECT_NAMES, WORKFLOW_EVENT_NAMES, WORKFLOW_MUTATION_NAMES, }
 const TASK_STATES = ['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'];
 const JOB_STATES = ['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'];
 const conditionRegistry = new ConditionRegistry([
-    ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'troubleshooterRecovery', 'retryAvailable', 'autonomousJob', 'platformFallbackSafe', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady'])
+    ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'troubleshooterRecovery', 'troubleshooterTask', 'awaitingInteractiveDecision', 'retryAvailable', 'autonomousJob', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady'])
 ].map(booleanCondition));
 const boolGuard = (name) => conditionRegistry.guard(name);
 export const lifecycleConditions = conditionRegistry;
@@ -31,9 +31,10 @@ export const taskLifecycleV2 = load('task-lifecycle', TASK_STATES, {
     dispatchable: boolGuard('dispatchable'),
     recoverableExecution: boolGuard('recoverableExecution'),
     troubleshooterRecovery: boolGuard('troubleshooterRecovery'),
+    troubleshooterTask: boolGuard('troubleshooterTask'),
+    awaitingInteractiveDecision: facts => facts.durableFacts.awaitingInteractiveDecision === true,
     retryAvailable: boolGuard('retryAvailable'),
     autonomousJob: boolGuard('autonomousJob'),
-    platformFallbackSafe: boolGuard('platformFallbackSafe'),
 });
 export const jobLifecycleV2 = load('job-lifecycle', JOB_STATES, {
     notMerged: boolGuard('notMerged'),

package/dist/workflow/lifecycle.js

@@ -26,7 +26,7 @@ function v2WorkflowDecision(runtime, from, event, facts = {}) {
     };
 }
 export function decideTaskLifecycle(task, event, facts = {}) {
-    return v2WorkflowDecision(taskLifecycleV2, task.state, event, facts);
+    return v2WorkflowDecision(taskLifecycleV2, task.state, event, { ...facts, troubleshooterTask: task.agentName === 'troubleshooter' });
 }
 export function decideJobLifecycle(job, event, facts = {}) {
     return v2WorkflowDecision(jobLifecycleV2, job.state, event, facts);
@@ -36,9 +36,9 @@ export function dispatchTaskLifecycleSync(task, event, facts = {}) {
     const result = dispatchWorkflowGraphSync(taskLifecycleV2, {
         initialState: task.state,
         input: { transport: 'event', id: event, payload: {} },
-        durableFacts: facts,
+        durableFacts: { ...facts, troubleshooterTask: task.agentName === 'troubleshooter' },
         graphName: 'task-lifecycle',
-        persistTransition: (_source, target) => applyTaskGraphTarget(task, target),
+        persistTransition: (_source, target) => applyTaskGraphTarget(task, target, new Date().toISOString(), event === 'task.unblocked' && task.agentName === 'troubleshooter'),
         executeAction: actionId => { actions.push(actionId); if (actionId.startsWith('mutation.'))
             applyTaskMutation(task, actionId); return {}; },
     });
@@ -49,9 +49,9 @@ export function dispatchTaskLifecycleSync(task, event, facts = {}) {
 export async function dispatchTaskLifecycle(task, event, facts = {}, executeEffect, persist) {
     const actions = [];
     const result = await dispatchWorkflowGraph(taskLifecycleV2, {
-        initialState: task.state, input: { transport: 'event', id: event, payload: {} }, durableFacts: facts,
+        initialState: task.state, input: { transport: 'event', id: event, payload: {} }, durableFacts: { ...facts, troubleshooterTask: task.agentName === 'troubleshooter' },
         graphName: 'task-lifecycle',
-        persistTransition: async (_source, target) => { applyTaskGraphTarget(task, target); await persist?.(); },
+        persistTransition: async (_source, target) => { applyTaskGraphTarget(task, target, new Date().toISOString(), event === 'task.unblocked' && task.agentName === 'troubleshooter'); await persist?.(); },
         executeAction: async (actionId) => {
             actions.push(actionId);
             if (actionId.startsWith('mutation.'))

package/dist/workflow/orchestrator-rescue.js

@@ -7,7 +7,7 @@ export const STALE_ORCHESTRATOR_TASK_MS = 30 * 60 * 1000;
 const source = readFileSync(new URL('../../workflow/orchestrator-rescue.mmd', import.meta.url), 'utf8');
 const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
 export const orchestratorRescueV2 = new GraphRuntime(source, {
-    states: new Set(['idle', 'check', 'external_completed', 'blocked', 'skip', 'rescued']),
+    states: new Set(['idle', 'check', 'external_completed', 'failed', 'skip', 'rescued']),
     guards: {
         legacyActive: boolGuard('legacyActive'),
         verifiedExternalCompletion: boolGuard('verifiedExternalCompletion'),
@@ -16,7 +16,7 @@ export const orchestratorRescueV2 = new GraphRuntime(source, {
     },
     actions: {
         'task.applyExternalCompletion': { id: 'task.applyExternalCompletion' },
-        'task.blockLegacyOrchestrator': { id: 'task.blockLegacyOrchestrator' },
+        'task.failLegacyOrchestrator': { id: 'task.failLegacyOrchestrator' },
         'task.rescueOrchestrator': { id: 'task.rescueOrchestrator' },
     },
     events: { 'orchestrator.rescue.reconcile': { id: 'orchestrator.rescue.reconcile' } },
@@ -46,9 +46,9 @@ export function prepareOrchestratorRepair(task, now) {
     const decision = decideOrchestratorRescue(task, now);
     const externallyCompleted = decision.accepted
         && decision.actions.some(action => action.id === 'task.applyExternalCompletion');
-    const blocked = decision.accepted
-        && decision.actions.some(action => action.id === 'task.blockLegacyOrchestrator');
-    const rescued = externallyCompleted || blocked
+    const failed = decision.accepted
+        && decision.actions.some(action => action.id === 'task.failLegacyOrchestrator');
+    const rescued = externallyCompleted || failed
         || (decision.accepted && decision.actions.some(action => action.id === 'task.rescueOrchestrator'));
     const ageMs = now - Date.parse(task.createdAt);
     if (decision.accepted && externallyCompleted) {
@@ -58,19 +58,20 @@ export function prepareOrchestratorRepair(task, now) {
         task.executionId = null;
         task.threadId = null;
         task.updatedAt = new Date(now).toISOString();
-        return { repaired: true, externallyCompleted: true, blocked: false, ageMs };
+        return { repaired: true, externallyCompleted: true, failed: false, ageMs };
     }
     if (!rescued)
-        return { repaired: false, externallyCompleted: false, blocked: false, ageMs };
-    if (blocked) {
-        tryTransitionTaskEvent(task, 'task.blocked');
-        task.error = 'Legacy orchestrator execution outcome is unknown; automatic replay is unsafe. Verify external effects and create replacement validation/recovery work before unblocking.';
+        return { repaired: false, externallyCompleted: false, failed: false, ageMs };
+    if (failed) {
+        tryTransitionTaskEvent(task, 'task.failed');
+        task.error = 'Legacy orchestrator execution outcome is unknown; Troubleshooter diagnosis is required before retry.';
+        task.failureReason = 'worker_outcome_unknown';
         task.leaseOwner = null;
         task.leaseExpiresAt = null;
         task.executionId = null;
         task.threadId = null;
         task.updatedAt = new Date(now).toISOString();
-        return { repaired: true, externallyCompleted: false, blocked: true, ageMs };
+        return { repaired: true, externallyCompleted: false, failed: true, ageMs };
     }
     task.adapter = 'codex';
     task.workerRequirements = { capabilities: [...task.capabilities] };
@@ -82,5 +83,5 @@ export function prepareOrchestratorRepair(task, now) {
     task.threadId = null;
     task.timeoutMs = taskOverallTimeoutMs(task.storySize ?? 'M');
     task.updatedAt = new Date(now).toISOString();
-    return { repaired: true, externallyCompleted: false, blocked: false, ageMs };
+    return { repaired: true, externallyCompleted: false, failed: false, ageMs };
 }

package/dist/workflow/runtime.js

@@ -32,6 +32,10 @@ export function applyTaskMutation(task, mutation) {
         task.error = 'Lease expired after maximum attempts';
     if (mutation === 'mutation.markStartupOrphanedExhausted')
         task.error = 'Orphaned after relayd restart after maximum attempts';
+    if (mutation === 'mutation.markUnknownOutcome') {
+        task.error = 'Worker execution outcome is unknown; Troubleshooter diagnosis is required before retry.';
+        task.failureReason = 'worker_outcome_unknown';
+    }
     if (mutation === 'mutation.markPlannerUnavailable')
         task.error = 'No objective planner configured';
     if (mutation === 'mutation.preparePlatformFallback') {
@@ -49,10 +53,17 @@ export function applyTaskMutation(task, mutation) {
         task.leaseOwner = null;
         task.leaseExpiresAt = null;
         task.executionId = null;
-        task.failureReason = task.platformFailure?.safeToReroute ? 'worker_platform_fallback_unavailable' : 'worker_outcome_unknown';
+        task.failureReason = ['outcome_unknown', 'start_ack_timeout'].includes(task.platformFailure?.classification ?? '')
+            ? 'worker_outcome_unknown' : 'worker_platform_failure';
     }
 }
-export function applyTaskGraphTarget(task, target, timestamp = new Date().toISOString()) {
+export function applyTaskGraphTarget(task, target, timestamp = new Date().toISOString(), authoritativeUnblock = false) {
+    if (target === 'BLOCKED' && task.agentName !== 'troubleshooter')
+        throw new Error(`Only a Troubleshooter Task may become BLOCKED (${task.id})`);
+    if (task.state === 'BLOCKED' && target === 'QUEUED' && (!authoritativeUnblock || task.agentName !== 'troubleshooter'))
+        throw new Error(`Blocked Task ${task.id} requires an authoritative Troubleshooter unblock before transition`);
+    if (task.state === 'BLOCKED' && target !== 'QUEUED' && target !== 'CANCELLED' && target !== 'BLOCKED')
+        throw new Error(`Blocked Task ${task.id} requires an authoritative Troubleshooter unblock before transition`);
     const previous = Date.parse(task.updatedAt), candidate = Date.parse(timestamp);
     task.state = target;
     task.updatedAt = Number.isFinite(previous)

package/dist/workflow/task-resolution.js

@@ -7,11 +7,12 @@ export const TASK_RESOLUTION_PATHS = [
 const source = readFileSync(new URL('../../workflow/task-resolution.mmd', import.meta.url), 'utf8');
 const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
 export const taskResolutionV2 = new GraphRuntime(source, {
-    states: new Set(['unresolved', 'check_owner', 'check_path', 'resolved']),
+    states: new Set(['unresolved', 'check_owner', 'check_path', 'check_fresh_execution', 'resolved', 'rejected']),
     guards: {
         recoveryOwnerAvailable: boolGuard('recoveryOwnerAvailable'), plannerOwnerAvailable: boolGuard('plannerOwnerAvailable'),
         exactOriginalRetry: boolGuard('exactOriginalRetry'), sameJobDependency: boolGuard('sameJobDependency'),
         blockerJobDependency: boolGuard('blockerJobDependency'), escalationGate: boolGuard('escalationGate'), genuinelyObsolete: boolGuard('genuinelyObsolete'),
+        freshRecoveryExecution: boolGuard('freshRecoveryExecution'),
     },
     actions: Object.fromEntries(['resolution.activateRecovery', 'resolution.attachSameJobDependency', 'resolution.registerBlockerDependency', 'resolution.createEscalationGate', 'resolution.cancelSupersede'].map(id => [id, { id }])),
     events: { 'resolution.propose': { id: 'resolution.propose' } },
@@ -22,8 +23,8 @@ export function validateResolutionProposal(job, original, proposal) {
         throw new Error(`Unknown task resolution path ${proposal.path}`);
     if (proposal.path === 'exact_original_retry' && original.state !== 'FAILED')
         throw new Error('Exact-original retry requires a FAILED original Task');
-    if (proposal.path === 'same_job_dependency' && (!proposal.targetTaskId || !job.tasks.some(task => task.id === proposal.targetTaskId && task.jobId === job.id)))
-        throw new Error('Same-Job dependency resolution requires an existing target Task in the same Job');
+    if (proposal.path === 'same_job_dependency' && (!proposal.targetTaskId || proposal.targetTaskId === original.id || !job.tasks.some(task => task.id === proposal.targetTaskId && task.jobId === job.id && !['SUCCEEDED', 'CANCELLED'].includes(task.state))))
+        throw new Error('Same-Job dependency resolution requires an existing unresolved target Task in the same Job');
     if (proposal.path === 'blocker_job_dependency' && (!proposal.targetJobId || !proposal.mode))
         throw new Error('Blocker-Job dependency resolution requires targetJobId and merge or verified mode');
     if (proposal.path === 'escalation_gate' && (!proposal.rootCause || !proposal.solution))
@@ -32,10 +33,15 @@ export function validateResolutionProposal(job, original, proposal) {
         throw new Error('Cancellation/supersession requires an explicit obsolescence rootCause');
 }
 export function resolutionFacts(task, proposal, owner) {
-    return { recoveryOwnerAvailable: owner === 'troubleshooter', plannerOwnerAvailable: owner !== null && owner !== 'troubleshooter', exactOriginalRetry: proposal.path === 'exact_original_retry', sameJobDependency: proposal.path === 'same_job_dependency', blockerJobDependency: proposal.path === 'blocker_job_dependency', escalationGate: proposal.path === 'escalation_gate', genuinelyObsolete: proposal.path === 'cancel_supersede', unresolved: unresolvedTask(task) };
+    const freshRecoveryExecution = owner !== 'troubleshooter' || proposal.path !== 'exact_original_retry' || (Boolean(proposal.recoveryExecutionId)
+        && proposal.recoveryExecutionId !== task.resolution?.recoveryExecutionId);
+    return { recoveryOwnerAvailable: owner === 'troubleshooter', plannerOwnerAvailable: owner !== null && owner !== 'troubleshooter', exactOriginalRetry: proposal.path === 'exact_original_retry' && task.state === 'FAILED', sameJobDependency: proposal.path === 'same_job_dependency' && owner !== null && proposal.targetTaskId !== task.id, blockerJobDependency: proposal.path === 'blocker_job_dependency' && owner !== null && Boolean(proposal.targetJobId && proposal.mode), escalationGate: proposal.path === 'escalation_gate' && owner === 'troubleshooter' && Boolean(proposal.rootCause && proposal.solution), genuinelyObsolete: proposal.path === 'cancel_supersede' && Boolean(proposal.rootCause), freshRecoveryExecution, unresolved: unresolvedTask(task) };
 }
 export function decideTaskResolution(task, proposal, owner) {
-    return dispatchWorkflowGraphSync(taskResolutionV2, { initialState: 'unresolved', input: { transport: 'event', id: 'resolution.propose', payload: proposal }, durableFacts: resolutionFacts(task, proposal, owner), graphName: 'task-resolution', isTransientState: state => state === 'check_owner' || state === 'check_path', maxSteps: 4 });
+    return checkedResolutionDecision(dispatchWorkflowGraphSync(taskResolutionV2, { initialState: 'unresolved', input: { transport: 'event', id: 'resolution.propose', payload: proposal }, durableFacts: resolutionFacts(task, proposal, owner), graphName: 'task-resolution', isTransientState: state => ['check_owner', 'check_path', 'check_fresh_execution'].includes(state), maxSteps: 8 }));
+}
+function checkedResolutionDecision(decision) {
+    return decision.accepted && decision.target === 'rejected' ? { ...decision, accepted: false, reason: 'no_transition' } : decision;
 }
 export function dispatchTaskResolutionSync(task, proposal, owner, effects) {
     const handlers = {
@@ -45,13 +51,13 @@ export function dispatchTaskResolutionSync(task, proposal, owner, effects) {
         'resolution.createEscalationGate': effects.createEscalationGate,
         'resolution.cancelSupersede': effects.cancelSupersede,
     };
-    return dispatchWorkflowGraphSync(taskResolutionV2, {
+    return checkedResolutionDecision(dispatchWorkflowGraphSync(taskResolutionV2, {
         initialState: 'unresolved', input: { transport: 'event', id: 'resolution.propose', payload: proposal },
         durableFacts: resolutionFacts(task, proposal, owner), graphName: 'task-resolution',
-        isTransientState: state => state === 'check_owner' || state === 'check_path', maxSteps: 6,
+        isTransientState: state => ['check_owner', 'check_path', 'check_fresh_execution'].includes(state), maxSteps: 8,
         executeAction: actionId => { const handler = handlers[actionId]; if (!handler)
             throw new Error(`Task resolution effect ${actionId} is unavailable`); handler(); return {}; },
-    });
+    }));
 }
 export async function dispatchTaskResolution(task, proposal, owner, effects) {
     const handlers = {
@@ -61,13 +67,13 @@ export async function dispatchTaskResolution(task, proposal, owner, effects) {
         'resolution.createEscalationGate': effects.createEscalationGate,
         'resolution.cancelSupersede': effects.cancelSupersede,
     };
-    return dispatchWorkflowGraph(taskResolutionV2, {
+    return checkedResolutionDecision(await dispatchWorkflowGraph(taskResolutionV2, {
         initialState: 'unresolved',
         input: { transport: 'event', id: 'resolution.propose', payload: proposal },
         durableFacts: resolutionFacts(task, proposal, owner),
         graphName: 'task-resolution',
-        isTransientState: state => state === 'check_owner' || state === 'check_path',
-        maxSteps: 6,
+        isTransientState: state => ['check_owner', 'check_path', 'check_fresh_execution'].includes(state),
+        maxSteps: 8,
         executeAction: async (actionId) => {
             const handler = handlers[actionId];
             if (!handler)
@@ -75,7 +81,7 @@ export async function dispatchTaskResolution(task, proposal, owner, effects) {
             await handler();
             return {};
         },
-    });
+    }));
 }
 export function materializeResolution(task, proposal, owner, now = new Date().toISOString()) {
     return { ...proposal, state: proposal.path === 'escalation_gate' || proposal.path === 'blocker_job_dependency' ? 'waiting' : 'active', owner, updatedAt: now };
@@ -100,5 +106,7 @@ export function attachResolutionOwnership(job, child, proposal, owner) {
     return original;
 }
 export function claimExactOriginalRecovery(original, recovery) {
-    original.resolution = materializeResolution(original, { path: 'exact_original_retry', targetTaskId: original.id, rootCause: original.failureReason ?? original.error ?? 'durable failure', solution: `Troubleshooter ${recovery.id} diagnosis and exact-original recovery` }, 'troubleshooter');
+    if (!recovery.executionId)
+        throw new Error(`Troubleshooter ${recovery.id} has no current execution for a fresh resolution`);
+    original.resolution = materializeResolution(original, { path: 'exact_original_retry', targetTaskId: original.id, recoveryExecutionId: recovery.executionId, rootCause: original.failureReason ?? original.error ?? 'durable failure', solution: `Troubleshooter ${recovery.id} diagnosis and exact-original recovery` }, 'troubleshooter');
 }

package/dist/workflow/troubleshooter-v2.js

@@ -4,7 +4,7 @@ import { dispatchWorkflowGraphSync } from './dispatcher.js';
 const source = readFileSync(new URL('../../workflow/troubleshooter.mmd', import.meta.url), 'utf8');
 const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
 export const troubleshooterV2 = new GraphRuntime(source, {
-    states: new Set(['idle', 'check_ordinary', 'check_run', 'check_needs', 'check_id', 'check_barrier', 'skip', 'create']),
+    states: new Set(['idle', 'check_ordinary', 'check_run', 'check_needs', 'check_id', 'check_barrier', 'skip', 'create', 'resumed_after_authoritative_unblock', 'fresh_resolution_proposed', 'remain_failed_without_original_mutation']),
     guards: {
         failedWork: boolGuard('failedWork'),
         ordinaryWork: boolGuard('ordinaryWork'),
@@ -12,9 +12,11 @@ export const troubleshooterV2 = new GraphRuntime(source, {
         needsRecovery: boolGuard('needsRecovery'),
         idUnused: boolGuard('idUnused'),
         noRecoveryBarrier: boolGuard('noRecoveryBarrier'),
+        freshConditionVerification: boolGuard('freshConditionVerification'),
+        resolutionForCurrentExecution: boolGuard('resolutionForCurrentExecution'),
     },
-    actions: { 'troubleshooter.create': { id: 'troubleshooter.create' } },
-    events: { 'troubleshooter.reconcile': { id: 'troubleshooter.reconcile' } },
+    actions: { 'troubleshooter.create': { id: 'troubleshooter.create' }, 'troubleshooter.proposeFreshResolution': { id: 'troubleshooter.proposeFreshResolution' }, 'troubleshooter.applyAuthorizedResolution': { id: 'troubleshooter.applyAuthorizedResolution' } },
+    events: { 'troubleshooter.reconcile': { id: 'troubleshooter.reconcile' }, 'troubleshooter.resumed': { id: 'troubleshooter.resumed' }, 'task.started': { id: 'task.started' }, 'resolution.propose': { id: 'resolution.propose' } },
 });
 export function dispatchTroubleshooter(facts, onCreate) {
     return dispatchWorkflowGraphSync(troubleshooterV2, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.155",
+  "version": "2.0.157",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 ---
 name: troubleshooter
-description: Recover FAILED Agents Relay tasks by diagnosing runtime/execution faults and repairing recoverable causes. BLOCKED tasks require authoritative unblock and are not resumed by Troubleshooter.
+description: Recover failed Agents Relay tasks by diagnosing execution faults and repairing recoverable causes. Only a Troubleshooter can wait in BLOCKED; after authoritative unblock, the same Troubleshooter reruns and re-verifies before issuing a fresh resolution.
 capabilities: [troubleshoot, recovery, orchestration, local_repo, iterative_tools]
 runtime: codex
 delegation: [p0-self-job, relay-task-retry]
@@ -9,7 +9,7 @@ restrictions: [preserve-failure-evidence, no-blind-retry, no-human-blocker-bypas
 
 # Troubleshooter Agent
 
-You are the recovery orchestrator for a FAILED Agents Relay task. Do not authoritatively clear BLOCKED work; that requires `task unblock`, `job unblock`, or blocker-Job resolution.
+You are the recovery orchestrator for a FAILED Agents Relay task. Ordinary Tasks never enter BLOCKED or UNBLOCKED. Only a Troubleshooter can become BLOCKED, and only an authoritative unblock can resume that same Troubleshooter.
 
 Your goal is not to explain the failure. Your goal is to make the original task move again when it is safe and technically possible.
 
@@ -33,7 +33,9 @@ Read `skills/agents-relay/troubleshooter-qa.md` for user-editable best practices
    - 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. 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.
+   - For a suspected genuine human/external blocker, 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.
+   - After unblock, this same Troubleshooter must run with a new execution ID, re-check the blocking condition, and produce a fresh resolution bound to that execution. A previously resolved resolution record never authorizes retrying a new attempt.
+   - Unknown worker execution outcomes fail closed. Do not automatically reroute or retry the original task, and do not block the original task; diagnose it through the Troubleshooter.
 7. For an immediate repair, only after the blocker is removed request `agents-relay task recover` with this Troubleshooter's recovery Task ID, then reconcile the original Job. Verify the SQLite postcondition: original Task state QUEUED, expected resolution and recovery correlation. An authorized human response is a Task Comment, not a rewrite of Task input. Retain historical conditions as provenance, independently verify the original failing execution context, and do not submit an identical escalation with no new evidence. Deferred repair uses the durable blocker relation: merge-mode blockers wake dependents after merge; release/deploy/runtime blockers require `--resolution verified` and `agents-relay blocker resolve` only after verification.
 8. Verify durable evidence the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
 9. Publish this Troubleshooter Task's terminal event only after the recovery outcome is durable.

package/skills/agents-relay/contracts/task-job-contract.md

@@ -70,7 +70,7 @@ Keep these concepts distinct: observation is not root cause; hypothesis is not r
 
 ### Job-defined Task tag
 
-`Task.state` is reserved for Relay lifecycle only: `DRAFT`, `QUEUED`, `RUNNING`, `BLOCKED`, `SUCCEEDED`, `FAILED`, and `CANCELLED`. A Job may additionally define one optional `tag` contract for a Job-specific result or classification that should be visible on each Task without changing its lifecycle state.
+`Task.state` is reserved for Relay lifecycle only: `DRAFT`, `QUEUED`, `RUNNING`, `BLOCKED`, `SUCCEEDED`, `FAILED`, and `CANCELLED`. `BLOCKED` is exclusive to Tasks whose `agentName` is exactly `troubleshooter`; ordinary Tasks never enter `BLOCKED` or an `UNBLOCKED` lifecycle state. A Job may additionally define one optional `tag` contract for a Job-specific result or classification that should be visible on each Task without changing its lifecycle state.
 
 The Job owns the meaning of the tag. Its trusted Job marker declares a human-readable `description` explaining what the tag means and when workers should set it, plus the allowed durable values and their dashboard display strings:
 
@@ -164,14 +164,14 @@ forbids it.
 
 ## Dependency vs block and authoritative unblock
 
-`dependencies` describe normal DAG ordering. Dependency completion does not create an unblock lifecycle event or Planner unblock trigger; Relay simply releases dependent work when its prerequisites succeed. `BLOCKED` is different: it records that execution reached a runtime/external condition that invalidates normal progress.
+`dependencies` describe normal DAG ordering. An unmet dependency keeps ordinary work in `DRAFT`; dispatchable work is `QUEUED`. Dependency completion does not create an unblock lifecycle event or Planner unblock trigger; Relay releases dependent work when its prerequisites succeed. Worker, platform, semantic, and unknown-outcome failures are `FAILED`. Unknown worker outcome fails closed and never justifies rerouting. Only a Troubleshooter waiting for an authoritative human response may become `BLOCKED`.
 
-A BLOCKED Task cannot be resumed through retry, queue, dashboard state editing, PR push, webhook, ordinary task update, or troubleshooter inference. Except for blocker-Job resolution, the authoritative entry points are `task unblock --reason ...` and `job unblock --reason ...`. Authoritative unblock records the blocked baseline and current evidence, then transitions `BLOCKED -> UNBLOCKED` through the durable `task.unblocked` lifecycle event. `BLOCKED` therefore always means the blocker is still effective; `UNBLOCKED` means the old blocked attempt is historical and its blocker was explicitly cleared.
+A BLOCKED Troubleshooter cannot be resumed through retry, queue, dashboard state editing, PR push, webhook, ordinary task update, or Troubleshooter inference. The authoritative entry point records the response and transitions that same Troubleshooter `BLOCKED -> QUEUED` through `task.unblocked`. The queued Troubleshooter must execute again, verify the condition from fresh evidence, and issue a fresh resolution before Relay may retry or replan the original FAILED Task. Prior `resolved` metadata never authorizes another attempt. Historical ordinary BLOCKED snapshots migrate to FAILED while their append-only event history remains unchanged; they are never silently converted to success.
 
-For autonomous Jobs, an UNBLOCKED Task is never silently retried. Its unblock metadata becomes the trigger/change context for the next Planner round, which decides whether to replace, split, wait, or otherwise re-plan the objective. For fixed Jobs, authoritative unblock records the UNBLOCKED transition first and may then requeue the same Task according to fixed-job retry semantics.
+The old `UNBLOCKED` state is compatibility-only input. It normalizes to QUEUED only for Troubleshooter Tasks and to FAILED for ordinary Tasks, pending diagnosis.
 
 Each Planner round is also a first-class durable Plan entity stored in its own `agents-relay:plan:v1` PR comment. Relay creates the Plan comment before the internal planner execution record and before any generated Task comments, then updates that same Plan comment with the final assessment and generated Task IDs. Unblock/change facts belong to the Plan trigger/context, not to new Job-level Change Cycle state. Historical `kind=planner` Task records and legacy Job `changeCycle` fields remain readable for compatibility only.
 
-A blocker Job owns reverse `unblocks` references. When it resolves, Relay checks the dependent Job. If that autonomous Job has an effective BLOCKED work Task, resolution uses the same authoritative `BLOCKED -> UNBLOCKED -> Planner` path. If it does not have BLOCKED work (for example the registered Task is DRAFT or FAILED), existing release/retry behavior remains unchanged.
+A blocker Job owns reverse `unblocks` references. When it resolves, Relay releases matching dependency-waiting Tasks through their ordinary DRAFT/QUEUED path. It cannot unblock ordinary work or resume a Troubleshooter without the authoritative response flow.
 
-Automatic Planner creation treats only a Task whose lifecycle state is exactly `BLOCKED` as a block gate. `UNBLOCKED` and FAILED history do not themselves gate a new Planner round; active DRAFT/QUEUED/RUNNING work still prevents a competing planning round.
+Automatic Planner creation treats a currently BLOCKED Troubleshooter as a recovery gate. FAILED history alone does not authorize resolution or success; active DRAFT/QUEUED/RUNNING work still prevents a competing planning round.

package/workflow/authoritative-unblock.mmd

@@ -5,15 +5,12 @@ description: Validates authoritative unblock requests and safely resumes blocked
 flowchart LR
 %% relay: initial blocked
 blocked["state: blocked"]
-autonomous["state: autonomous_replan"]
-fixed["state: fixed_retry"]
+queued["state: troubleshooter_queued"]
 
-autonomousJob["guard: autonomousJob"]
-replan["action: unblock.replan"]
+eligible["guard: blockedTroubleshooter"]
 retry["action: unblock.retry"]
 
-blocked -->|on: task.authoritative_unblock| autonomousJob
-autonomousJob -->|true| replan
-replan --> autonomous
-autonomousJob -->|false| retry
-retry --> fixed
+blocked -->|on: task.authoritative_unblock| eligible
+eligible -->|true| retry
+eligible -->|false| blocked
+retry --> queued

package/workflow/blocker-resolution.mmd

@@ -1,6 +1,6 @@
 ---
 title: Blocker Resolution
-description: Resolves blockers through verified recovery evidence and graph-authorized decisions.
+description: Releases dependency-waiting work; failed work and blocked Troubleshooters require their own fresh recovery flow.
 ---
 flowchart LR
 %% relay: initial waiting
@@ -27,12 +27,7 @@ isBlocked["guard: isBlocked"]
 isFailed["guard: isFailed"]
 isUnblocked["guard: isUnblocked"]
 
-autonomousUnblock["action: blocker.autonomousUnblock"]
-acceptExisting["action: blocker.acceptExistingUnblock"]
 releaseDraft["action: blocker.releaseDraft"]
-unblockTask["action: blocker.unblockTask"]
-retryFailed["action: blocker.retryFailed"]
-retryUnblocked["action: blocker.retryUnblocked"]
 
 waiting -->|on: blocker.resolved| resolutionAllowed
 resolutionAllowed -->|false| wait
@@ -47,13 +42,11 @@ autonomousJob -->|true| checkEffective
 autonomousJob -->|false| checkDraft
 
 checkEffective -->|on: blocker.resolved| effectivelyBlocked
-effectivelyBlocked -->|true| autonomousUnblock
-autonomousUnblock --> resumed
+effectivelyBlocked -->|true| wait
 effectivelyBlocked -->|false| checkAlreadyUnblocked
 
 checkAlreadyUnblocked -->|on: blocker.resolved| alreadyUnblocked
-alreadyUnblocked -->|true| acceptExisting
-acceptExisting --> resumed
+alreadyUnblocked -->|true| resumed
 alreadyUnblocked -->|false| checkDraft
 
 checkDraft -->|on: blocker.resolved| isDraft
@@ -62,16 +55,13 @@ releaseDraft --> resumed
 isDraft -->|false| checkBlocked
 
 checkBlocked -->|on: blocker.resolved| isBlocked
-isBlocked -->|true| unblockTask
-unblockTask --> resumed
+isBlocked -->|true| wait
 isBlocked -->|false| checkFailed
 
 checkFailed -->|on: blocker.resolved| isFailed
-isFailed -->|true| retryFailed
-retryFailed --> resumed
+isFailed -->|true| wait
 isFailed -->|false| checkUnblocked
 
 checkUnblocked -->|on: blocker.resolved| isUnblocked
-isUnblocked -->|true| retryUnblocked
-retryUnblocked --> resumed
+isUnblocked -->|true| wait
 isUnblocked -->|false| obsolete